# Keycloak

Costfluent signs your people in through a Keycloak realm over OpenID Connect. You create one client in the realm, and Costfluent trusts the addresses at the domains you verify.

## Before you start

- You need the Owner organization role in Costfluent, and administrator access to the Keycloak realm.
- Your Keycloak server is reachable from the internet over HTTPS, so Costfluent can read its discovery document and keys.
- Your people's addresses are at a domain you can publish a DNS TXT record for.

<PlanAvailability feature="Sso" plan="Core" />

## Register the application

<Stepper>

1. In the realm, create a client of the OpenID Connect type.
2. Turn on client authentication and the standard flow (authorization code).
3. Add the valid redirect URI `https://app.costfluent.com/api/auth/sso/callback`.
4. Copy the client ID, and the client secret from the client's credentials.

</Stepper>

Your discovery URL is `https://<keycloak-host>/realms/<realm>/.well-known/openid-configuration`.

## Send groups

<Stepper>

1. Open the client's dedicated client scope and add a mapper of the Group Membership type.
2. Name its token claim `groups` and add it to the ID token.
3. Decide on the full group path. With it on, Keycloak sends `/engineering/platform`; with it off, `platform`.

</Stepper>

The **Identity provider group** you map in Costfluent is the value exactly as the mapper sends it, with the leading slash when the full path is on.

:::note
Users imported into Keycloak often have their email marked as not verified. They still sign in, as long as their address is at a domain the connection verified.
:::

## Connect in Costfluent

<Stepper>

1. Open **Settings**, then **Single sign-on**, and connect your provider with the discovery URL, the client ID and the client secret.
2. Add your email domains to the connection and verify each with its DNS TXT record.
3. Map the groups to teams, then enable the connection.

</Stepper>

[Sign-in and security](/admin/sign-in-security) covers each of these steps, enforcement and break-glass Owners.

## How it behaves

Costfluent reads these claims from the ID token, and from the userinfo endpoint where the ID token leaves one out:

- `iss`, which must equal the issuer your discovery document named when you connected it, `https://<keycloak-host>/realms/<realm>`.
- `sub`, the Keycloak user ID, as the identity Costfluent keeps.
- `email`, which must be at one of the connection's verified domains, whatever `email_verified` says. An address outside every verified domain is refused, and so is a sign-in without an address.
- `name`, for the name of an account Costfluent creates.
- `groups`, or another claim name you set on the connection when your mapper uses a different one.

Costfluent also refuses a token whose signature, audience, nonce or lifetime does not check out, and a discovery document that starts naming another issuer.

## Related

- [Sign-in and security](/admin/sign-in-security)
- [Users, teams and roles](/admin/users-teams-and-roles)