Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 9. OpenID Connect in JBoss EAP

Use the JBoss EAP native OpenID Connect (OIDC) client to secure your applications through an external OpenID provider. OIDC is an identity layer that enables clients, such as JBoss EAP, to verify a user’s identity based on OpenID provider authentication. For example, you can secure your JBoss EAP applications using Red Hat Single Sign-On as the OpenID provider.

9.1. OpenID Connect configuration in JBoss EAP
Copy link

When you secure your applications using an OpenID provider, you do not need to configure any security domain resources locally. The elytron-oidc-client subsystem provides a native OpenID Connect (OIDC) client in JBoss EAP to connect with OpenID providers. JBoss EAP automatically creates a virtual security domain for your application, based on your OpenID provider configurations.

Important

It is recommended to use the OIDC client with Red Hat Single Sign-On. You can use other OpenID providers if they can be configured to use access tokens that are JSON Web Tokens (JWTs) and can be configured to use the RS256, RS384, RS512, ES256, ES384, or ES512 signature algorithm.

To enable the use of OIDC, you can configure either the elytron-oidc-client subsystem or an application itself. JBoss EAP activates the OIDC authentication as follows:

  • When you deploy an application to JBoss EAP, the elytron-oidc-client subsystem scans the deployment to detect if the OIDC authentication mechanism is required.
  • If the subsystem detects OIDC configuration for the deployment in either the elytron-oidc-client subsystem or the application deployment descriptor, JBoss EAP enables the OIDC authentication mechanism for the application.
  • If the subsystem detects OIDC configuration in both places, the configuration in the elytron-oidc-client subsystem secure-deployment attribute takes precedence over the configuration in the application deployment descriptor.
Note

The keycloak-client-oidc layer to secure your applications with Red Hat Single Sign-On is deprecated in JBoss EAP XP 4.0.0. Use the native OIDC client provided by the elytron-oidc-client subsystem instead.

Deployment configuration

To secure an application with OIDC by using a deployment descriptor, update the application’s deployment configuration as follows:

  • Create a file called oidc.json in the WEB-INF directory with the OIDC configuration information.

    Example oidc.json contents

    {
  "client-id" : "customer-portal",
    1 
    
  "provider-url" : "http://localhost:8180/auth/realms/demo",
    2 
    
  "ssl-required" : "external",
    3 
    
   "credentials" : {
      "secret" : "234234-234234-234234"
    4 
    
   }
}
    Copy to Clipboard Toggle word wrap

    1
    The name to identify the OIDC client with the OpenID provider.
    2
    The OpenID provider URL.
    3
    Require HTTPS for external requests.
    4
    The client secret that was registered with the OpenID provider.
  • Set the auth-method property to OIDC in the application deployment descriptor web.xml file.

Example deployment descriptor update

<login-config>
    <auth-method>OIDC</auth-method>
</login-config>
Copy to Clipboard Toggle word wrap

Subsystem configuration

You can secure applications with OIDC by configuring the elytron-oidc-client subsystem in the following ways:

  • Create a single configuration for multiple deployments if you use the same OpenID provider for each application.
  • Create a different configuration for each deployment if you use different OpenID providers for different applications.

Example XML configuration for a single deployment: 

<subsystem xmlns="urn:wildfly:elytron-oidc-client:1.0">
    <secure-deployment name="DEPLOYMENT_RUNTIME_NAME.war">
1 

        <client-id>customer-portal</client-id>
2 

        <provider-url>http://localhost:8180/auth/realms/demo</provider-url>
3 

        <ssl-required>external</ssl-required>
4 

        <credential name="secret" secret="0aa31d98-e0aa-404c-b6e0-e771dba1e798" />
5 

    </secure-deployment
</subsystem>
Copy to Clipboard Toggle word wrap
1
The deployment runtime name.
2
The name to identify the OIDC client with the OpenID provider.
3
The OpenID provider URL.
4
Require HTTPS for external requests.
5
The client secret that was registered with the OpenID provider.

To secure multiple applications using the same OpenID provider, configure the provider separately, as shown in the example: 

<subsystem xmlns="urn:wildfly:elytron-oidc-client:1.0">
    <provider name="${OpenID_provider_name}">
        <provider-url>http://localhost:8080/auth/realms/demo</provider-url>
        <ssl-required>external</ssl-required>
    </provider>
    <secure-deployment name="customer-portal.war">
1 

        <provider>${OpenID_provider_name}</provider>
        <client-id>customer-portal</client-id>
        <credential name="secret" secret="0aa31d98-e0aa-404c-b6e0-e771dba1e798" />
    </secure-deployment>
    <secure-deployment name="product-portal.war">
2 

        <provider>${OpenID_provider_name}</provider>
        <client-id>product-portal</client-id>
        <credential name="secret" secret="0aa31d98-e0aa-404c-b6e0-e771dba1e798" />
    </secure-deployment>
</subsystem>
Copy to Clipboard Toggle word wrap
1
A deployment: customer-portal.war
2
Another deployment: product-portal.war

9.2. Enabling the elytron-oidc-client subsystem
Copy link

The elytron-oidc-client subsystem is provided in the standalone-microprofile.xml configuration file. To use it, you must start your server with the bin/standalone.sh -c standalone-microprofile.xml command. You can include the elytron-oidc-client subsystem in the standalone.xml configuration by enabling it using the management CLI.

Prerequisites

  • You have installed JBoss EAP XP.

Procedure

  1. Add the elytron-oidc-client extension using the management CLI. 

    /extension=org.wildfly.extension.elytron-oidc-client:add
    Copy to Clipboard Toggle word wrap

  2. Enable the elytron-oidc-client subsystem using the management CLI. 

    /subsystem=elytron-oidc-client:add
    Copy to Clipboard Toggle word wrap

  3. Reload JBoss EAP. 

    reload
    Copy to Clipboard Toggle word wrap

You can now use the elytron-oidc-client subsystem by starting the server normally, with the command bin/standalone.sh

You can use OpenID Connect (OIDC) to delegate authentication to an external OpenID provider. The elytron-oidc-client subsystem provides a native OIDC client in JBoss EAP to connect with external OpenID providers.

To create an application secured with OpenID Connect using Red Hat Single Sign-On, follow these procedures:

Red Hat Single Sign-On is an identity and access management provider for securing web applications with single sign-on (SSO). It supports OpenID Connect (an extension to OAuth 2.0).

Prerequisites

  • You have installed the Red Hat Single Sign-On server. For more information, see Installing the Red Hat Single Sign-On server in the Red Hat Single Sign-On Getting Started Guide.
  • You have created a user in your Red Hat Single Sign-On server instance. For more information, see Creating a user in the Red Hat Single Sign-On Getting Started Guide.

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>
    Copy to Clipboard Toggle word wrap

    Example

    $ /home/servers/rh-sso-7.4/bin/standalone.sh -Djboss.socket.binding.port-offset=100
    Copy to Clipboard Toggle word wrap

  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
}
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap
  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/*

Create a Maven project with the required dependencies and the directory structure for creating a secure application.

Prerequisites

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
    Copy to Clipboard Toggle word wrap

    Example

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

  2. Navigate to the application root directory:

    Syntax

    $ cd <name-of-your-application>
    Copy to Clipboard Toggle word wrap

    Example

    $ cd simple-oidc-example
    Copy to Clipboard Toggle word wrap

  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>
      Copy to Clipboard Toggle word wrap

    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>
      Copy to Clipboard Toggle word wrap

    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>
      Copy to Clipboard Toggle word wrap

Verification

  • In the application root directory, enter the following command: 

    $ mvn install
    Copy to Clipboard Toggle word wrap

    You get an output similar to the following: 

    [INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1.440 s
[INFO] Finished at: 2021-12-27T14:45:12+05:30
[INFO] ------------------------------------------------------------------------
    Copy to Clipboard Toggle word wrap

You can now create your secure application.

You can secure an application by either updating its deployment configuration or by configuring the elytron-oidc-client subsystem. The following example demonstrates creating a servlet that prints a logged-in user’s Principal. For an existing application, only those steps that are related to updating the deployment configuration or the elytron-oidc-client subsystem are required.

In this example, the value of the Principal comes from the ID token from the OpenID provider. By default, the Principal is the value of the "sub" claim from the token. You can specify which claim value from the ID token to use as the Principal in one of the following:

  • The elytron-oidc-client subsystem attribute principal-attribute.
  • The oidc.json file.

<application_root> in the procedure denotes the pom.xml file directory. The pom.xml file contains your application’s Maven configuration.

Prerequisites

Procedure

  1. Create a directory to store the Java files.

    Syntax

    $ mkdir -p <application_root>/src/main/java/com/example/oidc
    Copy to Clipboard Toggle word wrap

    Example

    $ mkdir -p simple-oidc-example/src/main/java/com/example/oidc
    Copy to Clipboard Toggle word wrap

  2. Navigate to the new directory.

    Syntax

    $ cd <application_root>/src/main/java/com/example/oidc
    Copy to Clipboard Toggle word wrap

    Example

    $ cd simple-oidc-example/src/main/java/com/example/oidc
    Copy to Clipboard Toggle word wrap

  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>");
        }
    }

}
    Copy to Clipboard Toggle word wrap

  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>
    Copy to Clipboard Toggle word wrap

  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
}
        Copy to Clipboard Toggle word wrap

      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>
        Copy to Clipboard Toggle word wrap

    • 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)
        Copy to Clipboard Toggle word wrap

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

    $ mvn package
    Copy to Clipboard Toggle word wrap

  7. Deploy the application. 

    $ mvn wildfly:deploy
    Copy to Clipboard Toggle word wrap

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@$$
    Copy to Clipboard Toggle word wrap

    You get the following output: 

    Secured Servlet
Current Principal '5cb0c4ca-0477-44c3-bdef-04db04d7e39d'
    Copy to Clipboard Toggle word wrap

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

You can restrict access to all, or parts, of your application based on user roles. For example, you can let users with the "public" role have access to the parts of your application that aren’t sensitive, and give users with the "admin" role access to those parts that are.

Prerequisites

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>
    Copy to Clipboard Toggle word wrap

    Example

    <security-constraint>
    ...
    <auth-constraint>
        <role-name>example_role</role-name>
    1 
    
    </auth-constraint>
</security-constraint>
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

  3. Deploy the application. 

    $ mvn wildfly:deploy
    Copy to Clipboard Toggle word wrap

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@$$
    Copy to Clipboard Toggle word wrap

    You get the following output: 

    Forbidden
    Copy to Clipboard Toggle word wrap

    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.

To assign users the required roles, see Creating and assigning roles to users in Red Hat Single Sign-On.

Red Hat Single Sign-On is an identity and access management provider for securing your web applications with single sign-on (SSO). You can define users and assign roles in Red Hat Single Sign-On.

Prerequisites

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@$$
    Copy to Clipboard Toggle word wrap

    You get the following output: 

    Secured Servlet
Current Principal '5cb0c4ca-0477-44c3-bdef-04db04d7e39d'
    Copy to Clipboard Toggle word wrap

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

You can use OpenID Connect (OIDC) to delegate authentication to an external OpenID provider. The elytron-oidc-client galleon layer provides a native OIDC client in JBoss EAP bootable jar applications to connect with external OpenID providers.

To create an application secured with OpenID Connect using Red Hat Single Sign-On, follow these procedures:

Red Hat Single Sign-On is an identity and access management provider for securing web applications with single sign-on (SSO). It supports OpenID Connect (an extension to OAuth 2.0).

Prerequisites

  • You have installed the Red Hat Single Sign-On server. For more information, see Installing the Red Hat Single Sign-On server in the Red Hat Single Sign-On Getting Started Guide.
  • You have created a user in your Red Hat Single Sign-On server instance. For more information, see Creating a user in the Red Hat Single Sign-On Getting Started Guide.

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>
    Copy to Clipboard Toggle word wrap

    Example

    $ /home/servers/rh-sso-7.4/bin/standalone.sh -Djboss.socket.binding.port-offset=100
    Copy to Clipboard Toggle word wrap

  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
}
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap
  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-layer-example/secured/*

Create a Maven project with the required dependencies and the directory structure for creating a bootable jar application that uses OpenID Connect. The elytron-oidc-client galleon layer provides a native OpenID Connect (OIDC) client to connect with OpenID providers.

Prerequisites

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
    Copy to Clipboard Toggle word wrap

    Example

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

  2. Navigate to the application root directory.

    Syntax

    $ cd <name-of-your-application>
    Copy to Clipboard Toggle word wrap

    Example

    $ cd simple-oidc-layer-example
    Copy to Clipboard Toggle word wrap

  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>
      Copy to Clipboard Toggle word wrap

    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>
      Copy to Clipboard Toggle word wrap

    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>
      Copy to Clipboard Toggle word wrap

    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>
      Copy to Clipboard Toggle word wrap

    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>
      Copy to Clipboard Toggle word wrap
      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>
      Copy to Clipboard Toggle word wrap

Verification

  • In the application root directory, enter the following command: 

    $ mvn install
    Copy to Clipboard Toggle word wrap

    You get an output similar to the following: 

    ...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 19.157 s
[INFO] Finished at: 2022-03-10T09:38:21+05:30
[INFO] ------------------------------------------------------------------------
    Copy to Clipboard Toggle word wrap

You can now create a bootable jar application that uses OpenID Connect

The following example demonstrates creating a servlet that prints a logged-in user’s Principal. For an existing application, only those steps that are related to updating the deployment configuration are required.

In this example, the value of the Principal comes from the ID token from the OpenID provider. By default, the Principal is the value of the "sub" claim from the token. You can specify which claim value from the ID token to use as the Principal in one of the following:

  • The elytron-oidc-client subsystem attribute principal-attribute.
  • The oidc.json file.

<application_root> in the procedure denotes the pom.xml file directory. The pom.xml file contains your application’s Maven configuration.

Prerequisites

Procedure

  1. Create a directory to store the Java files.

    Syntax

    $ mkdir -p <application_root>/src/main/java/com/example/oidc
    Copy to Clipboard Toggle word wrap

    Example

    $ mkdir -p simple-oidc-layer-example/src/main/java/com/example/oidc
    Copy to Clipboard Toggle word wrap

  2. Navigate to the new directory.

    Syntax

    $ cd <application_root>/src/main/java/com/example/oidc
    Copy to Clipboard Toggle word wrap

    Example

    $ cd simple-oidc-layer-example/src/main/java/com/example/oidc
    Copy to Clipboard Toggle word wrap

  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>");
        }
    }

}
    Copy to Clipboard Toggle word wrap

  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>
    Copy to Clipboard Toggle word wrap

  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
}
        Copy to Clipboard Toggle word wrap

      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>
        Copy to Clipboard Toggle word wrap

    • 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>
        Copy to Clipboard Toggle word wrap

        Example

        $ mkdir simple-oidc-layer-example/scripts/
        Copy to Clipboard Toggle word wrap

        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)
        Copy to Clipboard Toggle word wrap

        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>
        Copy to Clipboard Toggle word wrap

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

    $ mvn package
    Copy to Clipboard Toggle word wrap

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

    Syntax

    $ java -jar <application_root>/target/simple-oidc-layer-example-bootable.jar
    Copy to Clipboard Toggle word wrap

    Example

    $ java -jar simple-oidc-layer-example/target/simple-oidc-layer-example-bootable.jar
    Copy to Clipboard Toggle word wrap

    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@$$
    Copy to Clipboard Toggle word wrap

    You get the following output: 

    Secured Servlet
Current Principal '5cb0c4ca-0477-44c3-bdef-04db04d7e39d'
    Copy to Clipboard Toggle word wrap

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

You can restrict access to all, or parts, of your application based on user roles. For example, you can let users with the "public" role have access to the parts of your application that aren’t sensitive, and give users with the "admin" role access to those parts that are.

Prerequisites

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>
    Copy to Clipboard Toggle word wrap

    Example

    <security-constraint>
    ...
    <auth-constraint>
        <role-name>example_role</role-name>
    1 
    
    </auth-constraint>
</security-constraint>
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

  3. Deploy the application. 

    $ java -jar simple-oidc-layer-example/target/simple-oidc-layer-example-bootable.jar
    Copy to Clipboard Toggle word wrap

    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@$$
    Copy to Clipboard Toggle word wrap

    You get the following output: 

    Forbidden
    Copy to Clipboard Toggle word wrap

    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.

To assign users the required roles, see Creating and assigning roles to users in Red Hat Single Sign-On.

Red Hat Single Sign-On is an identity and access management provider for securing your web applications with single sign-on (SSO). You can define users and assign roles in Red Hat Single Sign-On.

Prerequisites

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@$$
    Copy to Clipboard Toggle word wrap

    You get the following output: 

    Secured Servlet
Current Principal '5cb0c4ca-0477-44c3-bdef-04db04d7e39d'
    Copy to Clipboard Toggle word wrap

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

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat