Let’s connect your on-premises user store to Asgardeo

Asgardeo is the latest IDaaS introduced by WSO2 enabling developers with little IAM experience to create seamless login experiences in minutes. Currently Asgardeo is live, which I’m inviting you all to start your journey with next generation IDaaS today for free.

Asgardeo Logo

With this blog I am focusing on how to connect your on premises user store to your Asgardeo organization. With this feature Organization admins get the opportunity to onboard their existing users to Asgardeo by connecting the user store directly to Asgardeo.

If an organization wants to import the existing users to Asgardeo they can migrate the users to Asgardeo as well. For more information follow, https://wso2.com/asgardeo/docs/guides/users/migrate-users/

Keep in mind that

• Currently Asgardeo allows you to connect the on-premises user stores as the READ ONLY user stores, hence you won’t be able to modify the users and groups using the Asgardeo console.
• Asgardeo currently supports Lightweight Directory Access Protocol (LDAP) & Active Directory (AD) user stores only.
• Communication between your user store and Asgardeo is managed by using a java application called user store agent.

How this works.

Asgardeo provides an application called user store Agent, which you have to run in your server with the correct configurations to communicate with the user store. The communication between the user store agent and Asgardeo happens via a web socket channel.

As an example when a remote user (User inside your on-premise user store) authenticates with Asgardeo, the requests are redirected to the user store agent which validates the user against your AD/LDAP service and then sends the results of the validation back to Asgardeo.

Prerequisites.

• Sign up to Asgardeo.
• JAVA 8 or JAVA 11 installed locally and JAVA_HOME configured correctly

Set up an openLDAP instance to connect to Asgardeo

If you are having a LDAP/AD user store already configured in your machine/server, you can skip this part.

Here we are going to set up an openLDAP instance by using the bitnami openldap docker image. Then we will add the users to the LDAP Data Interchange Format (LDIF) file.

Step 1 — Run the openldap instance by using the following command. Here you can change your base dn, admin username and passwords as you prefer.

docker run --detach --rm --name openldap \
--env LDAP_BASE=dc=exmple,dc=org \
--env LDAP_BIND_DN=cn=admin,dc=exmple,dc=org \
--env LDAP_BIND_PASSWORD=adminpassword \
--env LDAP_ADMIN_USERNAME=admin \
--env LDAP_ADMIN_PASSWORD=adminpassword \
--env LDAP_USERS=customuser \
--env LDAP_PASSWORDS=custompassword \
-p 1389:1389 -p 1636:1636 -d bitnami/openldap:latest

Step 2 — create a file called users-and-groups.ldif file with the following content to create users and groups in your ldap instance. You need to replace <<PASSWORD>> with your own password to the users.

Step 3 — Copy the create the LDIF file to the openldap docker container using

docker cp users-and-groups.ldif openldap:/

Step 4 — Then execute the following two commands to add the users and groups.

docker exec -it openldap bash
ldapadd -a -D “cn=admin,dc=example,dc=org” -w adminpassword -H ldapi:/// -f users-and-groups.ldif

You can view the onboard users and groups using the Apache directory Studio — https://directory.apache.org/studio/

Let’s create a user store in Asgardeo to connect the remote user store.

• Login to your Asgardeo console.
• Navigate to Manage > User Stores and click Connect remote use store.
• Fill the General information of your user store and click next.

• Then Map the username and User ID attributes correctly. This is one of the most important configurations when creating the user store in Asgardeo. These two attributes need to be mapped correctly for proper authentication.

Username — This is the primary identifier of the user. Which is used to validate users authentication. Asgardeo is recommending you to use an attribute type of email as the username for the best experience. If you had a concern why I have added email for the user identification in my ldap I have created previously, hope you have the answer now.

User ID — This attribute is used to uniquely identify a user entry. Recommendation is to use some kind of a ID (UUID) to uniquely identify the users. This ID will be the user’s ID which you will be using to retrieve the users information (Even in SCIM).

In the openldap we have create previously, Username — cn and user ID — uid

• Then click finish to create the user store. This will take a few seconds to get created. After registering the user store, you’ll be redirected to the Setup Guide of the user store agent.

Lets assemble and configure the user store agent bundle to connect the user store to Asgardeo

• Download the user store agent and unzip as the first step.
• Then we need to configure the user store bundle with the relevant configuration to connect the user store to the Agent. These configurations need to be done in the deployment.toml file which can be found at the user store agent home. All the configuration that needs to be configured correctly can be found at https://wso2.com/asgardeo/docs/references/remote-user-store/remote-user-store-properties/ You need to read these properties carefully when connecting your own user store to Asgardeo.
• Below I have mentioned the configurations for the openldap instance that we have configured.

[user_store]
type = "ldap"
base_dn = "dc=example,dc=org"
connection_url = "ldap://localhost:1389"
connection_name = "cn=admin,dc=example,dc=org"
connection_password = "adminpassword"
user_search_base = "ou=users,dc=example,dc=org"
user_id_search_filter = "(&(objectClass=inetOrgperson)(uid=?))"
user_name_list_filter = "(objectClass=inetOrgperson)"
user_id_attribute = "uid"
user_name_search_filter = "(&(objectClass=inetOrgperson)(mail=?))"
user_name_attribute = "mail"
group_search_base = “ou=groups,dc=example,dc=org”
group_entry_object_class = "group"

• After configuring the `deployment.toml` you need to Generate an installation token by clicking the generate token button in the Step 3 of the setup guide.
• This Installation token is required when running the user store agent bundle. This will be used to authorize the web socket connection.

• The run the user store agent bundle with commands mentioned
  Linux/OSx: sh wso2agent.sh
  Windows: wso2agent.bat — run

When starting the user store agent, it will ask for an installation token as an input. There you have to provide the token obtained in step 3.

• Then you can validate the connection using the Test Connection button in the bottom of the setup guide page.

* Copy the installation token and save it in a safe location. You won’t be able to see it again!
* This token has no expiry time, but in case you lose or forget it, you can regenerate an installation token.
* If you find your token is compromised you can revoke the current token and generate a new token.

What’s Next?

Next immediate step you have to do is to map the attribute correctly. For that

• You need to navigate to the Attribute Mappings tab in the top of your user store.
• Then update the relevant values for the attribute.
• Please Note — By default Asgardeo filled these attribute values with the most commonly used attribute names in the LDAPs, If those values are correct you can simply click update button to set up the attribute mappings or else you can edit the relevant values click update. If you map the attribute incorrectly, users’ information will not be visible correctly.
• Once you have done that, Navigate to the users section in the console and select the user store name from the drop down. You can see the users you have added to the openldap.

• Similarly, you can see the groups as well.

• You can try login to My account portal or any or any of your business application using one of the remote user credentials.

What else?

1. You can navigate to the user store you have created and view the running agents. You get the capability to disconnect and regenerate the tokens of the agents that are running.

2. You can run another User store agent using a new installation token if you want High availability. This will help for load balancing as well. For more information refer — https://wso2.com/asgardeo/docs/guides/users/user-stores/configure-high-availability/#connect-a-second-user-store-agent

3. You can disable the user store temporarily if you require it. If you disable the user store, its users will lose access to Asgardeo applications and administrators can no longer view users or groups of that user store in the Asgardeo console.

Thank you for reading. Have a Good Day!!

References

https://wso2.com/asgardeo/docs/guides/users/user-stores/configure-a-user-store/#prerequisites