How to Configure Identity Management

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.

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"])

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.

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)

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.

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

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

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.

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$

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

user1=Admin
user2=Guest

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.

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)

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.

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

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

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.

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:

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

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

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)

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.

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

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

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.

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

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

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

Add a simple-role-decoder:

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

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)

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.

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

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

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.

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.

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.

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

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)

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

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

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

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

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>

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.

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

Create a caching-realm.

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

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

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.

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

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)

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

Create an application security domain in the undertow subsystem.

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

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

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

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.

Configure your application’s web.xml.

Your application’s web.xml needs to be configured to use the appropriate authentication method. When using the elytron subsystem, this is defined in the http-authentication-factory you created. When using the legacy security subsystem, this depends on your login module and the type of authentication you want to configure.

<web-app>
  <security-constraint>
    <web-resource-collection>
      <web-resource-name>secure</web-resource-name>
      <url-pattern>/secure/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
      <role-name>Admin</role-name>
    </auth-constraint>
  </security-constraint>
  <security-role>
    <description>The role that is required to log in to /secure/*</description>
    <role-name>Admin</role-name>
  </security-role>
  <login-config>
    <auth-method>BASIC</auth-method>
    <realm-name>exampleApplicationDomain</realm-name>
  </login-config>
</web-app>

Configure your application to use a security domain.

You can configure your application’s jboss-web.xml to specify the security domain you want to use for authentication. When using the elytron subsystem, this is defined when you created the application-security-domain. When using the legacy security subsystem, this is the name of the legacy security domain.

<jboss-web>
  <security-domain>exampleApplicationDomain</security-domain>
</jboss-web>

Using jboss-web.xml allows you to configure the security domain for a single application only. Alternatively, you can specify a default security domain for all applications using the undertow subsystem. This allows you to omit using jboss-web.xml to configure a security domain for an individual application.

/subsystem=undertow:write-attribute(name=default-security-domain, value="exampleApplicationDomain")

Create an outbound connection to the LDAP server.

The purpose of creating an outbound LDAP connection is to allow the security realm (and the JBoss EAP instance) to establish a connection to the LDAP server. This is similar to the case of creating a datasource for use with the Database login module in a security domain.

The LDAP outbound connection allows the following attributes:

Given the following example LDAP server, below are the management CLI commands for configuring an outbound LDAP connection:

/core-service=management/ldap-connection=ldap-connection/:add(search-credential=myPass,url=ldap://127.0.0.1:389,search-dn="cn=search,dc=acme,dc=com")

reload

Create a new LDAP-enabled security realm.

Once the outbound LDAP connection has been created, a new LDAP-enabled security realm must be created to use it.

The LDAP security realm has the following configuration attributes:

Below are the management CLI commands for configuring an LDAP-enabled security realm using the ldap-connection outbound LDAP connection.

/core-service=management/security-realm=ldap-security-realm:add

/core-service=management/security-realm=ldap-security-realm/authentication=ldap:add(connection="ldap-connection", base-dn="cn=users,dc=acme,dc=com",username-attribute="sambaAccountName")

reload

Reference the new security realm in the management interface. Once a security realm has been created and is using the outbound LDAP connection, that new security realm must be referenced by the management interfaces.

/core-service=management/management-interface=http-interface/:write-attribute(name=security-realm,value="ldap-security-realm")