Integrating with Keycloak

Edit online

Keycloak is a powerful tool that helps to implement authentication and authorization in applications quickly and efficiently.

To integrate Instana with Keycloak, follow the steps:

Prerequisites

Edit online
Note: After SAML is activated for a tenant, you have no other way to log in to Instana. The SAML configuration can be deleted through API by using a token with enough permissions.

Before you integrate Keycloak with Instana, you require administrator privileges in Keycloak.

Downloading the service provider metadata

Edit online

To configure Keycloak in Instana, a Service Provider Metadata XML file is provided. To download the file, click METADATA DOWNLOAD from the SAML settings dialog:

To save the file for later use, click METADATA DOWNLOAD.

For more information about configuring a service provider, see Configuring Service Provider.

Using an existing Realm

Edit online

You must have an existing Realm in Keycloak. The following example uses SAML-DEMO.

REALM

Creating the SAML client in Keycloak

Edit online

To create the SAML client in Keyclock, complete the following steps:

  1. Go to Configure > Clients, and click Create.

    Keycloak client

  2. Click Select file, and choose the previous downloaded service provider metadata.xml.

    Keycloak import

  3. Click Save. You return to the newly imported client edit page.

    Keycloak save

  4. Go to Realm Settings, and click SAML 2.0 Identity Provider Metadata to download the SAML 2.0 IdP metadata.

    Keycloak metadata

  5. Save the content as descriptor.xml.

  6. Go to the Instana-SAML setup page and upload the descriptor.xml file.

  7. Click Save to activate the SAML client configuration.

Adding users to Instana

Edit online

To add users to the SAML client configured for Instana, you must assign users their appropriate client roles. To add users to the SAML client configured for Instana in Keycloak, follow this overview:

  • Navigate to the SAML client configured for Instana in the respective realm (eg. SAML – DEMO).

  • Assign users appropriate client roles to add them to the SAML client.

    • Roles determine what permissions and access control users will receive in Instana.

    • If your realm or client has a default role configured, new users will automatically receive that role upon login.

For more details on assigning roles in Keycloak, refer to, Keycloak Server Administration Guide.

You are also encouraged to assign role mappings in Instana to help ensure that it correctly reads SAML assertions and applies the appropriate permissions to users. If you don’t configure role mappings, Instana assigns users a default role, if one is set. For more details, see IdP Role Mapping.