How To: Security

External Keycloak Authentication

The Apiman quickstart overlay ZIP comes with an embedded version of Keycloak that we use for authentication. You may already have a Keycloak instance that you use. This section explains how to modify Apiman to use yours instead of ours.

High Level Overview

  1. Create the Apiman Realm in Keycloak

  2. Configure the API Manager UI client in Keycloak

  3. Point Apiman at the remote Keycloak

Create the Apiman Realm in Keycloak

You’ll need to make sure you create the apiman realm in your Keycloak server. A quick way to do that is to use the Keycloak admin console to import the Apiman realm file located here:

github.com/apiman/apiman/blob/master/distro/data/src/main/resources/data/apiman-realm.json

Configure the API Manager UI client in Keycloak

Once the apiman realm has been created or imported, make sure to configure the Valid Redirect URIs section of the apimanui, apiman and apiman-gateway-api clients. The default relative URL of each must be replaced by the full (absolute) public URL of your API Manager UI.

For example, the values may be something like:

apimanui

apiman.myorg.com/apimanui/*

apiman

apiman.myorg.com/apiman/*

apiman-gateway-api

apiman.myorg.com/apiman-gateway-api/*

Don’t forget the "*" wildcard at the end of the URL.

Point Apiman at the remote Keycloak

You must modify the standalone-apiman.xml configuration file to point Apiman at the remote Keycloak server.

Make sure you know the full public URL of your Keycloak server and add it to the following section of standalone-apiman.xml:

<realm xmlns:kc="urn:jboss:domain:keycloak:1.0" name="apiman">
    <realm-public-key>MIIBIjAN<...>AQAB</realm-public-key>
    <auth-server-url>http://apiman.myorg.com:8080/auth</auth-server-url>
    <public-client>true</public-client>
    <ssl-required>NONE</ssl-required>
    <enable-cors>false</enable-cors>
    <principal-attribute>preferred_username</principal-attribute>
</realm>

Finally, if you are using a standalone gateway, you should also configure the Gateway API to point to the same Keycloak instance.

If you manually created the apiman realm in Keycloak, you will also need to copy the realm’s public key into <realm-public-key> above.