[[Security]]
= Security subsystem configuration

The security subsystem is the subsystem that brings the security
services provided by http://www.jboss.org/picketbox[PicketBox] to the
WildFly {wildflyVersion} server instances.

If you are looking to secure the management interfaces for the
management of the domain then you should read the
<<Security_Realms,Securing the Management Interfaces>> chapter as the
management interfaces themselves are not run within a WildFly process so
use a custom configuration.

[[structure-of-the-security-subsystem]]
== Structure of the Security Subsystem

When deploying applications to WildFly 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 provide 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,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.

[[security-authentication-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.

[[security-authorization-manager]]
=== 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]]
=== 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]]
=== Mapping Manager

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

[[security-subsystem-configuration]]
== 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]]
=== 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.

[cols=",",options="header"]
|=======================================================================
|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]]
=== 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]]
=== 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:

[cols=",",options="header"]
|=======================================================================
|name |The unique name of this security domain.

|extends |Although version 1.0 of the security subsystem schema
contained an 'extends' attribute, security domain inheritance is not
supported and this attribute should not be used.

|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:

[source,xml,options="nowrap"]
----
<login-module code="..." flag="..." module="...">
  <module-option name="..." value="..."/>
</login-module>
----

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:

[cols=",",options="header"]
|=======================================================================
|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 module attribute specifies the name of the JBoss Modules module from
which the class specified by the code attribute should be loaded.
Specifying it is not necessary if one of the abbreviated names in the
above list is used.

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]]
==== 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:

[source,xml,options="nowrap"]
----
<login-module-stack name="...">
  <login-module code="..." flag="..." module="...">
    <module-option name="..." value="..."/>
  </login-module>
</login-module-stack>
<auth-module code="..." login-module-stack-ref="...">
  <module-option name="..." value="..."/>
</auth-module>
----

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,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:

[source,xml,options="nowrap"]
----
<policy-module code="..." flag="..." module="...">
  <module-option name="..." value="..."/>
</policy-module>
----

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:

[cols=",",options="header"]
|=======================================================================
|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 module attribute specifies the name of the JBoss Modules module from
which the class specified by the code attribute should be loaded.
Specifying it is not necessary if one of the abbreviated names in the
above list is used.

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]]
==== mapping

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

[source,xml,options="nowrap"]
----
<mapping-module type="..."code="..." module="...">
  <module-option name="..." value="..."/>
</mapping-module>
----

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 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:

[cols=",",options="header"]
|=======================================================================
|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 module attribute specifies the name of the JBoss Modules module from
which the class specified by the code attribute should be loaded.
Specifying it is not necessary if one of the abbreviated names in the
above list is used.

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]]
==== 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:

[source,xml,options="nowrap"]
----
<provider-module code="..." module="...">
  <module-option name="..." value="..."/>
</provider-module>
----

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

The module attribute specifies the name of the JBoss Modules module from
which the class specified by the code attribute should be loaded.

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]]
==== 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:

[cols=",",options="header"]
|=======================================================================
|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:

[source,xml,options="nowrap"]
----
<jsse keystore-url="..." keystore-password="..." keystore-type="..." keystore-provider="..." keystore-provider-argument="..." key-manager-factory-algorithm="..." key-manager-factory-provider="..." truststore-url="..." truststore-password="..." truststore-type="..." truststore-provider="..." truststore-provider-argument="..." trust-manager-factory-algorithm="..." trust-manager-factory-provider="..." client-alias="..." server-alias="..." service-auth-token="..." client-auth="..." cipher-suites="..." protocols="...">
  <additional-properties>x=y
    a=b
  </additional-properties>
</jsse>
----

[[security-properties]]
=== security-properties

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

[source,xml,options="nowrap"]
----
<security-properties>
  <property name="..." value="..."/>
</security-properties>
----

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.

:leveloffset: +1

include::Security_Authentication_Modules.adoc[]

:leveloffset: -1
