Keycloak
Create a confidential OpenID Connect client in a Keycloak realm, add a Group Membership mapper, and connect it for single sign-on.
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.
Available on the Core, Optimize and Scale plans. Compare plans
Register the application
- In the realm, create a client of the OpenID Connect type.
- Turn on client authentication and the standard flow (authorization code).
- Add the valid redirect URI
https://app.costfluent.com/api/auth/sso/callback. - Copy the client ID, and the client secret from the client's credentials.
Your discovery URL is https://<keycloak-host>/realms/<realm>/.well-known/openid-configuration.
Send groups
- Open the client's dedicated client scope and add a mapper of the Group Membership type.
- Name its token claim
groupsand add it to the ID token. - Decide on the full group path. With it on, Keycloak sends
/engineering/platform; with it off,platform.
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.
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
- Open Settings, then Single sign-on, and connect your provider with the discovery URL, the client ID and the client secret.
- Add your email domains to the connection and verify each with its DNS TXT record.
- Map the groups to teams, then enable the connection.
Sign-in and 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, whateveremail_verifiedsays. 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.