Skip to content

Setting up an IAM with Keycloak

Prerequisites

Before this track, you should have completed the following:

You'll also need:

  • Basic understanding of Identity and Access Management (IAM) concepts

Adding Keycloak to your docker-compose

To include Keycloak in your development environment, add the following configuration to your docker-compose.yml file:

services:
    # Existing services like engine and engine-db...

    keycloak:
        image: quay.io/keycloak/keycloak:latest
        ports:
            - "11000:11000"
        environment:
            KEYCLOAK_ADMIN: admin
            KEYCLOAK_ADMIN_PASSWORD: admin
            KC_HTTP_PORT: 11000
        command: start-dev

This configuration:

  • Uses the official Keycloak Docker image
  • Maps port 11000 to access the Keycloak admin console and API
  • Sets up admin credentials (username: admin, password: admin)
  • Runs in development mode with the start-dev flag

If you want to configure a realm, you can add the following configuration to the keycloak service in the docker-compose.yml file:

services:
    # Existing services like engine and engine-db...
    keycloak:
        # Existing configuration...
        command: start-dev --import-realm
        entrypoint: |
            /bin/  sh -c "
            # Create realm JSON file directly
            cat > /tmp/realm.json << 'EOF'
            {
                \"realm\": \"noumena\",
                \"enabled\": true,
                \"users\": [ ],
                \"clients\": [
                    {
                        \"clientId\": \"noumena\",
                        \"enabled\": true,
                        \"publicClient\": true,
                        \"directAccessGrantsEnabled\": true,
                        \"redirectUris\": [ \"*\" ],
                        \"webOrigins\": [ \"*\" ],
                        \"protocol\": \"openid-connect\"
                    }
                ]
            }
            EOF

            /opt/keycloak/bin/kc.sh import --file /tmp/realm.json
            exec /opt/keycloak/bin/kc.sh start-dev
            "

To run keycloak and other services in the project, run

docker compose up

Once Keycloak is running, you can access the admin console at http://localhost:11000/ and log in with the admin credentials.

Setting up the engine trusted issuers

The NOUMENA Runtime delegates authentication to an OpenID Connect-compliant IAM service like Keycloak. To tell the engine which authentication servers to trust, you need to configure the ENGINE_ALLOWED_ISSUERS environment variable.

This variable should contain a comma-delimited list of trusted JWT issuers. The engine will only accept JWTs where the iss field exactly matches one of these values.

For a local development environment with Keycloak, update your engine service in docker-compose.yml:

services:
    engine:
        image: ghcr.io/noumenadigital/images/engine:latest
        environment:
            ENGINE_ALLOWED_ISSUERS: "http://keycloak:11000/realms/noumena"
            SWAGGER_SECURITY_AUTH_URL: "http://localhost:11000/realms/noumena"
            SWAGGER_SECURITY_CLIENT_ID: "noumena"
            # Other engine configuration...

Key points to note:

  • ENGINE_ALLOWED_ISSUERS specifies the trusted issuer URL; containers reference Keycloak by service name
  • The realm name (here noumena) should match the realm you create in Keycloak
  • SWAGGER settings help with authentication in the Swagger UI

If you're using a different host, port, or realm name for Keycloak, adjust the URLs accordingly.

Configuring Keycloak using the Admin UI

Keycloak provides a comprehensive admin interface for setting up realms, clients, users, and other configurations. Let's walk through the manual configuration process.

Creating a new realm

A realm in Keycloak is a space where you define your clients, users, roles, and groups. The above configuration, if you used it, already created a realm called noumena. Alternatively, you can create it manually using the Keycloak Admin Console.

To create a new realm:

  1. Log in to the Keycloak Admin Console (http://localhost:11000/)
  2. Hover over the dropdown menu in the top-left corner (which by default shows Master)
  3. Click "Add realm"
  4. Enter the following details:
  5. Name: noumena
  6. Enabled: ON
  7. Click "Create"

Creating an OpenID client

Clients in Keycloak represent applications that can request authentication. Similarly to the realm, a client has been created if you used the provided configuration.

To create a client:

  1. In your new realm, go to "Clients" in the left sidebar
  2. Click "Create client"
  3. Fill in the client details:
  4. Client type: OpenID Connect
  5. Client ID: noumena (this should match what you configured in ENGINE_ALLOWED_ISSUERS)
  6. Name: NPL Application Client
  7. Click "Next"
  8. Configure the client capability config:
  9. Client authentication: OFF
  10. Authorization: OFF
  11. Standard flow: ON
  12. Direct access grants: ON
  13. Service accounts: OFF
  14. Click "Next"
  15. Configure login settings:
  16. Valid redirect URIs:
    • http://localhost:12000/*
    • http://localhost:15000/*
  17. Web origins: *
  18. Click "Save"

Setting up protocol mappers for claims

Protocol mappers transform user attributes into JWT claims. Use attributes needed for your application:

  1. Go to your client and select the "Client scopes" tab
  2. Click on the client scope with the same name as your client (e.g., "noumena-dedicated")
  3. Go to the "Mappers" tab
  4. Click "Create"
  5. Create a mapper for an attribute, replace ATTRIBUTE with the actual attribute name:
  6. Name: ATTRIBUTE-mapper
  7. Mapper type: User Attribute
  8. User Attribute: ATTRIBUTE
  9. Token Claim Name: ATTRIBUTE
  10. Claim JSON Type: JSON
  11. Add to ID token: ON
  12. Add to access token: ON
  13. Add to userinfo: ON
  14. Multivalued: ON
  15. Aggregate attribute values: ON
  16. Click "Save"

Repeat steps 4-6 for any other attributes you want to include in the JWT token.

Creating Keycloak users in the Admin UI

Users in Keycloak represent the entities that will interact with your NPL application. Each user can have various attributes.

To create a user:

  1. In your realm, go to "Users" in the left sidebar
  2. Click "Add user"
  3. Fill in the user details: Username, Email, First Name and Last Name. Make sure the email is verified.
  4. Click "Create"
  5. Go to the "Credentials" tab
  6. Click "Set password"
  7. Enter a password, switch "Temporary" to OFF, and click "Save"
  8. Go to the "Attributes" tab
  9. Add attributes by respecting the value format (including quotes):

["firstAttributeValue", "secondAttributeValue"], or

"uniqueAttribute"

  1. Click "Save"

Repeat steps 2-10 for any other users you want to create.

Authorizing requests to the NOUMENA Runtime

Now that you've set up Keycloak using the Admin UI, you can start authorizing requests to your NPL application.

You can use Keycloak's token endpoint to obtain a JWT token for testing:

Open a terminal and run the following curl command:

export TOKEN=$(curl \
    -X POST \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "client_id=noumena" \
    -d "grant_type=password" \
    -d "username=USERNAME" \
    -d "password=PASSWORD" \
    "http://localhost:11000/realms/noumena/protocol/openid-connect/token" \
    | jq -r '.access_token') \
    && echo "$ACCESS_TOKEN"

Replace USERNAME, PASSWORD with values from your users created previously. If you have called your realm or clients differently, you will also need to replace that in the URL and configuration.

The token can be used in the same way as before. For more information, refer to the Using your NPL application guide.

Next steps

After setting up IAM with Keycloak for your NPL application using the Admin UI, you might want to:

  • Generate API clients for your NPL application
  • Configure more advanced authentication flows
  • Configure keycloak for production

Further reading