Chapter 2. Elytron Subsystem

2.1. Configure Authentication with a Filesystem-Based Identity Store

  1. Configure a filesystem-realm in JBoss EAP:

    Important

    filesystem-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.

    /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 http-authentication-factory:

    /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}]}])

    This example creates an http-authentication-factory using BASIC authentication, but it could be updated to use other mechanisms, such as FORM or DIGEST.

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

    /subsystem=undertow/application-security-domain=exampleApplicationDomain:add(http-authentication-factory=example-fs-http-auth)
    Note

    An application-security-domain in the undertow subsystem can be configured using the management console:

    1. Navigate to ConfigurationSubsystemsWeb/HTTP - UndertowHTTP → and click View.
    2. Click on the Application Security Domain tab. All security domain-related configurations for any deployed application can be done here.
  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.

Your application is now using a filesystem-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 http-authentication-factory:

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

    This example creates an http-authentication-factory using BASIC authentication, but it could be updated to use other mechanisms, such as FORM or DIGEST.

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

    /subsystem=undertow/application-security-domain=exampleApplicationDomain:add(http-authentication-factory=example-http-auth)
    Note

    An application-security-domain in the undertow subsystem can be configured using the management console:

    1. Navigate to ConfigurationSubsystemsWeb/HTTP - UndertowHTTP → and click View.
    2. Click on the Application Security Domain tab. All security domain-related configurations for any deployed application can be done here.
  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 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 postgres 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.

  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 http-authentication-factory:

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

    This example creates an http-authentication-factory using BASIC authentication, but it could be updated to use other mechanisms, such as FORM or DIGEST.

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

    /subsystem=undertow/application-security-domain=exampleApplicationDomain:add(http-authentication-factory=example-db-http-auth)
    Note

    An application-security-domain in the undertow subsystem can be configured using the management console:

    1. Navigate to ConfigurationSubsystemsWeb/HTTP - UndertowHTTP → and click View.
    2. Click on the Application Security Domain tab. All security domain-related configurations for any deployed application can be done here.
  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.

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 JMX 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 http-authentication-factory:

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

    This example creates an http-authentication-factory using BASIC authentication, but it could be updated to use other mechanisms, such as FORM or DIGEST.

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

    /subsystem=undertow/application-security-domain=exampleApplicationDomain:add(http-authentication-factory=example-ldap-http-auth)
    Note

    An application-security-domain in the undertow subsystem can be configured using the management console:

    1. Navigate to ConfigurationSubsystemsWeb/HTTP - UndertowHTTP → and click View.
    2. Click on the Application Security Domain tab. All security domain-related configurations for any deployed application can be done here.
  8. 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 http-authentication-factory.

    /subsystem=elytron/http-authentication-factory=exampleCertHttpAuth:add(http-server-mechanism-factory=global,security-domain=exampleCertSD,mechanism-configurations=[{mechanism-name=CLIENT_CERT,mechanism-realm-configurations=[{realm-name=exampleApplicationDomain}]}])
  6. Configure an application-security-domain in the undertow subsystem.

    /subsystem=undertow/application-security-domain=exampleApplicationDomain:add(http-authentication-factory=exampleCertHttpAuth)
    Note

    An application-security-domain in the undertow subsystem can be configured using the management console:

    1. Navigate to ConfigurationSubsystemsWeb/HTTP - UndertowHTTP → and click View.
    2. Click on the Application Security Domain tab. All security domain-related configurations for any deployed application can be done here.
  7. 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
  8. 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. 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:

  1. Navigate to ConfigurationSubsystemsWeb/HTTP - UndertowHTTP → and click View.
  2. Click on the Application Security Domain tab. All security domain-related configurations for any deployed application can be done here.

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.7. 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
Important

filesystem-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.

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.8. 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 HTTP authentication.

    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)

    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}]

    Use the following management CLI command to create an http-authentication-factory:

    /subsystem=elytron/http-authentication-factory=example-http-authentication:add(security-domain=example-domain, http-server-mechanism-factory=global, mechanism-configurations=[{mechanism-name=FORM}]
    Note

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

  3. 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(http-authentication-factory=example-http-authentication)
    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.

  4. 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:

    1. Navigate to ConfigurationSubsystemsWeb/HTTP - UndertowHTTP → and click View.
    2. Click on the Application Security Domain tab. All security domain-related configurations for any deployed application can be done here.

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

  5. 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.