Keycloak SSO Setup

As of Apiman 3, we no longer bundle Keycloak server into Apiman quickstart distributions.

You need to run Keycloak before you can use Apiman ^[1].

If you are interested in support for other SSO providers, please let us know in this GitHub Issue.

In order to use the Apiman quickstarts, you need to run Keycloak.

Keycloak is used to manage a range of security tasks for Apiman, including user account management, login security, OIDC provider, etc.

To provide flexibility, there are a few ways you can tell Apiman’s components where your Keycloak server is:

For simpler configurations, environment variables or Java system properties are available. See the Apiman Auth Configuration section.
For advanced configurations, manual editing of config files may be required. See the Advanced Setups section.

Apiman Auth Configuration

Point Apiman at your Keycloak server

Table 1. Required Params
Name	Type	Description
System property: `apiman.auth.url` Env var: `APIMAN_AUTH_URL`	String	Keycloak auth server URL

Name Type Description

System property: apiman.auth.realm
Env var: APIMAN_AUTH_REALM

String

Keycloak realm name.

Default Value: apiman

In older versions of Keycloak the auth server might have /auth at the end of the URL, rather than being at root (i.e. old-keycloak:8080/auth vs new-keycloak:8080).

System property: apiman.auth.api.secret
Env var: APIMAN_AUTH_API_SECRET

String

Keycloak secret credential for the Apiman Manager API (apiman client)

Default Value: password

System property: apiman.auth.ui.secret
Env var: APIMAN_AUTH_UI_SECRET

String

Keycloak secret credential for the Apiman Manager UI (apimanui client)

Default Value: password

System property: apiman.auth.gateway.secret
Env var: APIMAN_AUTH_GATEWAY_SECRET

String

Keycloak secret credential for the Apiman Gateway API (apiman-gateway-api client)

Default Value: password

System property: apiman.auth.realm-public-key
Env var: APIMAN_AUTH_REALM_PUBLIC_KEY

String

Public key for Apiman realm. Get this from your Keycloak realm.

Default Value: Apiman will retrieve this from your Keycloak server’s .well-known endpoint automatically.

Please change default secrets and keys before deploying Apiman to production.

Running Keycloak

There are numerous ways to run Keycloak SSO, including many important best practices that should be observed in production-grade setups. However, these are beyond the scope of Apiman’s documentation; instead we will provide some simple development-grade setups to get you started quickly.

Please refer to the Keycloak documentation for comprehensive instructions and guides.

Easy: Docker Compose

A quick and easy way to run Keycloak and initialise it with the Apiman’s default realm is Docker Compose.

Here’s an example Docker Compose file:

Example Docker Compose file

services:
  keycloak:
    container_name: keycloak_server_all
    image: quay.io/keycloak/keycloak:22.0.5
    entrypoint: ['/bin/bash', '-c']
    command:
      - |
        cd /opt/keycloak
        ./bin/kc.sh build
        ./bin/kc.sh start-dev --import-realm
    ports:
      - "8085:8080"
    environment:
      - "KEYCLOAK_ADMIN=admin"
      - "KEYCLOAK_ADMIN_PASSWORD=admin123!"
      - "KEYCLOAK_FRONTEND_URL=http://localhost:8085"
    volumes:
      - ${PWD}/apiman-realm-for-keycloak.json:/opt/keycloak/data/import/apiman-realm-for-keycloak.json (1)

1	Copy `apiman-realm-for-keycloak.json` from `apiman/data/apiman-realm-for-keycloak.json` to the same directory as your `docker-compose.yml` file.

Steps

Create a file called docker-compose.yml with the contents shown above.
Copy apiman/data/apiman-realm-for-keycloak.json from your distro zip to the same directory as your docker-compose.yml.
Start with docker-compose up.
You should now have Keycloak running on localhost port 8085
Try it with: localhost:8085/admin
- Admin username: admin
- Admin password: admin123!
Your Apiman Auth URL is: localhost:8085 (see Apiman Auth Configuration)

In this Docker Compose example, Keycloak is running in dev mode. For production, refer to the Keycloak Production Guides.

Alternative: Download Keycloak Quarkus Distro

Alternatively, you can download the bare metal Quarkus distribution (older versions run on EAP and WildFly, but we won’t provide any guides here).

Steps

Download and extract Keycloak.
Initialise Keycloak with the Apiman default realm.
1. You can find the default realm definition in your distribution zip:
  
  apiman/data/apiman-realm-for-keycloak.json
2. There are several ways to import a realm, please refer to the Keycloak docs. However, for this example, we’ll do:
  
  ./bin/kc.sh start-dev --hostname <somehost> --port <someport> --import apiman-realm-for-keycloak.json
Carefully note which host and port your Keycloak instance is running on.
Set the APIMAN_AUTH_URL environment variable to point at Keycloak:

export APIMAN_AUTH_URL="http://<somehost>:<someport>".

For example, if your hostname is localhost and your port is 8085, then your APIMAN_AUTH_URL would be localhost:8085

Please also refer to Apiman Auth Configuration for more options.

Gateway API Authentication

The Apiman Gateway’s REST API is what the API Manager invokes when publishing APIs and Client Apps to the Apiman Gateway ^[2].

The quickstart configurations should work out of the box, but they assume the locality of all components.

Real deployments will likely need to perform some reconfiguration.

This REST API should be protected, usually by BASIC authentication.

By default, the Apiman Gateway REST API requires BASIC authentication credentials, as well as a role of apipublisher.

The Apiman Gateway REST API can only be invoked by a valid user, and that user must have the apipublisher role.
The Keycloak client for this API is apiman-gateway-api
- The default user is: apimanager
- The default password is: apiman123!

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, devportal, and apiman-gateway-api clients.

The default relative URL of each should be replaced by the full (absolute) public URL of your API Manager UI.

Our quickstarts ship with very permissive Keycloak redirects. This is good for testing, but unsafe for production.

For example, the values may be something like:

apimanui: apiman.myorg.com/apimanui/*
devportal: apiman.myorg.com/portal/*
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.

Advanced Setups

For more advanced setups, the environment variables/system properties may not be sufficient; manual editing of configuration files might be necessary.

Vert.x Gateway

Additional options

These options apply to the auth.config section.

{
  // <Other sections>
  "auth": {
    "type": "keycloak",
    "config": {
      // Options inserted here.
    }
  }
}

Table 3. Optional Params
Name	Type	Description
`ssl-required`	Boolean	Whether SSL required for the server URL
`allow-any-hostname`	Boolean	Whether hostname verification should be performed (if true, all hostnames will be accepted).
`disable-trust-manager`	Boolean	Whether hostname verification should be performed (if true, all hostnames will be accepted).
`truststore`	String	Path to truststore
`truststore-password`	String	Truststore password
`client-keystore`	String	Path to client keystore
`client-keystore-password`	String	client keystore password

Additional OAuth2 issuers

A common issue is that your issuers may appear different depending upon how your network is configured.

For example, proxies, Docker internal vs external networks, Kubernetes, etc.

To get around this, you can set additional accepted issuers via allowed-issuers:

{
 // <Other sections>

 "auth": {
    "type": "keycloak",
    "config": {
      "flowType": "PASSWORD",
      "requiredRole": "realm:apipublisher",
      "auth-server-url": "${apiman.auth.url:-http://localhost:8085}",
      // You can add extra issuers here; this can be very useful if
      // your setup has internal vs external issuers, and you need to
      // support both simultaneously.
      "allowed-issuers": [
        "${apiman.auth.public-endpoint:-}",
        "${apiman.auth.private-endpoint:-}",
        "http://example.com:8080/"
      ]
    }
  }
}

Manual setup

If you don’t want to use the default discovery mechanism, then for the Vert.x gateway, the simplest way to retrieve the necessary configuration is to generate it from your Keycloak server administrator console.

The gateway accepts Keycloak’s generated JSON, allowing you to paste your chosen client configuration from the Keycloak console into the auth.config section.

To retrieve it:

Log into your Keycloak Administrator console (e.g localhost:8085/admin).
Clients → apiman-gateway-api → Installation.
Select Keycloak OIDC JSON for Format Option.
Copy the contents and merge into the config selection where indicated below.

The precise configuration you need to provide will vary depending upon your Keycloak setup.

Due to a current limitation in the underlying OAuth2 library you may be required to provide a credentials section to avoid issues.

You can change your client type to confidential, or simply provide a dummy credentials section.

{
    // Preceding config
    "auth": {
      "type": "keycloak",
      "config": {
      "flowType": "PASSWORD",
      "requiredRole": "realm:apipublisher",
      // Paste and overwrite your Keycloak config here. (1)
      "realm": "apiman",
      "realm-public-key": "<snip>",
      "auth-server-url": "http://localhost:8080/auth",
      "ssl-required": "none",
      "resource": "apiman-gateway-api",
      // A limitation in the current OAuth2 implementation means a credentials section is required
      // even if your client is not set to "confidential". Leave this dummy section if you're using non-confidential.
      "credentials": {
        "secret": "217b725d-7790-47a7-a3fc-5cf31f92a8db"
      }
    }
  }
}

1	Paste your Keycloak config over this segment

Servlet

The API Gateway has a REST based configuration API which the API Manager uses when publishing APIs to it. This API is protected by Keycloak authentication.

Most options can be configured using environment variables or system properties, rather than editing configuration directly. Please see the Keycloak Configuration Options section for details.

If the above options are not sufficient, the relevant portion of the standalone-apiman.xml file that you must change is keycloak subsystem. It looks something like this:

<subsystem xmlns="urn:jboss:domain:keycloak:1.1">
    <secure-deployment name="apiman.war">
        <realm>${apiman.auth.realm, env.APIMAN_AUTH_REALM:apiman}</realm>
        <resource>apiman</resource>
        <!-- Lots of other tags -->
    </secure-deployment>
    <secure-deployment name="apimanui.war">
        <realm>${apiman.auth.realm, env.APIMAN_AUTH_REALM:apiman}</realm>
        <resource>apimanui</resource>
        <!-- Lots of other tags -->
    </secure-deployment>
    <secure-deployment name="apiman-gateway-api.war">
        <realm>${apiman.auth.realm, env.APIMAN_AUTH_REALM:apiman}</realm>
        <resource>apiman-gateway-api</resource>
        <!-- Lots of other tags -->
    </secure-deployment>
</subsystem>

Refer to the Keycloak WildFly Java Adapter documentation for a full list of options, as Apiman does not expose all of them out of the box.

1. It is possible to use other auth providers, but this is out of the scope of this guide.

2. Some advanced configurations may interact directly with the Gateway API, whilst others may bypass it entirely by using polling, etc.