onboarding-members-invitation-link.adoc

Onboarding Organization Members using an Invitation Link

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, existing users in a realm are going to be able to join an organization by following a registration link.

In this playbook you will learn about:

• How to create an organization in a realm

• How to send an invitation link to invite a users in a realm to join an organization

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,
  "registrationAllowed": true,
  "smtpServer": {
    "from": "admin@orgdemo.com",
    "host": "{host}",
    "auth": "true",
    "user": "{user}",
    "password": "{password}"
  }
}
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.

Once you have the orgdemo realm created, you can now invite existing users to join an organization.

Create an user in the orgdemo realm

You also need an user in the `orgdemo`realm:

kcadm.sh create realms/orgdemo/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 orgdemo organization, to whom an invitation link will be sent to join the orga organization.

Save the id of the user as we are going to use it later to send the invitation link.

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

Send the Registration Link

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-existing-user -b {userid}

If 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 automatically redirect to the orgdemo realm to complete the action and, once the user confirms the intention to join the organization, the user will automatically join 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/members