This page describes how to configure Stronghold login through Keycloak using OIDC. For general information about the method, see OIDC auth method.

Keycloak client setup

  1. Select or create a Realm and a Client. Open the client Settings.

  2. Client Protocol: openid-connect.

  3. Access Type: confidential. In newer Keycloak versions, enable Client authentication.

  4. Enable Standard Flow Enabled.

  5. Set Valid Redirect URIs:

    https://stronghold.example.com/ui/stronghold/auth/oidc/oidc/callback
http://localhost:8250/oidc/callback

    The first URI is used for web interface login, the second one for CLI login. If the method is enabled at a different path, replace oidc in the first URI with that path.

  6. Click Save.

  7. Open the Credentials tab and note the Client ID and Client Secret.

  8. To make Keycloak pass user groups, add a Group Membership mapper with the groups claim name to the client (or its client scope). Disable Full group path if Stronghold needs group names without a path.

Stronghold setup

  1. Enable the OIDC auth method:

    d8 stronghold auth enable oidc

    By default, the method is enabled at auth/oidc/. To use a different path, specify -path.

  2. Configure the connection to Keycloak. Set oidc_discovery_url to the Realm address without /.well-known/openid-configuration:

    d8 stronghold write auth/oidc/config oidc_discovery_url="https://keycloak.example.com/realms/myrealm" oidc_client_id="<Client ID>" oidc_client_secret="<Client Secret>" default_role="keycloak"

    In older Keycloak versions, the Realm address contains the /auth prefix, for example https://keycloak.example.com/auth/realms/myrealm.

  3. Create a role. In allowed_redirect_uris, list the same URIs as in the Keycloak client:

    d8 stronghold write auth/oidc/role/keycloak -<<EOF
{
  "role_type": "oidc",
  "allowed_redirect_uris": [
    "https://stronghold.example.com/ui/stronghold/auth/oidc/oidc/callback",
    "http://localhost:8250/oidc/callback"
  ],
  "oidc_scopes": ["openid", "profile", "email"],
  "user_claim": "preferred_username",
  "groups_claim": "groups",
  "bound_claims": { "groups": ["stronghold-users", "stronghold-admins"] },
  "token_policies": ["default"],
  "token_ttl": "1h"
}
EOF

    Key role parameters:

    ParameterDescription
    allowed_redirect_urisAllowed redirect URIs. They must exactly match the URIs in Keycloak.
    user_claimClaim whose value becomes the entity alias name, for example preferred_username or sub.
    groups_claimClaim with the list of user groups (groups from the Group Membership mapper).
    bound_claimsClaims and values that must match for login to succeed. In the example, only members of the stronghold-users or stronghold-admins groups can log in.
    oidc_scopesRequested OIDC scopes.
    token_policies, token_ttlPolicies and TTL of the issued token.

Mapping Keycloak groups to Stronghold groups

To assign policies based on Keycloak group membership, create external Identity groups and group aliases. For more on external groups, see Identity.

  1. Create an external group with the required policies and save its ID:

    d8 stronghold write -field=id identity/group name="keycloak-admins" type="external" policies="admin"

  2. Get the accessor of the oidc/ auth method:

    d8 stronghold auth list -format=json | jq -r '."oidc/".accessor'

  3. Create a group alias. The name value must match the group name in the groups claim:

    d8 stronghold write identity/group-alias name="stronghold-admins" mount_accessor="<OIDC_ACCESSOR>" canonical_id="<GROUP_ID>"

    Where <OIDC_ACCESSOR> is the accessor from the previous step, and <GROUP_ID> is the ID of the external group created in the first step.

On every login and token renewal, Stronghold updates the entity’s external group membership based on Keycloak data.

Verifying login

  1. Log in via the CLI:

    d8 stronghold login -method=oidc -path=oidc role=keycloak

    The CLI opens a browser for Keycloak login and receives the response at http://localhost:8250/oidc/callback.

  2. Check the policies and metadata of the issued token:

    d8 stronghold token lookup

  3. To verify web interface login, select the OIDC method, specify the keycloak role if needed, and complete the Keycloak login.

If login fails, check that the redirect URIs match and see the troubleshooting tips in OIDC auth method.

Additional resources

←
OIDC / Gitlab
OIDC / Kubernetes
→