Skip to end of metadata
Go to start of metadata

The security subsystem is the subsystem that brings the security services provided by PicketBox to the JBoss Application Server 7 server instances.

If you are looking to secure the management interfaces for the management of the domain then you should read the Securing the Management Interfaces chapter as the management interfaces themselves are not run within an application server process so use a custom configuration.

Structure of the Security Subsystem

When deploying applications to the JBoss Application Server most of the time it is likely that you would be deploying a web application or EJBs and just require a security domain to be defined with login modules to verify the users identity, this chapter aims to provider additional detail regarding the architecture and capability of the security subsystem however if you are just looking to define a security domain and leave the rest to the container please jump to the security-domains section.

The security subsystem operates by using a security context associated with the current request, this security context then makes available to the relevant container a number of capabilities from the configured security domain, the capabilities exposed are an authentication manager, an authorization manager, an audit manager and a mapping manager.

Authentication Manager

The authentication manager is the component that performs the actual authentication taking the declared users identity and their credential so that the login context for the security domain can be used to 'login' the user using the configured login module or modules.

Authorization Manager

The authorization manager is a component which can be obtained by the container from the current security context to either obtain information about a users roles or to perform an authorization check against a resource for the currently authenticated user.

Audit Manager

The audit manager from the security context is the component that can be used to log audit events in relation to the security domain.

Mapping Manager

The mapping manager can be used to assign additional principals, credentials, roles or attributes to the authenticated subject.

Security Subsystem Configuration

By default a lot of defaults have already been selected for the security subsystem and unless there is a specific implementation detail you need to change, these defaults should not require modification. This chapter describes all of the possible configuration attributes for completeness but do keep in mind that not all will need to be changed.

The security subsystem is enabled by default by the addition of the following extension: -

<extension module="org.jboss.as.security"/>

The namespace used for the configuration of the security subsystem is urn:jboss:domain:security:1.0, the configuration is defined within the <subsystem> element from this namespace.

The <subsystem> element can optionally contain the following child elements.

  • security-management
  • subject-factory
  • security-domains
  • security-properties

security-management

This element is used to override some of the high level implementation details of the PicketBox implementation if you have a need to change some of this behaviour.

The element can have any or the following attributes set, all of which are optional.

authentication-manager-class-name Specifies the AuthenticationManager implementation class name to use.
deep-copy-subject-mode Sets the copy mode of subjects done by the security managers to be deep copies that makes copies of the subject principals and credentials if they are cloneable. It should be set to true if subject include mutable content that can be corrupted when multiple threads have the same identity and cache flushes/logout clearing the subject in one thread results in subject references affecting other threads. Default value is "false".
default-callback-handler-class-name Specifies a global class name for the CallbackHandler implementation to be used with login modules.
authorization-manager-class-name Attribute specifies the AuthorizationManager implementation class name to use.
audit-manager-class-name Specifies the AuditManager implementation class name to use.
identity-trust-manager-class-name Specifies the IdentityTrustManager implementation class name to use.
mapping-manager-class-name Specifies the MappingManager implementation class name to use.

subject-factory

The subject factory is responsible for creating subject instances, this also makes use of the authentication manager to actually verify the caller. It is used mainly by JCA components to establish a subject. It is not likely this would need to be overridden but if it is required the "subject-factory-class-name" attribute can be specified on the subject-factory element.

security-domains

This portion of the configuration is where the bulk of the security subsystem configuration will actually take place for most administrators, the security domains contain the configuration which is specific to a deployment.

The security-domains element can contain numerous <security-domain> definitions, a security-domain can have the following attributes set:

name
The unique name of this security domain.
extends
The optional name of a security domain extended by this security domain.
cache-type
The type of authentication cache to use with this domain. If this attribute is removed no cache will be used. Allowed values are "default" or "infinispan"

The following elements can then be set within the security-domain to configure the domain behaviour.

authentication

The authentication element is used to hold the list of login modules that will be used for authentication when this domain is used, the structure of the login-module element is:

The code attribute is used to specify the implementing class of the login module which can either be the full class name or one of the abbreviated names from the following list:

Code
Classname
Client
org.jboss.security.ClientLoginModule
Certificate
org.jboss.security.auth.spi.BaseCertLoginModule
CertificateUsers
org.jboss.security.auth.spi.BaseCertLoginModule
CertificateRoles
org.jboss.security.auth.spi.CertRolesLoginModule
Database
org.jboss.security.auth.spi.DatabaseServerLoginModule
DatabaseCertificate
org.jboss.security.auth.spi.DatabaseCertLoginModule
DatabaseUsers
org.jboss.security.auth.spi.DatabaseServerLoginModule
Identity
org.jboss.security.auth.spi.IdentityLoginModule
Ldap
org.jboss.security.auth.spi.LdapLoginModule
LdapExtended
org.jboss.security.auth.spi.LdapExtLoginModule
RoleMapping
org.jboss.security.auth.spi.RoleMappingLoginModule
RunAs
org.jboss.security.auth.spi.RunAsLoginModule
Simple
org.jboss.security.auth.spi.SimpleServerLoginModule
ConfiguredIdentity
org.picketbox.datasource.security.ConfiguredIdentityLoginModule
SecureIdentity
org.picketbox.datasource.security.SecureIdentityLoginModule
PropertiesUsers
org.jboss.security.auth.spi.PropertiesUsersLoginModule
SimpleUsers
org.jboss.security.auth.spi.SimpleUsersLoginModule
LdapUsers
org.jboss.security.auth.spi.LdapUsersLoginModule
Kerberos
com.sun.security.auth.module.Krb5LoginModule
SPNEGOUsers
org.jboss.security.negotiation.spnego.SPNEGOLoginModule
AdvancedLdap
org.jboss.security.negotiation.AdvancedLdapLoginModule
AdvancedADLdap
org.jboss.security.negotiation.AdvancedADLoginModule
UsersRoles
org.jboss.security.auth.spi.UsersRolesLoginModule

The flag attribute is used to specify the JAAS flag for this module and should be one of required, requisite, sufficient, or optional.

The module-option element can be repeated zero or more times to specify the module options as required for the login module being configured. It requires the name and value attributes.

authentication-jaspi

The authentication-jaspi is used to configure a Java Authentication SPI (JASPI) provider as the authentication mechanism. A security domain can have either a <authentication> or a <authentication-jaspi> element, but not both. We set up JASPI by configuring one or more login modules inside the login-module-stack element and setting up an authentication module. Here is the structure of the authentication-jaspi element:

The login-module-stack-ref attribute value must be the name of the login-module-stack element to be used. The sub-element login-module is configured just like in the authentication part

authorization

Authorization in the AS container is normally done with RBAC (role based access control) but there are situations where a more fine grained authorization policy is required. The authorization element allows definition of different authorization modules to used, such that authorization can be checked with JACC (Java Authorization Contract for Containers) or XACML (eXtensible Access Control Markup Language). The structure of the authorization element is:

The code attribute is used to specify the implementing class of the policy module which can either be the full class name or one of the abbreviated names from the following list:

Code
Classname
DenyAll
org.jboss.security.authorization.modules.AllDenyAuthorizationModule
PermitAll
org.jboss.security.authorization.modules.AllPermitAuthorizationModule
Delegating
org.jboss.security.authorization.modules.DelegatingAuthorizationModule
Web
org.jboss.security.authorization.modules.WebAuthorizationModule
JACC
org.jboss.security.authorization.modules.JACCAuthorizationModule
XACML
org.jboss.security.authorization.modules.XACMLAuthorizationModule

The flag attribute is used to specify the JAAS flag for this module and should be one of required, requisite, sufficient, or optional.

The module-option element can be repeated zero or more times to specify the module options as required for the login module being configured. It requires the name and value attributes.

mapping

The mapping element defines additional mapping of principals, credentials, roles and attributes for the subject. The structure of the mapping element is:

The code attribute is used to specify the implementing class of the login module which can either be the full class name or one of the abbreviated names from the following list:

Code
Classname
PropertiesRoles
org.jboss.security.mapping.providers.role.PropertiesRolesMappingProvider
SimpleRoles
org.jboss.security.mapping.providers.role.SimpleRolesMappingProvider
DeploymentRoles
org.jboss.security.mapping.providers.DeploymentRolesMappingProvider
DatabaseRoles
org.jboss.security.mapping.providers.role.DatabaseRolesMappingProvider
LdapRoles
org.jboss.security.mapping.providers.role.LdapRolesMappingProvider

The type attribute reflects the type of mapping of the provider and should be one of principal, credential, role or attribute. By default "role" is the type used if the attribute is not set.

The module-option element can be repeated zero or more times to specify the module options as required for the login module being configured. It requires the name and value attributes.

audit

The audit element can be used to define a custom audit provider. The default implementation used is org.jboss.security.audit.providers.LogAuditProvider. The structure of the audit element is:

The code attribute is used to specify the implementing class of the provider module.

The module-option element can be repeated zero or more times to specify the module options as required for the login module being configured. It requires the name and value attributes.

jsse

The jsse element defines configuration for keystores and truststores that can be used for SSL context configuration or for certificate storing/retrieving.

The set of attributes (all of them optional) of this element are:

keystore-password Password of the keystore
keystore-type Type of the keystore. By default it's "JKS"
keystore-url URL where the keystore file can be found
keystore-provider Provider of the keystore. The default JDK provider for the keystore type is used if this attribute is null
keystore-provider-argument String that can be passed as the argument of the keystore Provider constructor
key-manager-factory-algorithm Algorithm of the KeyManagerFactory. The default JDK algorithm of the key manager factory is used if this attribute is null
key-manager-factory-provider Provider of the KeyManagerFactory. The default JDK provider for the key manager factory algorithm is used if this attribute is null
truststore-password Password of the truststore
truststore-type Type of the truststore. By deafult it's "JKS"
truststore-url URL where the truststore file can be found
truststore-provider Provider of the truststore. The default JDK provider for the truststore type is used if this attribute is null
truststore-provider-argument String that can be passed as the argument of the truststore Provider constructor
trust-manager-factory-algorithm Algorithm of the TrustManagerFactory. The default JDK algorithm of the trust manager factory is used if this attribute is null
trust-manager-factory-provider Provider of the TrustManagerFactory. The default JDK provider for the trust manager factory algorithm is used if this attribute is null
client-alias Alias of the keystore to be used when creating client side SSL sockets
server-alias Alias of the keystore to be used when creating server side SSL sockets
service-auth-token Validation token to enable third party services to retrieve a keystore Key. This is typically used to retrieve a private key for signing purposes
client-auth Flag to indicate if the server side SSL socket should require client authentication. Default is "false"
cipher-suites Comma separated list of cipher suites to be used by a SSLContext
protocols Comma separated list of SSL protocols to be used by a SSLContext

The optional additional-properties element can be used to include other options. The structure of the jsse element is:

security-properties

This element is used to specify additional properties as required by the security subsystem, properties are specified in the following format:

The property element can be repeated as required for as many properties need to be defined.

Each property specified is set on the java.security.Security class.

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.