Onboarding Organization Members through an Identity Provider

onboarding-members-identity-provider.adoc

Onboarding Organization Members through an Identity Provider

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

Start Keycloak

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.

Configure the Admin CLI

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.

Create a realm

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.

Create a realm to represent an organization

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.

Create an user in the orga 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.

Create 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 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.

Create an Identity Provider in orgdemo realm and link it to the orga organization

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.

Onboarding an organization member through an identity provider

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.

Querying organization members

To list all members of an organization, you can run the following command:

kcadm.sh get realms/orgdemo/organizations/{orgid}/members

Authenticating an organization member

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.

Querying organization members

To list all members of an organization, you can run the following command:

kcadm.sh get realms/orgdemo/organizations/{orgid}/members