Chapter 4. Elytron Subsystem Example Scenarios

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.

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

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.

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.

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.

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.

The following users have been added to exampleRealm:

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.

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.

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

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

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.

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.

The following users have been created in the Kerberos server:

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

The following roles have also been configured in each application:

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.