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 authenticating with their accounts at the business partner and automatically become a member of an organization at the realm that represents the business partner itself.
While the same use case is already possible without using Keycloak Organizations, the feature provides built-in capabilities that makes a lot easier to solve this problem such as:
-
Manage third-parties entities in a realm as an organization
-
Link any of the built-in identity providers to an organization in order to authenticate and onboard its members
-
Manage organization domains at the organization and at the identity provider level
-
Enforce email domain verification depending on how domains set to identity providers
-
Automatically redirect users based on their email domains
-
Manage organization members
In this playbook you will learn about:
-
How to create an organization in arealm
-
How to create an identity provider and link it to an organization
-
How to onboard organization members through an identity provider
-
How to authenticate organization members
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 organization
Once 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 admin
Once 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
}
EOF
In 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.
Try reaching http://localhost:8080/realms/orgdemo/account/
and you’ll see the usual login page.
For the sake of simplicity, you will create another realm to represent a third-party company that you want to integrate with:
kcadm.sh create realms -f - << EOF
{
"realm": "orga",
"enabled": true
}
EOF
Once the orga
realm is created, you can now configure it to allow their users to authenticate to the orgdemo
realm through an identity provider so that they have access to the clients at the orgdemo
realm.
Create a client in the organization realm to allow authenticating users through an identity provider
In order to create an identity provider in the orgdemo
realm to authenticate and federate users from the orga
realm, you first need to create a client in the `orga`realm.
kcadm.sh create realms/orga/clients -f - << EOF
{
"protocol" : "openid-connect",
"enabled" : true,
"clientId" : "orgdemo-broker",
"clientAuthenticatorType" : "client-secret",
"secret" : "secret",
"redirectUris" : [ "*" ],
"standardFlowEnabled" : true,
"directAccessGrantsEnabled" : true,
"attributes" : {
"backchannel.logout.session.required" : "true"
}
}
EOF
We will use this client later to create the identity provider in the orgdemo
realm.
You also need an user in the `orga`realm to authenticate:
kcadm.sh create realms/orga/users -f - << EOF
{
"username": "jdoe",
"email": "jdoe@orga.com",
"firstName": "John",
"lastName": "Doe",
"enabled": true,
"credentials" : [
{
"type" : "password",
"value" : "password"
}
]
}
EOF
We will use this user to represent an existing user in the orga
organization, to whom we should allow to register to the orgdemo
realm as a member of the orga
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 start integrating with it:
kcadm.sh create realms/orgdemo/organizations -f - << EOF
{
"name": "orga",
"enabled": true,
"domains": [
{
"name": "orga.com"
}
]
}
EOF
Save 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 and realm does not support user self-registration. If you want, you can enable this setting at the orgdemo
realm and allow users to self-register but for now, we will only allow registrations through an identity provider associated with the orga
organization.
In the next steps, we will focus on integrating to the orga
organization by using an identity provider to onboard and authenticate its members.
In order to authenticate and onboard members from the orga
organization, you need an identity provider created at the orgademo
:
kcadm.sh create realms/orgdemo/identity-provider/instances -f - << EOF
{
"alias" : "orga",
"displayName" : "OrgA Inc.",
"providerId" : "oidc",
"enabled" : true,
"config" : {
"tokenUrl" : "http://localhost:8080/realms/orga/protocol/openid-connect/token",
"jwksUrl" : "http://localhost:8080/realms/orga/protocol/openid-connect/certs",
"issuer" : "http://localhost:8080/realms/orga",
"loginHint" : "true",
"clientAuthMethod" : "client_secret_post",
"clientId" : "orgdemo-broker",
"clientSecret" : "secret",
"userInfoUrl" : "http://localhost:8080/realms/orga/protocol/openid-connect/userinfo",
"authorizationUrl" : "http://localhost:8080/realms/orga/protocol/openid-connect/auth",
"logoutUrl" : "http://localhost:8080/realms/orga/protocol/openid-connect/logout",
"sendIdTokenOnLogout" : "true",
"kc.org.broker.public": "true"
}
}
EOF
Once the identity provider is created, you can now link it to the orga
organization in the orgdemo
realm:
kcadm.sh create realms/orgdemo/organizations/{orgid}/identity-providers -b orga
From now on, you can start looking at the different capabilities brough by Keycloak Organizations and check the different paths when onboarding members and authenticating them to a realm.
Let us try to authenticate to the orgdemo
realm using the email address of the user we created in the orga
realm. For that, access http://localhost:8080/realms/orgdemo/account/
.
Once you are presented with the identity-first login page, type the jdoe@orga.com
email in the username field and submit the form. Note that the email does not map yet to any user in the orgdemo
realm.
After submiting the form, you are informed that the user does not exist yet but the email domain matches the domain of an organization. In this case, the orga
organization.
By recognizing that the email you provided matches the domain of the orga
organization, the login page will show all the identity providers (only those that were marked as "public") available from the organization so that you can pick one to authenticate.
As a new user, you can then click on the OrgA Inc
identity provider at the botton of form to authenticate through the orga
realm.
In the login page at the orga
realm, type the credentials for the user:
-
Username:
jdoe@orga.com
-
Password:
password
Once you authenticate, the user is automatically redirected to the orgdemo
, a new account is created, and the user is now a a member of the orga
organization.
To list all members of an organization, you can run the following command:
kcadm.sh get realms/orgdemo/organizations/{orgid}/members
Once the user is a member of an organization and the account is linked to one of the identity providers associated with an organization, any attempt to authenticate to a realm when at the identity-first login page will automatically redirect the user to the corresponding identity provider in the organization.
For that, logout from the account console to log in again. When at the identity-first login page type the jdoe@orga.com
email and submit the form.
As a result, the user is automatically redirected to the orga
realm to authenticate and, once providing the credentials, the user is seamlessly authenticated to the orgdemo
realm.