Chapter 4. Elytron Subsystem Example Scenarios

4.1. Out of the Box

By default, JBoss EAP provides the following components preconfigured:

ApplicationDomain
The ApplicationDomain security domain uses ApplicationRealm and groups-to-roles for authentication. It also uses default-permission-mapper to assign the login permission.
ApplicationRealm
The ApplicationRealm security realm is a properties realm that authenticates principals using application-users.properties and assigns roles using application-roles.properties. These files are located under jboss.server.config.dir, which by default, maps to EAP_HOME/standalone/configuration. They are also the same files used by the legacy security default configuration.
application-http-authentication
The application-http-authentication http-authentication-factory can be used for doing authentication over HTTP. It uses the global provider-http-server-mechanism-factory to filter authentication mechanism and uses ApplicationDomain for authenticating principals. It accepts BASIC and FORM authentication mechanisms and exposes BASIC as Application Realm to applications.
application-sasl-authentication
The application-sasl-authentication sasl-authentication-factory can be used for authentication using SASL. It uses the configured sasl-server-factory to filter authentication mechanisms, which also uses the global provider-sasl-server-factory to filter by provider names. application-sasl-authentication uses the ApplicationDomain security domain for authentication of principals.
configured (configurable-sasl-server-factory)
This is used to filter sasl-authentication-factory is used based on the mechanism name. In this case, configured will match on JBOSS-LOCAL-USER and DIGEST-MD5. It also sets the wildfly.sasl.local-user.default-user to $local.
default-permission-mapper

The default-permission-mapper is a simple permission mapper that uses the default-permissions permission set to assign the full set of permissions that an identity requires to access any services on the server.

For example, the default-permission-mapper uses org.wildfly.extension.batch.jberet.deployment.BatchPermission specified by the default-permissions permission set to assign permissions for batch jobs. The batch permissions are start, stop, restart, abandon, and read which aligns with javax.batch.operations.JobOperator.

The default-permission-mapper also uses org.wildfly.security.auth.permission.LoginPermission specified by the login-permission permission set to assign the login permission.

elytron (mechanism-provider-filtering-sasl-server-factor)
This is used to filter which sasl-authentication-factory is used based on the provider. In this case, elytron will match on the WildFlyElytron provider name.
global (provider-http-server-mechanism-factory)
This is the HTTP server factory mechanism definition used to list the supported authentication mechanisms when creating an HTTP authentication factory.
global (provider-sasl-server-factory)
This is the SASL server factory definition used to create SASL authentication factories.
groups-to-roles
The groups-to-roles mapper is a simple-role-decoder that will decode the groups information of a principal and use it for the role information.
local (mapper)
The local mapper is a constant role mapper that maps to the local security realm. This is used to map authentication to the local security realm.
local (security realm)
The local security realm does no authentication and sets the identity of principals to $local.
ManagementDomain
The ManagementDomain security domain uses two security realms for authentication: ManagementRealm with groups-to-roles and local with super-user-mapper. It also uses default-permission-mapper to assign the login permission.
ManagementRealm
The ManagementRealm security realm is a properties realm that authenticates principals using mgmt-users.properties and assigns roles using mgmt-roles.properties. These files are located under jboss.server.config.dir, which by default, maps to EAP_HOME/standalone/configuration. They are also the same files used by the legacy security default configuration.
management-http-authentication
The management-http-authentication http-authentication-factory can be used for doing authentication over HTTP. It uses the global provider-http-server-mechanism-factory to filter authentication mechanism and uses ManagementDomain for authenticating principals. It accepts the DIGEST authentication mechanisms and exposes it as ManagementRealm to applications.
management-sasl-authentication
The management-sasl-authentication sasl-authentication-factory can be used for authentication using SASL. It uses the configured sasl-server-factory to filter authentication mechanisms, which also uses the global provider-sasl-server-factory to filter by provider names. management-sasl-authentication uses the ManagementDomain security domain for authentication of principals. It also maps authentication using JBOSS-LOCAL-USER mechanisms using the local realm mapper and authentication using DIGEST-MD5 to ManagementRealm.
super-user-mapper
The super-user-mapper mapper is a constant role mapper that maps the SuperUser role to a principal.

4.1.1. Security

For securing applications, JBoss EAP comes preconfigured with application-http-authentication for using HTTP and application-sasl-authentication for using SASL. The application-http-authentication http-authentication-factory uses ApplicationDomain which uses ApplicationRealm and groups-to-roles for authentication. ApplicationRealm is a properties-realm backed by application-users.properties and application-roles.properties for username, password, and role information.

For securing the management interfaces, JBoss EAP comes preconfigured with management-http-authentication for HTTP and management-sasl-authentication for SASL. The management-http-authentication http-authentication-factory uses ManagementDomain which uses ManagementRealm and groups-to-roles for authentication. ManagementRealm is a properties-realm backed by mgmt-users.properties and mgmt-roles.properties for username, password, and role information. The management-sasl-authentication sasl-authentication-factory uses ManagementDomain which uses local for JBOSS-LOCAL-USER authentication and ManagementRealm for DIGEST-MD5 authentication.

4.1.2. How It Works

By default, there are no users for JBoss EAP, but for the purposes of this example the following users have been added:

Table 4.1. Users

UsernamePasswordRolesSecurity Realm

Susan

Testing123!

 

ManagementRealm

Sarah

Testing123!

sample

ApplicationRealm

Frank

Testing123!

 

ApplicationRealm

On startup, the JBoss EAP instance loads all four authentication factories and their associated security domains, security realms, and other configured components.

If anyone attempts to access the management interface with the management CLI using JBOSS-LOCAL-USER, in other words running the management CLI from the same host as the JBoss EAP instance, the user will be directed to the management-sasl-authentication sasl-authentication-factory which will attempt to authenticate the user with ManagementDomain using the local security realm.

If Susan attempts to access the management interface using the management CLI from a different host, she will be using the DIGEST-MD5 authentication mechanism with SASL. She will be directed to the management-sasl-authentication sasl-authentication-factory which will attempt to authenticate the user with ManagementDomain using the ManagementRealm security realm.

If Susan attempts to access the management interface using the web-based management console, she will be using the DIGEST authentication mechanism with HTTP. She will be directed to the management-http-authentication http-authentication-factory which will attempt to authenticate the user with ManagementDomain using the ManagementRealm security realm.

The application sampleApp1.war has two HTML files, /hello.html and /secure/hello.html, and uses BASIC HTTP authentication to secure the path /secure/*. It uses the Application Realm and requires the role of sample. When a user attempts to access sampleApp1.war, they are directed to the application-http-authentication http-authentication-factory. It will attempt to authenticate the user with ApplicationDomain using the ApplicationRealm security realm.

When Sarah requests /hello.html, she is able to view the page without authenticating. When Sarah tries to request /secure/hello.html, she is prompted to enter her username and password. She is able to view /secure/hello.html after successfully logging in. Frank and Susan, or any user, can access /hello.html, but neither can access /secure/hello.html. Frank does not have the sample role, and Susan is not in the ApplicationRealm security realm.

4.2. Using SSL/TLS to Secure the Management Interfaces and Applications

This scenario shows how JBoss EAP is secured when using Elytron for SSL/TLS with both management interfaces and applications.

4.2.1. Security

JBoss EAP provides the ability to secure both the management interfaces as well as applications with SSL/TLS. With Elytron, this configuration is now unified so you now have the option to secure both the management interfaces and applications with the same SSL/TLS configuration. SSL/TLS is configured in Elytron by creating a key-store, key-manager, and server-ssl-context. SSL/TLS is enabled for the management interfaces by setting secure-socket-binding on the http-interface and by assigning the server-ssl-context to the management interfaces. This enables the management interfaces to use SSL/TLS for HTTP traffic. SSL/TLS is enabled for applications by assigning the server-ssl-context to the https-listener in the undertow subsystem. For more background information on SSL/TLS see the Advanced Security section.

4.2.2. How It Works

On startup, JBoss EAP loads the management interfaces as part of the core services, which also starts the http-interface, configured for SSL/TLS for the management interfaces. It also starts the undertow subsystem, which is configured for SSL/TLS for applications, and the elytron subsystem which provides the SSL/TLS configuration through the server-ssl-context. Both the management interfaces and applications can then be accessed over the secure ports with SSL/TLS enabled.

4.3. Securing the Management Interfaces and Applications with a New Identity Store

This scenario shows how both the management interfaces and applications in JBoss EAP are secured with a new identity store in Elytron. An application, sampleApp2.war, is deployed to JBoss EAP and is configured to use basicExampleDomain.

4.3.1. Security

JBoss EAP provides the ability to secure both the management interfaces as well as applications with identity stores beyond ManagementRealm and ApplicationRealm. With Elytron, the same identity store can be used to secure the management interfaces as well as applications, but you also still have the option to set up separate identity stores for each. An identity store is represented by a security realm, for example a filesystem-realm, jdbc-realm, or ldap-realm. For the purposes of this example, a filesystem-realm named exampleRealm has been created. A security domain named exampleDomain has also been created which uses exampleRealm as an identity store, the groups-to-roles role mapper to decode the group information provided by exampleRealm into roles, and default-permission-mapper for mapping permissions.

For HTTP authentication, an http-authentication-factory called exampleHttpAuthFactory has been created. It uses the global HTTP server factory mechanism and exampleDomain for authentication. It also has two mechanism configurations. One that uses the BASIC authentication method exposed as basicExampleDomain, and one that uses the DIGEST authentication method exposed as digestExampleDomain. The HTTP management interface has been configured to use exampleHttpAuthFactory. The undertow subsystem has also been configured with a new application-security-domain which also uses exampleHttpAuthFactory. The application sampleApp2.war is configured to use basicExampleDomain with BASIC authentication.

For SASL authentication a sasl-authentication-factory called exampleSaslAuthFactory has been created. It uses the configured SASL server factory and exampleDomain for authentication. It also has a DIGEST-MD5 authentication mechanism configured which is exposed as digestMD5ExampleDomain. The SASL configuration for the management interfaces has been set to use exampleSaslAuthFactory.

4.3.2. How It Works

The following users have been added to exampleRealm:

Table 4.2. exampleRealm Users

UsernamePasswordRoles

Vincent

samplePass

sample

Issac

samplePass

guest

On startup, JBoss EAP loads the core services and starts the undertow and elytron subsystems. This secures the management interfaces and exposes basicExampleDomain, digestExampleDomain, and digestMD5ExampleDomain for applications deployed to JBoss EAP.

When sampleApp2.war is loaded, it looks for basicExampleDomain to provide authentication and authorization for its secured URLs. It has two HTML files, /hello.html and /secure/hello.html, and uses BASIC authentication to secure the path /secure/*. It requires the role of sample to access any secure URLs.

When users authenticate, their credentials are submitted using a specific mechanism depending on how they are accessing JBoss EAP. For instance, if a user attempts to access the management console using HTTP with DIGEST authentication, they will authenticate using the DIGEST authentication method exposed as digestExampleDomain. If they attempt to access sampleApp2.war using HTTP with BASIC authentication, they will authenticate using the BASIC authentication method exposed as basicExampleDomain. If they attempt to access the management CLI using SASL with DIGEST authentication, they will authenticate using the DIGEST-MD5 exposed as digestMD5ExampleDomain. The HTTP authentication mechanisms use exampleHttpAuthFactory, and the SASL authentication mechanism uses exampleSaslAuthFactory. Both authentication factories handle authentication and role mapping with exampleDomain.

If Vincent or Issac attempt to access the management interfaces, they are prompted for their username and password. After successfully logging in, they are each able to perform management operations.

When Vincent or Issac requests /hello.html, they are able to view the page without authenticating. When Vincent or Issac tries to request /secure/hello.html, they are prompted to enter a username and password. After successfully logging in, Vincent is able to view /secure/hello.html since he has the sample role but Issac will not be able to view /secure/hello.html since he has the guest role. All other users can access /hello.html without logging in, but none can access /secure/hello.html because Vincent and Issac are the only users in exampleRealm.

4.4. Using RBAC to Secure the Management Interfaces

This scenario shows how the JBoss EAP management interfaces are secured with RBAC and an identity store in the elytron subsystem.

4.4.1. Security

JBoss EAP offers the ability to use RBAC on the management interfaces. The concepts behind RBAC are covered in the RBAC section. This example uses a security realm called exampleRealm. The remainder of the security configuration, including role decoder, security domain, and authentication factories, are the same as in the Securing the Management Interfaces and Applications with a New Identity Store section. RBAC is enabled by setting the provider attribute to rbac for the management interface and updating the exampleRealm with the desired users and roles.

4.4.2. How It Works

For this scenario, the following users have been added to the existing security realms:

Table 4.3. exampleRealm Users

UsernamePassword

Suzy

Testing123!

Tim

Testing123!

Emily

Testing123!

Zach

Testing123!

Natalie

Testing123!

Based on group membership, the users have also been mapped to the following RBAC roles:

Table 4.4. RBAC Roles

UsernameRBAC Role

Suzy

SuperUser

Tim

Administrator

Emily

Maintainer

Zach

Deployer

Natalie

Monitor

On startup, JBoss EAP loads the core services and elytron subsystem, which loads the security configuration and the RBAC configuration. If RBAC was not enabled, any user in the exampleRealm is considered a SuperUser and has unlimited access. Because RBAC has been enabled, each user is now restricted based on the roles they have. Suzy, Tim, Emily, Zach, and Natalie have different roles, which are shown in the table above. For example, only Suzy and Tim can read and modify access control information. Suzy, Tim, and Emily can modify runtime state and other persistent configuration information. Zach can also modify runtime state and other persistent configuration information but only related to application resources. Suzy, Tim, Emily, Zach, and Natalie can read configuration and state information, but Natalie cannot update anything. For more details on each of the roles and how JBoss EAP handles RBAC, see the Role-Based Access Control and Adding RBAC to the Management Interfaces sections.

4.5. Using Kerberos to Provide SSO for Web Applications

This scenario shows how Kerberos can be used with JBoss EAP to provide SSO for web applications. A JBoss EAP instance has been created, EAP1, and is running as a standalone server. Two web applications, sampleAppA and sampleAppB, have been deployed to EAP1. Both the web applications and EAP1 have been configured to authenticate using desktop-based SSO with Kerberos.

4.5.1. Security

JBoss EAP provides authentication with Kerberos using the SPNEGO authentication method. For more information on the specifics of Kerberos and SPNEGO, please see the Third-Party SSO Implementations section. To enable JBoss EAP and deployed web applications to use Kerberos for authentication, a kerberos-security-factory is created to connect to the Kerberos server. A security realm, role mapper, and security domain are also created for assigning roles to users from the Kerberos server. An http-authentication-factory is created that uses the kerberos-security-factory and uses the security domain for authentication and role assignment. An authentication mechanism is exposed as exampleSpnegoDomain using a SPNEGO authentication mechanism. The undertow subsystem is also configured to use the http-authentication-factory for authentication.

Both sampleAppA and sampleAppB are configured to use exampleSpnegoDomain to perform authentication and get a user’s roles for authorization. Both applications can also be configured with FORM authentication as a fallback authentication mechanism in case the security tokens cannot be passed from the operating system to the browser. If FORM authentication is configured as a fallback, an additional authentication mechanism, along with a supporting security domain, must be configured. This authentication mechanism is independent of Kerberos and SPNEGO and only has to support FORM authentication. In this case, an additional mechanism and supporting security domain have been configured for FORM authentication and exposed as exampleFormDomain. Each application is configured to use a exampleFormDomain and to provide FORM authentication as a fallback. Each application is also configured to secure the path /secure/* and supplies its own list of roles for handling authorization.

4.5.2. How It Works

The following users have been created in the Kerberos server:

Table 4.5. Kerberos Users

UsernamePassword

Sande

samplePass

Andrea

samplePass

Betty

samplePass

Chuck

samplePass

The following roles are mapped to the users using the security domain:

Table 4.6. User Roles

UsernameRoles

Sande

all

Andrea

A

Betty

B

Chuck

 

The following roles have also been configured in each application:

Table 4.7. Application Roles

Application/SPAllowed Roles

sampleAppA

all, A

sampleAppB

all, B

On startup, EAP1 loads the core services, followed by the elytron and other subsystems. The kerberos-security-factory establishes a connection to the Kerberos server. Both sampleAppA and sampleAppB are deployed and connect to exampleSpnegoDomain and exampleFormDomain for authentication.

Sande has logged in to a computer that is secured with Kerberos. She opens a browser and attempts to access sampleAppA/secure/hello.html. Because that is secured, authentication is required. EAP1 directs the browser to send a request for a key to the Kerberos server, specifically the Kerberos Key Distribution Center that is configured on her computer. After the browser obtains a key, it is sent to sampleAppA. sampleAppA sends the ticket using exampleSpnegoDomain to JBoss EAP where it is unpacked and authentication is performed in conjunction with the configured Kerberos server in the kerberos-security-factory. Once the ticket is authenticated, Sande’s role is passed back to sampleAppA to perform authorization. Because Sande has the all role, she will be able to access sampleAppA/secure/hello.html. If Sande tries to access sampleAppB/secure/hello.html, the same process will occur. She will be granted access, due to her having the all role. Andrea and Betty would follow the same process, but with Andrea only having access to sampleAppA/secure/hello.html and not sampleAppB/secure/hello.html. Betty would be the opposite, having access to sampleAppB/secure/hello.html and not sampleAppA/secure/hello.html. Chuck would pass authentication to either sampleAppA/secure/hello.html or sampleAppB/secure/hello.html but would not be granted access to either because he does not have any roles.

If Sande were to attempt to access sampleAppA/secure/hello.html from a computer not secured by Kerberos, for example a personal laptop connected to the office network, she would be directed to the FORM login page as a fallback. Her credentials would then be authenticated using the fallback authentication mechanism and the process would continue with authorization.