Manage Identities¶
Table of Contents¶
Identity Management in ODA Canvas¶
The ODA Canvas uses Keycloak as its Identity Management solution. When a Component is deployed, the Identity Config Operator reads the component’s spec.securityFunction and creates an IdentityConfig child resource. The operator then configures Keycloak by:
Creating a Keycloak client named after the component (e.g.,
pc1-productcatalogmanagement) in the Canvas realmRegistering the Canvas system role (typically
canvasRole) – this is a reserved role used by Canvas operators to interact with the component’s APIs; it should never be assigned to end usersListening for role changes – if the component exposes a
permissionSpecificationSetAPIorpartyRoleAPI, the operator registers a listener to detect when the component adds or removes roles dynamically
Key concepts:
Each deployed component has exactly one
IdentityConfigresource, owned by the parent ComponentThe
canvasSystemRoleis reserved for Canvas infrastructure – do not assign it to human usersComponent roles are managed by the ODA Component, not directly in Keycloak. The Identity Config Operator syncs roles from the component to Keycloak automatically. There are two mechanisms:
Static roles: defined in the Component YAML under
spec.securityFunction.componentRole[]and configured at deployment timeDynamic roles: the component exposes a
permissionSpecificationSetAPI(TMF672) orpartyRoleAPI(TMF669), and the Identity Config Operator registers a listener to detect role changes and syncs them to Keycloak
Roles are scoped to a Keycloak client, not the realm – each component manages its own set of roles
Do not create or delete roles directly in Keycloak for component clients – the Identity Config Operator is the authoritative source and will overwrite manual changes
Roles can be created directly in Keycloak for external clients (non-component clients created for M2M access)
Clients (applications/services) authenticate using the Client Credentials flow – this is the recommended approach for API access. Always create an external Keycloak client for programmatic access – do not create Keycloak users
View IdentityConfig Resources¶
Present the sub-menu when the user selects “Manage identities”:
# |
Action |
|---|---|
1 |
View IdentityConfig resources – List all IdentityConfig custom resources |
2 |
View Keycloak UI – Access the Keycloak admin console |
3 |
Add component roles – Add roles to a component (static or dynamic) |
4 |
Create a Keycloak client – Create an external client for the Client Credentials flow |
5 |
Check Keycloak-Kong JWT integration – Verify Kong can validate Keycloak JWT tokens |
6 |
Generate a Postman collection – Create a Postman collection for authenticated API testing |
7 |
Return to main menu |
Listing IdentityConfigs¶
# Raw output
kubectl get identityconfigs -n components
# Full YAML for detailed inspection
kubectl get identityconfigs -n components -o yaml
The summary shows:
Column |
Description |
|---|---|
NAME |
IdentityConfig resource name (matches component name) |
IDENTITY PROVIDER |
The identity provider in use (e.g., Keycloak) |
LISTENER REG. |
Whether a listener is registered for dynamic role changes |
ROLES |
Number of static roles, or “dynamic” if roles come via an API |
After listing, offer to drill into a specific IdentityConfig.
IdentityConfig Drill-Down¶
kubectl get identityconfig <name> -n components -o yaml
Interpret the YAML output to show:
Parent Component – the Component that owns this IdentityConfig
Canvas System Role – the reserved role for Canvas operators (typically
canvasRole)Identity Provider – the configured identity provider (Keycloak)
Listener Registered – whether the operator is listening for dynamic role changes
Static Component Roles – any roles declared in
spec.componentRole[]Permission Specification Set API – the API endpoint for dynamic role management (if configured)
Party Role API – legacy API for dynamic roles (if configured)
After drill-down, explain:
The canvasSystemRole (e.g.,
canvasRole) is used by Canvas operators to authenticate against the component’s APIs. It is created automatically and should not be assigned to users.If permissionSpecificationSetAPI is configured, the component exposes a TMF API (typically TMF672 Permission Specification) that allows it to define roles dynamically. The Identity Config Operator registers a listener on this API to detect role changes and syncs them to Keycloak.
Static componentRoles are defined in the Component YAML and configured once at deployment time.
You can also view the raw YAML:
kubectl get identityconfig <name> -n components -o yaml
Understanding the CRD Schema¶
Offer to explore the IdentityConfig schema:
kubectl explain identityconfig.spec
kubectl explain identityconfig.spec.componentRole
kubectl explain identityconfig.spec.permissionSpecificationSetAPI
Key v1 schema properties (from charts/oda-crds/templates/oda-identityconfig-crd.yaml):
Field |
Type |
Description |
|---|---|---|
|
string |
Role name for Canvas operators to use (reserved) |
|
array of {name, description} |
Statically defined roles |
|
object {implementation, path, port} |
API for dynamic role management |
|
object {implementation, path, port} |
Legacy API for dynamic roles (deprecated in future) |
Status fields:
Field |
Description |
|---|---|
|
The identity provider (e.g., Keycloak) |
|
Whether a listener is active for dynamic role changes |
Add Component Roles¶
ODA Component roles are managed by the component itself and synced to Keycloak automatically by the Identity Config Operator. You should never create roles directly in Keycloak for a component client – the operator is the authoritative source and will overwrite manual changes.
There are two mechanisms for defining component roles:
Option A: Static Roles (Component YAML)¶
Static roles are defined in the Component’s Helm chart under spec.securityFunction.componentRole[]. They are configured once at deployment time and synced to Keycloak by the Identity Config Operator.
Example (from feature-definition-and-test-kit/testData/productcatalog-static-roles-v1/):
spec:
securityFunction:
canvasSystemRole: canvasRole
componentRole:
- name: pcadmin
description: Product Catalogue Administrator
- name: cat1owner
description: Catalogue Owner for catalogue 1
- name: cat2owner
description: Catalogue Owner for catalogue 2
To add a new static role to an existing component:
Edit the component’s Helm chart values or template to add the role to
spec.securityFunction.componentRole[]Upgrade the Helm release:
helm upgrade <release-name> <chart> -n components
The Component Operator updates the
IdentityConfigchild resource, the Identity Config Operator detects the change and syncs the new role to Keycloak.Verify the role appears in Keycloak:
python <scripts>/manage_keycloak_users.py \ --keycloak-url http://localhost:8083/auth \ --admin-password <ADMIN_PASS> \ --realm odari \ --action list-roles \ --client-id <component-name>
Option B: Dynamic Roles (permissionSpecificationSetAPI)¶
Dynamic roles are defined at runtime by the component via its TMF672 Permission Specification API (or the legacy TMF669 Party Role API). The Identity Config Operator registers a listener on this API and syncs role changes to Keycloak automatically.
Example (from feature-definition-and-test-kit/testData/productcatalog-v1/):
spec:
securityFunction:
canvasSystemRole: canvasRole
exposedAPIs:
- name: userrolesandpermissions
specification:
- url: "https://raw.githubusercontent.com/tmforum-apis/TMF672_UserRolePermissions/master/TMF672-UserRolePermissions-v5.0.0.swagger.json"
implementation: pc1-permissionspecapi
apiType: openapi
path: /pc1-productcatalogmanagement/rolesAndPermissionsManagement/v5
port: 8080
To add a role dynamically, POST a new PermissionSpecificationSet to the component’s TMF672 API. The component must be running and the API must be accessible.
Step 1: Find the TMF672 API URL
kubectl get exposedapis -n components -o yaml
Look for the ExposedAPI with TMF ID TMF672. The URL will be in the format:
https://localhost/<component-path>/rolesAndPermissionsManagement/v5
Step 2: POST the PermissionSpecificationSet
Critical: The
@baseTypefield must be set toPermissionSpecificationSet(uppercase ‘P’). If omitted, the component’s API defaults to lowercasepermissionSpecificationSet, which the Identity Config Operator’s listener will reject with an “invalid @baseType” warning and the role will not be synced to Keycloak.
# PowerShell
$body = @{
"@type" = "PermissionSpecificationSet"
"@baseType" = "PermissionSpecificationSet"
"name" = "<ROLE_NAME>"
"involvementRole" = "<ROLE_NAME>"
"description" = "<ROLE_DESCRIPTION>"
"permissionSpecification" = @(@{
"@type" = "PermissionSpecification"
"name" = "<ROLE_NAME>:read-only"
"description" = "Read-only access to resources"
"function" = "<ROLE_NAME>"
"action" = "all"
})
} | ConvertTo-Json -Depth 5
Invoke-RestMethod -Uri "https://localhost/<COMPONENT_PATH>/rolesAndPermissionsManagement/v5/permissionSpecificationSet" `
-Method POST -ContentType "application/json" -Body $body -SkipCertificateCheck
# bash
curl -sk -X POST "https://localhost/<COMPONENT_PATH>/rolesAndPermissionsManagement/v5/permissionSpecificationSet" \
-H "Content-Type: application/json" \
-d '{
"@type": "PermissionSpecificationSet",
"@baseType": "PermissionSpecificationSet",
"name": "<ROLE_NAME>",
"involvementRole": "<ROLE_NAME>",
"description": "<ROLE_DESCRIPTION>",
"permissionSpecification": [{
"@type": "PermissionSpecification",
"name": "<ROLE_NAME>:read-only",
"description": "Read-only access to resources",
"function": "<ROLE_NAME>",
"action": "all"
}]
}'
Key fields:
Field |
Required |
Description |
|---|---|---|
|
Yes |
Must be |
|
Yes |
Must be |
|
Yes |
The role name (e.g., |
|
Yes |
Should match |
|
No |
Human-readable description of the role |
|
Yes |
Array of permission specs defining what the role grants |
Step 3: Wait for sync
The Identity Config Operator’s listener sidecar receives the PermissionSpecificationSetCreationNotification from the component and creates the role in Keycloak. This typically takes a few seconds.
Step 4: Verify the role appears in Keycloak:
python <scripts>/manage_keycloak_users.py \
--keycloak-url http://localhost:8083/auth \
--admin-password <ADMIN_PASS> \
--realm odari \
--action list-roles \
--client-id <component-name>
Troubleshooting: If the role does not appear after 10–15 seconds, check the listener sidecar logs:
kubectl logs <identityconfig-operator-pod> -n canvas -c idlistkey --tail=20
Look for:
"security-APIListener permissionSpecificationSet event listener success"– role was synced"@baseType was permissionSpecificationSet - not processed"– the@baseTypefield has the wrong case; re-POST with"@baseType": "PermissionSpecificationSet"
When to use each approach¶
Approach |
When to use |
|---|---|
Static roles |
Roles are known at design time, don’t change often, and are defined by the component developer |
Dynamic roles |
Roles are determined at runtime, managed by administrators or business logic, or change frequently |
Important¶
If the user asks to “create a role” on a component, guide them through one of these two approaches – do not create the role directly in Keycloak
If
canvasRoleis the only role and nopermissionSpecificationSetAPIis configured, the component needs to be redeployed with static roles or updated to expose a permission specification API
Keycloak UI Access¶
Prerequisites¶
Keycloak runs in the canvas namespace. Check if it’s running:
kubectl get pods -n canvas -l app.kubernetes.io/name=keycloak
Retrieve Admin Credentials¶
The admin username is admin. Retrieve the password from the Kubernetes secret:
# bash
kubectl get secret canvas-keycloak -n canvas -o jsonpath='{.data.admin-password}' | base64 -d
# PowerShell
kubectl get secret canvas-keycloak -n canvas -o jsonpath='{.data.admin-password}' | python -c "import sys,base64; print(base64.b64decode(sys.stdin.read()).decode())"
Access the Keycloak Console¶
Find the Keycloak service:
kubectl get svc canvas-keycloak -n canvas
If the service type is LoadBalancer and has an external IP/hostname, it may already be accessible. Otherwise, port-forward:
kubectl port-forward svc/canvas-keycloak -n canvas 8083:8083
Run port-forward as a background process so it remains accessible.
Open the Keycloak admin console in VS Code Simple Browser at: http://localhost:8083/auth/admin
Log in with:
Username:
adminPassword: (retrieved from the secret above)
Create a Keycloak Client¶
This section covers creating a Keycloak client (application identity) for external systems that need to call ODA Component APIs using the Client Credentials flow. This is the recommended authentication approach for machine-to-machine (M2M) API access.
Note: This creates an external client in Keycloak – separate from the component clients that are automatically managed by the Identity Config Operator. Roles can be freely created and assigned on external clients without conflicting with the operator.
Interactive Workflow¶
When the user selects “Create a Keycloak client”, follow this workflow:
Step 1: Identify the target component
List the deployed components to determine which APIs the client needs to access:
kubectl get identityconfigs -n components -o yaml
Step 2: Ask for client details
Ask the user for:
Client ID (required) – a descriptive name like
externalSystem,integration-test, ormy-billing-app. Must not conflict with existing component client names (e.g., do not usepc1-productcatalogmanagement)Description (optional) – what the client is for
Step 3: Create the client
Use the helper script:
python <scripts>/manage_keycloak_users.py \
--keycloak-url http://localhost:8083/auth \
--admin-password <ADMIN_PASS> \
--realm odari \
--action create-client \
--client-id <CLIENT_ID>
This creates a confidential Keycloak client with:
Client authentication: Enabled (confidential client – requires a client secret)
Service accounts roles: Enabled (allows Client Credentials grant)
Direct access grants: Enabled (allows password grant for testing)
Standard flow: Disabled (no browser-based login needed)
Step 4: Show the client secret
After creation, retrieve the client secret:
python <scripts>/manage_keycloak_users.py \
--keycloak-url http://localhost:8083/auth \
--admin-password <ADMIN_PASS> \
--realm odari \
--action get-client-secret \
--client-id <CLIENT_ID>
Step 5: Assign component roles (optional)
If the target component has roles beyond canvasRole, offer to assign them to the external client’s service account. These roles are defined by the component (statically or dynamically) and already exist in Keycloak – you are only assigning existing roles, not creating new ones:
python <scripts>/manage_keycloak_users.py \
--keycloak-url http://localhost:8083/auth \
--admin-password <ADMIN_PASS> \
--realm odari \
--action assign-client-roles \
--client-id <CLIENT_ID> \
--target-client <COMPONENT_CLIENT_ID> \
--roles <ROLE1>,<ROLE2>
If no assignable roles exist yet (only canvasRole), explain that the component needs to define roles first – either by adding static componentRole[] entries in the Component YAML or by publishing roles via its permissionSpecificationSetAPI. See the Add component roles section.
Step 6: Verify with a Client Credentials call
Test that the client can obtain a JWT token:
# PowerShell
$token = (Invoke-RestMethod -Uri "http://localhost:8083/auth/realms/odari/protocol/openid-connect/token" `
-Method POST -ContentType "application/x-www-form-urlencoded" `
-Body "grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>").access_token
Write-Host "Token obtained successfully (length: $($token.Length) chars)"
# bash
TOKEN=$(curl -s -X POST http://localhost:8083/auth/realms/odari/protocol/openid-connect/token \
-d "grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>" \
| python -c "import sys,json; print(json.load(sys.stdin)['access_token'])")
echo "Token: ${TOKEN:0:50}..."
If the Client Credentials call fails with “Client not enabled to retrieve service account”, the service accounts option was not enabled. The user can fix this in the Keycloak UI:
Navigate to Clients > select the client
Go to the Settings tab
Enable Service accounts roles (or Service account enabled in older Keycloak versions)
Click Save
Retry the token request
Explaining Client Scopes¶
When explaining the created client, mention:
The client’s service account is automatically created by Keycloak when service accounts are enabled. It appears as a user named
service-account-<client-id>in the Users list.Client scopes control which claims appear in the JWT token. The default scopes (
email,profile,roles) are typically sufficient.The JWT
iss(issuer) claim will be the Keycloak realm URL (e.g.,http://localhost:8083/auth/realms/odari). This is important for Kong JWT validation.The default token expiry is 300 seconds (5 minutes). This can be changed in the client’s Advanced Settings tab under Access Token Lifespan.
Verify Keycloak-Kong JWT Integration¶
When apiKeyVerification is enabled on ExposedAPIs, the Kong API Operator creates JWT KongPlugins for those APIs automatically. However, Kong needs to know Keycloak’s RSA public key to verify tokens. This section checks the bridge between Keycloak and Kong.
Important: The KongPlugins, KongConsumers, and JWT credential secrets described in this section are created and managed by the API Operator. Do not create, delete, or modify these resources directly. The commands below are for verification and debugging only. To enable or disable JWT authentication, use
helm upgrade --reuse-valueswith--set component.apipolicy.apiKeyVerification.enabled=trueon the parent Component’s Helm release (see View ExposedAPIs > Enable/Disable Authentication).
How Kong JWT Validation Works¶
The Kong JWT plugin uses these key settings (configured by the API Operator):
key_claim_name: iss– the JWTiss(issuer) claim identifies which consumer/key to useclaims_to_verify: [exp]– checks token expirysecret_is_base64: false– the RSA public key is stored in PEM format
For Kong to validate a Keycloak JWT, you need:
A KongConsumer resource pointing to Keycloak
A JWT credential on that consumer containing Keycloak’s RSA public key
The credential’s
keymust match the JWTissclaim (i.e., the Keycloak realm URL)
Step 1: Check if JWT KongPlugins exist¶
kubectl get kongplugins -n components -l oda.tmforum.org/type=apiauthentication
If no JWT plugins exist, apiKeyVerification is not enabled on any ExposedAPIs. Offer to enable it first (see View ExposedAPIs > Enable Authentication).
Step 2: Check for existing KongConsumers and JWT credentials¶
kubectl get kongconsumers -n components
kubectl get secrets -n components -l konghq.com/credential=jwt
If a JWT credential secret already exists with a key matching the Keycloak issuer URL, the bridge is already configured. Verify by inspecting:
# PowerShell
kubectl get secret <SECRET_NAME> -n components -o jsonpath='{.data.key}' | python -c "import sys,base64; print(base64.b64decode(sys.stdin.read()).decode())"
The key should be: http://localhost:8083/auth/realms/odari
Step 3: If no integration exists — troubleshooting¶
The KongConsumer and JWT credential resources are created automatically by the API Operator when apiKeyVerification.enabled is set to true on any ExposedAPI. You should not create these resources manually.
If apiKeyVerification is enabled on an ExposedAPI but the KongConsumer or JWT credential does not exist:
Check the API Operator logs for errors:
kubectl logs -n canvas -l app=api-operator-kong --tail=30
Check that the ExposedAPI has
apiKeyVerification.enabled: true:kubectl get exposedapi <name> -n components -o jsonpath='{.spec.apiKeyVerification}'
Trigger a reconciliation by annotating the ExposedAPI:
kubectl annotate exposedapi <name> -n components reconcile=$(date +%s) --overwrite
Verify the resources were created:
kubectl get kongconsumers -n components kubectl get secrets -n components -l konghq.com/credential=jwt
If the API Operator is not running or has persistent errors, investigate the operator deployment in the canvas namespace.
Step 4: Test the integration¶
Test with a valid JWT token (should return 200 OK):
# Get token via Client Credentials
$tokenResponse = Invoke-RestMethod -Uri "http://localhost:8083/auth/realms/odari/protocol/openid-connect/token" `
-Method POST -ContentType "application/x-www-form-urlencoded" `
-Body "grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>"
$jwt = $tokenResponse.access_token
# Call API with token (expect 200)
Invoke-RestMethod -Uri "https://localhost/<API_PATH>" `
-Headers @{Authorization="Bearer $jwt"} -SkipCertificateCheck
Test without a token (should return 401 Unauthorized):
try {
Invoke-RestMethod -Uri "https://localhost/<API_PATH>" -SkipCertificateCheck
} catch {
Write-Host "Status: $($_.Exception.Response.StatusCode) -- expected 401 Unauthorized"
}
Note on PowerShell versions: The -SkipCertificateCheck parameter requires PowerShell 7+ (pwsh). If using Windows PowerShell 5.1 (powershell.exe), use the SSL bypass workaround described in the Keycloak UI Access section.
Explaining the Bridge¶
After verifying the integration, explain:
Kong JWT plugin validates the token’s signature using the RSA public key and checks the
expclaimThe
issclaim in the Keycloak JWT matches thekeyin the KongConsumer’s JWT credential – this is how Kong finds the right public keyAny valid Keycloak JWT from the
odarirealm will be accepted, regardless of which Keycloak client issued itNo role-based authorization is enforced at the Kong level – Kong only verifies the token is valid and not expired
If the Keycloak RSA key is rotated, the Kong credential must be updated with the new public key
Generate a Postman Collection¶
When the user selects this option, generate a Postman collection file that includes requests to obtain a JWT token via Client Credentials flow and call the component’s ExposedAPI.
Interactive Workflow¶
Step 1: Identify the client and API
Ask which Keycloak client and ExposedAPI to use:
kubectl get exposedapis -n components -o yaml
Step 2: Gather parameters
Collect:
Keycloak URL (default:
http://localhost:8083/auth/realms/odari)Client ID (ask the user or list available clients)
Client Secret (retrieve using the helper script or ask the user)
API Base URL (from the ExposedAPI’s
.status.apiStatus.url)
Step 3: Generate the collection
python <scripts>/generate_postman_collection.py \
--keycloak-url "http://localhost:8083/auth/realms/odari" \
--client-id <CLIENT_ID> \
--client-secret <CLIENT_SECRET> \
--api-base-url <API_BASE_URL> \
--api-name "<API_NAME>" \
--output postman_collection.json
The script generates a Postman collection with:
Get JWT Token – POST to Keycloak token endpoint using Client Credentials grant. A test script automatically saves the
access_tokento a collection variable.List Resources – GET request to the API’s root resource. Uses the
{{access_token}}variable in theAuthorization: Bearerheader.Create Resource – POST request to create a new resource with a sample body.
Step 4: Import instructions
After generating, explain:
Import: File > Import > select the generated JSON file
SSL: Go to Settings > General > turn off “SSL certificate verification” (Kong uses a self-signed cert on localhost)
Run in order: Execute “Get JWT Token” first – the test script auto-saves the token. Then run the API requests.
Token refresh: The token expires after 300 seconds. Re-run the token request if you get a 401.
Collection Runner: Use Postman’s Collection Runner to execute all requests in sequence.
Contextual Next Steps¶
Present these options using ask_questions:
# |
Next Step |
|---|---|
1 |
View IdentityConfig resources – List and inspect identity configurations |
2 |
View Keycloak UI – Open the Keycloak admin console |
3 |
Add component roles – Define roles through the component (static or dynamic) |
4 |
Create a Keycloak client – Set up an external client for the Client Credentials flow |
5 |
Check Keycloak-Kong JWT integration – Verify token validation works end-to-end |
6 |
Generate a Postman collection – Create authenticated API test collection |
7 |
View ExposedAPIs – Check API access control settings (apiKeyVerification) |
8 |
View deployed components – See component status and security configuration |
9 |
Return to main menu |