[SDK-4644] Clarify that AuthenticationController should only be creat…

…ed once (#49)

* Clarify that only one AuthenticationController should be created per application

* rename to provider

* fix singleton

.gitignore

@@ -0,0 +1,26 @@
+.gradle
+build/
+!gradle/wrapper/gradle-wrapper.jar
+**/bin/
+
+### STS ###
+.apt_generated
+.classpath
+.factorypath
+.project
+.settings
+.springBeans
+.sts4-cache
+
+### IntelliJ IDEA ###
+.idea
+*.iws
+*.iml
+*.ipr
+/out/
+
+### VS Code ###
+.vscode/
+
+target/
+.DS_Store

01-Login/README.md

@@ -1,22 +1,24 @@
 
 # Auth0 Servlet Sample
 
-## Getting started
-
 This sample demonstrates how to use Auth0 to perform authentication using the Auth0 Java MVC Commons library in a Java Servlet web application. Download or clone this repository and follow the instructions below to configure and run the application.
 
 To learn more about the Auth0 Java MVC Commons library, refer to the project's [documentation](https://github.com/auth0/auth0-java-mvc-common/blob/master/README.md).
 
-### Auth0 Dashboard
+## Prerequisites
+
+- Java 8 or greater
+- An Auth0 account
 
-1. On the [Auth0 Dashboard](https://manage.auth0.com/#/clients), click **CREATE APPLICATION**, provide a name for your Application, select **Regular Web Application**, and click **Create**
-1. Go to the **Settings** tab of your Application
-1. Add the URL `http://localhost:3000/callback` to the **Allowed Callback URLs** field
-1. Add the URL `http://localhost:3000/login` to the **Allowed Logout URLs** field
-1. Click **SAVE CHANGES**
-1. The `Domain`, `Client ID`, and `Client Secret` values will be used next to configure the Java application
+## Configuration
+
+### Auth0 Dashboard
+1. On the [Auth0 Dashboard](https://manage.auth0.com/#/clients) create a new Application of type **Regular Web Application**.
+1. On the **Settings** tab of your application, add the URL `http://localhost:3000/callback` to the **Allowed Callback URLs** field.
+1. On the **Settings** tab of your application, add the URL `http://localhost:3000/login` to the **Allowed Logout URLs** field.
+1. Save the changes to your application settings. Don't close this page; you'll need some of the settings when configuring the application below.
 
-### Java Application
+### Application configuration
 
 Set the Auth0 Application values from above in the `src/main/webapp/WEB-INF/web.xml` file.
 
@@ -37,19 +39,6 @@ Set the Auth0 Application values from above in the `src/main/webapp/WEB-INF/web.
 </context-param>
 ```
 
-By default, `mvc-auth-commons` uses the Authorization Code flow and assumes tokens are signed with the HS256 signing algorithm.
-
-If using RS256 (recommended, and the default for new applications), you need to configure the `AuthenticationController` with a `JwkProvider` to fetch the public signing key used to verify the ID token:
-
-```java
-JwkProvider jwkProvider = new JwkProviderBuilder(domain).build();
-AuthenticationController.newBuilder(domain, clientId, clientSecret)
-    .withJwkProvider(jwkProvider)
-    .build();
-```
-
-These values are used by the the `AuthenticationControllerProvider` to configure the Auth0 Java MVC Commons library, to enable users to login to the application.
-
 ### Running the sample
 
 Open a terminal or command line, navigate to the `01-Login` directory, and run the following command:

01-Login/src/main/java/com/auth0/example/AuthenticationControllerProvider.java

@@ -7,21 +7,37 @@
 import javax.servlet.ServletConfig;
 import java.io.UnsupportedEncodingException;
 
-public abstract class AuthenticationControllerProvider {
+/**
+ * A class that manages a singleton instance of a {@link JwkProvider} and {@link AuthenticationController} to be used
+ * by Servlets to authenticate users with Auth0.
+ * <p>
+ * Note that each application instance should only create <strong>one</strong> instance of the {@linkplain AuthenticationController}
+ * per domain and application to minimize unnecessary resource usage.
+ */
+class AuthenticationControllerProvider {
 
-    public static AuthenticationController getInstance(ServletConfig config) throws UnsupportedEncodingException {
-        String domain = config.getServletContext().getInitParameter("com.auth0.domain");
-        String clientId = config.getServletContext().getInitParameter("com.auth0.clientId");
-        String clientSecret = config.getServletContext().getInitParameter("com.auth0.clientSecret");
+    private AuthenticationControllerProvider() {}
 
-        if (domain == null || clientId == null || clientSecret == null) {
-            throw new IllegalArgumentException("Missing domain, clientId, or clientSecret. Did you update src/main/webapp/WEB-INF/web.xml?");
+    private static AuthenticationController INSTANCE;
+
+    // if multiple threads may call this, synchronize this method and consider double locking
+    static AuthenticationController getInstance(ServletConfig config) throws UnsupportedEncodingException {
+        if (INSTANCE == null) {
+            String domain = config.getServletContext().getInitParameter("com.auth0.domain");
+            String clientId = config.getServletContext().getInitParameter("com.auth0.clientId");
+            String clientSecret = config.getServletContext().getInitParameter("com.auth0.clientSecret");
+
+            if (domain == null || clientId == null || clientSecret == null) {
+                throw new IllegalArgumentException("Missing domain, clientId, or clientSecret. Did you update src/main/webapp/WEB-INF/web.xml?");
+            }
+
+            // JwkProvider required for RS256 tokens. If using HS256, do not use.
+            JwkProvider jwkProvider = new JwkProviderBuilder(domain).build();
+            INSTANCE = AuthenticationController.newBuilder(domain, clientId, clientSecret)
+                    .withJwkProvider(jwkProvider)
+                    .build();
         }
 
-        // JwkProvider required for RS256 tokens. If using HS256, do not use.
-        JwkProvider jwkProvider = new JwkProviderBuilder(domain).build();
-        return AuthenticationController.newBuilder(domain, clientId, clientSecret)
-                .withJwkProvider(jwkProvider)
-                .build();
+        return INSTANCE;
     }
 }