Skip to main content

Invitations

Invitations provide a way to allow Keycloak and organization administrators to invite new members to the organization.

Invitations can be managed by the Keycloak admin in the Organizations tab of the Admin UI. You can enable organization administrators to manage invitations using the organization portal or building it into your application using the API. Creating an invite does not mean that the user is created, only that an invitation is pending for the given email address. The user will need to register with your application and will be presented a required action to accept the invitation.

Keycloak Phase Two Organizations Invites

Setup​

Invitees may or may not be existing users. If you choose to allow invitations to emails that are not represented by existing users, you must allow registration to your application, or use an authentication flow that automatically creates user accounts (such as magic link authentication).

If you want to email users an invite, it is important to provide a redirectUri to your application. Unless you have customized the [email template] at present to hard code an invite url, no link will be present in the email for the user to click on.

It is possible to pre-select any roles for a user by passing the roles array in the API (pre-selecting in the Admin UI is currently not implemented). This will automatically add the user to the given roles upon user creation and acceptance of the invitation.

Adapt the Authentication according to your needs.

Note: Users must have a verified email address to accept an invitation, as it presents a security issue to allow any User to register with an unverified email address and claim the invitation.

Following user creation and authentication, invitees will be prompted to accept or decline any outstanding invitations. In addition to any roles that were selected in the invitation, the user will automatically be added as a member to the inviting organization.

Admin Portal​

If you plan to use the Admin Portal to manage invitations, then you must configure the invitation template because there is no redirectUri field provided like in the Keycloak admin UI. In order to configure this template easily in the Phase Two deployments, enable the attributes theme for emails in the Realm Settings > Themes > Email Theme.

Once the attributes theme is set, go to (Extensions) Styles > Emails, select the invitation-email template and configure the {{link}} you would like to have in your email for the user to click on.

Options for user registration​

Self-registration​

This option requires either creating users on behalf of them before sending the invitation or enabling user registration on the realm.

Invitees will receive an email indicating the realm, organization and inviter. It is possible to add a specific application redirect URI so that they will be redirected to a specific location in the application.

This approach uses another extension in order to provide a magic link that will first register the user, authenticate them, and then present them with the required action to accept the invitation. This approach is preferred when user registration is disabled. It requires the following steps:

  • Create a magic link using force_create=true (to create a user if one does not exist) and send_email=false to skip sending the magic link to the user.
  • Use the returned magic link when creating an invitation. Set the redirectUri={magic-link}.

API access​

It is possible to create, remove pending and fetch all outstanding organization invitations using the API.