Chapter 5. Reference
Chapter 5. Reference 5.1. custom-realm attributes You can configure your custom-realm by setting its attributes. Table 5.1. custom-realm attributes Attribute Description class-name Fully qualified class name of the implementation of the custom realm. configuration The optional key/value configuration for the custom realm. module Name of the module to use to load the custom realm. 5.2. filesystem-realm attributes You can configure filesystem-realm by setting its attributes. Table 5.2. filesystem-realm attributes Attribute Description credential-store Reference to the credential store that contains the secret key to encrypt and decrypt the clear passwords, hashed passwords, and attributes in the realm. When you use this attribute, you must also specify the secret key to use by defining it in the secret-key attribute. encoded The attribute that indicates whether the identity names should be stored encoded (Base32) in file names. The default value is true . hash-charset The character set to use when converting the password string to a byte array. The default is UTF-8. hash-encoding The string format for the password if it is not stored in plain text. It can be one of: base64 hex The default is base64. key-store Reference to the key store that contains the key pair to use to verify integrity. When you define this attribute, you must also specify the key store alias in the key-store-alias attribute. key-store-alias The alias that identifies the private key entry within the key store to use to verify integrity. Use this attribute if you have added a reference to a key store by defining the key-store attribute. levels The number of levels of directory hashing to apply. The default value is 2 . path The path to the directory containing the realm. relative-to The predefined relative path to use with path . For example jboss.server.config.dir . secret-key The alias of the secret key to encrypt and decrypt the clear passwords, hashed passwords, and attributes in the realm. Use this attribute if you have added a reference to a credential store by defining the credential-store attribute. 5.3. file-audit-log attributes Table 5.3. file-audit-log attributes Attribute Description autoflush Specifies if the output stream requires flushing after every audit event. If you do not define the attribute, the synchronized attribute value is the default. encoding Specifies the audit file encoding. The default is UTF-8 . The possible values are the following: UTF-8 UTF-16BE UTF-16LE UTF-16 US-ASCII ISO-8859-1 format Default value is SIMPLE . Use SIMPLE for human readable text format or JSON for storing individual events in JSON . path Defines the location of the log files. relative-to Optional attribute. Defines the location of the log files. synchronized Default value is true . Specifies that the file descriptor gets synchronized after every audit event. 5.4. http-authentication-factory attributes You can configure http-authentication-factory by setting its attributes. Table 5.4. http-authentication-factory attributes Attribute Description http-server-mechanism-factory The HttpServerAuthenticationMechanismFactory to associate with this resource. mechanism-configurations The list of mechanism-specific configurations. security-domain The security domain to associate with the resource. Table 5.5. http-authentication-factory mechanism-configurations attributes 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. Table 5.6. http-authentication-factory mechanism-configurations mechanism-realm-configurations attributes 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. 5.5. identity-realm attributes You can configure your identity-realm by setting its attributes. Table 5.7. identity-realm attributes Attribute Description attribute-name The name of the attribute associated with this identity. attribute-values The list of values associated with the identity's attribute. identity The identity available from the security realm. 5.6. jdbc-realm attributes You can configure jdbc-realm by setting its attributes. Table 5.8. jdbc-realm Attributes Attribute Description hash-charset The character set to use when converting the password string to a byte array. The default is UTF-8. principal-query The list of authentication queries used to authenticate users based on specific key types. Table 5.9. jdbc-realm principal-query Attributes 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 Bcrypt key type. clear-password-mapper A key mapper that maps a column returned from a SQL query to a clear password key type. This has a password-index child element that is the column index from an authentication query that represents the user password. data-source The name of the data source used to connect to the database. salted-simple-digest-mapper A key mapper that maps a column returned from a SQL query to a Salted Simple Digest key type. scram-mapper A key mapper that maps a column returned from a SQL query to a SCRAM key type. simple-digest-mapper A key mapper that maps a column returned from a SQL query to a Simple Digest key type. sql The SQL statement used to obtain the keys as table columns for a specific user and map them accordingly with their type. Table 5.10. jdbc-realm principal-query attribute-mapping Attributes Attribute Description index The column index from the SQL query that represents the mapped attribute. to The name of the identity attribute mapped from a column returned from the SQL query. Additional resources Password mapper attributes 5.7. key-store attributes You can configure a key-store by setting its attributes. Table 5.11. key-store attributes 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: ALL:-alias1:-alias2 NONE:+alias1:+alias2 Note The alias-filter attribute is case sensitive. Because the use of mixed-case or uppercase aliases, such as elytronAppServer , might not be recognized by some keystore providers, it is recommended to use lowercase aliases, such as elytronappserver . 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 credential-store . path The path to the keystore file. provider-name The name of the provider to use to load the keystore. When you set this attribute, the search for the first provider that can create a key store of the specified type is disabled. 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 a predefined path such as jboss.server.config.dir . required If set to true , the key store file referenced must exist at the time the key store service starts. The default value is false . type The type of the key store, for example, JKS . Note The following key store types are automatically detected: JKS JCEKS PKCS12 BKS BCFKS UBER You must manually specify the other key store types. A full list of key store types can be found in Java Cryptography Architecture Standard Algorithm Name Documentation for JDK 11 in the Oracle JDK documentation. 5.8. ldap-realm attributes You can configure ldap-realm by setting its attributes. Table 5.12. ldap-realm attributes Attribute Description allow-blank-password Whether this realm supports blank password direct verification. If this attribute is not set, a blank password attempt is rejected. dir-context The name of the dir-context which will be used to connect to the LDAP server. direct-verification If this attribute is set to true , this realm supports verification of credentials by directly connecting to LDAP as the account being authenticated. Otherwise, the password is retrieved from the LDAP server and verified in JBoss EAP. If enabled, the JBoss EAP server must be able to obtain the plain user password from the client, which requires either the PLAIN SASL or BASIC HTTP mechanism to be used for authentication. Defaults to false . hash-charset The character set to use when converting the password string to a byte array. The default is UTF-8. hash-encoding The string format for the password if it is not stored in plain text. It can be one of: base64 hex The default is base64. identity-mapping The configuration options that define how principals are mapped to their corresponding entries in the underlying LDAP server. Table 5.13. ldap-realm identity-mapping attributes 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. It is required for the modifiability of the realm. This is a list of name and value pair objects. new-identity-parent-dn The DN of the parent of newly created identities. Required for modifiability of the realm. otp-credential-mapper The credential mapping for OTP credential. 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 this attribute is set to true , identity search queries are recursive. Defaults to false . user-password-mapper The credential mapping for a credential, similar to userPassword. x509-credential-mapper The configuration that enables using LDAP as storage of X509 credentials. If none of the -from child attributes are defined, then this configuration will be ignored. If more than one -from child attribute is defined, then the user certificate must match all the defined criteria. Table 5.14. ldap-realm identity-mapping attribute-mapping attributes 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. The string {0} will be replaced by username and`{1}` by user identity DN. 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 the LDAP attribute containing DN of entry to obtain value from. role-recursion Maximum depth for recursive role assignment. Use 0 to specify no recursion. Defaults to 0 . role-recursion-name Determine the LDAP attribute of role entry which will be a substitute for "{0}" in filter-name when searching roles of role. search-recursive If true attribute LDAP search queries are recursive. Defaults to true . 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 defined in from . If from is not defined too, the dn value is used. Table 5.15. ldap-realm identity-mapping user-password-mapper attributes 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 true password can be used to verify the user. Defaults to true . writable If true password can be changed. Defaults to false . Table 5.16. ldap-realm identity-mapping otp-credential-mapper Attributes 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. Table 5.17. ldap-realm identity-mapping x509-credential-mapper attributes Attribute Description certificate-from The name of the LDAP attribute to map to an encoded user certificate. If not defined, the encoded certificate will not be checked. digest-algorithm The digest algorithm, which is the hash function, that is used to compute the digest of the user certificate. It will be used only if digest-from has been defined. digest-from The name of the LDAP attribute to map to a user certificate digest. If not defined, the certificate digest will not be checked. serial-number-from The name of the LDAP attribute to map to a serial number of the user certificate. If not defined, the 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, the subject DN will not be checked. 5.9. Password mapper attributes A password mapper constructs a password from multiple fields in a database using one of the following algorithm types: Clear text Simple digest Salted simple digest bcrypt SCRAM Modular crypt A password mapper has the following attributes: Note The index of the first column is 1 for all the mappers. Table 5.18. password mapper attributes Mapper name Attributes Encryption method clear-password-mapper password-index The index of the column containing the clear text password. No encryption. simple-digest password-index The index of the column containing the password hash. algorithm The hashing algorithm used. The following values are supported: simple-digest-md2 simple-digest-md5 simple-digest-sha-1 simple-digest-sha-256 simple-digest-sha-384 simple-digest-sha-512 hash-encoding Specify the representation hash. Permitted values: base64 (default) hex A simple hashing mechanism is used. salted-simple-digest password-index The index of the column containing the password hash. algorithm The hashing algorithm used. The following values are supported: password-salt-digest-md5 password-salt-digest-sha-1 password-salt-digest-sha-256 password-salt-digest-sha-384 password-salt-digest-sha-512 salt-password-digest-md5 salt-password-digest-sha-1 salt-password-digest-sha-256 salt-password-digest-sha-384 salt-password-digest-sha-512 salt-index Index of the column containing the salt used for hashing. hash-encoding Specify the representation for the hash. Permitted values: base64 (default) hex salt-encoding Specify the representation for the salt. Permitted values: base64 (default) hex A simple hashing mechanism is used with a salt. bcrypt-password-mapper password-index The index of the column containing the password hash. salt-index Index of the column containing the salt used for hashing. iteration-count-index Index of the column containing the number of iterations used. hash-encoding Specify the representation for the hash. Permitted values: base64 (default) hex salt-encoding Specify the representation for the salt. Permitted values: base64 (default) hex Blowfish algorithm used for hashing. scram-mapper password-index The index of the column containing the password hash. algorithm The hashing algorithm used. The following values are supported: scram-sha-1 scram-sha-256 scram-sha-384 scram-sha-512 salt-index Index of the column containing the salt is used for hashing. iteration-count-index Index of the column containing the number of iterations used. hash-encoding Specify the representation for the hash. Permitted values: base64 (default) hex salt-encoding Specify the representation for the salt. Permitted values: base64 (default) hex Salted Challenge Response Authentication mechanism is used for hashing. modular-crypt-mapper password-index The index of the column containing the encrypted password. The modular-crypt encoding supports multiple pieces of information to be encoded in a single string. The information can include the following: password type hash or digest salt iteration count 5.10. periodic-rotating-file-audit-log attributes Table 5.19. periodic-rotating-file-audit-log attributes Attribute Description autoflush Specifies if the output stream requires flushing after every audit event. If you do not define the attribute, the synchronized attribute value is the default. encoding Specifies the audit file encoding. The default is UTF-8 . The possible values are the following: UTF-8 UTF-16BE UTF-16LE UTF-16 US-ASCII ISO-8859-1 format Use SIMPLE for human readable text format or JSON for storing individual events in JSON . path Defines the location of the log files. relative-to Optional attribute. Defines the location of the log files. suffix Optional attribute. Adds a date suffix to a rotated log. You must use the java.time.format.DateTimeFormatter format. For example .yyyy-MM-dd . synchronized Default value is true . Specifies that the file descriptor gets synchronized after every audit event. 5.11. properties-realm attributes You can configure properties-realm by setting its attributes. Table 5.20. properties-realm attributes Attribute Description groups-attribute The name of the attribute in the returned AuthorizationIdentity that should contain the group membership information for the identity. groups-properties The properties file containing the users and their groups. hash-charset Specifies the name of the character set to use when converting the client provided password string to a byte array for hashing calculations. Set to UTF-8 by default. hash-encoding Specifies the string format for the hashed password if the password is not being stored in plain text. It may specify one of two: hex or base64 . Set to hex by default for properties-realm . users-properties The properties file containing the users and their passwords. Table 5.21. properties-realm users-properties attributes 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 true , the passwords in properties file stored in plain text. If false , they are pre-hashed, taking the form of HEX(MD5(username ':' realm ':' password)) . Defaults to false . relative-to The predefined path that the path is relative to. Table 5.22. properties-realm groups-properties attributes Attribute Description path The path to the file containing the users and their groups. relative-to The predefined path that the path is relative to. 5.12. sasl-authentication-factory attributes You can configure sasl-authentication-factory by setting its attributes. Table 5.23. sasl-authentication-factory attributes 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. Table 5.24. sasl-authentication-factory mechanism-configurations attributes 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. Table 5.25. sasl-authentication-factory mechanism-configurations mechanism-realm-configurations attributes 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. 5.13. secret-key-credential-store Attributes You can configure secret-key-credential-store by setting its attributes. Table 5.26. secret-key-credential-store Attributes Attribute Description create Set the value to false if you do not want Elytron to create one if it doesn't already exist. Defaults to true . default-alias The alias name for a key generated by default. The default value is key . key-size The size of a generated key. The default size is 256 bits. You can set the value to one of the following: 128 192 256 path The path to the credential store. populate If a credential store does not contain a default-alias , this attribute indicates whether Elytron should create one. The default is true . relative-to A reference to a previously defined path that the attribute path is relative to. 5.14. security-domain attributes You can configure security-domain by setting its attributes. Attribute Description default-realm The default realm contained by this security domain. evidence-decoder A reference to an EvidenceDecoder to be used by this domain. outflow-anonymous This attribute specifies whether the anonymous identity should be used if outflow to a security domain is not possible, which happens in the following scenarios: The domain to outflow to does not trust this domain. The identity being outflowed to a domain does not exist in that domain Outflowing anonymous identity clears any previously established identity for that domain. outflow-security-domains The list of security domains that the security identity from this domain should automatically outflow to. permission-mapper A reference to a PermissionMapper to be used by this domain. post-realm-principal-transformer A reference to a principal transformer to be applied after the realm has operated on the supplied identity name. pre-realm-principal-transformer A reference to a principal transformer to be applied before the realm is selected. principal-decoder A reference to a PrincipalDecoder to be used by this domain. realm-mapper Reference to the RealmMapper to be used by this domain. realms The list of realms contained by this security domain. role-decoder Reference to the RoleDecoder to be used by this domain. role-mapper Reference to the RoleMapper to be used by this domain. security-event-listener Reference to a listener for security events. trusted-security-domains The list of security domains that are trusted by this security domain. trusted-virtual-security-domains The list of virtual security domains that are trusted by this security domain. 5.15. simple-role-decoder attributes You can configure simple role decoder by setting its attribute. Table 5.27. simple-role-decoder attributes Attribute Description attribute The name of the attribute from the identity to map directly to roles. 5.16. size-rotating-file-audit-log attributes Table 5.28. size-rotating-file-audit-log attributes Attribute Description autoflush Specifies if the output stream requires flushing after every audit event. If you do not define the attribute, the synchronized attribute value is the default. encoding Specifies the audit file encoding. The default is UTF-8 . The possible values are the following: UTF-8 UTF-16BE UTF-16LE UTF-16 US-ASCII ISO-8859-1 format Default value is SIMPLE . Use SIMPLE for human readable text format or JSON for storing individual events in JSON . max-backup-index The maximum number of files to back up when rotating. The default value is 1 . path Defines the location of the log files. relative-to Optional attribute. Defines the location of the log files. rotate-on-boot By default, Elytron does not create a new log file when you restart a server. Set this attribute to true to rotate the log on server restart. rotate-size The maximum size that the log file can reach before Elytron rotates the log. The default is 10m for 10 megabytes. You can also define the maximum size of the log with k, g, b, or t units. You can specify units in either uppercase or lowercase characters. suffix Optional attribute. Adds a date suffix to a rotated log. You must use the java.text.format.DateTimeFormatter format. For example .yyyy-MM-dd-HH . synchronized Default value is true . Specifies that the file descriptor gets synchronized after every audit event. 5.17. syslog-audit-log attributes Table 5.29. syslog-audit-log attributes Attribute Description format The format in which audit events are recorded. Supported values: JSON SIMPLE Default value: SIMPLE host-name The host name to 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: Any positive integer value. -1 indicates infinite reconnect attempts. Default value: 0 server-address IP address of the syslog server or a name that can be resolved by Java's InetAddress.getByName() method. ssl-context The SSL context to use when connecting to the syslog server. This attribute is only required if transport is set to SSL_TCP . syslog-format The RFC format to be used for describing the audit event. Supported values: RFC3164 RFC5424 Default value: RFC5424 transport The transport layer protocol to use to connect to the syslog server. Supported values: SSL_TCP TCP UDP Default value: TCP