Using Keycloak as an Identity Provider

This document describes how to use Keycloak as an identity provider for your Apcera cluster.

Prerequisites

To enable Keycloak on your Apcera cluster you will need the following:

  • SSH access to the Apcera cluster.
  • Base URL of Keycloak server instance
  • Access to Keycloak server instance's Admin Console.

Overview

Enabling Keycloak as an identity provider with an Apcera cluster involves the following steps:

  • Configuring the Keycloak server – This involves creating two Keycloak clients – entities that can request authentication of a user – in a selected Keycloak realm (not to be confused with realms in Apcera). This process results in a pair of client IDs (and a secret) you use to configure the Apcera cluster. You also create users under the same realm that you want to allow access to your Apcera cluster.
  • Configuring your Apcera cluster to use Keycloak for authentication – This involves modifying your cluster's cluster.conf file with the information obtained from the previous step. You also need to create policy that permits issuance of Apcera access tokens to authenticated Keycloak users.

Once these Keycloak server and Apcera cluster configurations are complete you can log in to your cluster with APC or the Web Console using Keycloak user credentials.

Configure the Keycloak server

To allow Apcera Platform to use your Keycloak instance for authentication and authorization services, the Apcera platform must be registered as a client with the Keycloak server. A Keycloak client is an entity that can request authentication of a user. You need to create two Keycloak clients: one for the Apcera Auth server (used by APC) and one for use by the Web Console.

Create Keycloak client for Apcera Auth server

The Apcera Auth server is the cluster component that handles all cluster authentication requests. To allow the Auth server to use your Keycloak instance for authentication and authorization services, it must be registered as a Keycloak client.

Note: A Keycloak realm secures and manages security metadata for a set of Keycloak users, applications, and registered oauth clients. It is distinct and separate from the concept of realms in Apcera policy declarations.

To create a Keycloak client for the Apcera Auth server:

  1. Login to your Keycloak server's Admin Console.
  2. Select the Realm for which the client should be registered, or click Add Realm to create a new realm (see Keycloak documentation for further instructions).
  3. Select Clients in the left navigation and then click Create to open the the Add Client dialog.
  4. In the Client ID field enter any name for the client ID, and select openid-connect from the Client Protocol menu.

    Alt text

    Note the client ID as you will need it when you enable Keycloak authentication on your Apcera cluster. The other fields can be left blank/default values.

  5. Click Save.
  6. In the client's Settings panel enter a name and description in the Name and Description fields, if desired, and the set the other fields as follows:

    • Set Access Type to confidential.
    • Set Standard Flow Enabled to ON.
    • Set Direct Access Grants Enabled to OFF
    • Set Service Accounts Enabled to OFF.
    • In the Valid Redirect URIs field add the URIs that OAuth 2.0 will use to redirect the client following successful user authentication. The URIs should be of the form http://keycloakauth.<cluster-name>.<top-level-domain>/v1/oauth2/redirect (for HTTP) and https://keycloakauth.<cluster-domain>:443/v1/oauth2/redirect (for HTTPS).

      For example, for a cluster deployed to mycluster.example.com you would add the following URIs:

      http://keycloakauth.mycluster.example.com/v1/oauth2/redirect
      https://keycloakauth.mycluster.example.com:443/v1/oauth2/redirect
      

      Your client's settings should now look similar to the following:

      Alt text

  7. Click Save.
  8. Click the Credentials tab.
  9. Note the generated value of the Secret field. You will need this value (and the Client ID value) that you defined for the client when you configure your Apcera cluster.

    Alt text

    Note: The Client Secret value is sensitive should be handled like other sensitive credentials.

Next, Create Keycloak client for Web Console.

Create Keycloak client for Web Console

In this section you will create a Keycloak client for the Web Console to authenticate users.

To create a Keycloak client for the Web Console:

  1. Login to your Keycloak server's Admin Console.
  2. Select the Realm for which the client should be registered, or click Add Realm to create a new realm (see Keycloak documentation for further instructions).
  3. Select Clients in the left navigation.
  4. Click Create to open the the Add Client dialog.
  5. In the Client ID field enter a client ID (e.g., apcera-webconsole). You will need this value when you enable Keycloak authentication on your Apcera cluster.
  6. Select openid-connect from the Client Protocol menu.

    Alt text

  7. Click Save. The client's Settings panel opens.
  8. In the Settings panel enter a client name and description, if desired, set the following options:

    • Set Enabled to ON.
    • Set Access Type to public.
    • Set Standard Flow Enabled to ON.
    • Set Implict Flow Enabled to ON.
    • Set Direct Access Grants Enabled to ON
    • In the Valid Redirect URIs field add the URI that OAuth 2.0 will use to redirect the client following successful user authentication. The URI should be of the form https://console.<cluster-domain>/oauth2/keycloak/.

      For example, for a cluster deployed to mycluster.example.com you would add the following URIs:

      https://console.mycluster.example.com/oauth2/keycloak
      

    Your client's settings should now look similar to the following:

    Alt text

  9. Click Save.

    The next step is to create Keycloak users to whom you want to provide access to your Apcera cluster. If you've already created the users, you can skip to Configuring your Apcera Platform cluster for Keycloak.

Create Users

Users defined under the realm are those users that are allowed to authenticate in the realm, and through the Apcera platform client. The basic steps for adding a user in Keycloak are included below, but your organization may have specific requirements for Keycloak user management. For more information see "Creating Users" in the Keycloak documentation.

To add a user:

  1. In the Keycloak admin console, click Users in the left navigation.
  2. Click Add user. The only required field is Username.

    Alt text

  3. Click Save.
  4. Click Credentials on the user details view that appears.
  5. Enter a password and confirmation, and click Reset Password.

Once you've created users in the Keycloak realm, you can configure your Apcera cluster to authenticate users against the Keycloak users in the specified realm.

Configuring Apcera cluster for Keycloak

Once you've created the required Keycloak clients the next step is to configure your cluster to use Keycloak to authenticate users. You also need to add policy that issues access tokens to authenticating users.

To complete this section you will need the following information:

An optional cluster configuration parameter (redeem_time_limit) lets you configure how long a user has to authenticate and have APC redeem their Keycloak token. See Token redemption time limit for more information.

Configure cluster to use Keycloak

Add a keycloak configuration object to the chef.continuum.auth_server.identity object of your cluster.conf file with the fields shown below, replacing placeholder values in <brackets> with the appropriate values obtained from your Keycloak server configuration:

"chef": {
  "continuum": {
    "auth_server": {
      "identity": {
        ...                
        "keycloak": {
          "enabled":       true,
          "client_id":     "<keycloak-authserver-clientID>",
          "client_secret": "<keycloak-authserver-secret>",
          "base_url":      "<keycloak-server-baseURL>",
          "realm":         "<keycloak-realm>",
          "web_client_id": "<keycloakd-webconsole-clientID>"
          "redeem_time_limit": <time_limit>                
        }                            
      }
    }
  }
}

The redeem_time_limit option specifies how long the Keycloak token will be available for redemption by the Apcera cluster during APC login flows. If not specified, the time limit defaults to 300 seconds. See APC login with Keycloak for more information.

If any additional certificates need to be installed in order for the Auth server to trust the Keycloak server, add them to the chef.continuum.pkix.system.additional_certs array. The certificates should be in PEM format. (See Configuring PKIX for more information.)

chef: {
  "continuum": {
    "pkix": {
      "system": {
        "additional_certs": [
          "-----BEGIN CERTIFICATE-----
           ...PEM CERTIFICATE 1 BODY...
           -----END CERTIFICATE-----",
          "-----BEGIN CERTIFICATE-----
           ...PEM CERTIFICATE 2 BODY...
           -----END CERTIFICATE-----"
        ]
      }
    }
  }
}

Next, Add policy to issue tokens to Keycloak users.

Add policy to issue tokens to Keycloak users

To give users defined in the Keycloak server access to your cluster you must add policy that issues access tokens to authenticated users. You can give access to users either by their Keycloak username or email. These values are provided by the Keycloak issuer.

For example, the following policy issues an Apcera token to the Keycloak user with the email "clusteruser-1@example.com", and also sets the token's name field to the Keycloak username value.

on auth::/oauth2/http {
  if (Keycloak->email == "clusteruser-1@example.com") {
    permit issue
    name Keycloak->name
  }
}

You can also issue a token based on the value of Keycloak->name, for example:

on auth::/oauth2/http {
  if (Keycloak->name == "clusteruser-1") {
    permit issue
    name Keycloak->name
  }
}

Note: The Keycloak issuer's name value is derived from the preferred_user field of the Keycloak access token.

Token redemption time limit configuration

When APC attempts a login with Keycloak (apc login --keycloak) it presents the user with a URL they open to initiate the authentication process in a web browser. It also asks the user to answer Yes/No when or if authentication was successful.

Browse to: http://keycloakauth.mycluster.example.com/v1/oauth2/device/auth/Z89QJ7BU
Did you successfully authorize the Apcera Platform? [Y/n]:

Upon an affirmative answer, APC redeems the Keycloak token. The redeem_time_limit value you specify in cluster.conf specifies the number of seconds the token will be available for redemption. Once the time limit has been reached, the token(s) will be disposed. This is done for security purposes, as the Apcera cluster should only keep the credentials long enough for the user to acquire them. The default time limit of 300 seconds is used if redeem_time_limit is not specified in cluster.conf.

Logging in with Keycloak credentials

Once your Keycloak server and Apcera Platform cluster have been configured, and you've added policy to issue Apcera access tokens to authenticated users, you can log in to your cluster via APC or the Web Console with valid Keycloak user credentials.

APC login with Keycloak

The process for logging in with APC using Keycloak is similar to logging in using Google Auth – the user is presented with a URL they open in a browser to initiate the authentication process. To have APC login using Keycloak run the apc login --keycloak command.

The command outputs instructions for the user to browse to the specified URL to initiate the Keycloak authentication process:

apc login --keycloak
Connecting to http://mycluster.example.com...

Sign in with Keycloak:

Browse to: http://keycloakauth.mycluster.example.com/v1/oauth2/device/auth/
Z89QJ7BU
Did you successfully authorize the Apcera Platform? [Y/n]:            

Open the specified URL in a browser, which displays a log in form for the configured Keycloak realm:

Alt text

Enter your Keycloak username and password and click Log in. Once you've successfully authenticated, return to APC and press the enter key at the prompt (Did you successfully authorize the Apcera Platform? [Y/n]:) to have APC redeem an Apcera token.

There is a limit on how long the cluster will allow a user to redeem a token, even if they authenticated successfully. By default, a user has 5 minutes to authenticate and redeem the token via APC (see Token redemption time limit.) You can configure this time limit in the Keycloak configuration object in cluster.conf (see Configuring your Apcera cluster for Keycloak).

Web Console login with Keycloak

Once your cluster is configured to use Keycloak a Sign in with Keycloak button appears on the Web Console log in screen:

Alt text

Click Sign in with Keycloak to open the Keycloak log in page. Enter your user's credentials and click Log In.

Alt text

On successful authentication, your browser is redirected to the Web Console.