In this playbook you are going to follow the basic steps to configure a Keycloak instance to support a common Business-to-Business (B2B) use case where a company wants to integrate with its business partners to allow their employees or customers to access its services.
For that, users from a business partner are going to be able to create their accounts at the company’s realm by following a registration link and automatically become a member of an organization at the realm that represents the business partner itself.
In this playbook you will learn about:
-
How to create an organization in a realm
-
How to send a registration link to invite a non-existent user to join an organization
The Keycloak Organization feature is a experimental feature that needs to be enabled when starting (or building an optimized image of) the server:
docker run --name kc-orgs -d -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin -p 8080:8080 quay.io/keycloak/keycloak:nightly start-dev --features organizationOnce you run the command above, make sure you can access the server at http://localhost:8080/ and log in into the administration console using the following credentials:
-
Username:
admin -
Password:
admin
You can now follow the instructions in this playbook.
In this playbook you are going to use the Keycloak Admin CLI to connect to the server instance and manage the realms. For that, run the command below to authenticate and configure the CLI:
kcadm.sh config credentials --server http://localhost:8080 --realm master --user adminOnce you run the command above, type admin when prompted for a password.
Let us start by creating a new realm called orgdemo:
kcadm.sh create realms -f - << EOF
{
"realm": "orgdemo",
"enabled": true,
"registrationAllowed": true,
"smtpServer": {
"from": "admin@orgdemo.com",
"host": "{host}",
"auth": "true",
"user": "{user}",
"password": "{password}"
}
}
EOFIn this playbook, the orgdemo realm is a first-party company that wants to integrate with third-parties, the organizations, so that their users can have access to protected resources served by client applications available at the orgdemo realm.
The realm must be configured to send emails by providing valid valudes to the smtpServer properties in the snippet above. You can also manage these settings through the administration console at the Email tab when managing the realm settings.
To allow users to self-register to the realm, you also need to enable the registrationAllowed setting. You can also manage this setting through the administration console at the Login tab when managing the realm settings.
Once you have the orgdemo realm created, you can now invite new users to register to your realm and join an organization.
Now that you have a third-party to integrate with, represented by the orga realm, we can create an organization in the orgdemo realm to integrate with it:
kcadm.sh create realms/orgdemo/organizations -f - << EOF
{
"name": "orga",
"enabled": true,
"domains": [
{
"name": "orga.com"
}
]
}
EOFSave the id of the realm after executing the command above. You will need it later whenever you see a {orgid} placeholder in the following commands.
Now that you have created the orga organization, you can try reaching http://localhost:8080/realms/orgdemo/account/. As you will see, and differently than before, the identity-first login took place and you are only asked for a username or email.
For now, you can’t do much in this page because there is no user yet to authenticate. You can self-register as a new user but in this playbook we are going to send a registration link to an email address instead.
To invite a new user to create an account at the orgdemo and join the orga organization, you can send a registration link by executing the following command:
kcadm.sh create realms/orgdemo/organizations/{orgid}/members/invite-user -b jdoe@orga.comIf the command completes successfuly, an email message is sent the person that owns the jdoe@orga.com email address with a subject Invitation to join the orga organization and a body similar to the following:
You were invited to join the orga organization. Click the link below to join.
Link to join the organization
This link will expire within 28595429 minutes.
If you dont want to join the organization, just ignore this message.By clicking the Link to join the organization, the user is aotumatically redirect to the orgdemo realm to complete the registration and, once the form is submited, an account is going to be created at the realm and the user will automatically join the orga organization.