Chapter 2. Elytron Subsystem

2.1. Configure Authentication with a Filesystem-Based Identity Store

  1. Configure a filesystem-realm in JBoss EAP: 

    /subsystem=elytron/filesystem-realm=exampleFsRealm:add(path=fs-realm-users,relative-to=jboss.server.config.dir)

    If your directory is located outside of jboss.server.config.dir, then you need to change the path and relative-to values appropriately.

  2. Add a user:

    When using the filesystem-realm, you can add users using the management CLI. 

    /subsystem=elytron/filesystem-realm=exampleFsRealm:add-identity(identity=user1)
/subsystem=elytron/filesystem-realm=exampleFsRealm:set-password(identity=user1, clear={password="password123"})
/subsystem=elytron/filesystem-realm=exampleFsRealm:add-identity-attribute(identity=user1, name=Roles, value=["Admin","Guest"])

  3. Add a simple-role-decoder: 

    /subsystem=elytron/simple-role-decoder=from-roles-attribute:add(attribute=Roles)

    This simple-role-decoder decodes a principal’s roles from the Roles attribute. You can change this value if your roles are in a different attribute.

  4. Configure a security-domain: 

    /subsystem=elytron/security-domain=exampleFsSD:add(realms=[{realm=exampleFsRealm,role-decoder=from-roles-attribute}],default-realm=exampleFsRealm,permission-mapper=default-permission-mapper)

  5. Configure an application-security-domain in the undertow subsystem: 

    /subsystem=undertow/application-security-domain=exampleApplicationDomain:add(security-domain=exampleFsSD)
    Note

    An application-security-domain in the undertow subsystem can be configured using the management console by navigating to Configuration → Subsystems → Web (Undertow) → Application Security Domain.

  6. Configure your application’s web.xml and jboss-web.xml:

    Your application’s web.xml and jboss-web.xml must be updated to use the application-security-domain you configured in JBoss EAP. An example of this is available in Configure Web Applications to Use Elytron or Legacy Security for Authentication.

Your application is now using a file system-based identity store for authentication.

2.2. Configure Authentication with a Properties File-Based Identity Store

  1. Create properties files:

    You must create two properties files: one that maps users to passwords and another that maps users to roles. Usually, these files are located in the jboss.server.config.dir directory and follow the naming convention *-users.properties and *-roles.properties, but other locations and names can be used. The *-users.properties file must also contain a reference to the properties-realm, which you will create in the next step: #$REALM_NAME=YOUR_PROPERTIES_REALM_NAME$

    Example user to password file: example-users.properties

    #$REALM_NAME=examplePropRealm$
user1=password123
user2=password123

    Example user to roles file: example-roles.properties

    user1=Admin
user2=Guest

  2. Configure a properties-realm in JBoss EAP: 

    /subsystem=elytron/properties-realm=examplePropRealm:add(groups-attribute=groups,groups-properties={path=example-roles.properties,relative-to=jboss.server.config.dir},users-properties={path=example-users.properties,relative-to=jboss.server.config.dir,plain-text=true})

    The name of the properties-realm is examplePropRealm, which is used in the previous step in the example-users.properties file. Also, if your properties files are located outside of jboss.server.config.dir, then you must change the path and relative-to values appropriately.

  3. Configure a security-domain: 

    /subsystem=elytron/security-domain=exampleSD:add(realms=[{realm=examplePropRealm,role-decoder=groups-to-roles}],default-realm=examplePropRealm,permission-mapper=default-permission-mapper)

  4. Configure an application-security-domain in the undertow subsystem: 

    /subsystem=undertow/application-security-domain=exampleApplicationDomain:add(security-domain=exampleSD)
    Note

    An application-security-domain in the undertow subsystem can be configured using the management console by navigating to Configuration → Subsystems → Web (Undertow) → Application Security Domain.

  5. Configure your application’s web.xml and jboss-web.xml:

    Your application’s web.xml and jboss-web.xml must be updated to use the application-security-domain you configured in JBoss EAP. An example of this is available in Configure Web Applications to Use Elytron or Legacy Security for Authentication.

Your application is now using a properties file-based identity store for authentication.

Important

The properties files are only read when the server starts. Any users added after server startup, either manually or by using an add-user script, requires a server reload. This reload is accomplished by running the reload command from the management CLI. 

reload

2.3. Configure Authentication with a Database-Based Identity Store

  1. Determine your database format for usernames, passwords, and roles:

    To set up authentication using a database for an identity store, you need to determine how your usernames, passwords, and roles are stored in that database. In this example, we are using a single table with the following sample data:

    usernamepasswordroles

    user1

    password123

    Admin

    user2

    password123

    Guest

  2. Configure a datasource:

    To connect to a database from JBoss EAP, you must have the appropriate database driver deployed, as well as a datasource configured. This example shows deploying the driver for PostgreSQL and configuring a datasource in JBoss EAP: 

    deploy /path/to/postgresql-9.4.1210.jar

data-source add --name=examplePostgresDS --jndi-name=java:jboss/examplePostgresDS --driver-name=postgresql-9.4.1210.jar  --connection-url=jdbc:postgresql://localhost:5432/postgresdb --user-name=postgresAdmin --password=mysecretpassword

  3. Configure a jdbc-realm in JBoss EAP: 

    /subsystem=elytron/jdbc-realm=exampleDbRealm:add(principal-query=[{sql="SELECT password,roles FROM eap_users WHERE username=?",data-source=examplePostgresDS,clear-password-mapper={password-index=1},attribute-mapping=[{index=2,to=groups}]}])
    Note

    The above example shows how to obtain passwords and roles from a single principal-query. You can also create additional principal-query with attribute-mapping attributes if you require multiple queries to obtain roles or additional authentication or authorization information.

    For a list of supported password mappers, see Password Mappers.

  4. Configure a security-domain: 

    /subsystem=elytron/security-domain=exampleDbSD:add(realms=[{realm=exampleDbRealm,role-decoder=groups-to-roles}],default-realm=exampleDbRealm,permission-mapper=default-permission-mapper)

  5. Configure an application-security-domain in the undertow subsystem: 

    /subsystem=undertow/application-security-domain=exampleApplicationDomain:add(security-domain=exampleDbSD)
    Note

    An application-security-domain in the undertow subsystem can be configured using the management console by navigating to Configuration → Subsystems → Web (Undertow) → Application Security Domain.

  6. Configure your application’s web.xml and jboss-web.xml:

    Your application’s web.xml and jboss-web.xml must be updated to use the application-security-domain you configured in JBoss EAP. An example of this is available in Configure Web Applications to Use Elytron or Legacy Security for Authentication.

2.4. Configure Authentication with an LDAP-Based Identity Store

  1. Determine your LDAP format for usernames, passwords, and roles:

    To set up authentication using an LDAP server for an identity store, you need to determine how your usernames, passwords, and roles are stored. In this example, we are using the following structure: 

    dn: dc=wildfly,dc=org
dc: wildfly
objectClass: top
objectClass: domain

dn: ou=Users,dc=wildfly,dc=org
objectClass: organizationalUnit
objectClass: top
ou: Users

dn: uid=jsmith,ou=Users,dc=wildfly,dc=org
objectClass: top
objectClass: person
objectClass: inetOrgPerson
cn: John Smith
sn: smith
uid: jsmith
userPassword: password123

dn: ou=Roles,dc=wildfly,dc=org
objectclass: top
objectclass: organizationalUnit
ou: Roles

dn: cn=Admin,ou=Roles,dc=wildfly,dc=org
objectClass: top
objectClass: groupOfNames
cn: Admin
member: uid=jsmith,ou=Users,dc=wildfly,dc=org

  2. Configure a dir-context:

    To connect to the LDAP server from JBoss EAP, you need to configure a dir-context that provides the URL as well as the principal used to connect to the server. 

    /subsystem=elytron/dir-context=exampleDC:add(url="ldap://127.0.0.1:10389",principal="uid=admin,ou=system",credential-reference={clear-text="secret"})
    Note

    It is not possible to use a Jakarta Management ObjectName to decrypt the LDAP credentials. Instead, credentials can be secured by using a Credential Store as discussed in How to Configure Server Security for JBoss EAP.

  3. Configure an ldap-realm in JBoss EAP: 

    /subsystem=elytron/ldap-realm=exampleLR:add(dir-context=exampleDC,identity-mapping={search-base-dn="ou=Users,dc=wildfly,dc=org",rdn-identifier="uid",user-password-mapper={from="userPassword"},attribute-mapping=[{filter-base-dn="ou=Roles,dc=wildfly,dc=org",filter="(&(objectClass=groupOfNames)(member={0}))",from="cn",to="Roles"}]})
    Warning

    If any referenced LDAP servers contain a loop in referrals, it can result in a java.lang.OutOfMemoryError error on the JBoss EAP server.

  4. Add a simple-role-decoder: 

    /subsystem=elytron/simple-role-decoder=from-roles-attribute:add(attribute=Roles)

  5. Configure a security-domain: 

    /subsystem=elytron/security-domain=exampleLdapSD:add(realms=[{realm=exampleLR,role-decoder=from-roles-attribute}],default-realm=exampleLR,permission-mapper=default-permission-mapper)

  6. Configure an application-security-domain in the undertow subsystem: 

    /subsystem=undertow/application-security-domain=exampleApplicationDomain:add(security-domain=exampleLdapSD)
    Note

    An application-security-domain in the undertow subsystem can be configured using the management console by navigating to Configuration → Subsystems → Web (Undertow) → Application Security Domain.

  7. Configure your application’s web.xml and jboss-web.xml:

    Your application’s web.xml and jboss-web.xml must be updated to use the application-security-domain you configured in JBoss EAP. An example of this is available in Configure Web Applications to Use Elytron or Legacy Security for Authentication.

Important

In cases where the elytron subsystem uses an LDAP server to perform authentication, JBoss EAP will return a 500, or internal server error, error code if that LDAP server is unreachable. This behavior differs from previous versions of JBoss EAP using the legacy security subsystem, which returned a 401, or unauthorized, error code under the same conditions.

2.5. Configure Authentication with Certificates

Important

Before you can set up certificate-based authentication, you must have two-way SSL configured. More details on configuring two-way SSL can be found in the Enable Two-way SSL/TLS for Applications using the Elytron Subsystem section of the How to Configure Server Security guide.

  1. Configure a key-store-realm. 

    /subsystem=elytron/key-store-realm=ksRealm:add(key-store=twoWayTS)

    You must configure this realm with a truststore that contains the client’s certificate. The authentication process uses the same certificate presented by the client during the two-way SSL handshake.

  2. Create a decoder.

    You need to create a x500-attribute-principal-decoder to decode the principal you get from your certificate. The below example will decode the principal based on the first CN value. 

    /subsystem=elytron/x500-attribute-principal-decoder=CNDecoder:add(oid="2.5.4.3",maximum-segments=1)

    For example, if the full DN was CN=client,CN=client-certificate,DC=example,DC=jboss,DC=org, CNDecoder would decode the principal as client. This decoded principal is used as the alias value to lookup a certificate in the truststore configured in ksRealm.

    Important

    The decoded principal MUST be the alias value you set in your server’s truststore for the client’s certificate.

  3. Add a constant-role-mapper for assigning roles.

    This is example uses a constant-role-mapper to assign roles to a principal from ksRealm, but you can also use other approaches. 

    /subsystem=elytron/constant-role-mapper=constantClientCertRole:add(roles=[Admin,Guest])

  4. Configure a security-domain. 

    /subsystem=elytron/security-domain=exampleCertSD:add(realms=[{realm=ksRealm}],default-realm=ksRealm,permission-mapper=default-permission-mapper,principal-decoder=CNDecoder,role-mapper=constantClientCertRole)

  5. Configure an application-security-domain in the undertow subsystem. 

    /subsystem=undertow/application-security-domain=exampleApplicationDomain:add(security-domain=exampleCertSD)
    Note

    An application-security-domain in the undertow subsystem can be configured using the management console by navigating to Configuration → Subsystems → Web (Undertow) → Application Security Domain.

  6. Update server-ssl-context. 

    /subsystem=elytron/server-ssl-context=twoWaySSC:write-attribute(name=security-domain,value=exampleCertSD)
/subsystem=elytron/server-ssl-context=twoWaySSC:write-attribute(name=authentication-optional, value=true)
reload

  7. Configure your application’s web.xml and jboss-web.xml.

    Your application’s web.xml and jboss-web.xml must be updated to use the application-security-domain you configured in JBoss EAP. An example of this is available in Configure Web Applications to Use Elytron or Legacy Security for Authentication.

    In addition, you need to update your web.xml to use CLIENT-CERT as its authentication method. 

    <login-config>
  <auth-method>CLIENT-CERT</auth-method>
  <realm-name>exampleApplicationDomain</realm-name>
</login-config>

2.6. Configure Authentication and Authorization Using Multiple Identity Stores

If you store attributes of an identity across different identity stores, then use an aggregate-realm to load the identity attributes into a single security realm for authentication and authorization.

2.6.1. Aggregate Realm in Elytron

With an aggregate-realm, you can use one security realm for authentication and another security realm, or an aggregation of multiple security realms, for authorization in Elytron. For example, you can configure an aggregate realm to use a properties realm for authentication and a JDBC realm for authorization.

In an aggregate realm configured to aggregate multiple authorization realms, an identity is created as follows:

  • Attribute values from each security realm configured for authorization are loaded.
  • If an attribute is defined in more than one authorization realm, the value of the first occurrence of the attribute is used.

The following example illustrates how an identity is created when multiple authorization realms contain definitions for the same identity attribute.

Example

Aggregate realm configuration: 

authentication-realm=properties-realm,
authorization-realms=[jdbc-realm,ldap-realm]

  • Attribute values obtained from the JDBC realm: 

    e-mail: user@example.com
groups: Supervisor, User

  • Attribute values obtained from the ldap realm: 

    e-mail: administrator@example.com
phone: 0000 0000 0000

Resulting identity obtained from the aggregate realm: 

e-mail: user@example.com
groups: Supervisor, User
phone: 0000 0000 0000

In the example, the attribute e-mail is defined in both the authorization realms. The value defined in JDBC realm gets used for the attribute e-mail in the resulting aggregate realm because the aggregate realm was configured to aggregate the authorization realms as: authorization-realms=[jdbc-realm,ldap-realm].

2.6.2. Configuring Authentication and Authorization Using an Aggregate Realm

To configure authentication and authorization using an aggregate realm, create an aggregate realm, and configure a security domain and an application security domain to use the aggregate realm.

Prerequisites

  • The security realms to be aggregated are configured.

    For information about configuring security realms, see Elytron Subsystem in the How to Configure Identity Management guide.

  • A role decoder to be used in the security domain is configured.

    For information about role decoders, see Create an Elytron Role Decoder in the How to Configure Server Security guide.

Procedure

  1. Create an aggregate realm:

    • To create an aggregate realm with one authorization realm: 

      /subsystem=elytron/aggregate-realm=exampleAggregateRealm:add(authentication-realm=__SECURITY_REALM_FOR_AUTHENTICATION__, authorization-realm=__SECURITY_REALM_FOR_AUTHORIZATION__)

    • To create an aggregate realm with multiple authorization realms: 

      /subsystem=elytron/aggregate-realm=exampleAggregateRealm:add(authentication-realm=__SECURITY_REALM_FOR_AUTHENTICATION__, authorization-realms=[__SECURITY_REALM_FOR_AUTHORIZATION_1__,__SECURITY_REALM_FOR_AUTHORIZATION_2__,...,__SECURITY_REALM_FOR_AUTHORIZATION_N__])

  2. Configure a security-domain: 

    /subsystem=elytron/security-domain=exampleAggregateRealmSD:add(realms=[{realm=exampleAggregateRealm,role-decoder=__ROLE-DECODER__}],default-realm=exampleAggregateRealm,permission-mapper=default-permission-mapper)

  3. Configure an application-security-domain in the undertow subsystem: 

    /subsystem=undertow/application-security-domain=exampleAggregareRealmApplicationDomain:add(security-domain=exampleAggregateRealmSD)

  4. Configure your application’s web.xml and jboss-web.xml:

    Your application’s web.xml and jboss-web.xml must be updated to use the application-security-domain you configured in JBoss EAP. An example of this is available in Configure Web Applications to Use Elytron or Legacy Security for Authentication.

2.6.3. Example Aggregate Realms

Example aggregate realm with a single authorizarion realm

In this example, a properties-realm is used for authentication and a jdbc-realm is used for authorization.

You must preconfigure the following realms:

  • properties-realm named examplPropertiesRealm
  • jdbc-realm named exampleJdbcRealm

Issuing the following command creates an aggregate realm: 

/subsystem=elytron/aggregate-realm:exampleSimpleAggregateRealm:add(authentication-realm=examplPropertiesRealm,authorization-realm=exampleJdbcRealm)

Example aggregate realm with two authorization realms

In this example, properties-realm is used for authentication and an aggregation of ldap-realm and jdbc-realm is used for authorization.

You must preconfigure the following realms:

  • properties-realm named examplPropertiesRealm
  • jdbc-realm named exampleJdbcRealm
  • ldap-realm named exampleLdapRealm

Issuing the following command creates an aggregate realm: 

/subsystem=elytron/aggregate-realm:exampleSimpleAggregateRealm:add(authentication-realm=examplPropertiesRealm,authorization-realms=[exampleJdbcRealm,exampleLdapRealm])

2.7. Override an Application’s Authentication Configuration

You can override the authentication configuration of an application with one configured in JBoss EAP. To do this, use the override-deployment-configuration property in the application-security-domain section of the undertow subsystem: 

/subsystem=undertow/application-security-domain=exampleApplicationDomain:write-attribute(name=override-deployment-config,value=true)
Note

An application-security-domain in the undertow subsystem can be configured using the management console by navigating to Configuration → Subsystems → Web (Undertow) → Application Security Domain.

For example, an application is configured to use FORM authentication with the exampleApplicationDomain in its jboss-web.xml.

Example jboss-web.xml

<login-config>
  <auth-method>FORM</auth-method>
  <realm-name>exampleApplicationDomain</realm-name>
</login-config>

By enabling override-deployment-configuration, you can create a new http-authentication-factory that specifies a different authentication mechanism, such as BASIC or DIGEST.

Example http-authentication-factory

/subsystem=elytron/http-authentication-factory=exampleHttpAuth:read-resource()
{
    "outcome" => "success",
    "result" => {
        "http-server-mechanism-factory" => "global",
        "mechanism-configurations" => [{
            "mechanism-name" => "BASIC",
            "mechanism-realm-configurations" => [{"realm-name" => "exampleApplicationDomain"}]
        }],
        "security-domain" => "exampleSD"
    }
}

This will override the authentication mechanism defined in the application’s jboss-web.xml and attempt to authenticate a user using BASIC instead of FORM.

2.8. Set Up Caching for Security Realms

Elytron provides a caching-realm which allows you to cache the results of a credential lookup from a security realm. For example, you could use this to configure a cache for credentials coming from LDAP or a database to increase performance for frequently queried users.

The caching-realm caches the PasswordCredential credential using a LRU or Least Recently Used caching strategy, in which the least accessed entries are discarded when maximum number of entries is reached.

You can use a caching-realm with the following security realms:

  • filesystem-realm
  • jdbc-realm
  • ldap-realm
  • a custom security realm

If you make changes to your credential source outside of JBoss EAP, those changes are only propagated to a JBoss EAP caching realm if the underlying security realm supports listening. In particular, an ldap-realm supports listening, however filtered attributes, such as roles, inside the ldap-realm do not.

To ensure that your caching realm has a correct cache of user data, it is recommended that you modify your user attributes through the caching realm rather than at your credential source. Alternatively, you can clear the cache.

Important

Making user changes through a caching realm is provided as Technology Preview only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

To configure and use a caching-realm:

  1. Create an existing security realm.

    You need an existing security realm to use with a caching-realm. For example, you could create a filesystem-realm similar to the steps in Configure Authentication with a Filesystem-Based Identity Store.

    Example filesystem-realm

    /subsystem=elytron/filesystem-realm=exampleFsRealm:add(path=fs-realm-users, relative-to=jboss.server.config.dir)

/subsystem=elytron/filesystem-realm=exampleFsRealm:add-identity(identity=user1)

/subsystem=elytron/filesystem-realm=exampleFsRealm:set-password(identity=user1, clear={password="password123"})

/subsystem=elytron/filesystem-realm=exampleFsRealm:add-identity-attribute(identity=user1,name=Roles,value=["Admin","Guest"])

/subsystem=elytron/simple-role-decoder=from-roles-attribute:add(attribute=Roles)

  2. Create a caching-realm.

    Once you have an existing realm you want to cache, create a caching-realm that references it.

    Example caching-realm that Uses exampleFsRealm

    /subsystem=elytron/caching-realm=exampleCacheRealm:add(realm=exampleFsRealm)

  3. Use the caching-realm.

    After you create the caching-realm, you can then use it in your security configuration just as you would any other security realm. For example, you could use it in the same place you would use a filesystem-realm in Configure Authentication with a Filesystem-Based Identity Store.

    Example Configuration Using the caching-realm

    /subsystem=elytron/security-domain=exampleFsSD:add(realms=[{realm=exampleCacheRealm, role-decoder=from-roles-attribute}], default-realm=exampleCacheRealm, permission-mapper=default-permission-mapper)

/subsystem=elytron/http-authentication-factory=example-fs-http-auth:add(http-server-mechanism-factory=global, security-domain=exampleFsSD, mechanism-configurations=[{mechanism-name=BASIC, mechanism-realm-configurations=[{realm-name=exampleApplicationDomain}]}])

You can control the cache size as well as item expiration by using maximum-entries and maximum-age attributes of the caching-realm. For more details on those attributes, see the Elytron Subsystem Components Reference section in How to Configure Server Security.

Clear a caching-realm Cache

You can clear an existing cache by using the clear-cache command. Clearing a cache forces it to repopulate using the latest data from the security realm. 

/subsystem=elytron/caching-realm=exampleCacheRealm:clear-cache

2.9. Configure Applications to use Container-managed Single Sign-on

You can configure JBoss EAP to use container-managed single sign-on for applications using the Elytron FORM authentication method. This allows users to authenticate once and access other resources secured by the FORM authentication method without having to reauthenticate.

The related single sign-on session is invalidated when:

  • there are no active local sessions left.
  • logging out from an application.
Important

You can use single sign-on across applications deployed on different JBoss EAP instances as long as these instances are in a cluster.

  1. Create a key-store.

    A key-store is necessary in order to configure a secure communication channel between the different servers participating in the SSO. This channel is used to exchange messages about events that occur when single sign-on sessions are created or destroyed, during log in and log out respectively.

    To create a key-store in the elytron subsystem, first create a Java KeyStore as follows: 

    keytool -genkeypair -alias localhost -keyalg RSA -keysize 1024 -validity 365 -keystore keystore.jks -dname "CN=localhost" -keypass secret -storepass secret

    Once the keystore.jks file is created, execute the following management CLI command to create a key-store definition in Elytron: 

    /subsystem=elytron/key-store=example-keystore:add(path=keystore.jks, relative-to=jboss.server.config.dir, credential-reference={clear-text=secret}, type=JKS)

  2. Add the security realm.

    Create a FileSystem realm, an identity store where users are stored in the local file system, using the following management CLI command: 

    /subsystem=elytron/filesystem-realm=example-realm:add(path=/tmp/example-realm)

  3. Use the following management CLI command to create a security-domain: 

    /subsystem=elytron/security-domain=example-domain:add(default-realm=example-realm,permission-mapper=default-permission-mapper,realms=[{realm=example-realm,role-decoder=groups-to-roles}]
    Note

    Applications using SSO should use HTTP FORM authentication as they usually need to provide a login page for the users.

  4. Create an application security domain in the undertow subsystem.

    Note

    If you already have a application-security-domain defined in the undertow subsystem and just want to use it to enable single sign-on to your applications, you can skip this step. 

    /subsystem=undertow/application-security-domain=other:add(security-domain=example-domain)
    Note

    By default, if your application does not define any specific security-domain in the jboss-web.xml file, the application server will choose one with a name other.

  5. Update the undertow subsystem to enable single sign-on and use the keystore.

    Single sign-on is enabled to a specific application-security-domain definition in the undertow subsystem. It is important that the servers you are using to deploy the applications are using the same configuration.

    To enable single sign-on, just change an existing application-security-domain in the undertow subsystem as follows: 

    /subsystem=undertow/application-security-domain=other/setting=single-sign-on:add(key-store=example-keystore, key-alias=localhost, domain=localhost, credential-reference={clear-text=secret})
    Note

    An application-security-domain in the undertow subsystem can be configured using the management console by navigating to Configuration → Subsystems → Web (Undertow) → Application Security Domain.

    For more information on the SSO attributes and their definitions, see Reference for Single Sign-on Attributes.

  6. Configure your application’s web.xml and jboss-web.xml files.

    Your application’s web.xml and jboss-web.xml must be updated to use the application-security-domain you configured in JBoss EAP. An example of this is available in Configure Web Applications to Use Elytron or Legacy Security for Authentication.

JBoss EAP provides out-of-the-box support for clustered and non-clustered SSO using the undertow and infinispan subsystems.

2.10. Configure authentication and authorization with bearer tokens

2.10.1. Bearer token authentication

You can use BEARER_TOKEN authentication mechanism to authorize HTTP requests sent to your application. After a client, such as a web browser, sends an HTTP request to your application, the BEARER_TOKEN mechanism verifies the presence of a bearer token in the Authorization HTTP header of the request.

Elytron supports authentication by using bearer tokens in JWT format, such as OpenID Connect ID tokens, or by using opaque tokens issued by the OAuth2 compliant authorization server. See the additional resources section.

The following example shows that the Authorization HTTP header contains the mF_9.B5f-4.1JqM bearer token: 

GET /resource HTTP/1.1
Host: server.example.com
Authorization: Bearer mF_9.B5f-4.1JqM

The BEARER_TOKEN mechanism can now extract the bearer token string and pass it to the token-realm implementation for validation. If the implementation successfully validates the bearer token, Elytron creates a security context based on the information represented by the token. The application can use this security context to obtain information about the requester. It can then decide whether to fulfill the request by providing the requester access to the HTTP resource.

The BEARER_TOKEN mechanism returns a 401 HTTP status code if the requester does not provide a bearer token. For example: 

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="example"

The BEARER_TOKEN mechanism returns a 403 HTTP status code if a requester is not authorized to access a resource. 

HTTP/1.1 403 Forbidden

Additional resources

2.10.2. Configuring JSON Web Tokens (JWTs) authentication

You can enable support for JWTs by specifying a token-realm in the elytron subsystem.

Within the token-realm, you can specify attributes and a jwt token validator. Elytron completes the following checks:

  • Automatic expiration checks on the values specified in the exp claim and nbf claim.

  • Optional: Signature checks based on a public key that is provided by one of the following methods:

    • Using a public-key or a certificate attribute.
    • Using a key map with named public keys.
    • Using the client-ssl-context attribute to retrieve a remote JSON Web Key (JWK) set from the URL specified in jku claim.
  • Optional: Checks on a JWT to ensure it contains only supported values in iss and aud claims. You can use issuer and audience attributes to perform these checks.

The following example shows token-realm as the security realm and principal-claim as the attribute. The principal-claim attribute defines the name of a claim that elytron uses to obtain a principal’s name. The jwt element specifies that the token must be validated as a JWT.

Example of a configured token-realm

<token-realm name="${token_realm_name}" principal-claim="${principal_claim_key}">
    <jwt issuer="${issuer_name}"
         audience="${audience_name}"
         <public-key="${public_key_in_PEM_format}"/>
 </token-realm>

You can define a key map for your token-realm. You can then use different key pairs for signature verification and easily rotate these key pairs. Elytron takes a kid claim from the token and uses the corresponding public key for verification.

  • If a kid claim is not present in JWT, the token-realm uses the value specified in the public-key attribute of jwt to verify the signature.
  • If a kid claim is not present in JWT and you have not configured the public-key then the token-realm invalidates the token.

Example of a configured key map for a token-realm.

<token-realm name="${token_realm_name}" principal-claim="${principal_claim_key}">
    <jwt issuer="${issuer_name}" audience="${audience_name}">
        <key kid="${key_ID_from_kid_claim}" public-key="${public_key_in_PEM_format}"/>
        <key kid="${another_key_ID_from_kid_claim}" public-key="${public_key_in_PEM_format}"/>
    </jwt>
</token-realm>

Procedure

  1. Create a key-store by using the keytool.

    Example of creating a key-store by using keytool.

    keytool -genkeypair -alias <alias_name> -keyalg <key_algorithm> -keysize <key_size> -validity <key_validity_in_days> -keystore <key_store_path> -dname <distinguished_name> -keypass <key_password> -storepass  <key_store_password>

    Next, add the key-store definition in the elytron subsystem.

    Example of adding a key-store definition in the elytron subsystem.

    /subsystem=elytron/key-store=<key_store_name>:add(path=<key_store_path> , credential-reference={clear-text=<key_store_password>}, type=<keystore_type>)

  2. Create your token-realm in the elytron subsystem, and specify attributes and a jwt token validator for your token-realm.

    Example of creating a token-realm in the elytron subsystem.

    /subsystem=elytron/token-realm=<token_realm_name>:add(jwt={issuer=[<issuer_name>],audience=[<audience_name>],key-store=<key_store_name>,certificate=<alias_name>},principal-claim=<principal_claim_key>)

Next steps

Additional resources

2.10.3. Configuring authentication with tokens issued by an OAuth2 compliant authorization server

Elytron supports bearer tokens issued by an OAuth2-compliant authorization server. You can configure a token realm to validate tokens against the predefined oauth2-introspection endpoint.

Procedure

  1. Create a token realm.

    Example of creating a token realm by using the elytron subsystem:

    /subsystem=elytron/token-realm=<token_realm_name>:add(principal-claim=<principal_claim_key>, oauth2-introspection={client-id=<client_id>, client-secret=<client_secret>, introspection-url=<introspection_URL>})

    The following example shows an oauth2-introspection element specified in the token-realm element. This token realm is configured to validate tokens against the predefined oauth2-introspection endpoint. The oauth2-introspection endpoint uses the values specified in the client-id and client-secret attributes to identify the client.

    Example of an oauth2-introspection element inside the token-realm element:

    <token-realm name="${token_realm_name}" principal-claim="${principal_claim_key}">
    <oauth2-introspection client-id="${client_id}"
                          client-secret="${client_secret}"
                          introspection-url="${introspection_URL}"
                          host-name-verification-policy="${hostname_verification_policy_value}"/>
</token-realm>

Next steps

Additional resources

2.10.4. Configuring bearer token authentication for an application

You can configure authentication for an application by using bearer tokens in JWT format, such as OpenID Connect ID tokens, or by using opaque tokens issued by the OAuth2 compliant authorization server.

Prerequisites

Procedure

  1. Create a security domain in the elytron subsystem. Ensure you specify your token security realm in the security domain.

    Example of creating a security domain in the elytron subsystem.

    /subsystem=elytron/security-domain=<security_domain_name>:add(realms=[{realm=<token_realm_name>,role-decoder=<role_decoder_name>}],permission-mapper=<permission_mapper_name>,default-realm=<token_realm_name>)

  2. Create a http-authentication-factory that uses the BEARER_TOKEN mechanism.

    Example of creating an http-authentication-factory.

    /subsystem=elytron/http-authentication-factory=<authentication_factory_name>:add(security-domain=<security_domain_name>,http-server-mechanism-factory=global,mechanism-configurations=[{mechanism-name=BEARER_TOKEN,mechanism-realm-configurations=[{realm-name=<token_realm_name>}]}])

  3. Configure an application-security-domain in the undertow subsystem.

    Example of configuring an application-security-domain in the undertow subsystem.

    /subsystem=undertow/application-security-domain=<application_security_domain_name>:add(http-authentication-factory=<authentication_factory_name>)

  4. Configure your application’s web.xml and jboss-web.xml files. You must ensure your application’s web.xml specifies the BEARER_TOKEN authentication method. Additionally, ensure jboss-web.xml uses the application-security-domain you configured in JBoss EAP.

Additional resources