Python Keycloak Client

Warnings

• breaking The `KeycloakAdmin` client's constructor significantly changed between versions 6.x and 7.x. Previously, it could accept a `KeycloakOpenID` object; now, it requires direct configuration parameters such as `server_url`, `realm_name`, `username`, `password`, `client_id`, and `client_secret_key`.
  Fix: Review the official documentation for `KeycloakAdmin` initialization in version 7.x. Update your `KeycloakAdmin` constructor calls to provide all necessary direct configuration parameters instead of passing a `KeycloakOpenID` instance.
• gotcha SSL certificate verification is enabled by default (`verify_ssl_cert=True`). This will cause connection errors with self-signed certificates or development setups that don't use valid CA-signed certificates.
  Fix: For development or testing with self-signed certificates, explicitly set `verify_ssl_cert=False` in the `KeycloakOpenID` or `KeycloakAdmin` constructor. Always re-enable `verify_ssl_cert=True` for production deployments.
• gotcha Confusing 'client_secret_key' parameter behavior for confidential clients. If your Keycloak client is confidential, you MUST provide `client_secret_key` during initialization. Public clients (e.g., SPA, mobile apps) should omit this parameter, and its presence can lead to authentication failures.
  Fix: Ensure `client_secret_key` is passed to `KeycloakOpenID` or `KeycloakAdmin` constructors ONLY if your Keycloak client is configured as 'confidential'. For public clients, ensure this parameter is omitted or set to `None`.

Install

• pip install python-keycloak Install stable version

Imports

• KeycloakOpenID

  from keycloak import KeycloakOpenID

• KeycloakAdmin

  from keycloak.admin import KeycloakAdmin

Quickstart

Demonstrates how to initialize the `KeycloakOpenID` client, obtain an access token using the Direct Access Grant (Resource Owner Password Credentials) flow, decode the token, and refresh it. Remember to configure your Keycloak server with a realm, client, and user. Set `verify_ssl_cert=True` in production environments.

import os
from keycloak import KeycloakOpenID

# Configuration from environment variables or sensible defaults
KEYCLOAK_SERVER_URL = os.environ.get('KEYCLOAK_SERVER_URL', 'http://localhost:8080/')
KEYCLOAK_REALM_NAME = os.environ.get('KEYCLOAK_REALM_NAME', 'myrealm')
KEYCLOAK_CLIENT_ID = os.environ.get('KEYCLOAK_CLIENT_ID', 'my-client-id')
KEYCLOAK_CLIENT_SECRET = os.environ.get('KEYCLOAK_CLIENT_SECRET', '') # Required for confidential clients
KEYCLOAK_USERNAME = os.environ.get('KEYCLOAK_USERNAME', 'testuser')
KEYCLOAK_PASSWORD = os.environ.get('KEYCLOAK_PASSWORD', 'password')

# Initialize KeycloakOpenID client
keycloak_openid = KeycloakOpenID(
    server_url=KEYCLOAK_SERVER_URL,
    realm_name=KEYCLOAK_REALM_NAME,
    client_id=KEYCLOAK_CLIENT_ID,
    client_secret_key=KEYCLOAK_CLIENT_SECRET, # Pass if client is confidential, otherwise omit
    verify_ssl_cert=False # Set to True for production, False for dev/self-signed certs
)

try:
    # Get initial tokens using Direct Access Grant (Resource Owner Password Credentials Flow)
    # Note: This flow is generally not recommended for public clients (e.g., browser-based apps)
    # and should be used cautiously, primarily for trusted backend services or CLI tools.
    token = keycloak_openid.token(KEYCLOAK_USERNAME, KEYCLOAK_PASSWORD)
    print("Successfully obtained token:")
    print(f"  Access Token (first 10 chars): {token.get('access_token', '')[:10]}...")
    print(f"  Refresh Token (first 10 chars): {token.get('refresh_token', '')[:10]}...")
    print(f"  Expires in: {token.get('expires_in')}s")

    # Example: Verify token
    decoded_token = keycloak_openid.decode_token(token['access_token'])
    print(f"  Decoded Access Token Subject: {decoded_token.get('sub')}")

    # Example: Refresh token
    if 'refresh_token' in token and token['refresh_token']:
        print("\nAttempting to refresh token...")
        refreshed_token = keycloak_openid.refresh_token(token['refresh_token'])
        print("Successfully refreshed token:")
        print(f"  New Access Token (first 10 chars): {refreshed_token.get('access_token', '')[:10]}...")
        print(f"  New Expires in: {refreshed_token.get('expires_in')}s")
    else:
        print("No refresh token available or provided.")

except Exception as e:
    print(f"Error during Keycloak interaction: {e}")
    print("Please ensure Keycloak is running, the realm, client ID/secret, and user credentials are correct.")
    print("Also, verify 'Direct Access Grants' is enabled for the client in Keycloak's client settings.")