Chapter 1. Configuring identity stores

1.1. Creating a filesystem-realm

1.1.1. Filesystem realm in Elytron

With a filesystem security realm, filesystem-realm, you can use a filesystem-based identity store in Elytron to store user credentials and attributes. Elytron stores each identity along with the associated credentials and attributes in an XML file in the filesystem. The name of the XML file is the name of the identity. You can associate multiple credentials and attributes with each identity.

By default, identities are stored in the filesystem as follows:

  • Elytron applies two levels of directory hashing to the directory structure where an identity is stored. For example, an identity named "user1" is stored at the location u/s/user1.xml.

    This is done to overcome the limit set by some filesystems on the number of files you can store in a single directory and for performance reasons.

    Use the levels attribute to configure the number of levels of directory hashing to apply.

  • The identity names are Base32 encoded before they are used as filenames. This is done because some filesystems are case-insensitive or might restrict the set of characters allowed in a filename.

    You can turn off the encoding by setting the attribute encoded to false.

For information about other attributes and their default values, see filesystem-realm attributes.

Encryption

The filesystem-realm uses Base64 encoding for clear passwords, hashed passwords, and attributes when storing an identity in an identity file. For added security, you can encrypt the clear passwords, hashed passwords, and attributes using a secret key stored in a credential store. The secret key is used both for encrypting and decrypting the passwords and attributes.

Integrity check

To ensure that the identities created with a filesystem-realm are not tampered with, you can enable integrity checking on the filesystem-realm by referencing a key pair in the filesystem-realm during creation.

Integrity checking works in filesystem-realm as follows:

  • When you create an identity in the filesystem-realm with integrity checking enabled, Elytron creates the identity file and generates a signature for it.
  • Whenever the identity file is read, for example when updating the identity or loading the identity for authentication, Elytron verifies the identity file contents against the signature to ensure the file has not been tampered with since the last authorized write.

  • When you update an existing identity that has an associated signature, Elytron updates the content and generates a new signature after the original content passes verification.

    If the verification fails, you get the following failure message: 

    {
    "outcome" => "failed",
    "failure-description" => "WFLYCTL0158: Operation handler failed:java.lang.RuntimeException: WFLYELY01008: Failed to obtain the authorization identity.",
    "rolled-back" => true
}

Additional resources

1.1.2. Creating a filesystem-realm in Elytron

Create a filesystem-realm and a security domain that references the realm to secure the JBoss EAP server interfaces or the applications deployed on the server.

Prerequisites

  • JBoss EAP is running.

Procedure

  1. Create a filesystem-realm in Elytron.

    Syntax

    /subsystem=elytron/filesystem-realm=<filesystem_realm_name>:add(path=<file_path>)

    Example

    /subsystem=elytron/filesystem-realm=exampleSecurityRealm:add(path=fs-realm-users,relative-to=jboss.server.config.dir)
{"outcome" => "success"}

  2. Add a user to the realm and configure the user’s role.

    1. Add a user.

      Syntax

      /subsystem=elytron/filesystem-realm=<filesystem_realm_name>:add-identity(identity=<user_name>)

      Example

      /subsystem=elytron/filesystem-realm=exampleSecurityRealm:add-identity(identity=user1)
{"outcome" => "success"}

    2. Set a password for the user.

      Syntax

      /subsystem=elytron/filesystem-realm=<filesystem_realm_name>:set-password(identity=<user_name>, clear={password=<password>})

      Example

      /subsystem=elytron/filesystem-realm=exampleSecurityRealm:set-password(identity=user1, clear={password="passwordUser1"})
{"outcome" => "success"}

    3. Set roles for the user.

      Syntax

      /subsystem=elytron/filesystem-realm=<filesystem_realm_name>:add-identity-attribute(identity=<user_name>, name=<roles_attribute_name>, value=[<role_1>,<role_N>])

      Example

      /subsystem=elytron/filesystem-realm=exampleSecurityRealm:add-identity-attribute(identity=user1, name=Roles, value=["Admin","Guest"])
{"outcome" => "success"}

  3. Create a security domain that references the filesystem-realm.

    Syntax

    /subsystem=elytron/security-domain=<security_domain_name>:add(default-realm=<filesystem_realm_name>,permission-mapper=default-permission-mapper,realms=[{realm=<filesystem_realm_name>,role-decoder="<role_decoder_name>"}])

    Example

    /subsystem=elytron/security-domain=exampleSecurityDomain:add(default-realm=exampleSecurityRealm,permission-mapper=default-permission-mapper,realms=[{realm=exampleSecurityRealm}])
{"outcome" => "success"}

Verification

  • To verify that Elytron can load an identity from the filesystem-realm, use the following command:

    Syntax

    /subsystem=elytron/security-domain=<security_domain_name>:read-identity(name=<username>)

    Example

    /subsystem=elytron/security-domain=exampleSecurityDomain:read-identity(name=user1)
{
    "outcome" => "success",
    "result" => {
        "name" => "user1",
        "attributes" => {"Roles" => [
            "Admin",
            "Guest"
        ]},
        "roles" => [
            "Guest",
            "Admin"
        ]
    }
}

You now can use the created security domain to add authentication and authorization to management interfaces and applications. For more information, see Securing management interfaces and applications.

Additional resources

1.1.3. Creating an encrypted filesystem-realm in Elytron

Create an encrypted filesystem-realm to secure JBoss EAP applications or server interfaces and ensure that the user credentials are encrypted and therefore secure.

1.1.3.1. Creating a secret-key-credential-store for a standalone server

Create a secret-key-credential-store using the management CLI. When you create a secret-key-credential-store, JBoss EAP generates a secret key by default. The name of the generated key is key and its size is 256-bit.

Prerequisites

  • JBoss EAP is running.
  • You have provided at least read/write access to the directory containing the secret-key-credential-store for the user account under which JBoss EAP is running.

Procedure

  • Use the following command to create a secret-key-credential-store using the management CLI:

    Syntax

    /subsystem=elytron/secret-key-credential-store=<name_of_credential_store>:add(path="<path_to_the_credential_store>", relative-to=<path_to_store_file>)

    Example

    /subsystem=elytron/secret-key-credential-store=examplePropertiesCredentialStore:add(path=examplePropertiesCredentialStore.cs, relative-to=jboss.server.config.dir)
{"outcome" => "success"}

1.1.3.2. Creating an encrypted filesystem-realm

Create an encrypted filesystem-realm and a security domain that references the realm to secure the JBoss EAP server interfaces or the applications deployed on the server.

Prerequisites

Procedure

  1. Create an encrypted filesystem-realm in Elytron.

    Syntax

    /subsystem=elytron/filesystem-realm=<filesystem_realm_name>:add(path=<file_path>,credential-store=<name_of_credential_store>,secret-key=<key>)

    Example

    /subsystem=elytron/filesystem-realm=exampleSecurityRealm:add(path=fs-realm-users,relative-to=jboss.server.config.dir, credential-store=examplePropertiesCredentialStore, secret-key=key)
{"outcome" => "success"}

  2. Add a user to the realm and configure the user’s role.

    1. Add a user.

      Syntax

      /subsystem=elytron/filesystem-realm=<filesystem_realm_name>:add-identity(identity=<user_name>)

      Example

      /subsystem=elytron/filesystem-realm=exampleSecurityRealm:add-identity(identity=user1)
{"outcome" => "success"}

    2. Set a password for the user.

      Syntax

      /subsystem=elytron/filesystem-realm=<filesystem_realm_name>:set-password(identity=<user_name>, clear={password=<password>})

      Example

      /subsystem=elytron/filesystem-realm=exampleSecurityRealm:set-password(identity=user1, clear={password="passwordUser1"})
{"outcome" => "success"}

    3. Set roles for the user.

      Syntax

      /subsystem=elytron/filesystem-realm=<filesystem_realm_name>:add-identity-attribute(identity=<user_name>, name=<roles_attribute_name>, value=[<role_1>,<role_N>])

      Example

      /subsystem=elytron/filesystem-realm=exampleSecurityRealm:add-identity-attribute(identity=user1, name=Roles, value=["Admin","Guest"])
{"outcome" => "success"}

  3. Create a security domain that references the filesystem-realm.

    Syntax

    /subsystem=elytron/security-domain=<security_domain_name>:add(default-realm=<filesystem_realm_name>,permission-mapper=default-permission-mapper,realms=[{realm=<filesystem_realm_name>,role-decoder="<role_decoder_name>"}])

    Example

    /subsystem=elytron/security-domain=exampleSecurityDomain:add(default-realm=exampleSecurityRealm,permission-mapper=default-permission-mapper,realms=[{realm=exampleSecurityRealm}])
{"outcome" => "success"}

Verification

  • To verify that Elytron can load an identity from the encrypted filesystem-realm, use the following command:

    Syntax

    /subsystem=elytron/security-domain=<security_domain_name>:read-identity(name=<username>)

    Example

    /subsystem=elytron/security-domain=exampleSecurityDomain:read-identity(name=user1)
{
    "outcome" => "success",
    "result" => {
        "name" => "user1",
        "attributes" => {"Roles" => [
            "Admin",
            "Guest"
        ]},
        "roles" => [
            "Guest",
            "Admin"
        ]
    }
}

You can now use the created security domain to add authentication and authorization to management interfaces and applications.

Additional resources

1.1.4. Creating a filesystem-realm with integrity support in Elytron

Create a filesystem-realm with integrity support to secure JBoss EAP applications or server interfaces and ensure that the user credentials are not tampered with.

1.1.4.1. Creating a key pair by using the management CLI

Create a key store with a key pair in Elytron.

Prerequisites

  • JBoss EAP is running.

Procedure

  1. Create a key store.

    Syntax

    /subsystem=elytron/key-store=<key_store_name>:add(path=<path_to_key_store_file>,credential-reference={<password>})

    Example

    /subsystem=elytron/key-store=exampleKeystore:add(path=keystore, relative-to=jboss.server.config.dir, type=JKS, credential-reference={clear-text=secret})
{"outcome" => "success"}

  2. Create a key pair in the key store.

    Syntax

    /subsystem=elytron/key-store=<key_store_name>:generate-key-pair(alias=<alias>,algorithm=<key_algorithm>,key-size=<size_of_key>,validity=<validity_in_days>,distinguished-name="<distinguished_name>")

    Example

    /subsystem=elytron/key-store=exampleKeystore:generate-key-pair(alias=localhost,algorithm=RSA,key-size=1024,validity=365,distinguished-name="CN=localhost")
{"outcome" => "success"}

  3. Persist the key pair to the key store file.

    Syntax

    /subsystem=elytron/key-store=<key_store_name>:store()

    Example

    /subsystem=elytron/key-store=exampleKeystore:store()
{
    "outcome" => "success",
    "result" => undefined
}

Additional resources

1.1.4.2. Creating a filesystem-realm with integrity support

Create a filesystem-realm with integrity support and a security domain that references the realm to secure the JBoss EAP server interfaces or the applications deployed on the server.

Prerequisites

Procedure

  1. Create filesystem-realm in Elytron.

    Syntax

    /subsystem=elytron/filesystem-realm=<filesystem_realm_name>:add(path=<file_path>,key-store=<key_store_name>,key-store-alias=<key_store_alias>)

    Example

    /subsystem=elytron/filesystem-realm=exampleSecurityRealm:add(path=fs-realm-users,relative-to=jboss.server.config.dir, key-store=exampleKeystore, key-store-alias=localhost)
{"outcome" => "success"}

  2. Add a user to the realm and configure the user’s role.

    1. Add a user.

      Syntax

      /subsystem=elytron/filesystem-realm=<filesystem_realm_name>:add-identity(identity=<user_name>)

      Example

      /subsystem=elytron/filesystem-realm=exampleSecurityRealm:add-identity(identity=user1)
{"outcome" => "success"}

    2. Set a password for the user.

      Syntax

      /subsystem=elytron/filesystem-realm=<filesystem_realm_name>:set-password(identity=<user_name>, clear={password=<password>})

      Example

      /subsystem=elytron/filesystem-realm=exampleSecurityRealm:set-password(identity=user1, clear={password="passwordUser1"})
{"outcome" => "success"}

    3. Set roles for the user.

      Syntax

      /subsystem=elytron/filesystem-realm=<filesystem_realm_name>:add-identity-attribute(identity=<user_name>, name=<roles_attribute_name>, value=[<role_1>,<role_N>])

      Example

      /subsystem=elytron/filesystem-realm=exampleSecurityRealm:add-identity-attribute(identity=user1, name=Roles, value=["Admin","Guest"])
{"outcome" => "success"}

  3. Create a security domain that references the filesystem-realm.

    Syntax

    /subsystem=elytron/security-domain=<security_domain_name>:add(default-realm=<filesystem_realm_name>,permission-mapper=default-permission-mapper,realms=[{realm=<filesystem_realm_name>,role-decoder="<role_decoder_name>"}])

    Example

    /subsystem=elytron/security-domain=exampleSecurityDomain:add(default-realm=exampleSecurityRealm,permission-mapper=default-permission-mapper,realms=[{realm=exampleSecurityRealm}])
{"outcome" => "success"}

Verification

  • To verify that Elytron can load an identity from the filesystem-realm, use the following command:

    Syntax

    /subsystem=elytron/security-domain=<security_domain_name>:read-identity(name=<username>)

    Example

    /subsystem=elytron/security-domain=exampleSecurityDomain:read-identity(name=user1)
{
    "outcome" => "success",
    "result" => {
        "name" => "user1",
        "attributes" => {"Roles" => [
            "Admin",
            "Guest"
        ]},
        "roles" => [
            "Guest",
            "Admin"
        ]
    }
}

You now can use the created security domain to add authentication and authorization to management interfaces and applications. For more information, see Securing management interfaces and applications.

Additional resources

1.1.4.3. Updating the key pair in an existing filesystem-realm with integrity support enabled

You can update the key pair referenced in a filesystem-realm with integrity support enabled in the case that the existing key was compromised. Also, it is a good practice to rotate keys.

Prerequisites

Procedure

  1. Create a key pair in the existing key store.

    Syntax

    /subsystem=elytron/key-store=<key_store_name>:generate-key-pair(alias=<alias>,algorithm=<key_algorithm>,key-size=<size_of_key>,validity=<validity_in_days>,distinguished-name="<distinguished_name>")

    Example

    /subsystem=elytron/key-store=exampleKeystore:generate-key-pair(alias=localhost2,algorithm=RSA,key-size=1024,validity=365,distinguished-name="CN=localhost")
{"outcome" => "success"}

  2. Persist the key pair to the key store file.

    Syntax

    /subsystem=elytron/key-store=<key_store_name>:store()

    Example

    /subsystem=elytron/key-store=exampleKeystore:store()
{
    "outcome" => "success",
    "result" => undefined
}

  3. Update the key store alias to reference a new key pair.

    Syntax

    /subsystem=elytron/filesystem-realm=<filesystem_realm_name>:write-attribute(name=key-store-alias, value=<key_store_alias>)

    Example

    /subsystem=elytron/filesystem-realm=exampleSecurityRealm:write-attribute(name=key-store-alias, value=localhost2)
{
    "outcome" => "success",
    "response-headers" => {
        "operation-requires-reload" => true,
        "process-state" => "reload-required"
    }
}

  4. Reload the server. 

    reload

  5. Use the new key pair to update the files in filesystem-realm with new signatures.

    Syntax

    /subsystem=elytron/filesystem-realm=<filesystem_realm_name>:update-key-pair()

    Example

    /subsystem=elytron/filesystem-realm=exampleSecurityRealm:update-key-pair()
{"outcome" => "success"}

Verification

  • Verify that the key pair referenced in the filesystem-realm has been updated using the following management CLI command:

    Syntax

    /subsystem=elytron/filesystem-realm=<filesystem_realm_name>:read-resource()

    Example

    /subsystem=elytron/filesystem-realm=exampleSecurityRealm:read-resource()
{
    "outcome" => "success",
    "result" => {
        "credential-store" => undefined,
        "encoded" => true,
        "hash-charset" => "UTF-8",
        "hash-encoding" => "base64",
        "key-store" => "exampleKeystoreFSRealm",
        "key-store-alias" => "localhost2",
        "levels" => 2,
        "secret-key" => undefined,
        "path" => "fs-realm-users",
        "relative-to" => "jboss.server.config.dir"
    }
}

The key pair referenced in the filesystem-realm has been updated.

Additional resources

1.1.5. Encrypting an unencrypted filesystem-realm

If you have a filesystem-realm configured in Elytron, you can add encryption to it using the WildFly Elytron Tool.

1.1.5.1. Creating a secret-key-credential-store for a standalone server

Create a secret-key-credential-store using the management CLI. When you create a secret-key-credential-store, JBoss EAP generates a secret key by default. The name of the generated key is key and its size is 256-bit.

Prerequisites

  • JBoss EAP is running.
  • You have provided at least read/write access to the directory containing the secret-key-credential-store for the user account under which JBoss EAP is running.

Procedure

  • Use the following command to create a secret-key-credential-store using the management CLI:

    Syntax

    /subsystem=elytron/secret-key-credential-store=<name_of_credential_store>:add(path="<path_to_the_credential_store>", relative-to=<path_to_store_file>)

    Example

    /subsystem=elytron/secret-key-credential-store=examplePropertiesCredentialStore:add(path=examplePropertiesCredentialStore.cs, relative-to=jboss.server.config.dir)
{"outcome" => "success"}

1.1.5.2. Converting an unencrypted filesystem-realm to an encrypted filesystem-realm

You can convert an unencrypted filesystem-realm into an encrypted one by using the WildFly Elytron tool filesystem-realm-encrypt command.

Prerequisites

Procedure

  1. Convert an unencrypted filesystem-realm into an encrypted one.

    Syntax

    $ JBOSS_HOME/bin/elytron-tool.sh filesystem-realm-encrypt --input-location <existing_filesystem_realm_name> --output-location JBOSS_HOME/standalone/configuration/<target_filesystem_realm_name> --credential-store <path_to_credential_store>/<credential_store>

    Example

    $ JBOSS_HOME/bin/elytron-tool.sh filesystem-realm-encrypt --input-location JBOSS_HOME/standalone/configuration/fs-realm-users --output-location JBOSS_HOME/standalone/configuration/fs-realm-users-enc --credential-store JBOSS_HOME/standalone/configuration/examplePropertiesCredentialStore.cs

Creating encrypted realm for: JBOSS_HOME/standalone/configuration/fs-realm-users
Found credential store and alias, using pre-existing key

    The WildFly Elytron command filesystem-realm-encrypt creates a filesystem-realm specified with the --output-location argument. It also creates a CLI script at the root of the filesystem-realm that you can use to add the filesystem-realm resource in the elytron subsystem.

    Tip

    Use the --summary option to see a summary of the command execution.

  2. Use the generated CLI script to add the filesystem-realm resource in the elytron subsystem.

    Synax

    $ JBOSS_HOME/bin/jboss-cli.sh --connect --file=<target_filesystem_realm_directory>/<target_filesystem_realm_name>.cli

    Example

    $ JBOSS_HOME/bin/jboss-cli.sh --connect --file=JBOSS_HOME/standalone/configuration/fs-realm-users-enc/encrypted-filesystem-realm.cli

You can use the encrypted filesystem-realm to create a security domain that references the realm to secure the JBoss EAP server interfaces or the applications deployed on the server.

Additional resources

1.1.6. Adding integrity support to an existing filesystem-realm

If you have a filesystem-realm configured in Elytron, you can sign it with a key pair by using the WildFly Elytron Tool to enable integrity checks.

1.1.6.1. Creating a key pair by using the management CLI

Create a key store with a key pair in Elytron.

Prerequisites

  • JBoss EAP is running.

Procedure

  1. Create a key store.

    Syntax

    /subsystem=elytron/key-store=<key_store_name>:add(path=<path_to_key_store_file>,credential-reference={<password>})

    Example

    /subsystem=elytron/key-store=exampleKeystore:add(path=keystore, relative-to=jboss.server.config.dir, type=JKS, credential-reference={clear-text=secret})
{"outcome" => "success"}

  2. Create a key pair in the key store.

    Syntax

    /subsystem=elytron/key-store=<key_store_name>:generate-key-pair(alias=<alias>,algorithm=<key_algorithm>,key-size=<size_of_key>,validity=<validity_in_days>,distinguished-name="<distinguished_name>")

    Example

    /subsystem=elytron/key-store=exampleKeystore:generate-key-pair(alias=localhost,algorithm=RSA,key-size=1024,validity=365,distinguished-name="CN=localhost")
{"outcome" => "success"}

  3. Persist the key pair to the key store file.

    Syntax

    /subsystem=elytron/key-store=<key_store_name>:store()

    Example

    /subsystem=elytron/key-store=exampleKeystore:store()
{
    "outcome" => "success",
    "result" => undefined
}

Additional resources

1.1.6.2. Enabling integrity checks for a filesystem-realm

You can create a filesystem-realm with integrity checks from an existing non-empty filesystem-realm by using the WildFly Elytron tool filesystem-realm-integrity command.

You can use the filesystem-realm-integrity command for the following use cases:

  • Creating a new filesystem-realm with integrity checks from an existing filesystem-realm.
  • Adding integrity checks to an existing filesystem-realm.

Prerequisites

Procedure

  1. Create a filesystem-realm with integrity support by using an existing filesystem-realm and signing it with a key pair.

    To add integrity support to the existing filesystem-realm, omit the --output-location and --realm-name options in the following command. If you specify the --output-location and --realm-name options, the command creates a new filesystem-realm with integrity checks without updating the existing one.

    Syntax

    $ JBOSS_HOME/bin/elytron-tool.sh filesystem-realm-integrity  --input-location <path_to_existing_filesystem_realm> --keystore <path_to_key_store_file> --password <keystore_password> --key-pair <key_pair_alias> --output-location <path_for_new_filesystem_realm> --realm-name <name_of_new_filesystem_realm>

    Example

    $ JBOSS_HOME/bin/elytron-tool.sh filesystem-realm-integrity --input-location JBOSS_HOME/standalone/configuration/fs-realm-users/ --keystore JBOSS_HOME/standalone/configuration/keystore --password secret --key-pair localhost --output-location JBOSS_HOME/standalone/configuration/fs-realm-users --realm-name exampleRealmWithIntegrity

    Exmaple output

    Creating filesystem realm with integrity verification for: JBOSS_HOME/standalone/configuration/fs-realm-users

    The WildFly Elytron command filesystem-realm-integrity creates a filesystem-realm specified with the --output-location argument. It also creates a CLI script at the root of the filesystem-realm that you can use to add the filesystem-realm resource in the elytron subsystem.

    Tip

    Use the --summary option to see a summary of the command execution.

  2. Use the generated CLI script to add the filesystem-realm resource in the elytron subsystem.

    Syntax

    $ JBOSS_HOME/bin/jboss-cli.sh --connect --file=<target_filesystem_realm_directory>/<target_filesystem_realm_name>.cli

    Example

    $ JBOSS_HOME/bin/jboss-cli.sh --connect --file=JBOSS_HOME/standalone/configuration/fs-realm-users/exampleRealmWithIntegrity.cli

You can use the filesystem-realm to create a security domain that references the realm to secure the JBoss EAP server interfaces or the applications deployed on the server.

Additional resources

1.2. Creating a JDBC realm

1.2.1. Creating a jdbc-realm in Elytron

Create a jdbc-realm and a security domain that references the realm to secure the JBoss EAP server interfaces or the applications deployed on the server.

The examples in the procedure use a PostgreSQL database which is configured as follows:

  • Database name: postgresdb

  • Database login credentials:

    • username: postgres
    • password: postgres
  • Table name: example_jboss_eap_users

  • example_jboss_eap_users contents:

    usernamepasswordroles

    user1

    passwordUser1

    Admin

    user2

    passwordUser2

    Guest

Prerequisites

  • You have configured the database containing the users.
  • JBoss EAP is running.
  • You have downloaded the appropriate JDBC driver.

Procedure

  1. Deploy the database driver for the database using the management CLI.

    Syntax

    deploy <path_to_jdbc_driver>/<jdbc-driver>

    Example

    deploy PATH_TO_JDBC_DRIVER/postgresql-42.2.9.jar

  2. Configure the database as the data source.

    Syntax

    data-source add --name=<data_source_name> --jndi-name=<jndi_name> --driver-name=<jdbc-driver>  --connection-url=<database_URL> --user-name=<database_username> --password=<database_username>

    Example

    data-source add --name=examplePostgresDS --jndi-name=java:jboss/examplePostgresDS --driver-name=postgresql-42.2.9.jar  --connection-url=jdbc:postgresql://localhost:5432/postgresdb --user-name=postgres --password=postgres

  3. Create a jdbc-realm in Elytron.

    Syntax

    /subsystem=elytron/jdbc-realm=<jdbc_realm_name>:add(principal-query=[<sql_query_to_load_users>])

    Example

    /subsystem=elytron/jdbc-realm=exampleSecurityRealm:add(principal-query=[{sql="SELECT password,roles FROM example_jboss_eap_users WHERE username=?",data-source=examplePostgresDS,clear-password-mapper={password-index=1},attribute-mapping=[{index=2,to=Roles}]}])
{"outcome" => "success"}

    Note

    The example shows how to obtain passwords and roles from a single principal-query. You can also create additional principal-query with attribute-mapping attributes if you require multiple queries to obtain roles or additional authentication or authorization information.

    For a list of supported password mappers, see Password Mappers.

  4. Create a security domain that references the jdbc-realm.

    Syntax

    /subsystem=elytron/security-domain=<security_domain_name>:add(default-realm=<jdbc_realm_name>,permission-mapper=default-permission-mapper,realms=[{realm=< jdbc_realm_name>,role-decoder="<role_decoder_name>"}])

    Example

    /subsystem=elytron/security-domain=exampleSecurityDomain:add(default-realm=exampleSecurityRealm,permission-mapper=default-permission-mapper,realms=[{realm=exampleSecurityRealm}])
{"outcome" => "success"}

Verification

  • To verify that Elytron can load data from the database, use the following command:

    Syntax

    /subsystem=elytron/security-domain=<security_domain_name>:read-identity(name=<username>)

    Example

    /subsystem=elytron/security-domain=exampleSecurityDomain:read-identity(name=user1)
{
    "outcome" => "success",
    "result" => {
        "name" => "user1",
        "attributes" => {"Roles" => ["Admin"]},
        "roles" => ["Admin"]
    }
}

    The output confirms that Elytron can load data from the database.

You now can use the created security domain to add authentication and authorization to management interfaces and applications. For more information, see Securing management interfaces and applications.

Additional resources

1.3. Creating an LDAP realm

1.3.1. LDAP realm in Elytron

The Lightweight Directory Access Protocol (LDAP) realm, ldap-realm, in Elytron is a security realm that you can use to load identities from an LDAP identity store.

The following example illustrates how an identity in LDAP is mapped with an Elytron identity in JBoss EAP.

Example LDAP Data Interchange Format (LDIF) file

dn: ou=Users,dc=wildfly,dc=org
objectClass: organizationalUnit
objectClass: top
ou: Users

dn: uid=user1,ou=Users,dc=wildfly,dc=org
objectClass: top
objectClass: person
objectClass: inetOrgPerson
cn: user1
sn: user1
uid: user1
userPassword: userPassword1

dn: ou=Roles,dc=wildfly,dc=org
objectclass: top
objectclass: organizationalUnit
ou: Roles

dn: cn=Admin,ou=Roles,dc=wildfly,dc=org
objectClass: top
objectClass: groupOfNames
cn: Admin
member: uid=user1,ou=Users,dc=wildfly,dc=org

Example commands to create an LDAP realm

/subsystem=elytron/dir-context=exampleDirContext:add(url="ldap://10.88.0.2",principal="cn=admin,dc=wildfly,dc=org",credential-reference={clear-text="secret"})

/subsystem=elytron/ldap-realm=exampleSecurityRealm:add(dir-context=exampleDirContext,identity-mapping={search-base-dn="ou=Users,dc=wildfly,dc=org",rdn-identifier="uid",user-password-mapper={from="userPassword"},attribute-mapping=[{filter-base-dn="ou=Roles,dc=wildfly,dc=org",filter="(&(objectClass=groupOfNames)(member={1}))",from="cn",to="Roles"}]})

The commands result in the following configuration: 

<ldap-realm name="exampleLDAPRealm" dir-context="exampleDirContext"> 1
    <identity-mapping rdn-identifier="uid" search-base-dn="ou=Users,dc=wildfly,dc=org"> 2
        <attribute-mapping> 3
            <attribute from="cn" to="Roles" filter="(&amp;(objectClass=groupOfNames)(member={1}))" filter-base-dn="ou=Roles,dc=wildfly,dc=org"/> 4
        </attribute-mapping>
        <user-password-mapper from="userPassword"/> 5
    </identity-mapping>
</ldap-realm>
1
The realm definition.
  • name is the ldap-realm realm name.
  • dir-context is the configuration to connect to an LDAP server.
2
Define how identity is mapped.

  • rdn-identifier is relative distinguished name (RDN) of the principal’s distinguished name (DN) to use to obtain the principal’s name from an LDAP entry. In the example LDIF, uid is configured to represent the principal’s name from the base DN=ou=Users,dc=wildfly,dc=org.

    search-base-dn is the base DN to search for identities. In the example LDIF, it is defined as dn: ou=Users,dc=wildfly,dc=org.

3
Define the LDAP attributes to the identity’s attributes mappings.
4
Configure how to map a specific LDAP attribute as an Elytron identity attribute.
  • from is the LDAP attribute to map. If it is not defined, the DN of the entry is used.
  • to is the name of the identity’s attribute mapped from LDAP attribute. If not provided, the name of the attribute is the same as the one defined in from. If from is also not defined, the DN of the entry is used.

  • filter is a filter to use to obtain the values for a specific attribute. String '{0}' is replaced by the username, '{1}' by user identity DN.

    • objectClass is the LDAP object class to use. In the example LDIF, the object class to use is defined as groupOfNames.
    • member is the member to map. {0} is replaced by user name, and {1} by user identity DN. In this example, {1} is used to map member to user1.

  • filter-base-dn is the name of the context where the filter should be applied.

    The result of the example filter is that the user user1 is mapped with the Admin role.

5
user-password-mapper defines the LDAP attribute from which an identity’s password is obtained. In the example it is configured as userPassword, which is defined in the LDIF as userPassword1.

Additional resources

1.3.2. Creating an ldap-realm in Elytron

Create an Elytron security realm backed by a Lightweight Directory Access Protocol (LDAP) identity store. Use the security realm to create a security domain to add authentication and authorization to management interfaces or the applications deployed on the server.

Note

ldap-realm configured as caching realm does not support Active Directory. For more information, see Changing LDAP/AD User Password via JBossEAP CLI for Elytron.

Important

In cases where the elytron subsystem uses an LDAP server to perform authentication, JBoss EAP will return a 500 error code, or internal server error, if that LDAP server is unreachable.

To ensure that the management interfaces and applications secured using an LDAP realm can be accessed even if the LDAP server becomes available, use a failover realm. For information see Creating a failover realm.

For the examples in this procedure, the following LDAP Data Interchange Format (LDIF) is used: 

dn: ou=Users,dc=wildfly,dc=org
objectClass: organizationalUnit
objectClass: top
ou: Users

dn: uid=user1,ou=Users,dc=wildfly,dc=org
objectClass: top
objectClass: person
objectClass: inetOrgPerson
cn: user1
sn: user1
uid: user1
userPassword: userPassword1

dn: ou=Roles,dc=wildfly,dc=org
objectclass: top
objectclass: organizationalUnit
ou: Roles

dn: cn=Admin,ou=Roles,dc=wildfly,dc=org
objectClass: top
objectClass: groupOfNames
cn: Admin
member: uid=user1,ou=Users,dc=wildfly,dc=org

The LDAP connection parameters used for the example are as follows:

  • LDAP URL: ldap://10.88.0.2

  • LDAP admin password: secret

    You need this for Elytron to connect with the LDAP server.

  • LDAP admin Distinguished Name (DN): (cn=admin,dc=wildfly,dc=org)

  • LDAP organization: wildfly

    If no organization name is specified, it defaults to Example Inc.

  • LDAP domain: wildfly.org

    This is the name that is matched when the platform receives an LDAP search reference.

Prerequisites

  • You have configured an LDAP identity store.
  • JBoss EAP is running.

Procedure

  1. Configure a directory context that provides the URL and the principal used to connect to the LDAP server.

    Syntax

    /subsystem=elytron/dir-context=<dir_context_name>:add(url="<LDAP_URL>",principal="<principal_distinguished_name>",credential-reference=<credential_reference>)

    Example

    /subsystem=elytron/dir-context=exampleDirContext:add(url="ldap://10.88.0.2",principal="cn=admin,dc=wildfly,dc=org",credential-reference={clear-text="secret"})

  2. Create an LDAP realm that references the directory context. Specify the Search Base DN and how users are mapped.

    Syntax

    /subsystem=elytron/ldap-realm=<ldap_realm_name>add:(dir-context=<dir_context_name>,identity-mapping=search-base-dn="ou=<organization_unit>,dc=<domain_component>",rdn-identifier="<relative_distinguished_name_identifier>",user-password-mapper={from=<password_attribute_name>},attribute-mapping=[{filter-base-dn="ou=<organization_unit>,dc=<domain_component>",filter="<ldap_filter>",from="<ldap_attribute_name>",to="<identity_attribute_name>"}]})

    Example

    /subsystem=elytron/ldap-realm=exampleSecurityRealm:add(dir-context=exampleDirContext,identity-mapping={search-base-dn="ou=Users,dc=wildfly,dc=org",rdn-identifier="uid",user-password-mapper={from="userPassword"},attribute-mapping=[{filter-base-dn="ou=Roles,dc=wildfly,dc=org",filter="(&(objectClass=groupOfNames)(member={1}))",from="cn",to="Roles"}]})

    If you store hashed passwords in the LDIF file, you can specify the following attributes:

    • hash-encoding: This attribute specifies the string format for the password if it is not stored in plain text. It is set to base64 encoding by default, but hex is also supported.
    • hash-charset: This attribute specifies the character set to use when converting the password string to a byte array. It is set to UTF-8 by default.
    Warning

    If any referenced LDAP servers contain a loop in referrals, it can result in a java.lang.OutOfMemoryError error in JBoss EAP.

  3. Create a role decoder to map attributes to roles.

    Syntax

    /subsystem=elytron/simple-role-decoder=<role_decoder_name>:add(attribute=<attribute>)

    Example

    /subsystem=elytron/simple-role-decoder=from-roles-attribute:add(attribute=Roles)

  4. Create a security domain that references the LDAP realm and the role decoder.

    Syntax

    /subsystem=elytron/security-domain=<security_domain_name>:add(realms=[{realm=<ldap_realm_name>,role-decoder=<role_decoder_name>}],default-realm=<ldap_realm_name>,permission-mapper=<permission_mapper>)

    Example

    /subsystem=elytron/security-domain=exampleSecurityDomain:add(realms=[{realm=exampleSecurityRealm,role-decoder=from-roles-attribute}],default-realm=exampleSecurityRealm,permission-mapper=default-permission-mapper)

You now can use the created security domain to add authentication and authorization to management interfaces and applications. For more information, see Securing management interfaces and applications.

Additional resources

1.4. Creating a properties realm

1.4.1. Create a security domain referencing a properties-realm in Elytron

Create a properties-realm and a security domain that references the realm to secure your JBoss EAP management interfaces or the applications that you deployed on the server.

Prerequisites

  • JBoss EAP is running.

  • You have an authorized user and an existing legacy properties file with the correct realm written in the commented out line in the users.properties file:

    Example $EAP_HOME/standalone/configuration/my-example-users.properties

     #$REALM_NAME=exampleSecurityRealm$
 user1=078ed9776d4b8e63b6e51135ec45cc75

    • The password for user1 is userPassword1. The password is hashed to the file as HEX( MD5( user1:exampleSecurityRealm:userPassword1 )).

  • The authorized user listed in your users.properties file has a role in the groups.properties file:

    Example $EAP_HOME/standalone/configuration/my-example-groups.properties

    user1=Admin

Procedure

  1. Create a properties-realm in Elytron.

    Syntax

    /subsystem=elytron/properties-realm=<properties_realm_name>:add(users-properties={path=<file_path>},groups-properties={path=<file_path>})

    Example

    /subsystem=elytron/properties-realm=exampleSecurityRealm:add(users-properties={path=my-example-users.properties,relative-to=jboss.server.config.dir,plain-text=true},groups-properties={path=my-example-groups.properties,relative-to=jboss.server.config.dir})

  2. Create a security domain that references the properties-realm.

    Syntax

    /subsystem=elytron/security-domain=<security_domain_name>:add(default-realm=<properties_realm_name>,permission-mapper=default-permission-mapper,realms=[{realm=<properties_realm_name>,role-decoder="<role_decoder_name>"}])

    Example

    /subsystem=elytron/security-domain=exampleSecurityDomain:add(default-realm=exampleSecurityRealm,permission-mapper=default-permission-mapper,realms=[{realm=exampleSecurityRealm,role-decoder=groups-to-roles}])

Verification

  • To verify that Elytron can load data from the properties file, use the following command:

    Syntax

    /subsystem=elytron/security-domain=<security_domain_name>:read-identity(name=<username>)

    Example

    /subsystem=elytron/security-domain=exampleSecurityDomain:read-identity(name=user1)
{
    "outcome" => "success",
    "result" => {
        "name" => "user1",
        "attributes" => {"Roles" => ["Admin"]},
        "roles" => ["Admin"]
    }
}

    The output confirms that Elytron can load data from the properties file.

You now can use the created security domain to add authentication and authorization to management interfaces and applications. For more information, see Securing management interfaces and applications.

Additional resources

1.5. Creating a custom realm

1.5.1. Adding a custom-realm security realm in Elytron

You can use a custom-realm to create an Elytron security realm that is tailored to your use case. You can add a custom-realm when existing Elytron security realms do not suit your use case.

Prerequisites

  • JBoss EAP is installed and running.
  • Maven is installed.
  • You have an implemented custom realm java class.

Procedure

  1. Implement a custom realm java class and package it as a JAR file. 

    $ mvn package

  2. Add a module containing your custom realm implementation.

    Syntax

    module add --name=<name_of_your_wildfly_module>
--resources=<path_to_custom_realm_jar> --dependencies=org.wildfly.security.elytron

    Example

    module add --name=com.example.customrealm --resources=EAP_HOME/custom-realm.jar --dependencies=org.wildfly.security.elytron

  3. Create your custom-realm.

    Syntax

    /subsystem=elytron/custom-realm=<name_of_your_custom_realm>:add(module=<name_of_your_wildfly_module>,class-name=<class_name_of_custom_realm_>,configuration={<configuration_option_1>=<configuration_value_1>,<configuration_option_2>=<configuration_value_2>})

    Example

    /subsystem=elytron/custom-realm=example-realm:add(module=com.example.customrealm,class-name=com.example.customrealm.ExampleRealm,configuration={exampleConfigOption1=exampleConfigValue1,exampleConfigOption2=exampleConfigValue2})

    Note

    This example expects that the implemented custom realm has the class name com.example.customrealm.ExampleRealm.

    Note

    You can use the configuration attribute to pass key/value configuration to the custom-realm. The configuration attribute is optional.

  4. Define a security domain based on the realm that you created.

    Syntax

    /subsystem=elytron/security-domain=<your_security_domain_name>:add(realms=[{realm=<your_realm_name>}],default-realm=<your_realm_name>,permission-mapper=<your_permission_mapper_name>)

    Example

    /subsystem=elytron/security-domain=exampleSecurityDomain:add(realms=[{realm=example-realm}],default-realm=example-realm,permission-mapper=default-permission-mapper)

You now can use the created security domain to add authentication and authorization to management interfaces and applications. For more information, see Securing management interfaces and applications.

Additional resources