Chapter 1. Configuring identity stores

Procedure

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

   /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"})
   {"outcome" => "success"}

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=exampleLDAPRealm: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"},{from="mail",to="mail"},{from="telephoneNumber",to="telephoneNumber"}]})
   {"outcome" => "success"}

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=exampleFileSystemRealm: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=exampleFileSystemRealm:add-identity(identity=user1)
      {"outcome" => "success"}

   2. 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=exampleFileSystemRealm:add-identity-attribute(identity=user1, name=Roles, value=["Admin","Guest"])
      {"outcome" => "success"}

   3. Set attributes for the user.

      Syntax

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

      Example

      /subsystem=elytron/filesystem-realm=exampleFileSystemRealm:add-identity-attribute(identity=user1, name=mail, value=["user@example.com"])
      /subsystem=elytron/filesystem-realm=exampleFileSystemRealm:add-identity-attribute(identity=user1, name=website, value=["http://www.example.com/"])

Procedure

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

   /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"})
   {"outcome" => "success"}

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=exampleLDAPRealm: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"}]})
   {"outcome" => "success"}

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=exampleFileSystemRealm: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=exampleFileSystemRealm:add-identity(identity=user2)
      {"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=exampleFileSystemRealm:set-password(identity=user2, clear={password="passwordUser2"})
      {"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=exampleFileSystemRealm:add-identity-attribute(identity=user2, name=Roles, value=["Admin","Guest"])
      {"outcome" => "success"}

Procedure

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

   /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"})
   {"outcome" => "success"}

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=exampleLDAPRealm: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"}]})
   {"outcome" => "success"}

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=exampleFileSystemRealm: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=exampleFileSystemRealm: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=exampleFileSystemRealm: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=exampleFileSystemRealm:add-identity-attribute(identity=user1, name=Roles, value=["Admin","Guest"])
      {"outcome" => "success"}

Procedure

1. Use the mvn command in the CLI to set up a Maven project. This command creates the directory structure for the project and the pom.xml configuration file.

   Syntax

   $ mvn archetype:generate \
   -DgroupId=<group-to-which-your-application-belongs> \
   -DartifactId=<name-of-your-application> \
   -DarchetypeGroupId=org.apache.maven.archetypes \
   -DarchetypeArtifactId=maven-archetype-simple \
   -DinteractiveMode=false

   Example

   $ mvn archetype:generate \
   -DgroupId=com.example.loginmodule \
   -DartifactId=example-custom-login-module \
   -DarchetypeGroupId=org.apache.maven.archetypes \
   -DarchetypeArtifactId=maven-archetype-simple \
   -DinteractiveMode=false

2. Navigate to the application root directory.

   Syntax

   $ cd <name-of-your-application>

   Example

   $ cd example-custom-login-module

3. Replace the content of the generated pom.xml file with the following text:

   <?xml version="1.0" encoding="UTF-8"?>
   <project xmlns="http://maven.apache.org/POM/4.0.0"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
       <modelVersion>4.0.0</modelVersion>
   
       <groupId>custom.loginmodules</groupId>
       <artifactId>custom-login-modules</artifactId>
       <version>1.0</version>
       <dependencies>
           <dependency>
               <groupId>org.wildfly.security</groupId>
               <artifactId>wildfly-elytron</artifactId>
               <version>1.17.2.Final</version>
           </dependency>
           <dependency>
               <groupId>jakarta.security.enterprise</groupId>
               <artifactId>jakarta.security.enterprise-api</artifactId>
               <version>3.0.0</version>
           </dependency>
       </dependencies>
   
       <properties>
           <maven.compiler.source>11</maven.compiler.source>
           <maven.compiler.target>11</maven.compiler.target>
       </properties>
   
   </project>

4. Remove the directories site and test because they are not required for this example.

   $ rm -rf src/site/
   $ rm -rf src/test/

Procedure

1. Create a directory to store the Java files.

   Syntax

   $ mkdir -p src/main/java/<path_based_on_artifactID>

   Example

   $ mkdir -p src/main/java/com/example/loginmodule

2. Navigate to the directory containing the source files.

   Syntax

   $ cd src/main/java/<path_based_on_groupID>

   Example

   $ cd src/main/java/com/example/loginmodule

3. Delete the generated file App.java.

   $ rm App.java

4. Create a file ExampleCustomLoginModule.java for custom login module source.

   package com.example.loginmodule;
   
   import org.wildfly.security.auth.principal.NamePrincipal;
   
   import javax.security.auth.Subject;
   import javax.security.auth.callback.Callback;
   import javax.security.auth.callback.CallbackHandler;
   import javax.security.auth.callback.NameCallback;
   import javax.security.auth.callback.PasswordCallback;
   import javax.security.auth.callback.UnsupportedCallbackException;
   import javax.security.auth.login.LoginException;
   import javax.security.auth.spi.LoginModule;
   import java.io.IOException;
   import java.security.Principal;
   import java.util.Arrays;
   import java.util.HashMap;
   import java.util.Map;
   
   
   public class ExampleCustomLoginModule implements LoginModule {
   
       private final Map<String, char[]> usersMap = new HashMap<String, char[]>();
       private Principal principal;
       private Subject subject;
       private CallbackHandler handler;
   
       /**
        * In this example, identities are created as fixed Strings.
        *
        * The identities are:
        *    user1 has the password passwordUser1
        *    user2 has the password passwordUser2
        *
        * Use these credentials when you secure management interfaces
        * or applications with this login module.
        *
        * In a production login module, you would get the identities
        * from a data source.
        *
        */
   
       @Override
       public void initialize(Subject subject, CallbackHandler callbackHandler, Map<String, ?> sharedState, Map<String, ?> options) {
           this.subject = subject;
           this.handler = callbackHandler;
           this.usersMap.put("user1", "passwordUser1".toCharArray());
           this.usersMap.put("user2", "passwordUser2".toCharArray());
       }
   
       @Override
       public boolean login() throws LoginException {
           // obtain the incoming username and password from the callback handler
           NameCallback nameCallback = new NameCallback("Username");
           PasswordCallback passwordCallback = new PasswordCallback("Password", false);
           Callback[] callbacks = new Callback[]{nameCallback, passwordCallback};
           try {
               this.handler.handle(callbacks);
           } catch (UnsupportedCallbackException | IOException e) {
               throw new LoginException("Error handling callback: " + e.getMessage());
           }
   
           final String username = nameCallback.getName();
           this.principal = new NamePrincipal(username);
           final char[] password = passwordCallback.getPassword();
   
           char[] storedPassword = this.usersMap.get(username);
           if (!Arrays.equals(storedPassword, password)) {
               throw new LoginException("Invalid password");
           } else {
               return true;
           }
       }
   
       /**
        * user1 is assigned the roles Admin, User and Guest.
        * In a production login module, you would get the identities
        * from a data source.
        *
        */
   
       @Override
       public boolean commit() throws LoginException {
           if (this.principal.getName().equals("user1")) {
               this.subject.getPrincipals().add(new Roles("Admin"));
               this.subject.getPrincipals().add(new Roles("User"));
               this.subject.getPrincipals().add(new Roles("Guest"));
           }
           return true;
       }
   
       @Override
       public boolean abort() throws LoginException {
           return true;
       }
   
       @Override
       public boolean logout() throws LoginException {
           this.subject.getPrincipals().clear();
           return true;
       }
   
       /**
       * Principal with simple classname 'Roles' will be mapped to the identity's attribute with name 'Roles'.
       */
   
       private static class Roles implements Principal {
   
           private final String name;
   
           Roles(final String name) {
               this.name = name;
           }
   
           /**
            * @return name of the principal. This will be added as a value to the identity's attribute which has a name equal to the simple name of this class. In this example, this value will be added to the attribute with a name 'Roles'.
           */
   
           public String getName() {
               return this.name;
           }
       }
   }

5. In the <application_home> directory, create JAAS configuration file JAAS-login-modules.conf.

   exampleConfiguration {
   	com.example.loginmodule.ExampleCustomLoginModule optional;
   };

   • exampleConfiguration is the Entry name.
   • com.example.loginmodule.ExampleCustomLoginModule is the login module.
   • optional is the flag.

6. Compile the login module.

   $ mvn package
   ...
   [INFO] ------------------------------------------------------------------------
   [INFO] BUILD SUCCESS
   [INFO] ------------------------------------------------------------------------
   [INFO] Total time: 1.321 s
   [INFO] Finished at: 2022-04-28T14:16:03+05:30
   [INFO] ------------------------------------------------------------------------