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 (required)¶

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

Not optional. A token with no plc_access claim reaches no PLC — every request answers 403 PLC_ACCESS_DENIED. Use ["*"] for a client that genuinely needs the whole fleet. See Authorization.