Keycloak Setup

1. Create a Realm

Create a new realm called adsify (or use an existing one).

2. Create a Client

• Client ID: adsify-api
• Client Protocol: openid-connect
• Access Type: confidential (for machine clients) or public (for HMI apps with PKCE)
• Valid Redirect URIs: your HMI app URLs

3. Configure Client Scopes

Create custom scopes: ads:read, ads:write, ads:lifecycle

Assign them to the adsify-api client as optional scopes.

4. Create Roles

In the realm, create roles: viewer, operator, admin

5. Map Roles to Users

Assign realm roles to users or service accounts.

6. Configure Adsify

{
  "Authentication": {
    "Authority": "https://keycloak.example.com/realms/adsify",
    "Audience": "adsify-api",
    "RequireHttpsMetadata": true,
    "RoleClaimType": "realm_access.roles",
    "ValidIssuers": ["https://keycloak.example.com/realms/adsify"]
  }
}

Keycloak nests roles under realm_access.roles in the JWT. The RoleClaimTransformer handles this automatically.

7. Add plc_access claim (optional)

Use a Keycloak protocol mapper (User Attribute → Token Claim) to add a plc_access JSON array claim to tokens.