Keycloak

Keycloak is an open-source, self-hosted identity and access management solution that provides single sign-on (SSO), user authentication, and authorization services for applications. In AMT environments, Keycloak enables secure authentication for Java backend services and Python client scripts through standard OAuth2 and OpenID Connect protocols.

By centralizing authentication and identity management, Keycloak eliminates the need for applications to handle user credentials directly, supports role-based access control, and provides a unified authentication experience across multiple AMT components. It is particularly useful when you need to secure gRPC communication between Python clients and Java backend services, or when implementing enterprise-grade authentication with features like multi-factor authentication, user federation, and session management.

Installation and Setup

Download and extract the latest version of Keycloak.

Starting Keycloak (Development Mode)

1. Open a terminal and navigate to the keycloak-<version>\bin folder.
2. Enter the following command to start Keycloak:
   kc.bat start-dev
   warning Using the start-dev parameter is only meant for development. For production or HTTPS configuration, use kc.bat start and configure certificates as described in the HTTPS Configuration section below.
3. Open a web browser and browse to localhost:8080 (or https://localhost:8443 if HTTPS is configured).

Creating An Admin Account

1. Fill the form with a username and password to create the admin account.
2. Click the Open Administration Console button and log in with the admin account.
3. Navigate to the Admin Console at http://localhost:8080/admin (or https://localhost:8443/admin if HTTPS is configured).
4. Log in using the credentials of the admin account.

Creating A Realm And A User

1. In the Administration Console, click on the drop-down menu at the top-left of the page and select Create realm.
2. Enter a name for the realm. For example, "AMTRealm" and click the Create button.
3. Within the newly created realm, click Users in the menu on the left side.
4. Click Create new user.
5. Enter a value for the following fields:
1. Username
2. First name
3. Last name
6. Click the Create button.
7. Click Credentials.
8. Enter a password for the new user.
9. Confirm the password by re-entering it in the Password confirmation field.
10. Click the Save button.

Optional – Verifying User Configuration

1. Navigate to http://localhost:8080/realms/AMTRealm/account (or https://localhost:8443/realms/AMTRealm/account if HTTPS is configured) to open the Account Console.
2. Log in using the credentials of the user created in the previous section.
3. From the Account Console, the user configuration can be verified and the account and profile can be managed.

Securing An Application

1. Navigate to the Admin Console at http://localhost:8080/admin (or https://localhost:8443/admin if HTTPS is configured).
2. Within the realm, click Clients in the sidebar menu, then click the Create client button.
3. In the General settings menu, configure the following:
   
   1. Client type: OpenID Connect
   2. Client ID: amt-java-cc
   3. Name: AMT Java Control Center
4. Click the Next button.
5. Leave the Capability settings as is and click the Next button.
6. Configure the following Login settings:
   1. Root URL: http://localhost:4200
   2. Home URL: http://localhost:4200
   3. Valid redirect URIs:
      1. http://localhost:4200/*
      2. http://localhost:4300/*
   4. Valid post logout redirect URIs: None
   5. Web origins:
      1. http://localhost:4200
      2. http://localhost:4300

Creating a Backend Resource Server Client

For gRPC authentication with Python clients, you need to register a backend resource server client. This client is used as the audience target for tokens but doesn't perform authentication itself.

1. Navigate to Clients in the sidebar menu, then click the Create client button.
2. Configure General settings:
   1. Client type: OpenID Connect
   2. Client ID: amt-backend (or any appropriate name for your backend)
   3. Name: AMT Backend Server
3. Click the Next button.
4. Configure Capability settings:
   1. Client authentication: Off
   2. Authorization: Off
   3. Standard flow: Off
   4. Direct access grants: Off
5. Click Next, then Save.

Note
The backend client is registered in Keycloak primarily for administration purposes, so it can be selected as an audience in token audience mappers. It doesn't authenticate itself.

Creating A Client Scope for Backend Audience

1. Navigate to Client scopes in the sidebar menu, then click the Create client scope button.
2. Configure the following Client scope settings:
   1. Name: backend_audience_scope
   2. Description: Scope to add backend server as audience to access tokens
   3. Type: None
3. Click the Save button.
4. Click the Mappers tab and click on Configure a new mapper to configure the following:
   1. Name: backend audience mapper
   2. Included Client Audience: amt-backend (the backend client created above)
   3. Add to ID token: Off
   4. Add to access token: On
5. Click the Save button.

HTTPS Configuration

For production environments or when using Python client libraries with gRPC, Keycloak should be configured to use HTTPS. This requires generating a certificate and configuring Keycloak to run in production mode.

Generate Self-Signed Certificate

Create a directory for certificates and generate a self-signed certificate using OpenSSL:

# Windows PowerShell
New-Item -ItemType Directory -Force -Path "C:\Tools\certs"
cd C:\Tools\certs

# Generate certificate (365 days validity)
openssl req -x509 -newkey rsa:2048 -nodes -keyout localhost.key -out localhost.pem -days 365 -subj "/CN=localhost"

This creates two files:

• localhost.pem - The certificate (public)
• localhost.key - The private key (keep secure)

Configure Keycloak for HTTPS

Edit the Keycloak configuration file at <keycloak-dir>\conf\keycloak.conf:

# HTTPS Certificate Configuration
https-certificate-file=C:/Tools/certs/localhost.pem
https-certificate-key-file=C:/Tools/certs/localhost.key
https-port=8443

# Disable HTTP (optional, recommended for production)
http-enabled=false

# Allow any hostname (for development)
hostname-strict=false

Start Keycloak in Production Mode

HTTPS with custom certificates requires Keycloak to run in production mode:

# Navigate to Keycloak bin directory
cd <keycloak-dir>\bin

# Start in production mode (required for HTTPS)
kc.bat start

Note
Development mode (start-dev) ignores custom HTTPS certificate configuration. You must use start for HTTPS to work with self-signed certificates.

Keycloak will now be accessible at https://localhost:8443

Python Client Configuration

When using Python client libraries (such as amt-jcl) with Keycloak for gRPC authentication, additional configuration is required for OIDC and certificate trust.

Creating a Python Client in Keycloak

Python clients require a confidential client configuration with client credentials flow enabled.

1. Navigate to Clients and click Create client.
2. Configure General settings:
   1. Client type: OpenID Connect
   2. Client ID: amt-python-client (or any appropriate name)
   3. Name: AMT Python Client
3. Click Next.
4. Configure Capability settings:
   1. Client authentication: On
   2. Authorization: Off
   3. Standard flow: Off
   4. Direct access grants: Off
   5. Service accounts roles: On
5. Click Next, then Save.
6. Navigate to the Credentials tab and copy the Client secret (needed for Python configuration).
7. Navigate to the Client scopes tab, click Add client scope, select the backend scope you created (e.g., backend_audience_scope), and set it as Default.

Python Configuration File

Configure your Python application's jcl_config.json file with the following settings:

{
  "oidc_url": "https://localhost:8443/realms/AMTRealm/protocol/openid-connect/token",
  "oidc_client_id": "amt-python-client",
  "oidc_client_secret": "<YOUR_CLIENT_SECRET>",
  "oidc_scope": "openid offline_access backend_audience_scope",
  "cert": "path/to/server1.pem",
  "app_host": "localhost",
  "app_grpc_port": "8081"
}

Field	Description
oidc_url	Keycloak token endpoint URL
oidc_client_id	The Python client ID created in Keycloak
oidc_client_secret	Client secret from Keycloak Credentials tab
oidc_scope	Scopes to request. Must include the backend scope to get the correct audience
cert	Path to the server certificate that the Java backend serves on the gRPC port

Certificate Trust Configuration

When Keycloak uses HTTPS with self-signed certificates, Python clients need to trust the certificate to avoid SSL verification errors.

Setting the Certificate Trust for Python Clients

Set the REQUESTS_CA_BUNDLE environment variable to point to the Keycloak certificate:

# Windows PowerShell
$env:REQUESTS_CA_BUNDLE = "C:\Tools\certs\localhost.pem"

# Windows Command Prompt
set REQUESTS_CA_BUNDLE=C:\Tools\certs\localhost.pem

# Linux/macOS
export REQUESTS_CA_BUNDLE=/path/to/localhost.pem

This allows Python's requests library to trust the self-signed certificate when connecting to Keycloak.

Setting Certificate Trust for Java Backend

If the Java backend needs to validate tokens by connecting to Keycloak's JWKS endpoint over HTTPS with a self-signed certificate, import the certificate into the Java truststore:

keytool -importcert -alias keycloak -file localhost.pem -keystore $JAVA_HOME/lib/security/cacerts -storepass changeit -noprompt

Troubleshooting

SSL Certificate Verification Errors

Symptom: Python scripts fail with error:

[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate

Solution:

1. Ensure the Keycloak certificate file exists at the configured path
2. Set the REQUESTS_CA_BUNDLE environment variable to point to the certificate file
3. Verify the certificate path in jcl_config.json matches the Java backend's server certificate

Token Validation Fails

Symptom: Java backend rejects tokens with "invalid audience"

Solution:

1. Ensure the client scope is assigned to the Python client as Default
2. Verify the scope contains an audience mapper pointing to the backend client ID
3. Check that the oidc_scope in Python configuration includes the backend scope name

gRPC Connection Fails

Symptom: Python client cannot connect to Java backend

Solution:

1. Verify the cert path in jcl_config.json points to the correct server1.pem (the certificate served by the Java backend on port 8081)
2. Ensure the Java backend is running on the configured app_grpc_port
3. Check that the certificate in jcl_config.json matches what the server is serving

OIDC Token Request Fails

Symptom: Python client cannot obtain tokens from Keycloak

Solution:

1. Verify oidc_client_secret matches the value in Keycloak
2. Ensure Service accounts roles is enabled on the Python client
3. Check that Keycloak is accessible at the oidc_url
4. Set REQUESTS_CA_BUNDLE if using self-signed certificates