Appendix A. Reference Material
A.1. Elytron subsystem components reference
Attribute | Description |
---|---|
prefix | The prefix to add to each role. |
Attribute | Description |
---|---|
suffix | The suffix to add to each role. |
Attribute | Description |
---|---|
http-server-mechanism-factories | The list of HTTP server factories to aggregate. |
Attribute | Description |
---|---|
principal-decoders | The list of principal decoders to aggregate. |
Attribute | Description |
---|---|
principal-transformers | The list of principal transformers to aggregate. |
Attribute | Description |
---|---|
providers |
The list of referenced |
Attribute | Description |
---|---|
authentication-realm | Reference to the security realm to use for authentication steps. This is used for obtaining or validating credentials. |
authorization-realm | Reference to the security realm to use for loading the identity for authorization steps. |
authorization-realms | Reference to the security realms to aggregate for loading the identity for authorization steps. For information about using multiple authorization realms, see Configure Authentication and Authorization Using Multiple Identity Stores in the How to Configure Identity Management guide. |
The authorization-realm
and authorization-realms
attributes are mutually exclusive. Define only one of the two attributes in a realm.
Attribute | Description |
---|---|
role-mappers | The list of role mappers to aggregate. |
Attribute | Description |
---|---|
sasl-server-factories | The list of SASL server factories to aggregate. |
Attribute | Description |
---|---|
anonymous |
If |
authentication-name | The authentication name to use. |
authorization-name | The authorization name to use. |
credential-reference |
The credential to use for authentication. This can be in clear text or as a reference to a credential stored in a |
extends | An existing authentication configuration to extend. |
host | The host to use. |
kerberos-security-factory | Reference to a kerberos security factory used to obtain a GSS kerberos credential. |
mechanism-properties | Configuration properties for the SASL authentication mechanism. |
port | The port to use. |
protocol | The protocol to use. |
realm | The realm to use. |
sasl-mechanism-selector |
The SASL mechanism selector string. For more information about the grammar required for the |
security-domain | Reference to a security domain to obtain a forwarded identity. |
Attribute | Description |
---|---|
extends | An existing authentication context to extend. |
match-rules | The rules to match against for this authentication context. |
Attribute | Description |
---|---|
authentication-configuration | Reference to the authentication configuration to use for a successful match. |
match-abstract-type | The abstract type to match against. |
match-abstract-type-authority | The abstract type authority to match against. |
match-host | The host to match against. |
match-local-security-domain | The local security domain to match against. |
match-no-user |
If |
match-path | The patch to match against. |
match-port | The port to match against. |
match-protocol | The protocol to match against. |
match-urn | The URN to match against. |
match-user | The user to match against. |
ssl-context |
Reference to the |
Attribute | Description |
---|---|
maximum-age |
The time in milliseconds that an item can stay in the cache. A value of |
maximum-entries |
The maximum number of entries to keep in the cache. This defaults to |
realm |
A reference to a cacheable security realm such as |
Attribute | Description |
---|---|
upper-case |
An optional attribute that converts a principal transformer’s name to uppercase characters when set as |
Attribute | Description |
---|---|
alias |
The alias of certificate authority account key in the keystore. If the alias does not already exist in the keystore, a certificate authority account key will be automatically generated and stored as a |
certificate-authority |
The name of the certificate authority to use. The default, and only allowed value, is |
contact-urls | A list of URLs that the certificate authority can contact about any issues related to this account. |
credential-reference | The credential to be used when accessing the certificate authority account key. |
key-store | The keystore that contains the certificate authority account key. |
Attribute | Description |
---|---|
principal-transformers | List of principal transformers to chain. |
Attribute | Description |
---|---|
cipher-suite-filter |
The filter to apply to specify the enabled cipher suites. This filter takes a list of items delimited by colons, commas, or spaces. Each item may be a OpenSSL-style cipher suite name, a standard SSL/TLS cipher suite name, or a keyword such as |
key-manager |
Reference to the |
protocols |
The enabled protocols. Allowed options: Warning Red Hat recommends that SSLv2, SSLv3, and TLSv1.0 be explicitly disabled in favor of TLSv1.1 or TLSv1.2 in all affected packages. |
provider-name | The name of the provider to use. If not specified, all providers from providers will be passed to the SSLContext. |
providers |
The name of the providers to obtain the |
session-timeout | The timeout for SSL sessions. |
trust-manager |
Reference to the |
Attribute | Description |
---|---|
joiner |
The string that will be used to join the values in the |
principal-decoders | The list of principal decoders to concatenate. |
Attribute | Description |
---|---|
filters | The list of filters to be applied in order to enable or disable mechanisms based on the name. |
http-server-mechanism-factory | Reference to the http server factory to be wrapped. |
properties | Custom properties to be passed in to the HTTP server factory calls. |
Attribute | Description |
---|---|
pattern-filter | Filter based on a regular expression pattern. |
enabling |
If |
Attribute | Description |
---|---|
filters |
List of filters to be evaluated sequentially and combined using |
properties | Custom properties to be passed in to the SASL server factory calls. |
protocol | The protocol passed into the factory when creating the mechanism. |
sasl-server-factory | Reference to the SASL server factory to be wrapped. |
server-name | The server name passed into the factory when creating the mechanism. |
Attribute | Description |
---|---|
enabling |
If |
predefined-filter |
A predefined filter to use to filter the mechanism name. Allowed values are |
pattern-filter | A filter for the mechanism name based on a regular expression. |
Attribute | Description |
---|---|
permission-sets | The permission sets to assign in the event of a match. Permission sets can be used to assign permissions to an identity.
Note
The |
Attribute | Description |
---|---|
constant | The constant value the principal decoder will always return. |
Attribute | Description |
---|---|
constant | The constant value this principal transformer will always return. |
Attribute | Description |
---|---|
realm-name | Reference to the realm that will be returned. |
Attribute | Description |
---|---|
roles | The list of roles that will be returned. |
Attribute | Description |
---|---|
create |
Specifies whether the credential store should create storage when it does not exist. The default values is |
credential-reference |
The reference to the credential used to create protection parameter. This can be in clear text or as a reference to a credential stored in a |
implementation-properties | Map of credentials store implementation-specific properties. |
modifiable |
Whether you can modify the credential store. The default value is |
other-providers | The name of the providers to obtain the providers to search for the one that can create the required Jakarta Connectors objects within the credential store. This is valid only for keystore-based credential store. If this is not specified, then the global list of providers is used instead. |
path | The file name of the credential store. |
provider-name |
The name of the provider to use to instantiate the |
providers | The name of the providers to obtain the providers to search for the one that can create the required credential store type. If this is not specified, then the global list of providers is used instead. |
relative-to | The base path this credential store path is relative to. |
type |
Type of the credential store, for example, |
Attribute | Description |
---|---|
entry-type | Type of credential entry stored in the credential store. |
secret-value | Secret value such as password. |
Attribute | Description |
---|---|
cryptoAlg |
Cryptographic algorithm name to be used to encrypt decrypt entries at external storage. This attribute is only valid if |
external |
Whether data is stored to external storage and encrypted by the |
externalPath |
Specifies path to external storage. This attribute is only valid if |
keyAlias | The secret key alias within the credential store that is used to encrypt or decrypt data to the external storage. |
keyStoreType |
The keystore type, such as |
Attribute | Description |
---|---|
class-name | The class name of the implementation of the custom security factory. |
configuration | The optional key and value configuration for the custom security factory. |
module | The module to use to load the custom security factory. |
Attribute | Description |
---|---|
class-name | The class name of the implementation of the custom realm. |
configuration | The optional key and value configuration for the custom realm. |
module | The module to use to load the custom realm. |
Attribute | Description |
---|---|
class-name | Fully qualified class name of the permission mapper. |
configuration | The optional key and value configuration for the permission mapper. |
module | Name of the module to use to load the permission mapper. |
Attribute | Description |
---|---|
class-name | Fully qualified class name of the principal decoder. |
configuration | The optional key and value configuration for the principal decoder. |
module | Name of the module to use to load the principal decoder. |
Attribute | Description |
---|---|
class-name | Fully qualified class name of the principal transformer. |
configuration | The optional key and value configuration for the principal transformer. |
module | Name of the module to use to load the principal transformer. |
Attribute | Description |
---|---|
class-name | Fully qualified class name of the custom realm. |
configuration | The optional key and value configuration for the custom realm. |
module | Name of the module to use to load the custom realm. |
Attribute | Description |
---|---|
class-name | Fully qualified class name of the realm mapper. |
configuration | The optional key and value configuration for the realm mapper. |
module | Name of the module to use to load the realm mapper. |
Attribute | Description |
---|---|
class-name | Fully qualified class name of the role decoder. |
configuration | The optional key and value configuration for the role decoder. |
module | Name of the module to use to load the role decoder. |
Attribute | Description |
---|---|
class-name | Fully qualified class name of the role mapper. |
configuration | The optional key and value configuration for the role mapper. |
module | Name of the module to use to load the role mapper. |
Attribute | Description |
---|---|
authentication-context |
The authentication context to obtain login credentials to connect to the LDAP server. Can be omitted if |
authentication-level |
The authentication level, meaning security level or authentication mechanism, to use. Corresponds to |
connection-timeout | The timeout for connecting to the LDAP server in milliseconds. |
credential-reference |
The credential reference to authenticate and connect to the LDAP server. This can be omitted if |
enable-connection-pooling |
If |
module | Name of module that will be used as the class loading base. |
principal |
The principal to authenticate and connect to the LDAP server. This can be omitted if |
properties |
The additional connection properties for the |
read-timeout | The read timeout for an LDAP operation in milliseconds. |
referral-mode |
The mode used to determine if referrals should be followed. Allowed values are |
ssl-context | The name of the SSL context used to secure connection to the LDAP server. |
url | The connection URL. |
Attribute | Description |
---|---|
default-resolver |
Optional attribute. The resolver to use when an encrypted expression is defined without one. For example if you set "exampleResolver" as the |
prefix |
The prefix to use within an encrypted expression. Default is |
resolvers | A list of defined resolvers. A resolver has the following attributes:
|
Attribute | Description |
---|---|
encoded | Whether the identity names should be stored encoded (Base32) in file names. |
levels |
The number of levels of directory hashing to apply. The default value is |
path | The path to the file containing the realm. |
relative-to |
The predefined relative path to use with |
Attribute | Description |
---|---|
alias-filter |
A filter to apply to the aliases returned from the
Note
The |
key-store |
Reference to the |
Attribute | Description |
---|---|
algorithm | Specifies the encryption algorithm, such as RSA, DSA, or EC. The default value is RSA. |
size |
Specifies the size of the private key in bits. The default size values in bits for the key pair types are as follows: RSA is |
Attribute | Description |
---|---|
http-server-mechanism-factory |
The |
mechanism-configurations | The list of mechanism-specific configurations. |
security-domain | The security domain to associate with this resource. |
Attribute | Description |
---|---|
credential-security-factory | The security factory to use to obtain a credential as required by the mechanism. |
final-principal-transformer | A final principal transformer to apply for this mechanism realm. |
host-name | The host name this configuration applies to. |
mechanism-name | This configuration will only apply where a mechanism with the name specified is used. If this attribute is omitted then this will match any mechanism name. |
mechanism-realm-configurations | The list of definitions of the realm names as understood by the mechanism. |
pre-realm-principal-transformer | A principal transformer to apply before the realm is selected. |
post-realm-principal-transformer | A principal transformer to apply after the realm is selected. |
protocol | The protocol this configuration applies to. |
realm-mapper | The realm mapper to be used by the mechanism. |
Attribute | Description |
---|---|
final-principal-transformer | A final principal transformer to apply for this mechanism realm. |
post-realm-principal-transformer | A principal transformer to apply after the realm is selected. |
pre-realm-principal-transformer | A principal transformer to apply before the realm is selected. |
realm-mapper | The realm mapper to be used by the mechanism. |
realm-name | The name of the realm to be presented by the mechanism. |
Attribute | Description |
---|---|
attribute-name | The name of the attribute associated with this identity. |
attribute-values | The list of values associated with the identities attribute. |
identity | The identity available from the security realm. |
Attribute | Description |
---|---|
key-passphrase | Optional attribute. Sets the passphrase to decrypt the private key. |
private-key-location |
The path to a file containing a private key. Only specify if you have not already specified the |
private-key-string |
Sets the private key as a string. Only specify if you have not already specified the |
public-key-location |
Required if private key is in any format other than OpenSSH. The path to a file containing a public key. Only specify if you have not already specified the |
public-key-string |
Required if private key is in any format other than OpenSSH. Sets the public key as a string. Only specify if you have not already specified the |
Attribute | Description |
---|---|
application-context |
Used when registering this configuration with the |
description |
Is used to provide a description to the |
layer |
Used when registering this configuration with the |
name | A name that allows the resource to be referenced in the management model. |
Attribute | Description |
---|---|
class-name |
The fully qualified class name of the |
flag | The control flag to indicate how this module operates in relation to the other modules. |
module |
The module to load the |
options |
Configuration options to be passed into the |
Attribute | Description |
---|---|
principal-query | The list of authentication queries used to authenticate users based on specific key types. |
Attribute | Description |
---|---|
attribute-mapping | The list of attribute mappings defined for this resource. |
bcrypt-mapper |
A key mapper that maps a column returned from a SQL query to a |
clear-password-mapper |
A key mapper that maps a column returned from a SQL query to a clear password key type. This has a |
data-source | The name of the datasource used to connect to the database. |
salted-simple-digest-mapper |
A key mapper that maps a column returned from a SQL query to a |
scram-mapper |
A key mapper that maps a column returned from a SQL query to a |
simple-digest-mapper |
A key mapper that maps a column returned from a SQL query to a |
sql | The SQL statement used to obtain the keys as table columns for a specific user and map them accordingly with their type. |
Attribute | Description |
---|---|
index | The column index from a query that representing the mapped attribute. |
to | The name of the identity attribute mapped from a column returned from a SQL query. |
Attribute | Description |
---|---|
iteration-count-index | The column index from an authentication query that represents the password’s iteration count, if supported. |
password-index | The column index from an authentication query that represents the user password. |
salt-index | The column index from an authentication query that represents the password’s salt, if supported. |
Attribute | Description |
---|---|
algorithm |
The algorithm for a specific password key mapper. Allowed values are |
password-index | The column index from an authentication query that represents the user password. |
salt-index | The column index from an authentication query that represents the password’s salt, if supported. |
Attribute | Description |
---|---|
algorithm |
The algorithm for a specific password key mapper. Allowed values are |
password-index | The column index from an authentication query that represents the user password. |
Attribute | Description |
---|---|
algorithm |
The algorithm for a specific password key mapper. The allowed values are |
iteration-count-index | The column index from an authentication query that represents the password’s iteration count, if supported. |
password-index | The column index from an authentication query that represents the user password. |
salt-index | The column index from an authentication query that represents the password’s salt, if supported. |
Attribute | Description |
---|---|
debug |
If |
mechanism-names |
The mechanism names the credential should be usable with. Names will be converted to OIDs and used together with OIDs from |
mechanism-oids | The list of mechanism OIDs the credential should be usable with. |
minimum-remaining-lifetime | The amount of time in seconds a cached credential can have before it is recreated. |
obtain-kerberos-ticket |
Should the |
options |
The |
path | The path of the keytab to load to obtain the credential. |
principal | The principal represented by the keytab. |
relative-to | The relative path to the keytab. |
request-lifetime | How much lifetime should be requested for newly created credentials. |
required | Whether the keytab file with an adequate principal is required to exist at the time the service starts. |
server |
If |
wrap-gss-credential | Whether generated GSS credentials should be wrapped to prevent improper disposal. |
Attribute | Description |
---|---|
algorithm |
The name of the algorithm to use to create the underlying |
alias-filter | A filter to apply to the aliases returned from the keystore. This can either be a comma-separated list of aliases to return or one of the following formats:
|
credential-reference |
The credential reference to decrypt keystore item. This can be specified in clear text or as a reference to a credential stored in a |
key-store |
Reference to the |
provider-name |
The name of the provider to use to create the underlying |
providers |
Reference to obtain the |
Attribute | Description |
---|---|
alias-filter | A filter to apply to the aliases returned from the keystore, can either be a comma separated list of aliases to return or one of the following formats:
Note
The |
credential-reference |
The password to use to access the keystore. This can be specified in clear text or as a reference to a credential stored in a |
path | The path to the keystore file. |
provider-name | The name of the provider to use to load the keystore. Setting this attribute disables searching for the first provider that can create a keystore of the specified type. |
providers | A reference to the providers that should be used to obtain the list of provider instances to search. If not specified, the global list of providers will be used instead. |
relative-to |
The base path this store is relative to. This can be a full path or predefined path such as |
required |
If |
type |
The type of the keystore, for example, Note The following keystore types are detected automatically:
You must manually specify the other keystore types. A full list of keystore types can be found in the Java Cryptography Architecture Standard Algorithm Name Documentation for JDK 8. |
Attribute | Description |
---|---|
key-store | Reference to the keystore used to back this security realm. |
Attribute | Description |
---|---|
alias-attribute | The name of LDAP attribute where the item alias will be stored. |
certificate-attribute | The name of LDAP attribute where the certificate will be stored. |
certificate-chain-attribute | The name of LDAP attribute where the certificate chain will be stored. |
certificate-chain-encoding | The encoding of the certificate chain. |
certificate-type | The type of the certificate. |
dir-context |
The name of the |
filter-alias | The LDAP filter for obtaining an item in the keystore by alias. |
filter-certificate | The LDAP filter for obtaining an item in the keystore by certificate. |
filter-iterate | The LDAP filter for iterating over all items of the keystore. |
key-attribute | The name of LDAP attribute where the key will be stored. |
key-type |
The type of keystore that is stored in a serialized manner in the LDAP attribute. For example, |
new-item-template | Configuration for item creation. This defines how the LDAP entry of newly created keystore item will look. |
search-path | The path in LDAP where the keystore items will be searched. |
search-recursive | If the LDAP search should be recursive. |
search-time-limit |
The time limit in milliseconds for obtaining keystore items from LDAP. Defaults to |
Attribute | Description |
---|---|
new-item-attributes |
The LDAP attributes which will be set for newly created items. This takes a list of items with |
new-item-path | The path in LDAP where the newly created keystore items will be stored. |
new-item-rdn | The name of LDAP RDN for the newly created items. |
Attribute | Description |
---|---|
allow-blank-password | Whether this realm supports blank password direct verification. A blank password attempt will be rejected otherwise. |
dir-context |
The name of the |
direct-verification |
If |
identity-mapping | The configuration options that define how principals are mapped to their corresponding entries in the underlying LDAP server. |
Attribute | Description |
---|---|
attribute-mapping | List of attribute mappings defined for this resource. |
filter-name | The LDAP filter for getting identity by name. |
iterator-filter | The LDAP filter for iterating over identities of the realm. |
new-identity-attributes |
The list of attributes of newly created identities and is required for modifiability of the realm. This is a list of |
otp-credential-mapper | The credential mapping for OTP credential. |
new-identity-parent-dn | The DN of parent of newly created identities. Required for modifiability of the realm. |
rdn-identifier | The RDN part of the principal’s DN to be used to obtain the principal’s name from an LDAP entry. This is also used when creating new identities. |
search-base-dn | The base DN to search for identities. |
use-recursive-search |
If |
user-password-mapper | The credential mapping for a credential similar to userPassword. |
x509-credential-mapper |
The configuration allowing to use LDAP as storage of X509 credentials. If none of the |
Attribute | Description |
---|---|
extract-rdn | The RDN key to use as the value for an attribute, in case the value in its raw form is in X.500 format. |
filter | The filter to use to obtain the values for a specific attribute. |
filter-base-dn | The name of the context where the filter should be performed. |
from | The name of the LDAP attribute to map to an identity attribute. If not defined, DN of entry is used. |
reference | The name of LDAP attribute containing DN of entry to obtain value from. |
role-recursion |
Maximum depth for recursive role assignment. Use |
role-recursion-name |
Determine the LDAP attribute of role entry which will be a substitute for "{0}" in |
search-recursive |
If |
to |
The name of the identity attribute mapped from a specific LDAP attribute. If not provided, the name of the attribute is the same as define in |
Attribute | Description |
---|---|
from | The name of the LDAP attribute to map to an identity attribute. If not defined, DN of entry is used. |
verifiable |
If |
writable |
If |
Attribute | Description |
---|---|
algorithm-from | The name of the LDAP attribute of OTP algorithm. |
hash-from | The name of the LDAP attribute of OTP hash function. |
seed-from | The name of the LDAP attribute of OTP seed. |
sequence-from | The name of the LDAP attribute of OTP sequence number. |
Attribute | Description |
---|---|
certificate-from | The name of the LDAP attribute to map to an encoded user certificate. If not defined, encoded certificate will not be checked. |
digest-algorithm |
The digest algorithm, which is the hash function, used to compute digest of the user certificate. Will be used only if |
digest-from | The name of the LDAP attribute to map to a user certificate digest. If not defined, certificate digest will not be checked. |
serial-number-from | The name of the LDAP attribute to map to a serial number of user certificate. If not defined, serial number will not be checked. |
subject-dn-from | The name of the LDAP attribute to map to a subject DN of user certificate. If not defined, subject DN will not be checked. |
Attribute | Description |
---|---|
left | Reference to the permission mapper to use to the left of the operation. |
logical-operation |
The logical operation to use to combine the permission mappers. Allowed values are |
right | Reference to the permission mapper to use to the right of the operation. |
Attribute | Description |
---|---|
left | Reference to a role mapper to be used on the left side of the operation. |
logical-operation |
The logical operation to be performed on the role mapper mappings. Allowed values are: |
right | Reference to a role mapper to be used on the right side of the operation. |
Attribute | Description |
---|---|
delegate-realm-mapper | The realm mapper to delegate to if there is no match using the pattern. |
pattern | The regular expression which must contain at least one capture group to extract the realm from the name. |
realm-map | Mapping of realm name extracted using the regular expression to a defined realm name. |
Attribute | Description |
---|---|
enabling |
If |
filters | The list of filters to apply when comparing the mechanisms from the providers. A filter matches when all of the specified values match the mechanism and provider pair. |
sasl-server-factory | Reference to a SASL server factory to be wrapped by this definition. |
Attribute | Description |
---|---|
mechanism-name | The name of the SASL mechanism this filter matches with. |
provider-name | The name of the provider this filter matches. |
provider-version | The version to use when comparing the provider’s version. |
version-comparison |
The equality to use when evaluating the Provider’s version. The allowed values are |
Attribute | Description |
---|---|
responder | Override the OCSP Responder URI resolved from the certificate. |
responder-certificate |
Alias for responder certificate located in |
responder-keystore |
Alternative keystore for responder certificate. |
prefer-crls |
When both OCSP and CRL mechanisms are configured, OCSP mechanism is called first. When |
Attribute | Description |
---|---|
action | The action to pass to the permission as it is constructed. |
class-name | The fully qualified class name of the permission. |
module | The module to use to load the permission. |
target-name | The target name to pass to the permission as it is constructed. |
Attribute | Description |
---|---|
|
Specifies if the output stream requires flushing after every audit event. If you do not define the attribute, the value of the |
|
Use |
| Defines the location of the log files. |
| Optional attribute. Defines the location of the log files. |
|
Optional attribute. Adds a date suffix to a rotated log. You must use the |
|
Default value is |
Attribute | Description |
---|---|
groups-attribute |
The name of the attribute in the returned |
groups-properties | The properties file containing the users and their groups. |
users-properties | The properties file containing the users and their passwords. |
Attribute | Description |
---|---|
digest-realm-name | The default realm name to use for digested passwords if one is not discovered in the properties file. |
path | The path to the file containing the users and their passwords. The file should contain realm name declaration. |
plain-text |
If |
relative-to | The predefined path the path is relative to. |
Attribute | Description |
---|---|
path | The path to the file containing the users and their groups. |
relative-to | The predefined path the path is relative to. |
providers | The providers to use to locate the factories. If not specified, the globally registered list of providers will be used. |
---|
Attribute | Description |
---|---|
argument |
An argument to be passed into the constructor as the |
class-names | The list of the fully qualified class names of providers to load. These are loaded after the service-loader discovered providers, and any duplicates will be skipped. |
configuration | The key and value configuration to be passed to the provider to initialize it. |
module | The name of the module to load the provider from. |
path | The path of the file to use to initialize the providers. |
relative-to | The base path of the configuration file. |
Attribute | Description |
---|---|
providers | The providers to use to locate the factories. If not specified, the globally registered list of providers will be used. |
Attribute | Description |
---|---|
pattern | The regular expression to use to locate the portion of the name to be replaced. |
replace-all |
If |
replacement | The value to be used as the replacement. |
Attribute | Description |
---|---|
pattern |
The regular expression to use to match roles. You can use group capturing if you want to use a portion of the original role in the replacement. For example, to capture a string after a hyphen in roles such as "app-admin", "batch-admin", use the pattern |
replacement |
The string to replace the match. You can use a fixed string or refer to captured groups from the regular expression specified in the |
keep-non-mapped |
Set the value to |
Attribute | Description |
---|---|
match |
If |
pattern | The regular expression to use for the principal transformer. |
Attribute | Description |
---|---|
mechanism-configurations | The list of mechanism specific configurations. |
sasl-server-factory | The SASL server factory to associate with this resource. |
security-domain | The security domain to associate with this resource. |
Attribute | Description |
---|---|
credential-security-factory | The security factory to use to obtain a credential as required by the mechanism. |
final-principal-transformer | A final principal transformer to apply for this mechanism realm. |
host-name | The host name this configuration applies to. |
mechanism-name | This configuration will only apply where a mechanism with the name specified is used. If this attribute is omitted then this will match any mechanism name. |
mechanism-realm-configurations | The list of definitions of the realm names as understood by the mechanism. |
protocol | The protocol this configuration applies to. |
post-realm-principal-transformer | A principal transformer to apply after the realm is selected. |
pre-realm-principal-transformer | A principal transformer to apply before the realm is selected. |
realm-mapper | The realm mapper to be used by the mechanism. |
Attribute | Description |
---|---|
final-principal-transformer | A final principal transformer to apply for this mechanism realm. |
post-realm-principal-transformer | A principal transformer to apply after the realm is selected. |
pre-realm-principal-transformer | A principal transformer to apply before the realm is selected. |
realm-mapper | The realm mapper to be used by the mechanism. |
realm-name | The name of the realm to be presented by the mechanism. |
Attribute | Description |
---|---|
create |
Set the value to |
default-alias |
The alias name for a key generated by default. The default value is |
key-size | The size of a generated key. The default size is 256 bits. You can set the value to one of the following:
|
path | The path to the credential store. |
populate |
If a credential store does not contain a |
relative-to |
A reference to a previously defined path that the attribute |
Attribute | Description |
---|---|
authentication-optional |
If |
cipher-suite-filter |
The filter to apply to specify the enabled cipher suites. This filter takes a list of items delimited by colons, commas, or spaces. Each item may be an OpenSSL-style cipher suite name, a standard SSL/TLS cipher suite name, or a keyword such as |
final-principal-transformer | A final principal transformer to apply for this mechanism realm. |
key-manager |
Reference to the key managers to use within the |
maximum-session-cache-size | The maximum number of SSL/TLS sessions to be cached. |
need-client-auth |
If |
post-realm-principal-transformer | A principal transformer to apply after the realm is selected. |
pre-realm-principal-transformer | A principal transformer to apply before the realm is selected. |
protocols |
The enabled protocols. Allowed options are Warning Red Hat recommends that SSLv2, SSLv3, and TLSv1.0 be explicitly disabled in favor of TLSv1.1 or TLSv1.2 in all affected packages. |
provider-name |
The name of the provider to use. If not specified, all providers from providers will be passed to the |
providers |
The name of the providers to obtain the |
realm-mapper | The realm mapper to be used for SSL authentication. |
security-domain | The security domain to use for authentication during SSL/TLS session establishment. |
session-timeout | The timeout for SSL/TLS sessions. |
trust-manager |
Reference to the |
use-cipher-suites-order |
If |
want-client-auth |
If |
wrap |
If |
The realm mapper and principal transformer attributes for a server-ssl-context
apply only for the SASL EXTERNAL mechanism, where the certificate is verified by the trust manager. HTTP CLIENT-CERT authentication settings are configured in an http-authentication-factory
.
Attribute | Description |
---|---|
module | The module to use to obtain the class loader to load the factories. If not specified the class loader to load the resource will be used instead. |
Attribute | Description |
---|---|
module | The module to use to obtain the class loader to load the factories. If not specified the class loader to load the resource will be used instead. |
Attribute | Description |
---|---|
mapping-mode |
The mapping mode that should be used in the event of multiple matches. Allowed values |
permission-mappings | The list of defined permission mappings. |
Attribute | Description |
---|---|
permission-sets | The permission sets to assign in the event of a match. Permission sets can be used to assign permissions to an identity.
Important
The |
principals | The list of principals to compare when mapping permissions, if the identities principal matches any one in the list it is a match. |
roles | The list of roles to compare when mapping permissions, if the identity is a member of any one in the list it is a match. |
Attribute | Description |
---|---|
delegate-realm-mapper | The realm mapper to delegate to if there is no match using the pattern. |
pattern | The regular expression which must contain at least one capture group to extract the realm from the name. |
Attribute | Description |
---|---|
attribute | The name of the attribute from the identity to map directly to roles. |
Attribute | Description |
---|---|
pattern | A regular expression that specifies the IP address of a client or the IP addresses of clients to match. |
source-address | Specifies the IP address of the client. |
roles |
Provides the list of roles to assign to a user if the IP address of the client matches the values specified in the |
You must specify at least one IP address in either the source-address
attribute or the pattern
attribute. Otherwise, you cannot make authorization decisions based on the IP address of a client.
Attribute | Description |
---|---|
format | The format that audit events should be recorded in. Supported values:
Default value:
|
host-name | The host name to be be embedded into all events sent to the syslog server. |
port | The listening port on the syslog server. |
reconnect-attempts | The maximum number of times that Elytron will attempt to send successive messages to a syslog server before closing the connection. The value of this attribute is only valid when the transmission protocol used is UDP. Supported values:
Default value:
|
server-address |
IP address of the syslog server, or a name that can be resolved by Java’s |
ssl-context |
The SSL context to use when connecting to the syslog server. This attribute is only required if |
syslog-format | The RFC format to be used for describing the audit event. Supported values:
Default value:
|
transport | The transport layer protocol to use to connect to the syslog server. Supported values:
Default value:
|
Attribute | Description |
---|---|
|
Specifies if the output stream requires flushing after every audit event. If you do not define the attribute, the value of the |
|
Default value is |
| Defines the location of the log files |
| Optional attribute. Defines the location of the log files |
|
Default value is |
Attribute | Description |
---|---|
|
Specifies if the output stream requires flushing after every audit event. If you do not define the attribute, the value of the |
|
Default value is |
|
The maximum number of files to back up when rotating. The default value is |
| Defines the location of the log files. |
| Optional attribute. Defines the location of the log files. |
|
By default, Elytron does not create a new log file when you restart a server. Set this attribute to |
|
The maximum size that the log file can reach before Elytron rotates the log. The default is |
|
Optional attribute. Adds a date suffix to a rotated log. You must use the |
|
Default value is |
Attribute | Description |
---|---|
jwt | A token validator to be used in conjunction with a token-based realm that handles security tokens based on the JWT/JWS standard. |
oauth2-introspection | A token validator to be used in conjunction with a token-based realm that handles OAuth2 Access Tokens and validates them using an endpoint compliant with the RFC-7662 OAuth2 Token Introspection specification. |
principal-claim |
The name of the claim that should be used to obtain the principal’s name. The default is |
Attribute | Description |
---|---|
audience |
A list of strings representing the audiences supported by this configuration. During validation JWT tokens must have an |
certificate |
The name of the certificate with a public key to load from the keystore that is defined by the |
client-ssl-context |
The SSL context to use for a remote JSON Web Key (JWK). This enables you to use the URL from the |
host-name-verification-policy | A policy that defines how host names should be verified when using remote JSON Web Keys. You can set either of the following values for the attribute:
|
issuer |
A list of strings representing the issuers supported by this configuration. During validation JWT tokens must have an |
key-store |
The keystore from which the certificate with a public key should be loaded. This attribute, along with the |
public-key | A public key in PEM Format. During validation, if a public key is provided, the signature will be verified based on the key value provided by this attribute.
Alternatively, you can define a |
Attribute | Description |
---|---|
client-id | The identifier of the client on the OAuth2 Authorization Server. |
client-secret | The secret of the client. |
client-ssl-context | The SSL context to be used if the introspection endpoint is using HTTPS. |
host-name-verification-policy | A policy that defines how host names should be verified when using HTTPS. You can set either of the following values for the attribute:
|
introspection-url | The URL of token introspection endpoint. |
Attribute | Description |
---|---|
algorithm |
The name of the algorithm to use to create the underlying |
alias-filter | A filter to apply to the aliases returned from the keystore. This can either be a comma-separated list of aliases to return or one of the following formats:
|
certificate-revocation-list |
Enables the certificate revocation list that can be checked by a trust manager. The attributes of
See Using a Certificate Revocation List for more information. |
key-store |
Reference to the |
maximum-cert-path |
The maximum number of non-self-issued intermediate certificates that can exist in a certification path. The default value is
This attribute has been moved to Note
Define |
only-leaf-cert |
Check revocation status of only the leaf certificate. This is an optional attribute. The default values is |
provider-name |
The name of the provider to use to create the underlying |
providers |
Reference to obtain the |
soft-fail |
When set to |
Attribute | Description |
---|---|
attribute-name |
The name of the X.500 attribute to map. This can also be defined using the |
convert |
When set to |
joiner |
The joining string. The default value is a period ( |
maximum-segments |
The maximum number of occurrences of the attribute to map. The default value is |
oid |
The OID of the X.500 attribute to map. This can also be defined using the |
required-attributes | The list of attribute names of the attributes that must be present in the principal |
required-oids | The list of OIDs of the attributes that must be present in the principal. |
reverse |
If |
start-segment |
The starting occurrence of the attribute you want to map. This uses a zero-based index and the default value is |
Attribute | Description |
---|---|
| The subject alternative name type. Must be one of the following subject alternative name types:
This is a required attribute. |
|
|
A.2. Configure Your Environment to use the BouncyCastle
Provider
You can configure your JBoss EAP installation to use a BouncyCastle
provider. The Bouncy Castle JARs are not provided by Red Hat, and must be obtained directly from Bouncy Castle.
Java 8 must be used when the BouncyCastle
providers are specified, as the BouncyCastle APIs are only certified up to Java 8.
-
Include both BouncyCastle JARs, beginning with
bc-fips
andbctls-fips
, on your JDK’s classpath. For Java 8 this is accomplished by placing the JAR files in$JAVA_HOME/lib/ext
. Using either of the following methods, include the
BouncyCastle
providers in your Java security configuration file:-
A default configuration file,
java.security
, is provided in your JDK, and can be updated to include theBouncyCastle
providers. This file is used if no other security configuration files are specified. See the JDK vendor’s documentation for the location of this file. Define a custom Java security configuration file and reference it by adding the
-Djava.security.properties==/path/to/java.security.properties
system property.When referenced using two equal signs the default policy is overwritten, and only the providers defined in the referenced file are used. When a single equal sign is used, as in
-Djava.security.properties=/path/to/java.security.properties
, then the providers are appended to the default security file, preferring to use the file passed in the argument when keys are specified in both files. This option is useful when having multiple JVMs running on the same host that require different security settings.
An example configuration file that defines these providers is seen below.
Example: BouncyCastle Security Policy
# We can override the values in the JRE_HOME/lib/security/java.security # file here. If both properties files specify values for the same key, the # value from the command-line properties file is selected, as it is the last # one loaded. We can reorder and change security providers in this file. security.provider.1=org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider security.provider.2=org.bouncycastle.jsse.provider.BouncyCastleJsseProvider fips:BCFIPS security.provider.3=sun.security.provider.Sun security.provider.4=com.sun.crypto.provider.SunJCE # This is a comma-separated list of algorithm and/or algorithm:provider # entries. # securerandom.strongAlgorithms=DEFAULT:BCFIPS
ImportantIf the default configuration file is updated, then every other
security.provider.X
line in this file, for examplesecurity.provider.2
, must increase its value ofX
to ensure that this provider is given priority. Each provider must have a unique priority.-
A default configuration file,
Configure the
elytron
subsystem to exclusively use theBouncyCastle
providers. By default, the system is configured to use both theelytron
andopenssl
providers. Because it also includes a TLS implementation, it is recommended to disable the OpenSSL provider to ensure the TLS implementation from Bouncy Castle is used./subsystem=elytron:write-attribute(name=final-providers,value=elytron)
Reload the server for the changes to take effect.
reload
A.3. SASL Authentication Mechanisms Reference
A.3.1. Support Level for SASL Authentication Mechanisms
Name | Support Level | Comments |
---|---|---|
ANONYMOUS | Supported | |
DIGEST-SHA-512 | Technology Preview | Supported but name not currently IANA registered. |
DIGEST-SHA-256 | Technology Preview | Supported but name not currently IANA registered. |
DIGEST-SHA | Technology Preview | Supported but name not currently IANA registered. |
DIGEST-MD5 | Supported | |
EXTERNAL | Supported | |
GS2-KRB5 | Supported | |
GS2-KRB5-PLUS | Supported | |
GSSAPI | Supported | |
JBOSS-LOCAL-USER | Supported | Supported but name not currently IANA registered. |
OAUTHBEARER | Supported | |
OTP | Not supported | |
PLAIN | Supported | |
SCRAM-SHA-1 | Supported | |
SCRAM-SHA-1-PLUS | Supported | |
SCRAM-SHA-256 | Supported | |
SCRAM-SHA-256-PLUS | Supported | |
SCRAM-SHA-384 | Supported | |
SCRAM-SHA-384-PLUS | Supported | |
SCRAM-SHA-512 | Supported | |
SCRAM-SHA-512-PLUS | Supported | |
9798-U-RSA-SHA1-ENC | Not supported | |
9798-M-RSA-SHA1-ENC | Not supported | |
9798-U-DSA-SHA1 | Not supported | |
9798-M-DSA-SHA1 | Not supported | |
9798-U-ECDSA-SHA1 | Not supported | |
9798-M-ECDSA-SHA1 | Not supported |
A.3.2. SASL Authentication Mechanism Properties
You can see a list of standard Java SASL authentication mechanism properties in the Java documentation. Other JBoss EAP-specific SASL authentication mechanism properties are listed in the following tables.
Property | Client / Server | Description |
---|---|---|
com.sun.security.sasl.digest.realm | Server |
Used by some SASL mechanisms, including the DIGEST-MD5 algorithm supplied with most Oracle JDKs, to provide the list of possible server realms to the mechanism. Each realm name must be separated by a space character ( |
com.sun.security.sasl.digest.utf8 | Client, server |
Used by some SASL mechanisms, including the DIGEST-MD5 algorithm supplied with most Oracle JDKs, to indicate that information exchange should take place using UTF-8 character encoding instead of the default Latin-1/ISO-8859-1 encoding. The default value is |
wildfly.sasl.authentication-timeout | Server | The amount of time, in seconds, after which a server should terminate an authentication attempt. The default value is 150 seconds. |
wildfly.sasl.channel-binding-required | Client, server |
Indicates that a mechanism which supports channel binding is required. A value of |
wildfly.sasl.digest.alternative_protocols | Server | Supplies a separated list of alternative protocols that are acceptable in responses received from the client. The list can be space, comma, tab, or new line separated. |
wildfly.sasl.gssapi.client.delegate-credential | Client |
Specifies if the GSSAPI mechanism supports credential delegation. If set to
This property defaults to |
wildfly.sasl.gs2.client.delegate-credential | Client |
Specifies if the GS2 mechanism supports credential delegation. If set to
This property defaults to |
wildfly.sasl.local-user.challenge-path | Server |
Specifies the directory in which the server generates the challenge file. The default value is the |
wildfly.sasl.local-user.default-user | Server | The user name to use for silent authentication. |
wildfly.sasl.local-user.quiet-auth | Client |
Enables silent authentication for a local user. The default value is Note that the Jakarta Enterprise Beans client and naming client disables silent local authentication if this property is not explicitly defined and a callback handler or user name was specified in the client configuration. |
wildfly.sasl.local-user.use-secure-random | Server |
Specifies whether the server uses a secure random number generator when creating the challenge. The default value is |
wildfly.sasl.mechanism-query-all | Client, server | Indicates that all possible supported mechanism names should be returned, regardless of the presence or absence of any other properties.
This property is only effective on calls to |
wildfly.sasl.otp.alternate-dictionary | Client |
Provides an alternate dictionary to the OTP SASL mechanism. Each dictionary word must be separated by a space character ( |
wildfly.sasl.relax-compliance | Server |
The specifications for the SASL mechanisms mandate certain behavior and verification of that behavior at the opposite side of the connection. When interacting with other SASL mechanism implementations, some of these requirements are interpreted loosely. If this property is set to |
wildfly.sasl.scram.min-iteration-count | Client, server |
The minimum iteration count to use for SCRAM. The default value is |
wildfly.sasl.scram.max-iteration-count | Client, server |
The maximum iteration count to use for SCRAM. The default value is |
wildfly.sasl.secure-rng | Client, server |
The algorithm name of a |
wildfly.security.sasl.digest.ciphers | Client, server | Comma-separated list of supported ciphers that directly limits the set of supported ciphers for SASL mechanisms. |
Property | Client / Server | Description |
---|---|---|
wildfly.sasl.principal | Client | Contains the negotiated client principal after a successful SASL client-side authentication. |
wildfly.sasl.security-identity | Server | Contains the negotiated security identity after a successful SASL server-side authentication. |
A.4. Security Authorization Arguments
Arguments to the security
commands in JBoss EAP are determined by the defined mechanism. Each mechanism requires different properties, and it is recommended to use tab completion to examine the various requirements for the defined mechanism.
Attribute | Description |
---|---|
--mechanism |
Specifies the mechanism to enable or disable. A list of supported SASL mechanisms is available at Support Level for SASL Authentication Mechanisms, and the |
--no-reload | If specified, then the server is not reloaded after the security command is completed. |
Mechanism Specific Attributes
The following attributes are only eligible for specific mechanisms. They are grouped below based on their function.
Attribute | Description |
---|---|
--key-store-name |
The name of the truststore as an existing keystore. This must be specified if |
--key-store-realm-name |
The name of the truststore as an existing keystore realm. This must be specified if |
--roles | An optional argument that defines a comma separated list of roles associated with the current identity. If no existing role mapper contains the specified list of roles, then a role mapper will be generated and assigned. |
Attribute | Description |
---|---|
--exposed-realm | The realm exposed to the user. |
--file-system-realm-name | The name of the filesystem realm. |
--user-role-decoder |
The name of the role decoder used to extract the roles from the user’s repository. This attribute is only used if |
Attribute | Description |
---|---|
--exposed-realm |
The realm exposed to the user. This value must match the |
--groups-properties-file |
A path to the properties file that contains the |
--properties-realm-name | The name of an existing properties realm. |
--relative-to |
Adjusts the paths of |
--users-properties-file | A path to the properties file that contains the user details. |
Attribute | Description |
---|---|
--management-interface |
The management interface to configure for management authentication commands. This defaults to the |
--new-auth-factory-name | Used to specify a name for the authentication factory. If not defined, a name is automatically created. |
--new-realm-name | Used to specify a name for the properties file realm resource. If not defined, a name is automatically created. |
--new-security-domain | Used to specify a name for the security domain. If not defined, a name is automatically created. |
--super-user |
Configures a local user with super-user permissions. Usable with the |
A.5. Elytron Client Side One Way Example
After configuring a server SSL context, it is important to test the configuration if possible. An Elytron client SSL context can be placed in a configuration file and then executed from the management CLI, allowing functional testing of the server configuration. These steps assume that the server-side configuration is completed, and the server has been reloaded if necessary.
If the server keystore already exists, then proceed to the next step; otherwise, create the server keystore.
$ keytool -genkeypair -alias localhost -keyalg RSA -keysize 1024 -validity 365 -keystore server.keystore.jks -dname "CN=localhost" -keypass secret -storepass secret
If the server certificate has already been exported, then proceed to the next step; otherwise, export the server certificate.
$ keytool -exportcert -keystore server.keystore.jks -alias localhost -keypass secret -storepass secret -file server.cer
Import the server certificate into the client’s truststore.
$ keytool -importcert -keystore client.truststore.jks -storepass secret -alias localhost -trustcacerts -file server.cer
Define the client-side SSL context inside of
example-security.xml
. This configuration file contains an Elytronauthentication-client
that defines the authentication and SSL configuration for outbound connections. The following file demonstrates defining a client SSL context and keystore.<?xml version="1.0" encoding="UTF-8"?> <configuration> <authentication-client xmlns="urn:elytron:client:1.2"> <key-stores> <key-store name="clientStore" type="jks" > <file name="/path/to/client.truststore.jks"/> <key-store-clear-password password="secret" /> </key-store> </key-stores> <ssl-contexts> <ssl-context name="client-SSL-context"> <trust-store key-store-name="clientStore" /> </ssl-context> </ssl-contexts> <ssl-context-rules> <rule use-ssl-context="client-SSL-context" /> </ssl-context-rules> </authentication-client> </configuration>
Using the management CLI, reference the newly created file and attempt to access the server. The following command accesses the management interface and executes the
whoami
command.$ EAP_HOME/bin/jboss-cli.sh -c --controller=remote+https://127.0.0.1:9993 -Dwildfly.config.url=/path/to/example-security.xml :whoami
A.6. Elytron Client Side Two Way Example
After configuring a server SSL context, it is important to test the configuration if possible. An Elytron client SSL context can be placed in a configuration file and then executed from the management CLI, allowing functional testing of the server configuration. These steps assume that the server-side configuration is completed, and the server has been reloaded if necessary.
If the server and client keystores already exist, then proceed to the next step; otherwise, create the server and client keystores.
$ keytool -genkeypair -alias localhost -keyalg RSA -keysize 1024 -validity 365 -keystore server.keystore.jks -dname "CN=localhost" -keypass secret -storepass secret $ keytool -genkeypair -alias client -keyalg RSA -keysize 1024 -validity 365 -keystore client.keystore.jks -dname "CN=client" -keypass secret -storepass secret
If the server and client certificates have already been exported, then proceed to the next step; otherwise, export the server and client certificates.
$ keytool -exportcert -keystore server.keystore.jks -alias localhost -keypass secret -storepass secret -file server.cer $ keytool -exportcert -keystore client.keystore.jks -alias client -keypass secret -storepass secret -file client.cer
Import the server certificate into the client’s truststore.
$ keytool -importcert -keystore client.truststore.jks -storepass secret -alias localhost -trustcacerts -file server.cer
Import the client certificate into the server’s truststore.
$ keytool -importcert -keystore server.truststore.jks -storepass secret -alias client -trustcacerts -file client.cer
Define the client-side SSL context inside of
example-security.xml
. This configuration file contains an Elytronauthentication-client
that defines the authentication and SSL configuration for outbound connections. The following file demonstrates defining a client SSL context and keystore.<?xml version="1.0" encoding="UTF-8"?> <configuration> <authentication-client xmlns="urn:elytron:client:1.2"> <key-stores> <key-store name="clientStore" type="jks" > <file name="/path/to/client.truststore.jks"/> <key-store-clear-password password="secret" /> </key-store> </key-stores> <key-store name="clientKeyStore" type="jks" > <file name="/path/to/client.keystore.jks"/> <key-store-clear-password password="secret" /> </key-store> <ssl-contexts> <ssl-context name="client-SSL-context"> <trust-store key-store-name="clientStore" /> <key-store-ssl-certificate key-store-name="clientKeyStore" alias="client"> <key-store-clear-password password="secret" /> </key-store-ssl-certificate> </ssl-context> </ssl-contexts> <ssl-context-rules> <rule use-ssl-context="client-SSL-context" /> </ssl-context-rules> </authentication-client> </configuration>
Using the management CLI, reference the newly created file and attempt to access the server. The following command accesses the management interface and executes the
whoami
command.$ EAP_HOME/bin/jboss-cli.sh -c --controller=remote+https://127.0.0.1:9993 -Dwildfly.config.url=/path/to/example-security.xml :whoami
Revised on 2024-01-17 05:25:10 UTC