To configure an external identity provider you first need to access the Keycloak administration console. Follow the instructions in Accessing Keycloak admin console.
In the akamas realm, navigate to the Identity providers section.
From here on, the steps required to proceed with the configuration vary depending on the provider you are integrating with. Select yours from the guides below:
In case you need to limit the count of user session logins for this provider, follow this guide
This page provides a walkthrough to configure Google as an external identity provider for Akamas users.
You will need a Google account with the privileges required to create app registrations.
To integrate Akamas with your Google Workspace, you first need a project with a dedicated OAuth client. Log in to your Google Developer Console, and navigate to the "Credentials" page of "API & Services".
If the "Credentials" page displays a warning box reminding you to configure the consent screen, you first need to create an app. Click the enclosed button to start the wizard.
Follow the wizard to configure the consent screen according to your company's policies. For more details, refer to Configure the OAuth consent screen on the official documentation.
Once the configuration is complete, return to the "Credentials" page.
Click the "Create Credentials" link on top, and select "OAuth Client ID".
Configure the client as follows:
"Application Type": select "Web application"
"Name": populate with the name of the new client
"Authorized redirect URIs": leave it blank, as you will fill it in a later step
Once you click "Create" the console will show you a confirmation pop-up containing the client's configuration. Note the Client ID and the Client Secret.
Access the Identity providers section for the "akamas" realm in the Keycloak administration console, as described on the page Configure an external identity provider, and select "Google" to start creating the new provider.
Configure the following fields using the values from the OAuth client you just created:
"Client ID": fill in the id of the client
"Client Secret": fill in the secret of the client
To complete the configuration, note the "Redirect URI" value and click "Add".
Back to the Google Developer Console, on the "Credentials" page, open the newly created client and add the URI from the previous step to the list of "Authorized redirect URIs".
If you change the hostname of the Akamas installation, then you will need to update or add the configured redirect URI registration for the integration to work correctly.
The final setup step is to instruct Akamas to associate the default roles with the users automatically. This way, users will be added to the default workspace with read and write permissions the first time they log in.
On the Keycloak console, on the provider's details page, navigate to "Mappers":
Now, add the following configurations.
User role
Name: User role
Mapper type: Hardcoded role
Role: USER
Default Workspace Read
Name: Default Workspace Read
Mapper type: Hardcoded role
Role: WS_ac8481d3-d031-4b6a-8ae9-c7b366f027e8_R
Default Workspace Write
Name: Default Workspace Write
Mapper type: Hardcoded role
Role: WS_ac8481d3-d031-4b6a-8ae9-c7b366f027e8_W
Visit the installation's login page to check that the new authentication method is displayed and works correctly.
This page provides a walkthrough to configure Azure Active Directory as an external identity provider for Akamas users.
You will need an Azure account with the Application.ReadWrite.All permission, required to create app registrations in your Azure AD tenant.
To integrate Akamas with your Active Directory, you first need a dedicated App registration in your Azure Organization. If you want to use an existing registration, skip to Get the client configuration; to create a new one, refer to the following sub-section.
Multiple Akamas instances can share the same app registration. It implies that any AD user added to a registration could access all the associated Akamas instances.
If you need to manage accesses with finer granularity, create a dedicated registration for each Akamas installation.
To create a new registration, navigate to "App registrations" in your Azure portal and select "New registration" and specify the following:
a name for the application
the account type that best suits your use case
Complete the creation by clicking on "Register".
On the "Overview" page of the application, note the following values:
Application (client) ID
OpenID Connect metadata document (found in the "Endpoints" side panel)
Furthermore, in the "Certificates & secrets" section, create a new Client secret and note its value.
With these values, we can now complete the provider configuration in the Keycloak console.
Access the Identity providers section for the "akamas" realm in the Keycloak administration console, as described on the page Configure an external identity provider, and select "OpenID Connect v1.0" to start creating the new provider.
Here, specify an alias for the client ("microsoft" in our case) and optionally the display name used in the login page ("Microsoft").
In the "OpenID Connect settings" section, configure the following fields using the values from the app registration in the Azure portal:
"Discovery endpoint": populate with the URL of the "OpenID Connect metadata document". This box should become green upon successful validation.
"Client ID": populate with the "Application (client) ID" from the app's overview page
"Client Secret": populate with the value of the generated secret
Complete the configuration by clicking "Add". You will land on the detail page of the new provider: here, copy the value of the redirect URI.
Back to the app registration in the Azure portal, navigate to the "Authentication" section. Add the "Web" platform (if not already present).
Finally, add to the list of redirect URIs the one from the previous step.
You have now configured Akamas to delegate to Azure your users' login.
When changing the hostname of the Akamas installation, you need to update the redirect URI configured in the app registration. Skipping this step will block any login attempt with the following error:
The redirect URI 'https://...' specified in the request does not match the redirect URIS configured for the application '...'.
The final setup step is to instruct Akamas to associate the default roles with the users automatically. This way, users will be added to the default workspace with read and write permissions the first time they log in.
On the Keycloak console, on the provider's details page, navigate to "Mappers":
Now, add the following configurations.
User role
Name: User role
Mapper type: Hardcoded role
Role: USER
Default Workspace Read
Name: Default Workspace Read
Mapper type: Hardcoded role
Role: WS_ac8481d3-d031-4b6a-8ae9-c7b366f027e8_R
Default Workspace Write
Name: Default Workspace Write
Mapper type: Hardcoded role
Role: WS_ac8481d3-d031-4b6a-8ae9-c7b366f027e8_W
Visit the installation's login page to check that the new authentication method is displayed and works correctly.
