Chapter 2. How Red Hat JBoss Enterprise Application Platform Handles Security out of the Box

There are three components that ship with JBoss EAP that relate to security:

These components are based on the general security concepts discussed in the Overview of General Security Concepts, but they also incorporate some JBoss EAP-specific concepts in their implementation.

2.1. Core Services, Subsystems, and Profiles

JBoss EAP is built on the concept of modular class loading. Each API or service provided by JBoss EAP is implemented as a module, which is loaded and unloaded on demand. The core services are services that are always loaded on server startup and are required to be running prior to starting an additional subsystem.

A subsystem is a set of capabilities added to the core server by an extension. For example, different subsystems handle servlet processing, manage the EJB container, and provide JTA support.

A profile is a named list of subsystems, along with the details of each subsystem’s configuration. A profile with a large number of subsystems results in a server with a large set of capabilities. A profile with a small, focused set of subsystems will have fewer capabilities but a smaller footprint. By default, JBoss EAP comes with several predefined profiles, for example default, full, ha, full-ha. In these profiles, the management interfaces and the associated security realms are loaded as core services.

2.2. Management Interfaces

JBoss EAP offers two main management interfaces for interacting with and editing its configuration: the management console and the management CLI. Both interfaces expose the functionality of the core management of JBoss EAP. These interfaces offer two ways to access the same core management system.

The management console is a web-based administration tool for JBoss EAP. It may be used to start and stop servers, deploy and undeploy applications, tune system settings, and make persistent modifications to the server configuration. The management console also has the ability to perform administrative tasks, with live notifications when any changes require the server instance to be restarted or reloaded. In a managed domain, server instances and server groups in the same domain can be centrally managed from the management console of the domain controller.

The management CLI is a command-line administration tool for JBoss EAP. The management CLI may be used to start and stop servers, deploy and undeploy applications, configure system settings, and perform other administrative tasks. Operations can be performed in batch mode, allowing multiple tasks to be run as a group. The management CLI may also connect to the domain controller in a managed domain to execute management operations on the domain. The management CLI can perform all tasks that the web-based administration tool can perform as well as many other lower-level operations that are unavailable to the web-based administration tool.

Note

In addition to the clients that ship with JBoss EAP, other clients can be written to invoke the management interfaces over either the HTTP or native interfaces using the APIs included with JBoss EAP.

2.3. JMX

Java Management Extensions (JMX) provides a way to remotely trigger JDK and application management operations. The management API of JBoss EAP is exposed as JMX managed beans. These managed beans are referred to as core MBeans, and access to them is controlled and filtered exactly the same as the underlying management API itself.

In addition to the management CLI and management console, JMX-exposed beans are an alternative mechanism to access and perform management operations.

2.4. Role-Based Access Control

Role-Based Access Control (RBAC) is a mechanism for specifying a set of permissions for management users. It allows multiple users to share responsibility for managing JBoss EAP servers without each of them requiring unrestricted access. By providing a separation of duties for management users, JBoss EAP makes it easy for an organization to spread responsibility between individuals or groups without granting unnecessary privileges. This ensures the maximum possible security of your servers and data while still providing flexibility for configuration, deployment, and management.

RBAC in JBoss EAP works through a combination of role permissions and constraints. Seven predefined roles are provided, with every role having different fixed permissions. Each management user is assigned one or more roles that specify what the user is permitted to do when managing the server.

RBAC is disabled by default for JBoss EAP.

Standard Roles

JBoss EAP provides seven predefined user roles: Monitor, Operator, Maintainer, Deployer, Auditor, Administrator, and SuperUser. Each role has a different set of permissions and is designed for specific use cases. The Monitor, Operator, Maintainer, Administrator, and SuperUser roles build successively upon each other, with each having more permissions than the previous. The Auditor and Deployer roles are similar to the Monitor and Maintainer roles, respectively, but they have some special permissions and restrictions.

Monitor
Users of the Monitor role have the fewest permissions and can only read the current configuration and state of the server. This role is intended for users who need to track and report on the performance of the server. Monitor cannot modify server configuration, nor can they access sensitive data or operations.
Operator
The Operator role extends the Monitor role by adding the ability to modify the runtime state of the server. This means that Operator can reload and shutdown the server as well as pause and resume JMS destinations. The Operator role is ideal for users who are responsible for the physical or virtual hosts of the application server so they can ensure that servers can be shutdown and restarted correctly when need be. Operator cannot modify server configuration or access sensitive data or operations.
Maintainer
The Maintainer role has access to view and modify the runtime state and all configurations except sensitive data and operations. The Maintainer role is the general purpose role that does not have access to sensitive data and operation. The Maintainer role allows users to be granted almost complete access to administer the server without giving those users access to passwords and other sensitive information. Maintainer cannot access sensitive data or operations.
Administrator
The Administrator role has unrestricted access to all resources and operations on the server except the audit logging system. The Administrator role has access to sensitive data and operations. This role can also configure the access control system. The Administrator role is only required when handling sensitive data or configuring users and roles. Administrator cannot access the audit logging system and cannot change themselves to the Auditor or SuperUser role.
SuperUser
The SuperUser role does not have any restrictions, and it has complete access to all resources and operations of the server, including the audit logging system. If RBAC is disabled, all management users have permissions equivalent to the SuperUser role.
Deployer
The Deployer role has the same permissions as the Monitor, but it can modify the configuration and state for deployments and any other resource type enabled as an application resource.
Auditor
The Auditor role has all the permissions of the Monitor role and can also view, but not modify, sensitive data. It has full access to the audit logging system. The Auditor role is the only role besides SuperUser that can access the audit logging system. Auditor cannot modify sensitive data or resources. Only read access is permitted.

Permissions

Permissions determine what each role can do; not every role has every permission. Notably, SuperUser has every permission and Monitor has the least. Each permission can grant read and/or write access for a single category of resources. The categories are runtime state, server configuration, sensitive data, the audit log, and the access control system.

Table 2.1. Permissions of Each Role for Monitor, Operator, Maintainer and Deployer

 MonitorOperatorMaintainerDeployer

Read Config and State

Read Sensitive Data 2

    

Modify Sensitive Data 2

    

Read/Modify Audit Log

    

Modify Runtime State

 

1

Modify Persistent Config

  

1

Read/Modify Access Control

    

1 Permissions are restricted to application resources.

Table 2.2. Permissions of Each Role for Auditor, Administration and SuperUser

 AuditorAdministratorSuperUser

Read Config and State

Read Sensitive Data 2

Modify Sensitive Data 2

 

Read/Modify Audit Log

 

Modify Runtime State

 

Modify Persistent Config

 

Read/Modify Access Control

 

2 Which resources are considered to be sensitive data are configured using sensitivity.

Constraints

Constraints are named sets of access-control configuration for a specified list of resources. The RBAC system uses the combination of constraints and role permissions to determine if any specific user can perform a management action.

Constraints are divided into three classifications.

Application Constraints
Application constraints define sets of resources and attributes that can be accessed by Deployer users. By default, the only enabled application constraint is core, which includes deployments and deployment overlays. Application constraints are also included, but not enabled by default, for data sources, logging, mail, messaging, naming, resource adapters, and security. These constraints allow Deployer users to not only deploy applications, but also configure and maintain the resources that are required by those applications.
Sensitivity Constraints
Sensitivity constraints define sets of resources that are considered sensitive. A sensitive resource is generally one that is either secret, like a password, or one that will have serious impact on the operation of the server, like networking, JVM configuration, or system properties. The access control system itself is also considered sensitive. The only roles permitted to write to sensitive resources are Administrator and SuperUser. The Auditor role is only able to read sensitive resources. No other roles have access.
Vault Expression Constraint
The vault expression constraint defines if reading and writing vault expressions are considered sensitive operations. By default, reading and writing vault expressions are sensitive operations.

2.5. Declarative Security and JAAS

Declarative security is a method to separate security concerns from application code by using the container to manage security. The container provides an authorization system based on either file permissions or users, groups, and roles. This approach is usually superior to programmatic security, which gives the application itself all of the responsibility for security. JBoss EAP provides declarative security by using security domains in the security subsystem.

Java Authentication and Authorization Service (JAAS), is a declarative security API comprising a set of Java packages designed for user authentication and authorization. The API is a Java implementation of the standard Pluggable Authentication Modules (PAM) framework. It extends the Java EE access control architecture to support user-based authorization. The JBoss EAP security subsystem is actually based on the JAAS API.

Because JAAS is the foundation for the security subsystem, authentication is performed in a pluggable fashion. This permits Java applications to remain independent from underlying authentication technologies, such as Kerberos or LDAP, and allows the security manager to work in different security infrastructures. Integration with a security infrastructure is achievable without changing the security manager implementation. Only the configuration of the authentication stack that JAAS uses needs to be changed.

2.6. Elytron Subsystem

The elytron subsystem was introduced in JBoss EAP 7.1. It is based on the WildFly Elytron project, which is a security framework used to unify security across the entire application server. The elytron subsystem enables a single point of configuration for securing both applications and the management interfaces. WildFly Elytron also provides a set of APIs and SPIs for providing custom implementations of functionality and integrating with the elytron subsystem.

In addition, there are several other important features of WildFly Elytron:

  • Stronger authentication mechanisms for HTTP and SASL authentication.
  • Improved architecture that allows for SecurityIdentities to be propagated across security domains. This ensures transparent transformation that is ready to be used for authorization. This transformation takes place using configurable role decoders, role mappers, and permission mappers.
  • Centralized point for SSL/TLS configuration including cipher suites and protocols.
  • SSL/TLS optimizations such as eager SecureIdentity construction and closely tying authorization to establishing an SSL/TLS connection. Eager SecureIdentity construction eliminates the need for a SecureIdentity to be constructed on a per-request basis. Closely tying authentication to establishing an SSL/TLS connection enables permission checks to happen BEFORE the first request is received.
  • A secure credential store that replaces the previous vault implementation to store plain text strings.

The new elytron subsystem exists in parallel to the legacy security subsystem and legacy core management authentication. Both the legacy and Elytron methods can be used for securing the management interfaces as well as providing security for applications.

Important

The architectures of Elytron and the legacy security subsystem that is based on PicketBox are very different. With Elytron, an attempt was made to create a solution that allows you to operate in the same security environments in which you currently operate; however, this does not mean that every PicketBox configuration option has an equivalent configuration option in Elytron.

If you are not able to find information in the documentation to help you achieve similar functionality using Elytron that you had when using the legacy security implementation, you can find help in one of the following ways.

2.6.1. Core Concepts and Components

The concept behind the architecture and design of the elytron subsystem is using smaller components to assemble a full security policy. By default, JBoss EAP provides implementations for many components, but the elytron subsystem also allows you to provide specialized, custom implementations.

Each implementation of a component in the 'elytron' subsystem is handled as an individual capability. This means that different implementations can be mixed, matched and modeled using distinct resources.

2.6.1.1. Capabilities and Requirements

A capability is a piece of functionality used in JBoss EAP and is exposed using the management layer. One capability can depend on other capabilities and this dependency is mediated by the management layer. Some capabilities are provided automatically by JBoss EAP, but the full set of available capabilities available at runtime are determined using the JBoss EAP configuration. The management layer validates that all capabilities required by other capabilities are present during server startup as well as when any configuration changes are made. Capabilities integrate with JBoss Modules and extensions, but they are all distinct concepts.

In addition to registering other capabilities it depends on, a capability must also register a set of requirements related to those capabilities. A capability can specify the following types of requirements:

Hard requirements
A capability is depended on another capability to function, therefore it must always be present.
Optional requirements
An optional aspect of a capability depends on another capability, which can or can not be enabled. Therefore the requirement cannot be determined or known until the configuration is analyzed.
Runtime-only requirements
A capability will check if the required capability exists at runtime. If the required capability is present it will be used. If the required capability is not present, it will not be used.

You can find more information on capabilities and requirements in the WildFly documentation.

2.6.1.2. APIs, SPIs and Custom Implementations

Elytron provides a set of security APIs and SPIs so that other subsystems and consumers can use them directly, which reduces integration overhead. While the majority of users will use the provided functionality of JBoss EAP, the Elytron APIs and SPIs can also be used by custom implementations to replace or extend Elytron functionality.

2.6.1.3. Security Domains

A security domain is the representation of a security policy which is backed by one or more security realms and a set of resources that perform transformations. A security domain produces a SecurityIdentity. The SecurityIdentity is used by other resources that perform authorizations, such as an application. A SecurityIdentity is the representation of the current user, which is based on the raw AuthorizationIdentity and its associated roles and permissions.

You can also configure a security domain to allow inflow of a SecurityIdentity from another security domain. When an identity is inflowed, it retains its original raw AuthorizationIdentity, and a new set of roles and permissions are assigned to it, creating a new SecurityIdentity.

Important

Deployments are limited to using one Elytron security domain per deployment. Scenarios that may have required multiple legacy security domains can now be accomplished using a single Elytron security domain.

2.6.1.4. Security Realms

Security realms provide access to an identity store and are used to obtain credentials. These credentials allow authentication mechanisms to obtain the raw AuthorizationIdentity for performing authentication. They also allow authentication mechanisms to perform verification when doing validation of evidence.

You can associate one or more security realms with a security domain. Some security realm implementations also expose an API for modifications, meaning the security realm can make updates to the underlying identity store.

2.6.1.5. Role Decoders

A role decoder is associated with a security domain and is used to decode the current user’s roles. The role decoder takes the raw AuthorizationIdentity returned from the security realm and converts its attributes into roles.

2.6.1.6. Role Mappers

A role mapper applies a role modification to an identity. This can range from normalizing the format of the roles to adding or removing specific roles. A role mapper can be associated with both security realms as well as security domains. In cases where a role mapper is associated with a security realm, the role mapping will be applied at the security realm level before any transformations, such as role decoding or additional role mapping, occur at the security domain level. If a role mapper and another transformation, such as a role decoder, are both configured in a security domain, all other transformations are performed before the role mapper is applied.

2.6.1.7. Permission Mappers

A permission mapper is associated with a security domain and assigns a set of permissions to a SecurityIdentity.

2.6.1.8. Principal Transformers

A principal transformer can be used in multiple locations within the elytron subsystem. A principal transformer can transform or map a name to another name.

2.6.1.9. Principal Decoders

A principal decoder can be used in multiple locations within the elytron subsystem. A principal decoder converts an identity from a Principal to a string representation of the name. For example, the X500PrincipalDecoder allows you to convert an X500Principal from a certificate’s distinguished name to a string representation.

2.6.1.10. Realm Mappers

A realm mapper is associated with a security domain and is used in cases where a security domain has multiple security realms configured. The realm mappers can be also associated with mechanism or mechanism-realm of http-authentication-factory and sasl-authentication-factory. The realm mapper uses the name provided during authentication to choose a security realm for authentication and obtaining the raw AuthorizationIdentity.

2.6.1.11. Authentication Factories

An authentication factory is a representation of an authentication policy. An authentication is associated with security domain, mechanism factory, and a mechanism selector. The security domain provides the SecurityIdentity to be authenticated, the mechanism factory provides the server-side authentication mechanisms, and the mechanism selector is used to obtain configuration specific to the mechanism selected. The mechanism selector can include information about realm names a mechanism should present to a remote client plus additional principal transformers and realm mappers to use during the authentication process.

2.6.1.12. KeyStores

A key-store is the definition of a keystore or truststore including the type of keystore, its location, and credential for accessing it.

2.6.1.13. Key Managers

A key-manager references a key-store and is used in conjunction with an SSL context.

2.6.1.14. Trust Managers

A trust-manager references as truststore, which is defined in a key-store, and is used in conjunction with an SSL context, usually for two-way SSL/TLS.

2.6.1.15. SSL Context

The SSL context defined within the elytron subsystem is a javax.net.ssl.SSLContext meaning it can be used by anything that uses an SSL context directly. In addition to the usual configuration for an SSL context it is possible to configure additional items such as cipher suites and protocols. The SSL context will wrap any additional items that are configured.

2.6.1.16. Secure Credential Store

The previous vault implementation used for plain text string encryption has been replaced with a newly designed credential store. In addition to the protection for the credentials it stores, the credential store is used to store plain text strings.

2.6.2. Elytron Authentication Process

Multiple principal transformers, realm mappers, and a principal decoder can be defined within the elytron subsystem. The following sections discuss how these components function during the authentication process, and how principals are mapped to the appropriate security realm.

When a principal is authenticated it performs the following steps, in order:

  1. The appropriate mechanism configuration is determined and configured.
  2. The incoming principal is mapped into a SecurityIdentity.
  3. This SecurityIdentity is used to determine the appropriate security realm.
  4. After the security realm has been identified the principal is transformed again.
  5. One final transformation occurs to allow for mechanism-specific transformations.

The following image demonstrates these steps, highlighted in the left column, along with showing the components used in each phase.

Figure 2.1. Elytron Authentication Process

Elytron Authentication Process
Pre-realm Mapping

During pre-realm mapping the authenticated principal is mapped to a SecurityIdentity, a form that can identify which security realm should be used, and will contain a single Principal that represents the authenticated information. Principal transformers and principal decoders are called in the following order:

  1. Mechanism Realm - pre-realm-principal-transformer
  2. Mechanism Configuration - pre-realm-principal-transformer
  3. Security Domain - principal-decoder and pre-realm-principal-transformer

If this procedure results in a null principal, then an error will be thrown and authentication will terminate.

Figure 2.2. Pre-realm Mapping

Pre-realm Mapping
Realm Name Mapping

Once a mapped principal has been obtained, a security realm is identified which will be used to load the identity. At this point the realm name is the name defined by the security realm as referenced by the security domain, and is not yet the mechanism realm name. The configuration will look for a security realm name in the following order:

  1. Mechanism Realm - realm-mapper
  2. Mechanism Configuration - realm-mapper
  3. Security Domain - realm-mapper

If the RealmMapper returns null, or if no mapper is available, then the default-realm on the security domain will be used.

Figure 2.3. Realm Name Mapping

Realm Name Mapping
Post-realm Mapping

After a realm has been identified, the principal goes through another round of transformation. Transformers are called in the following order:

  1. Mechanism Realm - post-realm-principal-transformer
  2. Mechanism Configuration - post-realm-principal-transformer
  3. Security Domain - post-realm-principal-transformer

If this procedure results in a null principal, then an error will be thrown and authentication will terminate.

Figure 2.4. Post-realm Mapping

Post-realm Mapping
Final Principal Transformation

Finally, one last round of principal transformation occurs to allow for mechanism-specific transformations to be applied both before and after domain-specific transformations. If this stage is not required, then the same results can be obtained during the post-realm mapping stage. Transformers are called in the following order:

  1. Mechanism Realm - final-principal-transformer
  2. Mechanism Configuration - final-principal-transformer
  3. Realm Mapping - principal-transformer

If this procedure results in a null principal, then an error will be thrown and authentication will terminate.

Figure 2.5. Final Principal Transformation

Final Principal Transformation
Obtain the Realm Identity

After the final round of principal transformation, the security realm identified in realm name mapping is called to obtain a realm identity used to continue authentication.

2.6.3. HTTP Authentication

Elytron provides a complete set of HTTP authentication mechanisms including BASIC, FORM, DIGEST, SPNEGO, and CLIENT_CERT. HTTP authentication is handled using the HttpAuthenticationFactory, which is both an authentication policy for using HTTP authentication mechanisms as well as factory for configured authentication mechanisms.

The HttpAuthenticationFactory references the following:

SecurityDomain
The security domain that any mechanism authentication will be performed against.
HttpServerAuthenticationMechanismFactory
The general factory for server-side HTTP authentication mechanisms.
MechanismConfigurationSelector
You can use this to supply additional configuration for the authentication mechanisms. The purpose of the MechanismConfigurationSelector is to obtain configuration specific for the mechanism selected. This can include information about realm names a mechanism should present to a remote client, additional principal transformers, and realm mappers to use during the authentication process.

2.6.4. SASL Authentication

SASL is a framework for authentication that separate the authentication mechanism itself from the protocol it uses. It also allows for additional authentication mechanisms such as DIGEST-MD5, GSSAPI, OTP, and SCRAM. SASL authentication is not part of the Java EE specification. SASL authentication is handled using the SaslAuthenticationFactory, which is both an authentication policy for using SASL authentication mechanisms as well as a factory for configured authentication mechanisms.

The SaslAuthenticationFactory references the following:

SecurityDomain
The security domain that any mechanism authentication will be performed against.
SaslServerFactory
The general factory for server-side SASL authentication mechanisms.
MechanismConfigurationSelector
You can use this to supply additional configuration for the authentication mechanisms. The purpose of the MechanismConfigurationSelector is to obtain configuration specific for the mechanism selected. This can include information about realm names a mechanism should present to a remote client, additional principal transformers, and realm mappers to use during the authentication process.

2.6.5. Interaction between the Elytron Subsystem and Legacy Systems

You can map some of the major components of both the legacy security subsystem components as well as the legacy core management authentication to Elytron capabilities. This allows those legacy components to be used in an Elytron based configuration and allow for an incremental migration from legacy components.

2.6.6. Resources in the Elytron Subsystem

JBoss EAP provides a set of resources in the elytron subsystem:

Factories
aggregate-http-server-mechanism-factory
An HTTP server factory definition where the HTTP server factory is an aggregation of other HTTP server factories.
aggregate-sasl-server-factory
A SASL server factory definition where the SASL server factory is an aggregation of other SASL server factories.
configurable-http-server-mechanism-factory
An HTTP server factory definition that wraps another HTTP server factory and applies the specified configuration and filtering.
configurable-sasl-server-factory
A SASL server factory definition that wraps another SASL server factory and applies the specified configuration and filtering.
custom-credential-security-factory
A custom credential SecurityFactory definition.
http-authentication-factory

Resource containing the association of a security domain with a HttpServerAuthenticationMechanismFactory.

For more information, see Configure Authentication with Certificates in How to Configure Identity Management for JBoss EAP.

kerberos-security-factory

A security factory for obtaining a GSSCredential for use during authentication.

For more information, see Configure the Elytron Subsystem in How to Set Up SSO with Kerberos for JBoss EAP.

mechanism-provider-filtering-sasl-server-factory
A SASL server factory definition that enables filtering by provider where the factory was loaded using a provider.
provider-http-server-mechanism-factory
An HTTP server factory definition where the HTTP server factory is an aggregation of factories from the provider list.
provider-sasl-server-factory
A SASL server factory definition where the SASL server factory is an aggregation of factories from the provider list.
sasl-authentication-factory

Resource containing the association of a security domain with a SASL server factory.

For more information, see Secure the Management Interfaces with a New Identity Store in How to Configure Server Security for JBoss EAP.

service-loader-http-server-mechanism-factory
An HTTP server factory definition where the HTTP server factory is an aggregation of factories identified using a ServiceLoader.
service-loader-sasl-server-factory
A SASL server factory definition where the SASL server factory is an aggregation of factories identified using a ServiceLoader.
Principal Transformers
aggregate-principal-transformer
Individual transformers attempt to transform the original principal until one returns a non-null principal.
chained-principal-transformer
A principal transformer definition where the principal transformer is a chaining of other principal transformers.
constant-principal-transformer
A principal transformer definition where the principal transformer always returns the same constant.
custom-principal-transformer
A custom principal transformer definition.
regex-principal-transformer
A regular expression based principal transformer.
regex-validating-principal-transformer
A regular expression based principal transformer which uses the regular expression to validate the name.
Principal Decoders
aggregate-principal-decoder
A principal decoder definition where the principal decoder is an aggregation of other principal decoders.
concatenating-principal-decoder
A principal decoder definition where the principal decoder is a concatenation of other principal decoders.
constant-principal-decoder
Definition of a principal decoder that always returns the same constant.
custom-principal-decoder
Definition of a custom principal decoder.
x500-attribute-principal-decoder

Definition of an X500 attribute based principal decoder.

For more information, see Configure Authentication with Certificates in How to Configure Identity Management for JBoss EAP.

x509-subject-alternative-name-evidence-decoder

Evidence decoder to use a subject alternative name extension in an X.509 certificate as the principal.

For more information, see Configuring Evidence Decoder for X.509 Certificate with Subject Alternative Name Extension in How to Configure Server Security for JBoss EAP.

Realm Mappers
constant-realm-mapper
Definition of a constant realm mapper that always returns the same value.
custom-realm-mapper
Definition of a custom realm mapper.
mapped-regex-realm-mapper
Definition of a realm mapper implementation that first uses a regular expression to extract the realm name, this is then converted using the configured mapping of realm names.
simple-regex-realm-mapper
Definition of a simple realm mapper that attempts to extract the realm name using the capture group from the regular expression, if that does not provide a match then the delegate realm mapper is used instead.
Realms
aggregate-realm

A realm definition that is an aggregation of two realms, one for the authentication steps and one for loading the identity for the authorization steps.

Note

The exported legacy security domain cannot be used as Elytron security realm for the authorization step of the aggregate-realm.

caching-realm

A realm definition that enables caching to another security realm. The caching strategy is Least Recently Used, where the least accessed entries are discarded when the maximum number of entries is reached.

For more information, see Set Up Caching for Security Realms in How to Configure Identity Management for JBoss EAP.

custom-modifiable-realm
Custom realm configured as being modifiable will be expected to implement the ModifiableSecurityRealm interface. By configuring a realm as being modifiable management operations will be made available to manipulate the realm.
custom-realm
A custom realm definitions can implement either the s SecurityRealm interface or the ModifiableSecurityRealm interface. Regardless of which interface is implemented management operations will not be exposed to manage the realm. However other services that depend on the realm will still be able to perform a type check and cast to gain access to the modification API.
filesystem-realm

A simple security realm definition backed by the file system.

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.

For more information, see Configure Authentication with a Filesystem-Based Identity Store in How to Configure Identity Management for JBoss EAP.

identity-realm
A security realm definition where identities are represented in the management model.
jdbc-realm

A security realm definition backed by database using JDBC.

For more information, see Configure Authentication with a Database-Based Identity Store in How to Configure Identity Management for JBoss EAP.

key-store-realm

A security realm definition backed by a keystore.

For more information, see Configure Authentication with Certificates in How to Configure Identity Management for JBoss EAP.

ldap-realm

A security realm definition backed by LDAP.

For more information, see Configure Authentication with a LDAP-Based Identity Store in How to Configure Identity Management for JBoss EAP.

properties-realm

A security realm definition backed by properties files.

Configure Authentication with a Properties File-Based Identity Store in How to Configure Identity Management for JBoss EAP.

token-realm
A security realm definition capable of validating and extracting identities from security tokens.
Permission Mappers
custom-permission-mapper
Definition of a custom permission mapper.
logical-permission-mapper
Definition of a logical permission mapper.
simple-permission-mapper
Definition of a simple configured permission mapper.
constant-permission-mapper
Definition of a permission mapper that always returns the same constant.
Role Decoders
custom-role-decoder
Definition of a custom RoleDecoder.
simple-role-decoder

Definition of a simple RoleDecoder that takes a single attribute and maps it directly to roles.

For more information, see Configure Authentication with a Filesystem-Based Identity Store in How to Configure Identity Management for JBoss EAP.

Role Mappers
add-prefix-role-mapper
A role mapper definition for a role mapper that adds a prefix to each provided.
add-suffix-role-mapper
A role mapper definition for a role mapper that adds a suffix to each provided.
aggregate-role-mapper
A role mapper definition where the role mapper is an aggregation of other role mappers.
constant-role-mapper

A role mapper definition where a constant set of roles is always returned.

For more information, see Configure Authentication with Certificates in How to Configure Identity Management for JBoss EAP.

custom-role-mapper
Definition of a custom role mapper.
logical-role-mapper
A role mapper definition for a role mapper that performs a logical operation using two referenced role mappers.
mapped-role-mapper
A role mapper definition for a role mapper that uses preconfigured mapping of role names.
SSL Components
client-ssl-context

An SSLContext for use on the client side of a connection.

For more information, see Using a client-ssl-context in How to Configure Server Security for JBoss EAP.

filtering-key-store

A filtering keystore definition, which provides a keystore by filtering a key-store.

For more information, see Using a filtering-key-store in How to Configure Server Security for JBoss EAP.

key-manager

A key manager definition for creating the key manager list as used to create an SSL context.

For more information, see Enable One-way SSL/TLS for the Management Interfaces Using the Elytron Subsystem in How to Configure Server Security for JBoss EAP.

key-store

A keystore definition.

For more information, see Enable One-way SSL/TLS for the Management Interfaces Using the Elytron Subsystem in How to Configure Server Security for JBoss EAP.

ldap-key-store

An LDAP keystore definition, which loads a keystore from an LDAP server.

For more information, see Using an ldap-key-store in How to Configure Server Security for JBoss EAP.

server-ssl-context

An SSL context for use on the server side of a connection.

For more information, see Enable One-way SSL/TLS for the Management Interfaces Using the Elytron Subsystem in How to Configure Server Security for JBoss EAP.

trust-manager

A trust manager definition for creating the TrustManager list as used to create an SSL context.

For more information, see Enable Two-way SSL/TLS for the Management Interfaces using the Elytron Subsystem in How to Configure Server Security for JBoss EAP.

Other
aggregate-providers
An aggregation of two or more provider-loader resources.
authentication-configuration
An individual authentication configuration definition, which is used by clients deployed to JBoss EAP and other resources for authenticating when making a remote connection.
authentication-context
An individual authentication context definition, which is used to supply an ssl-context and authentication-configuration when clients deployed to JBoss EAP and other resources make a remoting connection.
credential-store

Credential store to keep alias for sensitive information such as passwords for external services.

For more information, see Create a Credential Store in How to Configure Server Security for JBoss EAP.

dir-context

The configuration to connect to a directory (LDAP) server.

For more information, see Using an ldap-key-store in How to Configure Server Security for JBoss EAP.

provider-loader
A definition for a provider loader.
security-domain

A security domain definition.

For more information, see Configure Authentication with Certificates in How to Configure Identity Management for JBoss EAP.

security-property
A definition of a security property to be set.

2.7. Core Management Authentication

Core management authentication is responsible for securing the management interfaces, HTTP and native, for the core management functionality using the ManagementRealm. It is built into the core management and is enabled and configured as a core service by default. It is only responsible for securing the management interfaces.

2.7.1. Security Realms

A security realm is an identity store of usernames, passwords, and group membership information that can be used when authenticating users in EJBs, web applications, and the management interface. Initially, JBoss EAP comes preconfigured with two security realms by default: ManagementRealm and ApplicationRealm. Both security realms use the file system to store mappings between users and passwords and users and group membership information. They both use a digest mechanism by default when authenticating.

A digest mechanism is an authentication mechanism that authenticates the user by making use of one-time, one-way hashes comprising various pieces of information, including information stored in the usernames and passwords mapping property file. This allows JBoss EAP to authenticate users without sending any passwords in plain text over the network.

The JBoss EAP installation contains a script that enables administrators to add users to both realms. When users are added in this way, the username and hashed password are stored in the corresponding usernames and passwords properties file. When a user attempts to authenticate, JBoss EAP sends back a one-time use number, nonce, to the client. The client then generates a one-way hash using its username, password, nonce, and a few other fields, and sends the username, nonce, and one-way hash to JBoss EAP. JBoss EAP looks up the user’s prehashed password and uses it, along with the provided username, nonce, and a few other fields, to generate another one-way hash in the same manner. If all the same information is used on both sides, including the correct password, hashes will match and the user is authenticated.

Although security realms use the digest mechanism by default, they may be reconfigured to use other authentication mechanisms. On startup, the management interfaces determine which authentication mechanisms will be enabled based on what authentication mechanisms are configured in ManagementRealm.

Security realms are not involved in any authorization decisions; however, they can be configured to load a user’s group membership information, which can subsequently be used to make authorization decisions. After a user has been authenticated, a second step occurs to load the group membership information based on the username.

By default, the ManagementRealm is used during authentication and authorization for the management interfaces. The ApplicationRealm is a default realm made available for web applications and EJBs to use when authenticating and authorizing users.

2.7.2. Default Security

By default, the core management authentication secures each of the management interfaces, HTTP and native, in two different forms: local clients and remote clients, both of which are configured using the ManagementRealm security realm by default. These defaults may be configured differently or replaced entirely.

Note

Out of the box, the management interfaces are configured to use simple access controls, which does not use roles. As a result, all users by default, when using simple access controls, have the same privileges as the SuperUser role, which essentially has access to everything.

2.7.2.1. Local and Remote Client Authentication with the Native Interface

The native interface, or management CLI, can be invoked locally on the same host as the running JBoss EAP instance or remotely from another machine. When attempting to connect using the native interface, JBoss EAP presents the client with a list of available SASL authentication mechanisms, for example, local jboss user, BASIC, etc. The client chooses its desired authentication mechanism and attempts to authenticate with the JBoss EAP instance. If it fails, it retries with any remaining mechanisms or stops attempting to connect. Local clients have the option to use the local jboss user authentication mechanism. This security mechanism is based on the client’s ability to access the local file system. It validates that the user attempting to log in actually has access to the local file system on the same host as the JBoss EAP instance.

This authentication mechanism happens in four steps:

  1. The client sends a message to the server that includes a request to authenticate using local jboss user.
  2. The server generates a one-time token, writes it to a unique file, and sends a message to the client with the full path of the file.
  3. The client reads the token from the file and sends it to the server, verifying that it has local access to the file system.
  4. The server verifies the token and then deletes the file.

This form of authentication is based on the principle that if physical access to the file system is achieved, other security mechanisms are superfluous. The reasoning is that if a user has local file system access, that user has enough access to create a new user or otherwise thwart other security mechanisms put in place. This is sometimes referred to as silent authentication because it allows the local user to access the management CLI without username or password authentication.

This functionality is enabled as a convenience and to assist local users running management CLI scripts without requiring additional authentication. It is considered a useful feature given that access to the local configuration typically also gives the user the ability to add their own user details or otherwise disable security checks.

The native interface can also be accessed from other servers, or even the same server, as a remote client. When accessing the native interface as a remote client, clients will not be able to authenticate using local jboss user and will be forced to use another authentication mechanism, for example, DIGEST. If a local client fails to authenticate by using local jboss user, it will automatically fall back and attempt to use the other mechanisms as a remote client.

Note

The management CLI may be invoked from other servers, or even the same server, using the HTTP interface as opposed to the native interface. All HTTP connections, CLI or otherwise, are considered to be remote and NOT covered by local interface authentication.

Important

By default, the native interface is not configured, and all management CLI traffic is handled by the HTTP interface. JBoss EAP 7 supports HTTP upgrade, which allows a client to make an initial connection over HTTP but then send a request to upgrade that connection to another protocol. In the case of the management CLI, an initial request over HTTP to the HTTP interface is made, but then the connection is upgraded to the native protocol. This connection is still handled over the HTTP interface, but it is using the native protocol for communication rather than HTTP. Alternatively, the native interface may still be enabled and used if desired.

2.7.2.2. Local and Remote Client Authentication with the HTTP Interface

The HTTP interface can be invoked locally by clients on the same host as the running JBoss EAP instance or remotely by clients from another machine. Despite allowing local and remote clients to access the HTTP interface, all clients accessing the HTTP interface are treated as remote connections.

When a client attempts to connect to the HTTP management interfaces, JBoss EAP sends back an HTTP response with a status code of 401 Unauthorized, and a set of headers that list the supported authentication mechanisms, for example, Digest, GSSAPI, and so on. The header for Digest also includes the nonce generated by JBoss EAP. The client looks at the headers and chooses which authentication method to use and sends an appropriate response. In the case where the client chooses Digest, it prompts the user for their username and password. The client uses the supplied fields such as username and password, the nonce, and a few other pieces of information to generate a one-way hash. The client then sends the one-way hash, username, and nonce back to JBoss EAP as a response. JBoss EAP takes that information, generates another one-way hash, compares the two, and authenticates the user based on the result.

2.7.3. Advanced Security

There are a number of ways to change the default configuration of management interfaces as well as the authentication and authorization mechanisms to affect how it is secured.

2.7.3.1. Updating the Management Interfaces

In addition to modifying the Authentication and Authorization mechanisms, JBoss EAP allows administrators to update the configuration of the management interface itself. There are a number of options.

Configuring the Management Interfaces to Use One-way SSL/TLS
Configuring the JBoss EAP management console for communication only using one-way SSL/TLS provides increased security. All network traffic between the client and management console is encrypted, which reduces the risk of security attacks, such as a man-in-the-middle attack. Anyone administering a JBoss EAP instance has greater permissions on that instance than non-privileged users, and using one-way SSL/TLS helps protect the integrity and availability of that instance. When configuring one-way SSL/TLS with JBoss EAP, authority-signed certificates are preferred over self-signed certificates because they provide a chain of trust. Self-signed certificates are permitted but are not recommended.
Using Two-way SSL/TLS
Two-way SSL/TLS authentication, also known as client authentication, authenticates the client and the server using SSL/TLS certificates. This provides assurance that not only is the server what it says it is, but the client is also what it says it is.
Updating or Creating a New Security Realm
The default security realm can be updated or replaced with a new security realm.

2.7.3.2. Adding Outbound Connections

Some security realms connect to external interfaces, such as an LDAP server. An outbound connection defines how to make this connection. A predefined connection type, ldap-connection, sets all of the required and optional attributes to connect to the LDAP server and verify the credential.

2.7.3.3. Adding RBAC to the Management Interfaces

By default the RBAC system is disabled. It is enabled by changing the provider attribute from simple to rbac. This can be done using the management CLI. When RBAC is disabled or enabled on a running server, the server configuration must be reloaded before it takes effect.

When RBAC is enabled for the management interfaces, the role assigned to a user determines the resources to which they have access and what operations they can conduct with a resource’s attributes. Only users of the Administrator or SuperUser role can view and make changes to the access control system.

Warning

Enabling RBAC without having users and roles properly configured could result in administrators being unable to log in to the management interfaces.

RBAC’s Effect on the Management Console

In the management console, some controls and views are disabled, which show up as grayed out, or not visible at all, depending on the permissions of the role the user has been assigned.

If the user does not have read permissions to a resource attribute, that attribute will appear blank in the console. For example, most roles cannot read the username and password fields for data sources.

If the user has read permissions but does not have write permissions to a resource attribute, that attribute will be disabled in the edit form for the resource. If the user does not have write permissions to the resource, the edit button for the resource will not appear.

If a user does not have permissions to access a resource or attribute, meaning it is unaddressable for that role, it will not appear in the console for that user. An example of that is the access control system itself, which is only visible to a few roles by default.

The management console also provides an interface for the following common RBAC tasks:

  • View and configure what roles are assigned to, or excluded from, each user.
  • View and configure what roles are assigned to, or excluded from, each group.
  • View group and user membership per role.
  • Configure default membership per role.
  • Create a scoped role.
Note

Constraints cannot be configured in the management console at this time.

RBAC’s Effect on the Management CLI or Management API

Users of the management CLI or management API will encounter slightly different behavior when RBAC is enabled.

Resources and attributes that cannot be read are filtered from results. If the filtered items are addressable by the role, their names are listed as filtered-attributes in the response-headers section of the result. If a resource or attribute is not addressable by the role, it is not listed.

Attempting to access a resource that is not addressable will result in a Resource Not Found error.

If a user attempts to write or read a resource that they can address but lacks the appropriate write or read permissions, a Permission Denied error is returned.

The management CLI can perform all of same RBAC tasks as the management console as well as a few additional tasks:

  • Enable and disable RBAC
  • Change permission combination policy
  • Configuring application resource and resource sensitivity constraints

RBAC’s Effect on JMX Managed Beans

Role-Based Access Control applies to JMX in three ways:

  1. The management API of JBoss EAP is exposed as JMX managed beans. These managed beans are referred to as core mbeans, and access to them is controlled and filtered exactly the same as the underlying management API itself.
  2. The jmx subsystem is configured with write permissions being sensitive. This means only users of the Administrator and SuperUser roles can make changes to that subsystem. Users of the Auditor role can also read this subsystem configuration.
  3. By default, managed beans registered by deployed applications and services, or non-core MBeans, can be accessed by all management users, but only users of the Maintainer, Operator, Administrator, and SuperUser roles can write to them.

RBAC Authentication

RBAC works with the standard authentication providers that are included with JBoss EAP:

Username/Password
Users are authenticated using a username and password combination that is verified according to the settings of the ManagementRealm, which has the ability to use a local properties file or LDAP.
Client Certificate
The truststore provides authentication information for client certificates.
local jboss user
The jboss-cli script authenticates automatically as local jboss user if the server is running on the same machine. By default local jboss user is a member of the SuperUser group.

Regardless of which provider is used, JBoss EAP is responsible for assigning roles to users. When authenticating with the ManagementRealm or an LDAP server, those systems can supply user group information. This information can also be used by JBoss EAP to assign roles to users.

2.7.3.4. Using LDAP with the Management Interfaces

JBoss EAP includes several authentication and authorization modules that allow an LDAP server to be used as the authentication and authorization authority for web and EJB applications.

To use an LDAP directory server as the authentication source for the management console, management CLI, or management API, the following tasks must be performed:

  1. Create an outbound connection to the LDAP server.
  2. Create an LDAP-enabled security realm or update an existing security realm to use LDAP.
  3. Reference the new security realm in the management interface.

The LDAP authenticator operates by first establishing a connection to the remote directory server. It then performs a search using the username, which the user passed to the authentication system, to find the fully qualified distinguished name (DN) of the LDAP record. A new connection to the LDAP server is established, using the DN of the user as the credential and password supplied by the user. If this authentication to the LDAP server is successful, the DN is verified as valid.

Once an LDAP-enabled security realm is created, it can be referenced by the management interface. The management interface will use the security realm for authentication. JBoss EAP can also be configured to use an outbound connection to an LDAP server using two-way SSL/TLS for authentication in the management interface and management CLI.

2.7.3.5. JAAS and the Management Interfaces

JAAS can be used to secure the management interfaces. When using JAAS for the management interfaces, the security realm must be configured to use a security domain. This introduces a dependency between core services and the subsystems. While SSL/TLS is not required to use JAAS to secure the management interfaces, it is recommended that administrators enable SSL/TLS to avoid accidentally transmitting sensitive information in an unsecured manner.

Note

When JBoss EAP instances are running in admin-only mode, using JAAS to secure the management interfaces is not supported. For more information on admin-only mode, see Running JBoss EAP in Admin-only Mode in the JBoss EAP Configuration Guide.

2.8. Security Subsystem

The security subsystem provides security infrastructure for applications and is based on the JAAS API. The subsystem uses a security context associated with the current request to expose the capabilities of the authentication manager, authorization manager, audit manager, and mapping manager to the relevant container.

The authentication and authorization managers handle authentication and authorization. The mapping manager handles adding, modifying, or deleting information from a principal, role, or attribute before passing the information to the application. The auditing manager allows users to configure provider modules to control the way that security events are reported.

In most cases, administrators should need to focus only on setting up and configuring security domains in regards to updating the configuration of the security subsystem. Outside of security domains, the only security element that may need to be changed is deep-copy-subject-mode. See the Security Management section for more information on deep copy subject mode.

2.8.1. Security Domains

A security domain is a set of Java Authentication and Authorization Service (JAAS) declarative security configurations that one or more applications use to control authentication, authorization, auditing, and mapping. Four security domains are included by default: jboss-ejb-policy, jboss-web-policy, other, and jaspitest. The jboss-ejb-policy and jboss-web-policy security domains are the default authorization mechanisms for the JBoss EAP instance. They are used if an application’s configured security domain does not define any authentication mechanisms. Those security domains, along with other, are also used internally within JBoss EAP for authorization and are required for correct operation. The jaspitest security domain is a simple JASPI security domain included for development purposes.

A security domain comprises configurations for authentication, authorization, security mapping, and auditing. Security domains are part of the JBoss EAP security subsystem and are managed centrally by the domain controller or standalone server. Users can create as many security domains as needed to accommodate application requirements.

You can also configure the type of authentication cache to be used by a security domain, using the cache-type attribute. If this attribute is removed, no cache will be used. The allowed values for this property are default or infinispan.

Comparison Between Elytron and PicketBox Security Domains

A deployment should be associated with either a single Elytron security domain or one or more legacy PicketBox security domain. A deployment should not be associated with both. That is an invalid configuration.

An exception occurs if a deployment is associated with more than one Elytron security domain, whereas a deployment can be associated with multiple legacy security domains.

Note

When working with PicketBox, the security domain encapsulates both access to the underlying identity store and the mapping for authorization decisions. Thus, users of PicketBox with different stores are required to use different security domains for different sources.

In Elytron, these two functions are separated. Access to the stores is handled by security realms and mapping for authorization is handled by security domains.

So, a deployment requiring independent PicketBox security domains does not necessarily require independent Elytron security domains.

2.8.2. Using Security Realms and Security Domains

Security realms and security domains can be used to secure web applications deployed to JBoss EAP. When deciding if either should be used, it is important to understand the difference between the two.

Web applications and EJB deployments can only use security domains directly. They perform the actual authentication and authorization using login modules using the identity information passed from an identity store. Security domains can be configured to use security realms for identity information; for example, other allows applications to specify a security realm to use for authentication and getting authorization information. They can also be configured to use external identity stores. Web applications and EJB deployments cannot be configured to directly use security realms for authentication. The security domains are also part of the security subsystem and are loaded after core services.

Only the core management, for example the management interfaces and the EJB remoting endpoints, can use the security realms directly. They are identity stores that provide authentication as well as authorization information. They are also a core service and are loaded before any subsystems are started. The out-of-the-box security realms, ManagementRealm and ApplicationRealm, use a simple file-based authentication mechanism, but they can be configured to use other mechanisms.

2.8.3. Security Auditing

Security auditing refers to triggering events, such as writing to a log, in response to an event that happens within the security subsystem. Auditing mechanisms are configured as part of a security domain, along with authentication, authorization, and security mapping details. Auditing uses provider modules to control the way that security events are reported. JBoss EAP ships with several security auditing providers, but custom ones may be used. The core management of JBoss EAP also has its own security auditing and logging functionality, which is configured separately and is not part of the security subsystem.

2.8.4. Security Mapping

Security mapping adds the ability to combine authentication and authorization information after the authentication or authorization happens but before the information is passed to your application. Roles for authorization, principals for authentication, or credentials which are attributes that are not principals or roles, may all be mapped. Role mapping is used to add, replace, or remove roles to the subject after authentication. Principal mapping is used to modify a principal after authentication. You can use credential mapping to convert attributes from an external system to be used by your application. You can also use credential mapping conversely, to convert attributes from your application for use by an external system.

2.8.5. Password Vault System

JBoss EAP has a password vault to encrypt sensitive strings, store them in an encrypted keystore, and decrypt them for applications and verification systems. In plain text configuration files, such as XML deployment descriptors, it is sometimes necessary to specify passwords and other sensitive information. The JBoss EAP password vault can be used to securely store sensitive strings for use in plain text files.

2.8.6. Security Domain Configuration

Security domains are configured centrally either at the domain controller or on the standalone server. When security domains are used, an application may be configured to use a security domain in lieu of individually configuring security. This allows users and administrators to leverage Declarative Security.

Example

One common scenario that benefits from this type of configuration structure is the process of moving applications between testing and production environments. If an application has its security individually configured, it may need to be updated every time it is promoted to a new environment, for example, from a testing environment to a production environment. If that application used a security domain instead, the JBoss EAP instances in the individual environments would have their security domains properly configured for the current environment, allowing the application to rely on the container to provide the proper security configuration, using the security domain.

2.8.6.1. Login Modules

JBoss EAP includes several bundled login modules suitable for most user management roles that are configured within a security domain. The security subsystem offers some core login modules that can read user information from a relational database, an LDAP server, or flat files. In addition to these core login modules, JBoss EAP provides other login modules that provide user information and functionality for customized needs.

Summary of Commonly Used Login Modules

Ldap Login Module
The Ldap login module is a login module implementation that authenticates against an LDAP server. The security subsystem connects to the LDAP server using connection information, that is, a bindDN that has permissions to search the baseCtxDN and rolesCtxDN trees for the user and roles, provided using a JNDI initial context. When a user attempts to authenticate, the LDAP login module connects to the LDAP server and passes the user’s credentials to the LDAP server. Upon successful authentication, an InitialLDAPContext is created for that user within JBoss EAP, populated with the user’s roles.
LdapExtended Login Module
The LdapExtended login module searches for the user as well as the associated roles to bind for authentication. The roles query recursively and follow DNs to navigate a hierarchical role structure. The login module options include whatever options are supported by the chosen LDAP JNDI provider supports.
UsersRoles Login Module
The UsersRoles login module is a simple login module that supports multiple users and user roles loaded from Java properties files. The primary purpose of this login module is to easily test the security settings of multiple users and roles using properties files deployed with the application.
Database Login Module
The Database login module is a Java Database Connectivity-based (JDBC) login module that supports authentication and role mapping. This login module is used if username, password, and role information are stored in a relational database. This works by providing a reference to logical tables containing principals and roles in the expected format.
Certificate Login Module
The Certificate login module authenticates users based on X509 certificates. A typical use case for this login module is CLIENT-CERT authentication in the web tier. This login module only performs authentication and must be combined with another login module capable of acquiring authorization roles to completely define access to secured web or EJB components. Two subclasses of this login module, CertRolesLoginModule and DatabaseCertLoginModule, extend the behavior to obtain the authorization roles from either a properties file or database.
Identity Login Module
The Identity login module is a simple login module that associates a hard-coded username to any subject authenticated against the module. It creates a SimplePrincipal instance using the name specified by the principal option. This login module is useful when a fixed identity is required to be provided to a service. This can also be used in development environments for testing the security associated with a given principal and associated roles.
RunAs Login Module
The RunAs login module is a helper module that pushes a run-as role onto the stack for the duration of the login phase of authentication; it then pops the run-as role from the stack in either the commit or abort phase. The purpose of this login module is to provide a role for other login modules that must access secured resources to perform their authentication, for example, a login module that accesses a secured EJB. The RunAs login module must be configured ahead of the login modules that require a run as role established.
Client Login Module
The Client login module is an implementation of a login module for use by JBoss clients when establishing caller identity and credentials. This creates a new SecurityContext, assigns it a principal and a credential, and sets the SecurityContext to the ThreadLocal security context. The Client login module is the only supported mechanism for a client to establish the current thread’s caller. Both standalone client applications and server environments, acting as JBoss EJB clients where the security environment has not been configured to use the JBoss EAP security subsystem transparently, must use the Client login module.
Warning

This login module does not perform any authentication. It merely copies the login information provided to it into the server EJB invocation layer for subsequent authentication on the server. Within JBoss EAP, this is only supported for switching a user’s identity for in-JVM calls. This is not supported for remote clients to establish an identity.

SPNEGO Login Module
The SPNEGO login module is an implementation of a login module that establishes caller identity and credentials with a KDC. The module implements SPNEGO and is a part of the JBoss Negotiation project. This authentication can be used in the chained configuration with the AdvancedLdap login module to allow cooperation with an LDAP server. Web applications must also enable the NegotiationAuthenticator within the application to use this login module.
RoleMapping Login Module
The RoleMapping login module supports mapping roles that are the end result of the authentication process to one or more declarative roles. For example, if the authentication process has determined that the user John has the roles ldapAdmin and testAdmin, and the declarative role defined in the web.xml or ejb-jar.xml file for access is admin, then this login module maps the ldapAdmin and testAdmin roles to John. The RoleMapping login module must be defined as an optional module to a login module configuration as it alters mapping of the previously mapped roles.
Remoting Login Module
The Remoting login module checks if the request that is currently being authenticated was received over the remoting connection. In cases where the request was received using the remoting interface, that request is associated with the identity created during the authentication process.
RealmDirect Login Module
The RealmDirect login module allows an existing security realm to be used in making authentication and authorization decisions. When configured, this module will look up identity information using the referenced realm for making authentication decisions and mapping user roles. For example, the preconfigured other security domain that ships with JBoss EAP has a RealmDirect login module. If no realm is referenced in this module, the ApplicationRealm security realm is used by default.
Custom Modules
In cases where the login modules bundled with the JBoss EAP security framework do not meet the needs of the security environment, a custom login module implementation may be written. The AuthenticationManager requires a particular usage pattern of the Subject principals set. A full understanding of the JAAS Subject class’s information storage features and the expected usage of these features are required to write a login module that works with the AuthenticationManager.

The UnauthenticatedIdentity login module option is also commonly used. There are certain cases when requests are not received in an authenticated format. The Unauthenticated Identity is a login module configuration option that assigns a specific identity, for example, guest, to requests that are made with no associated authentication information. This can be used to allow unprotected servlets to invoke methods on EJBs that do not require a specific role. Such a principal has no associated roles and can only access either unsecured EJBs or EJB methods that are associated with the unchecked permission constraint.

2.8.6.2. Password Stacking

Multiple login modules can be chained together in a stack, with each login module providing the credentials verification and role assignment during authentication. This works for many use cases, but sometimes credentials verification and role assignment are split across multiple user management stores.

Consider the case where users are managed in a central LDAP server and application-specific roles are stored in the application’s relational database. The password-stacking module option captures this relationship.

To use password stacking, each login module should set the password-stacking attribute to useFirstPass, which is located in the <module-option> section. If a previous module configured for password stacking has authenticated the user, all the other stacking modules will consider the user authenticated and only attempt to provide a set of roles for the authorization step.

When the password-stacking option is set to useFirstPass, this module first looks for a shared username and password under the property names javax.security.auth.login.name and javax.security.auth.login.password, respectively, in the login module shared state map.

If found, these properties are used as the principal name and password. If not found, the principal name and password are set by this login module and stored under the property names javax.security.auth.login.name and javax.security.auth.login.password, respectively.

2.8.6.3. Password Hashing

Most login modules must compare a client-supplied password to a password stored in a user management system. These modules generally work with plain text passwords, but they can be configured to support hashed passwords to prevent plain text passwords from being stored on the server side. JBoss EAP supports the ability to configure the hashing algorithm, encoding, and character set. It also defines when the user password and store password are hashed.

Important

Red Hat JBoss Enterprise Application Platform Common Criteria certified configuration does not support hash algorithms weaker than SHA-256.

2.8.7. Security Management

The security management portion of the security subsystem is used to override the high-level behaviors of the security subsystem. Each setting is optional. It is unusual to change any of these settings except for the deep copy subject mode.

2.8.7.1. Deep Copy Mode

If the deep copy subject mode is disabled, which it is by default, copying a security data structure makes a reference to the original rather than copying the entire data structure. This behavior is more efficient, but it is prone to data corruption if multiple threads with the same identity clear the subject by means of a flush or logout operation.

If the deep copy subject mode is enabled, a complete copy of the data structure, along with all its associated data as long as they are marked cloneable, is made. This is more thread-safe but less efficient.

2.8.8. Additional Components

2.8.8.1. JASPI

Java Authentication SPI for Containers (JASPI or JASPIC) is a pluggable interface for Java applications and is defined in JSR-196. In addition to JAAS authentication, JBoss EAP allows for JASPI authentication to be used. JASPI authentication is configured using login modules in a security domain, and those modules may be stacked. The jaspitest security domain is a simple JASPI security domain that is included by default for development purposes.

The web-based administration console provides the following operations to configure the JASPI module:

  • add
  • edit
  • remove
  • reset

Applications deployed to JBoss EAP require a special authenticator to be configured in their deployment descriptors to use the JASPI security domains.

2.8.8.2. JACC

Java Authorization Contract for Containers (JACC) is a standard that defines a contract between containers and authorization service providers, which results in the implementation of providers for use by containers. It was defined in JSR-115 and has been part of the core Java EE specification since version 1.3.

JBoss EAP implements support for JACC within the security functionality of the security subsystem.

2.8.8.3. Java EE Security API

The Java EE Security API, defined in JSR-375, defines portable plug-in interfaces for authentication and identity stores, and a new injectable-type SecurityContext interface that provides an access point for programmatic security. You can use the built-in implementations of these APIs, or define custom implementations. For details about the specifications, see Java EE Security API Specification.

The Java EE Security API is available in the elytron subsystem and can be enabled from the management CLI. For more information, see About Java EE Security API in the Development Guide.

2.8.8.4. About Fine-Grained Authorization and XACML

Fine-grained authorization allows administrators to adapt to the changing requirements and multiple variables involved in the decision making process for granting access to a module. As a result, fine-grained authorization can become complex.

Note

The XACML bindings, for web or EJB, are not supported in JBoss EAP.

JBoss EAP uses XACML as a medium to achieve fine-grained authorization. XACML provides standards-based solution to the complex nature of achieving fine-grained authorization. XACML defines a policy language and an architecture for decision making. The XACML architecture includes a Policy Enforcement Point (PEP) which intercepts any requests in a normal program flow and asks a Policy Decision Point (PDP) to make an access decision based on the policies associated with the PDP. The PDP evaluates the XACML request created by the PEP and runs through the policies to make one of the following access decisions.

PERMIT
The access is approved.
DENY
The access is denied.
INDETERMINATE
There is an error at the PDP.
NOTAPPLICABLE
There is some attribute missing in the request or there is no policy match.

XACML also has the following features:

  • Oasis XACML v2.0 library
  • JAXB v2.0 based object model
  • ExistDB integration for storing and retrieving XACML policies and attributes

2.8.8.5. SSO

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

  • A configured security domain that handles authentication and authorization.
  • The SSO infinispan replication cache. It is present in the ha and full-ha profiles for a managed domain, or by using the standalone-ha.xml or standalone-full-ha.xml configuration files for a standalone server.
  • The web cache-container and SSO replication cache within it must be present.
  • The undertow subsystem needs to be configured to use SSO.
  • Each application that will share the SSO information must be configured to use the same security domain.