Chapter 9. OpenID Connect in JBoss EAP

Procedure

1. Start the Red Hat Single Sign-On server at a port other than 8080 because JBoss EAP default port is 8080.

   Syntax

   $ RH_SSO_HOME/bin/standalone.sh -Djboss.socket.binding.port-offset=<offset-number>

   Example

   $ /home/servers/rh-sso-7.4/bin/standalone.sh -Djboss.socket.binding.port-offset=100

2. Log in to the Admin Console at http://localhost:<port>/auth/. For example, http://localhost:8180/auth/.
3. To create a realm, in the Admin Console, hover over Master, and click Add realm.
4. Enter a name for the realm. For example, example_realm. Ensure that Enabled is ON and click Create.
5. Click Users, then click Add user to add a user to the realm.
6. Enter a user name. For example, jane_doe. Ensure that User Enabled is ON and click Save.
7. Click Credentials to add a password to the user.
8. Set a password for the user. For example, janedoep@$$. Toggle Temporary to OFF and click Set Password. In the confirmation prompt, click Set password.
9. Click Clients, then click Create to configure a client connection.
10. Enter a client ID. For example, my_jbeap. Ensure that Client Protocol is set to openid-connect, and click Save.

11. Click Installation, then select Keycloak OIDC JSON as the Format Option to see the connection parameters.

    {
      "realm": "example_realm",
      "auth-server-url": "http://localhost:8180/auth/",
      "ssl-required": "external",
      "resource": "my_jbeap",
      "public-client": true,
      "confidential-port": 0
    }

    When configuring your JBoss EAP application to use Red Hat Single Sign-On as the identity provider, you use the parameters as follows:

    "provider-url" : "http://localhost:8180/auth/realms/example_realm",
    "ssl-required": "external",
    "client-id": "my_jbeap",
    "public-client": true,
    "confidential-port": 0

12. Click Clients, click Edit next to my_jbeap to edit the client settings.

13. In Valid Redirect URIs, enter the URL where the page should redirect after authentication is successful.

    For this example, set this value to http://localhost:8080/simple-oidc-example/secured/*

Procedure

1. Set up a Maven project using the mvn command. The command creates the directory structure for the project and the pom.xml configuration file.

   Syntax

   $ mvn archetype:generate \
   -DgroupId=${group-to-which-your-application-belongs} \
   -DartifactId=${name-of-your-application} \
   -DarchetypeGroupId=org.apache.maven.archetypes \
   -DarchetypeArtifactId=maven-archetype-webapp \
   -DinteractiveMode=false

   Example

   $ mvn archetype:generate \
   -DgroupId=com.example.oidc \
   -DartifactId=simple-oidc-example \
   -DarchetypeGroupId=org.apache.maven.archetypes \
   -DarchetypeArtifactId=maven-archetype-webapp \
   -DinteractiveMode=false

2. Navigate to the application root directory:

   Syntax

   $ cd <name-of-your-application>

   Example

   $ cd simple-oidc-example

3. Update the generated pom.xml file as follows:

   1. Set the following properties:

      <properties>
          <maven.compiler.source>1.8</maven.compiler.source>
          <maven.compiler.target>1.8</maven.compiler.target>
          <failOnMissingWebXml>false</failOnMissingWebXml>
          <version.server.bom>4.0.0.GA</version.server.bom>
          <version.server.bootable-jar>4.0.0.GA</version.server.bootable-jar>
          <version.wildfly-jar.maven.plugin>4.0.0.GA</version.wildfly-jar.maven.plugin>
      </properties>

   2. Set the following dependencies:

      <dependencies>
          <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>javax.servlet-api</artifactId>
            <version>3.1.0.redhat-1</version>
            <scope>provided</scope>
          </dependency>
      </dependencies>

   3. Set the following build configuration to use mvn widlfy:deploy to deploy the application:

      <build>
          <finalName>${project.artifactId}</finalName>
          <plugins>
              <plugin>
                  <groupId>org.wildfly.plugins</groupId>
                  <artifactId>wildfly-maven-plugin</artifactId>
                  <version>2.1.0.Final</version>
              </plugin>
          </plugins>
      </build>

Procedure

1. Create a directory to store the Java files.

   Syntax

   $ mkdir -p <application_root>/src/main/java/com/example/oidc

   Example

   $ mkdir -p simple-oidc-example/src/main/java/com/example/oidc

2. Navigate to the new directory.

   Syntax

   $ cd <application_root>/src/main/java/com/example/oidc

   Example

   $ cd simple-oidc-example/src/main/java/com/example/oidc

3. Create a servlet "SecuredServlet.java" with the following content:

   package com.example.oidc;
   
   import java.io.IOException;
   import java.io.PrintWriter;
   import java.security.Principal;
   
   import javax.servlet.ServletException;
   import javax.servlet.annotation.WebServlet;
   import javax.servlet.http.HttpServlet;
   import javax.servlet.http.HttpServletRequest;
   import javax.servlet.http.HttpServletResponse;
   
   /**
    * A simple secured HTTP servlet.
    *
    */
   @WebServlet("/secured")
   public class SecuredServlet extends HttpServlet {
   
       @Override
       protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
           try (PrintWriter writer = resp.getWriter()) {
               writer.println("<html>");
               writer.println("  <head><title>Secured Servlet</title></head>");
               writer.println("  <body>");
               writer.println("    <h1>Secured Servlet</h1>");
               writer.println("    <p>");
               writer.print(" Current Principal '");
               Principal user = req.getUserPrincipal();
               writer.print(user != null ? user.getName() : "NO AUTHENTICATED USER");
               writer.print("'");
               writer.println("    </p>");
               writer.println("  </body>");
               writer.println("</html>");
           }
       }
   
   }

4. Add security rules for access to your application in the deployment descriptor web.xml file located in the WEB-INF directory of the application.

   <?xml version="1.0" encoding="UTF-8"?>
   
   <web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
      metadata-complete="false">
   
       <security-constraint>
           <web-resource-collection>
               <web-resource-name>secured</web-resource-name>
               <url-pattern>/secured</url-pattern>
           </web-resource-collection>
           <auth-constraint>
               <role-name>*</role-name>
           </auth-constraint>
       </security-constraint>
   
       <security-role>
           <role-name>*</role-name>
       </security-role>
   </web-app>

5. To secure the application with OpenID Connect, either update the deployment configuration or configure the elytron-oidc-client subsystem.

   Note

   If you configure OpenID Connect in both the deployment configuration and the elytron-oidc-client subsystem, the configuration in the elytron-oidc-client subsystem secure-deployment attribute takes precedence over the configuration in the application deployment descriptor.

   • Updating the deployment configuration:

     1. Create a file oidc.json in the WEB-INF directory, like this:

        {
          "provider-url" : "http://localhost:8180/auth/realms/example_realm",
          "ssl-required": "external",
          "client-id": "my_jbeap",
          "public-client": true,
          "confidential-port": 0
        }

     2. Update the deployment descriptor web.xml file with the following text to declare that this application uses OIDC:

        <login-config>
            <auth-method>OIDC</auth-method>
        </login-config>

   • Configuring the elytron-oidc-client subsystem:

     • To secure your application, use the following management CLI command:

       /subsystem=elytron-oidc-client/secure-deployment=simple-oidc-example.war/:add(client-id=my_jbeap,provider-url=http://localhost:8180/auth/realms/example_realm,public-client=true,ssl-required=external)

6. In the application root directory, compile your application with the following command:

   $ mvn package

7. Deploy the application.

   $ mvn wildfly:deploy

Verification

1. In a browser, navigate to http://localhost:8080/simple-oidc-example/secured.

2. Log in with your credentials. For example:

   username: jane_doe
   password: janedoep@$$

   You get the following output:

   Secured Servlet
   Current Principal '5cb0c4ca-0477-44c3-bdef-04db04d7e39d'

   You can now log in to the application using the credentials you configured in the Red Hat Single Sign-On as the OpenID provider.

Procedure

1. Update the deployment descriptor web.xml file with the following text:

   Syntax

   <security-constraint>
       ...
       <auth-constraint>
           <role-name><allowed_role></role-name>
       </auth-constraint>
   </security-constraint>

   Example

   <security-constraint>
       ...
       <auth-constraint>
           <role-name>example_role</role-name> 

   1

   
       </auth-constraint>
   </security-constraint>

   1

   Allow only those users with the role example_role to access your application.

2. In the application root directory, recompile your application with the following command:

   $ mvn package

3. Deploy the application.

   $ mvn wildfly:deploy

Verification

1. In a browser, navigate to http://localhost:8080/simple-oidc-example/secured.

2. Log in with your credentials. For example:

   username: jane_doe
   password: janedoep@$$

   You get the following output:

   Forbidden

   Because you have not assigned the required role to the user "jane_doe," jane_doe can’t log in to your application. Only the users with the required role can log in.

Procedure

1. Log in to the admin console at http://localhost:<port>/auth/. For example, http://localhost:8180/auth/.
2. Click the realm you use to connect with JBoss EAP. For example, example_realm.
3. Click Clients, then click the client-name you configured for JBoss EAP. For example, my_jbeap.
4. Click Roles, then Add Role.
5. Enter a role name, such as example_role, then click Save. This is the role name you configure in JBoss EAP for authorization.
6. Click Users, then View all users.
7. Click an ID to assign the role you created. For example, click the ID for jane_doe.
8. Click Role Mappings. In the Client Roles field, select the client-name you configured for JBoss EAP. For example, my_jbeap.
9. In Available Roles, select a role to assign. For example, example_role. Click Add selected.

Verification

1. In a browser, navigate to the application URL.

2. Log in with your credentials. For example:

   username: jane_doe
   password: janedoep@$$

   You get the following output:

   Secured Servlet
   Current Principal '5cb0c4ca-0477-44c3-bdef-04db04d7e39d'

   Users with the required role can log in to your application.

Procedure

1. Set up a Maven project using the mvn command. The command creates the directory structure for the project and the pom.xml configuration file.

   Syntax

   $ mvn archetype:generate \
   -DgroupId=${group-to-which-your-application-belongs} \
   -DartifactId=${name-of-your-application} \
   -DarchetypeGroupId=org.apache.maven.archetypes \
   -DarchetypeArtifactId=maven-archetype-webapp \
   -DinteractiveMode=false

   Example

   $ mvn archetype:generate \
   -DgroupId=com.example.oidc \
   -DartifactId=simple-oidc-layer-example \
   -DarchetypeGroupId=org.apache.maven.archetypes \
   -DarchetypeArtifactId=maven-archetype-webapp \
   -DinteractiveMode=false

2. Navigate to the application root directory.

   Syntax

   $ cd <name-of-your-application>

   Example

   $ cd simple-oidc-layer-example

3. Update the generated pom.xml file as follows:

   1. Set the following repositories:

      <repositories>
          <repository>
              <id>jboss</id>
              <url>https://maven.repository.redhat.com/ga</url>
              <snapshots>
                  <enabled>false</enabled>
              </snapshots>
          </repository>
      </repositories>

   2. Set the following plugin repositories:

      <pluginRepositories>
          <pluginRepository>
              <id>jboss</id>
              <url>https://maven.repository.redhat.com/ga</url>
              <snapshots>
                  <enabled>false</enabled>
              </snapshots>
          </pluginRepository>
      </pluginRepositories>

   3. Set the following properties:

      <properties>
          <maven.compiler.source>1.8</maven.compiler.source>
          <maven.compiler.target>1.8</maven.compiler.target>
          <bootable.jar.maven.plugin.version>6.1.2.Final-redhat-00001</bootable.jar.maven.plugin.version>
          <jboss.xp.galleon.feature.pack.version>4.0.0.GA-redhat-00002</jboss.xp.galleon.feature.pack.version>
      </properties>

   4. Set the following dependencies:

      <dependencies>
          <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>javax.servlet-api</artifactId>
            <version>3.1.0.redhat-1</version>
            <scope>provided</scope>
          </dependency>
      </dependencies>
      
      <dependencyManagement>
          <dependencies>
              <dependency>
                  <groupId>org.jboss.bom</groupId>
                  <artifactId>jboss-eap-jakartaee8</artifactId>
                  <version>7.3.4.GA</version>
                  <type>pom</type>
                  <scope>import</scope>
              </dependency>
              <dependency>
                  <groupId>org.jboss.spec.javax.servlet</groupId>
                  <artifactId>jboss-servlet-api_4.0_spec</artifactId>
                  <scope>provided</scope>
              </dependency>
          </dependencies>
      </dependencyManagement>

   5. Set the following build configuration in the <build> element of the pom.xml file:

      <finalName>${project.artifactId}</finalName>
      <plugins>
          <plugin>
              <groupId>org.wildfly.plugins</groupId>
              <artifactId>wildfly-jar-maven-plugin</artifactId>   

      1

      
              <version>${bootable.jar.maven.plugin.version}</version>
              <configuration>
                  <feature-pack-location>org.jboss.eap:wildfly-galleon-pack:${jboss.xp.galleon.feature.pack.version}</feature-pack-location>
                  <layers>
                      <layer>jaxrs-server</layer>
                      <layer>elytron-oidc-client</layer>    

      2

      
                  </layers>
                  <context-root>false</context-root>   

      3

      
              </configuration>
              <executions>
                  <execution>
                      <goals>
                          <goal>package</goal>
                      </goals>
                  </execution>
              </executions>
          </plugin>
      </plugins>

      1

      JBoss EAP Maven plug-in to build the application as a bootable JAR

      2

      The elytron-oidc-client layer provides a native OpenID Connect (OIDC) client to connect with external OpenID providers.

      3

      Register the application in the simple-oidc-layer-example resource path. The servlet is then available at the URL http://server-url/application_name/servlet_path, for example: http://localhost:8080/simple-oidc-layer-example/secured. By default, the application WAR file is registered under the root-context path, like http://server-url/servlet_path, for example: http://localhost:8080/secured.

   6. Set the application name, for example "simple-oidc-layer-example" in the <build> element of the pom.xml file.

      <finalName>simple-oidc-layer-example</finalName>

Procedure

1. Create a directory to store the Java files.

   Syntax

   $ mkdir -p <application_root>/src/main/java/com/example/oidc

   Example

   $ mkdir -p simple-oidc-layer-example/src/main/java/com/example/oidc

2. Navigate to the new directory.

   Syntax

   $ cd <application_root>/src/main/java/com/example/oidc

   Example

   $ cd simple-oidc-layer-example/src/main/java/com/example/oidc

3. Create a servlet "SecuredServlet.java" with the following content:

   package com.example.oidc;
   
   import java.io.IOException;
   import java.io.PrintWriter;
   import java.security.Principal;
   
   import javax.servlet.ServletException;
   import javax.servlet.annotation.WebServlet;
   import javax.servlet.http.HttpServlet;
   import javax.servlet.http.HttpServletRequest;
   import javax.servlet.http.HttpServletResponse;
   
   /**
    * A simple secured HTTP servlet.
    *
    */
   @WebServlet("/secured")
   public class SecuredServlet extends HttpServlet {
   
       @Override
       protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
           try (PrintWriter writer = resp.getWriter()) {
               writer.println("<html>");
               writer.println("  <head><title>Secured Servlet</title></head>");
               writer.println("  <body>");
               writer.println("    <h1>Secured Servlet</h1>");
               writer.println("    <p>");
               writer.print(" Current Principal '");
               Principal user = req.getUserPrincipal();
               writer.print(user != null ? user.getName() : "NO AUTHENTICATED USER");
               writer.print("'");
               writer.println("    </p>");
               writer.println("  </body>");
               writer.println("</html>");
           }
       }
   
   }

4. Add security rules for access to your application in the deployment descriptor web.xml file located in the WEB-INF directory of the application.

   <?xml version="1.0" encoding="UTF-8"?>
   
   <web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
      metadata-complete="false">
   
       <security-constraint>
           <web-resource-collection>
               <web-resource-name>secured</web-resource-name>
               <url-pattern>/secured</url-pattern>
           </web-resource-collection>
           <auth-constraint>
               <role-name>*</role-name>
           </auth-constraint>
       </security-constraint>
   
       <security-role>
           <role-name>*</role-name>
       </security-role>
   </web-app>

5. To secure the application with OpenID Connect, either update the deployment configuration or configure the elytron-oidc-client subsystem.

   Note

   If you configure OpenID Connect in both the deployment configuration and the elytron-oidc-client subsystem, the configuration in the elytron-oidc-client subsystem secure-deployment attribute takes precedence over the configuration in the application deployment descriptor.

   • Updating the deployment configuration:

     1. Create a file oidc.json in the WEB-INF directory, like this:

        {
          "provider-url" : "http://localhost:8180/auth/realms/example_realm",
          "ssl-required": "external",
          "client-id": "my_jbeap",
          "public-client": true,
          "confidential-port": 0
        }

     2. Update the deployment descriptor web.xml file with the following text to declare that this application uses OIDC:

        <login-config>
            <auth-method>OIDC</auth-method>
        </login-config>

   • Configuring the elytron-oidc-client subsystem:

     1. Create a directory to store a CLI script in the application root directory:

        Syntax

        $ mkdir <application_root>/<cli_script_directory>

        Example

        $ mkdir simple-oidc-layer-example/scripts/

        You can create the directory at any place that Maven can access, inside the application root directory.

     2. Create a CLI script, such as configure-oidc.cli, with the following content:

        /subsystem=elytron-oidc-client/secure-deployment=simple-oidc-layer-example.war:add(client-id=my_jbeap,provider-url=http://localhost:8180/auth/realms/example_realm,public-client=true,ssl-required=external)

        The subsystem command defines the simple-oidc-layer-example.war resource as the deployment to secure in elytron-oidc-client subsystem.

     3. In the project pom.xml file, add the following configuration extract to the existing plug-in <configuration> element:

        <cli-sessions>
            <cli-session>
                <script-files>
                    <script>scripts/configure-oidc.cli</script>
                </script-files>
            </cli-session>
        </cli-sessions>

6. In the application root directory, compile your application with the following command:

   $ mvn package

7. Deploy the bootable jar application using the following command:

   Syntax

   $ java -jar <application_root>/target/simple-oidc-layer-example-bootable.jar

   Example

   $ java -jar simple-oidc-layer-example/target/simple-oidc-layer-example-bootable.jar

   This starts JBoss EAP and deploys the application.

Verification

1. In a browser, navigate to http://localhost:8080/simple-oidc-layer-example/secured.

2. Log in with your credentials. For example:

   username: jane_doe
   password: janedoep@$$

   You get the following output:

   Secured Servlet
   Current Principal '5cb0c4ca-0477-44c3-bdef-04db04d7e39d'

   You can now log in to the application using the credentials you configured in the Red Hat Single Sign-On as the OpenID provider.

Procedure

1. Update the deployment descriptor web.xml file with the following text:

   Syntax

   <security-constraint>
       ...
       <auth-constraint>
           <role-name><allowed_role></role-name>
       </auth-constraint>
   </security-constraint>

   Example

   <security-constraint>
       ...
       <auth-constraint>
           <role-name>example_role</role-name> 

   1

   
       </auth-constraint>
   </security-constraint>

   1

   Allow only those users with the role example_role to access your application.

2. In the application root directory, recompile your application with the following command:

   $ mvn package

3. Deploy the application.

   $ java -jar simple-oidc-layer-example/target/simple-oidc-layer-example-bootable.jar

   This starts JBoss EAP and deploys the application.

Verification

1. In a browser, navigate to \localhost:8080/simple-oidc-layer-example/secured.

2. Log in with your credentials. For example:

   username: jane_doe
   password: janedoep@$$

   You get the following output:

   Forbidden

   Because you have not assigned the required role to the user "jane_doe," jane_doe can’t log in to your application. Only the users with the required role can log in.

Procedure

1. Log in to the admin console at http://localhost:<port>/auth/. For example, http://localhost:8180/auth/.
2. Click the realm you use to connect with JBoss EAP. For example, example_realm.
3. Click Clients, then click the client-name you configured for JBoss EAP. For example, my_jbeap.
4. Click Roles, then Add Role.
5. Enter a role name, such as example_role, then click Save. This is the role name you configure in JBoss EAP for authorization.
6. Click Users, then View all users.
7. Click an ID to assign the role you created. For example, click the ID for jane_doe.
8. Click Role Mappings. In the Client Roles field, select the client-name you configured for JBoss EAP. For example, my_jbeap.
9. In Available Roles, select a role to assign. For example, example_role. Click Add selected.

Verification

1. In a browser, navigate to the application URL.

2. Log in with your credentials. For example:

   username: jane_doe
   password: janedoep@$$

   You get the following output:

   Secured Servlet
   Current Principal '5cb0c4ca-0477-44c3-bdef-04db04d7e39d'

   Users with the required role can log in to your application.