From 51a72b777f17b8eec362b0bf78eb290f2c017bad Mon Sep 17 00:00:00 2001 From: Anthony Lukach Date: Wed, 30 Oct 2024 14:59:38 -0700 Subject: [PATCH] Document add clients, scopes, roles, groups --- README.md | 119 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 119 insertions(+) diff --git a/README.md b/README.md index a5c6fa4..eca50f5 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,125 @@ Configuration is stored within `config/src` in YAML files for each Keycloak real > [!IMPORTANT] > At each deployment, the keycloak-config-cli will likely overwrite changes made outside of the configuration stored within this repository for a given realm. +#### Creating Clients + +Creating a client application within Keycloak is done by editing the config YAML for the realm. + +##### Public Client + +A minimum example of a public client (ie a client that only runs within the frontend, such as single page application): + +```yaml +clients: + - clientId: grafana + name: Grafana + publicClient: true + rootUrl: https://example.com + redirectUris: + - https://example.com/* + webOrigins: + - https://example.com + protocol: openid-connect + fullScopeAllowed: true +``` + +##### Private Client + +For a private client (ie a client that runs within the frontend, such as single page application), a secret will automatically be created and injected into the configuration runtime environemt at time of deployment. This secret will be made avaiable at an environment variable of `$SLUG_CLIENT_SECRET` where `$SLUG` represents a slugify version of the `clientId` value (e.g. a client with an id of `stac-api` will have a secret available at `STAC_API_CLIENT_SECRET`). + +A minimum example of a private client (note `publicClient: false` and `secret`): + +```yaml +clients: + - clientId: grafana + name: Grafana + publicClient: false + secret: $(env:GRAFANA_CLIENT_SECRET) + rootUrl: https://example.com + redirectUris: + - https://example.com/* + webOrigins: + - https://example.com + protocol: openid-connect + fullScopeAllowed: true +``` + +##### Scopes, Roles, and Groups + +Clients will typically have associated Scopes, Roles, and Groups. + +- Scopes can be thought of as individual permissions used by a client. +- Roles are collections of permissions that enable a typical function (e.g. system administration) +- Groups are collections of users that we want to grant with roles. + +An exmaple: + +```yaml +clients: + - clientId: grafana + # ... omitted for brevity + fullScopeAllowed: true + defaultClientScopes: + - web-origins + - acr + - profile + - roles + - basic + - email + - grafana:admin + - grafana:editor + - grafana:viewer + +roles: + client: + grafana: + - name: Administrator + description: Grafana Administrator + - name: Editor + description: Grafana Editor + - name: Viewer + description: Grafana Viewer + +clientScopeMappings: + grafana: + - clientScope: grafana:admin + roles: + - Administrator + - clientScope: grafana:editor + roles: + - Editor + - clientScope: grafana:viewer + roles: + - Viewer + +clientScopes: + - name: grafana:admin + description: Admin access to Grafana + protocol: openid-connect + - name: grafana:editor + description: Editor access to Grafana + protocol: openid-connect + - name: grafana:viewer + description: Viewer access to Grafana + protocol: openid-connect + +groups: + - name: System Administrators + clientRoles: + grafana: + - Administrator + + - name: Developers + clientRoles: + grafana: + - Editor + + - name: Data Editors + clientRoles: + grafana: + - Viewer +``` + #### Identity Provider OAuth Clients When a third party service operates as an Identity Provider (IdP, e.g. CILogon or GitHub) for Keycloak, we must register that IdP within the Keycloak configuration. This involves registering the IdP's OAuth client ID and client secret within Keycloak's configuration (along with additional information about the OAuth endpoints used within the login process).