Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 1. Configuring identity stores

1.1. Creating a filesystem-realm
Copy link

1.1.1. Filesystem realm in Elytron
Copy link

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
}
    Copy to Clipboard Toggle word wrap

1.1.2. Creating a filesystem-realm in Elytron
Copy link

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>)
    Copy to Clipboard Toggle word wrap

    Example

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

  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>)
      Copy to Clipboard Toggle word wrap

      Example

      /subsystem=elytron/filesystem-realm=exampleSecurityRealm:add-identity(identity=user1)
{"outcome" => "success"}
      Copy to Clipboard Toggle word wrap

    2. Set a password for the user.

      Syntax

      /subsystem=elytron/filesystem-realm=<filesystem_realm_name>:set-password(identity=<user_name>, clear={password=<password>})
      Copy to Clipboard Toggle word wrap

      Example

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

    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>])
      Copy to Clipboard Toggle word wrap

      Example

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

  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>"}])
    Copy to Clipboard Toggle word wrap

    Example

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

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>)
    Copy to Clipboard Toggle word wrap

    Example

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

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.

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

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>)
    Copy to Clipboard Toggle word wrap

    Example

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

1.1.3.2. Creating an encrypted filesystem-realm
Copy link

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>)
    Copy to Clipboard Toggle word wrap

    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"}
    Copy to Clipboard Toggle word wrap

  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>)
      Copy to Clipboard Toggle word wrap

      Example

      /subsystem=elytron/filesystem-realm=exampleSecurityRealm:add-identity(identity=user1)
{"outcome" => "success"}
      Copy to Clipboard Toggle word wrap

    2. Set a password for the user.

      Syntax

      /subsystem=elytron/filesystem-realm=<filesystem_realm_name>:set-password(identity=<user_name>, clear={password=<password>})
      Copy to Clipboard Toggle word wrap

      Example

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

    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>])
      Copy to Clipboard Toggle word wrap

      Example

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

  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>"}])
    Copy to Clipboard Toggle word wrap

    Example

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

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>)
    Copy to Clipboard Toggle word wrap

    Example

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

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

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.

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>})
    Copy to Clipboard Toggle word wrap

    Example

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

  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>")
    Copy to Clipboard Toggle word wrap

    Example

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

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

    Syntax

    /subsystem=elytron/key-store=<key_store_name>:store()
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/key-store=exampleKeystore:store()
{
    "outcome" => "success",
    "result" => undefined
}
    Copy to Clipboard Toggle word wrap

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>)
    Copy to Clipboard Toggle word wrap

    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"}
    Copy to Clipboard Toggle word wrap

  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>)
      Copy to Clipboard Toggle word wrap

      Example

      /subsystem=elytron/filesystem-realm=exampleSecurityRealm:add-identity(identity=user1)
{"outcome" => "success"}
      Copy to Clipboard Toggle word wrap

    2. Set a password for the user.

      Syntax

      /subsystem=elytron/filesystem-realm=<filesystem_realm_name>:set-password(identity=<user_name>, clear={password=<password>})
      Copy to Clipboard Toggle word wrap

      Example

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

    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>])
      Copy to Clipboard Toggle word wrap

      Example

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

  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>"}])
    Copy to Clipboard Toggle word wrap

    Example

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

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>)
    Copy to Clipboard Toggle word wrap

    Example

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

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.

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>")
    Copy to Clipboard Toggle word wrap

    Example

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

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

    Syntax

    /subsystem=elytron/key-store=<key_store_name>:store()
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/key-store=exampleKeystore:store()
{
    "outcome" => "success",
    "result" => undefined
}
    Copy to Clipboard Toggle word wrap

  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>)
    Copy to Clipboard Toggle word wrap

    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"
    }
}
    Copy to Clipboard Toggle word wrap

  4. Reload the server. 

    reload
    Copy to Clipboard Toggle word wrap

  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()
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/filesystem-realm=exampleSecurityRealm:update-key-pair()
{"outcome" => "success"}
    Copy to Clipboard Toggle word wrap

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()
    Copy to Clipboard Toggle word wrap

    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"
    }
}
    Copy to Clipboard Toggle word wrap

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

1.1.5. Encrypting an unencrypted filesystem-realm
Copy link

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

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>)
    Copy to Clipboard Toggle word wrap

    Example

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

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>
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

    Example

    $ JBOSS_HOME/bin/jboss-cli.sh --connect --file=JBOSS_HOME/standalone/configuration/fs-realm-users-enc/encrypted-filesystem-realm.cli
    Copy to Clipboard Toggle word wrap

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.

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.

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>})
    Copy to Clipboard Toggle word wrap

    Example

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

  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>")
    Copy to Clipboard Toggle word wrap

    Example

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

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

    Syntax

    /subsystem=elytron/key-store=<key_store_name>:store()
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/key-store=exampleKeystore:store()
{
    "outcome" => "success",
    "result" => undefined
}
    Copy to Clipboard Toggle word wrap

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>
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

    Exmaple output

    Creating filesystem realm with integrity verification for: JBOSS_HOME/standalone/configuration/fs-realm-users
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

    Example

    $ JBOSS_HOME/bin/jboss-cli.sh --connect --file=JBOSS_HOME/standalone/configuration/fs-realm-users/exampleRealmWithIntegrity.cli
    Copy to Clipboard Toggle word wrap

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.

1.2. Creating a JDBC realm
Copy link

1.2.1. Creating a jdbc-realm in Elytron
Copy link

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:

    Expand
    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>
    Copy to Clipboard Toggle word wrap

    Example

    deploy PATH_TO_JDBC_DRIVER/postgresql-42.2.9.jar
    Copy to Clipboard Toggle word wrap

  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>
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

  3. Create a jdbc-realm in Elytron.

    Syntax

    /subsystem=elytron/jdbc-realm=<jdbc_realm_name>:add(principal-query=[<sql_query_to_load_users>])
    Copy to Clipboard Toggle word wrap

    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"}
    Copy to Clipboard Toggle word wrap

    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>"}])
    Copy to Clipboard Toggle word wrap

    Example

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

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>)
    Copy to Clipboard Toggle word wrap

    Example

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

    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.

1.3. Creating an LDAP realm
Copy link

1.3.1. LDAP realm in Elytron
Copy link

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
Copy to Clipboard Toggle word wrap

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"}]})
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap
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.

1.3.2. Creating an ldap-realm in Elytron
Copy link

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
Copy to Clipboard Toggle word wrap

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>)
    Copy to Clipboard Toggle word wrap

    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"})
    Copy to Clipboard Toggle word wrap

  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>"}]})
    Copy to Clipboard Toggle word wrap

    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"}]})
    Copy to Clipboard Toggle word wrap

    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>)
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/simple-role-decoder=from-roles-attribute:add(attribute=Roles)
    Copy to Clipboard Toggle word wrap

  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>)
    Copy to Clipboard Toggle word wrap

    Example

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

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.

1.4. Creating a properties realm
Copy link

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
    Copy to Clipboard Toggle word wrap

    • 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
    Copy to Clipboard Toggle word wrap

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>})
    Copy to Clipboard Toggle word wrap

    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})
    Copy to Clipboard Toggle word wrap

  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>"}])
    Copy to Clipboard Toggle word wrap

    Example

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

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>)
    Copy to Clipboard Toggle word wrap

    Example

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

    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.

1.5. Creating a custom realm
Copy link

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
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

    Example

    module add --name=com.example.customrealm --resources=EAP_HOME/custom-realm.jar --dependencies=org.wildfly.security.elytron
    Copy to Clipboard Toggle word wrap

  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>})
    Copy to Clipboard Toggle word wrap

    Example

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

    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>)
    Copy to Clipboard Toggle word wrap

    Example

    /subsystem=elytron/security-domain=exampleSecurityDomain:add(realms=[{realm=example-realm}],default-realm=example-realm,permission-mapper=default-permission-mapper)
    Copy to Clipboard Toggle word wrap

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.

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat