Keycloak Provider

Installation

The Keycloak provider is available as a package in all Pulumi languages:

• JavaScript/TypeScript: @pulumi/keycloak
• Python: pulumi-keycloak
• Go: github.com/pulumi/pulumi-keycloak/sdk/v6/go/keycloak
• .NET: Pulumi.Keycloak
• Java: com.pulumi/keycloak

Overview

The Keycloak provider can be used to interact with Keycloak.

A note for users of the legacy Wildfly distribution

Recently, Keycloak has been updated to use Quarkus over the legacy Wildfly distribution. The only significant change here that affects this Pulumi provider is the removal of /auth from the default context path for the Keycloak API.

If you are using the legacy Wildfly distribution of Keycloak, you will need to set the basePath provider argument to /auth. This can also be done by using the KEYCLOAK_BASE_PATH environment variable.

Keycloak Setup

This Pulumi provider can be configured to use the client credentials or password grant types. If you aren’t sure which to use, the client credentials grant is recommended, as it was designed for machine to machine authentication.

Client Credentials Grant Setup (recommended)

1. Create a new client using the openid-connect protocol. This client can be created in the master realm if you would like to manage your entire Keycloak instance, or in any other realm if you only want to manage that realm.
2. Update the client you just created:
   1. Set Access Type to confidential.
   2. Set Standard Flow Enabled to OFF.
   3. Set Direct Access Grants Enabled to OFF
   4. Set Service Accounts Enabled to ON.
3. Grant required roles for managing Keycloak via the Service Account Roles tab in the client you created in step 1, see Assigning Roles section below.

Out of the many authentication methods of the client credentials grant type, this Pulumi provider supports the authentication using the client secret or the private key signed JWT.

Client Secret Authentication Type Setup

This is the default client authentication type and requires no further step.

Private Key Signed JWT Authentication Type Setup

These steps assume that you have already followed the steps for the client credentials grant and have created the client pulumi.

1. Change the Client authenticator in the Credentialstab to Signed JWT.
2. Generate or import a key pair via Keys. In case the key pair is generated by the Keycloak server, a keystore file would be downloaded and you have to extract the private key and keep it safe.

Password Grant Setup

These steps will assume that you are using the admin-cli client, which is already correctly configured for this type of authentication. Do not follow these steps if you have already followed the steps for the client credentials grant.

1. Create or identify the user whose credentials will be used for authentication.
2. Edit this user in the “Users” section of the management console and assign roles using the “Role Mappings” tab.

Assigning Roles

There are many ways that roles can be assigned to manage Keycloak. Here are a couple of common scenarios accompanied by suggested roles to assign. This is not an exhaustive list, and there is often more than one way to assign a particular set of permissions.

• Managing the entire Keycloak instance: Assign the admin role to a user or service account within the master realm.
• Managing the entire foo realm: Assign the realm-admin client role from the realm-management client to a user or service account within the foo realm.
• Managing clients for all realms within the entire Keycloak instance: Assign the create-client client role from each of the realm clients to a user or service account within the master realm. For example, given a Keycloak instance with realms master, foo, and bar, assign the create-client client role from the clients master-realm, foo-realm, and bar-realm.

Authentication

The Pulumi Provider currently supports the following authentication methods:

• Client-Credentials Grant (client_id + client_secret)
• Password Grant (client_id (+client_secret), username, password)
• Signed JWT (Private Key JWT)
• Provided Access Token (pre-provisioned Keycloak Access Token)

Additionally, the Pulumi Provider also supports using an mTLS client certificate to access Keycloak.

Example Usage (client credentials grant - client secret)

# Pulumi.yaml provider configuration file
name: configuration-example
runtime:
config:
    keycloak:clientId:
        value: pulumi
    keycloak:clientSecret:
        value: 884e0f95-0f42-4a63-9b1f-94274655669e
    keycloak:url:
        value: http://localhost:8080

Example Usage (client credentials grant - private key signed JWT)

# Pulumi.yaml provider configuration file
name: configuration-example
runtime:
config:
    keycloak:clientId:
        value: pulumi
    keycloak:jwtSigningKey:
        value: <pem-formatted-private-key>
    keycloak:url:
        value: http://localhost:8080

Example Usage (password grant)

# Pulumi.yaml provider configuration file
name: configuration-example
runtime:
config:
    keycloak:clientId:
        value: admin-cli
    keycloak:password:
        value: password
    keycloak:url:
        value: http://localhost:8080
    keycloak:username:
        value: keycloak

Example Usage (provided Token)

# Pulumi.yaml provider configuration file
name: configuration-example
runtime:
config:
    keycloak:accessToken:
        value: <encoded-access-token-here>
    keycloak:clientId:
        value: admin-cli
    keycloak:url:
        value: http://localhost:8080

Example Usage (mTLS Certificate)

# Pulumi.yaml provider configuration file
name: configuration-example
runtime:
config:
    keycloak:clientId:
        value: pulumi
    keycloak:clientSecret:
        value: 884e0f95-0f42-4a63-9b1f-94274655669e
    keycloak:jwtSigningKey:
        value: <pem-formatted-private-key>
    keycloak:rootCaCertificate:
        value: <pem-formatted-server-certificate>
    keycloak:tlsClientCertificate:
        value: <pem-formatted-client-certificate>
    keycloak:tlsClientPrivateKey:
        value: <pem-formatted-client-key>
    keycloak:url:
        value: https://localhost:8443

Configuration Reference

The following configuration inputs are supported:

• clientId - (Required) The clientId for the client that was created in the “Keycloak Setup” section. Use the admin-cli client if you are using the password grant. Defaults to the environment variable KEYCLOAK_CLIENT_ID.
• url - (Required) The URL of the Keycloak instance, before /auth/admin. Defaults to the environment variable KEYCLOAK_URL.
• adminUrl - (Optional) The admin URL of the Keycloak instance if different from the base URL, before /auth/admin. Defaults to the environment variable KEYCLOAK_ADMIN_URL.
• clientSecret - (Optional) The secret for the client used by the provider for authentication via the client credentials grant. This can be found or changed using the “Credentials” tab in the client settings. Defaults to the environment variable KEYCLOAK_CLIENT_SECRET. This attribute is required when using the client credentials grant, and cannot be set when using the password grant.
• username - (Optional) The username of the user used by the provider for authentication via the password grant. Defaults to the environment variable KEYCLOAK_USER. This attribute is required when using the password grant, and cannot be set when using the client credentials grant.
• password - (Optional) The password of the user used by the provider for authentication via the password grant. Defaults to the environment variable KEYCLOAK_PASSWORD. This attribute is required when using the password grant, and cannot be set when using the client credentials grant.
• accessToken - (Optional) The access token that should be used by the provider for authentication via token. Defaults to the environment variable KEYCLOAK_ACCESS_TOKEN.
• jwtSigningKey - (Optional) The PEM-formatted private key used by provider to generate a signed JWT for authentication.
• jwtSigningAlg - (Optional) The signing algorithm used by provider to generate a signed JWT for authentication. Defaults to RS256.
• realm - (Optional) The realm used by the provider for authentication. Defaults to the environment variable KEYCLOAK_REALM, or master if the environment variable is not specified.
• initialLogin - (Optional) Optionally avoid Keycloak login during provider setup, for when Keycloak itself is being provisioned by pulumi. Defaults to true, which is the original method.
• clientTimeout - (Optional) Sets the timeout of the client when addressing Keycloak, in seconds. Defaults to the environment variable KEYCLOAK_CLIENT_TIMEOUT, or 15 if the environment variable is not specified.
• tlsInsecureSkipVerify - (Optional) Allows ignoring insecure certificates when set to true. Defaults to false. Disabling this security check is dangerous and should only be done in local or test environments.
• rootCaCertificate - (Optional) Allows x509 calls using an unknown CA certificate (for development purposes)
• tlsClientCertificate - (Optional) The TLS client certificate in PEM format when the keycloak server is configured with TLS mutual authentication.
• tlsClientPrivateKey - (Optional) The TLS client pkcs1 private key in PEM format when the keycloak server is configured with TLS mutual authentication.
• basePath - (Optional) The base path used for accessing the Keycloak REST API. Defaults to the environment variable KEYCLOAK_BASE_PATH, or an empty string if the environment variable is not specified. Note that users of the legacy distribution of Keycloak will need to set this attribute to /auth.
• additionalHeaders - (Optional) A map of custom HTTP headers to add to each request to the Keycloak API.