Set up SSO with Keycloak

Part of Single sign-on (SSO) for your workspace: step 2 of 3, on Keycloak.

Keycloak speaks both protocols Tinct accepts. Choose OpenID Connect unless your organisation has standardised on SAML: it takes fewer steps and nothing to keep in sync afterwards.

You must be an admin of the workspace, and the workspace must be entitled to single sign-on. The screens below are those of Keycloak 26.

Before you start

• Verify at least one email domain: Verify your email domain. You can describe the connection first, but you cannot enable it until a domain is verified.
• Have an administrator account on the realm your people sign in to, and a user of that realm whose email address is on a verified domain, to run the test sign-in with.
• Know your realm's address, https://<your Keycloak host>/realms/<realm>. On Keycloak 16 and older it has /auth in front: https://<host>/auth/realms/<realm>. Tinct reads from it over the internet, so it must be an https address that Tinct can reach.

Option A: OpenID Connect

1. Create the client

1. In the Keycloak admin console, pick your realm, then go to Clients → Create client.
2. Client type: OpenID Connect. Client ID: a name of your choice, for example tinct. Name: Tinct. Click Next.
3. Turn Client authentication on. Under Authentication flow, keep Standard flow only. Click Next.
4. Leave the login settings empty for now: Tinct gives you the redirect URI in step 3. Click Save.
5. In the Credentials tab, copy the Client secret.

2. Describe Keycloak in Tinct

1. In Tinct, go to Settings → Security, to the Identity provider card, and keep OpenID Connect.
2. Fill in:
   • Issuer: your realm's address, https://<your Keycloak host>/realms/<realm>
   • Client ID: the client ID from step 1
   • Client secret: the secret you copied
3. Click Save identity provider.

3. Register the redirect URI

1. Copy the Redirect URI the card now shows.
2. In Keycloak, open the client, and in the Settings tab paste it into Valid redirect URIs. Click Save.

Keycloak releases the profile and email scopes to a new client by default: the Client scopes tab lists both as Default. Leave them there.

Then go to Test, then enable.

Option B: SAML 2.0

1. Get Tinct's metadata

1. In Tinct, go to Settings → Security, to the Identity provider card.
2. Under Protocol, choose SAML 2.0. If no connection exists yet, click Get the values for my provider.
3. Next to Service provider metadata, click Download.

2. Import it as a client

1. In the Keycloak admin console, pick your realm, then go to Clients → Import client.
2. Under Resource file, pick the metadata file you downloaded. Keycloak fills in the client from it:
   • the Client ID is Tinct's entity ID, a long address ending in sso-<an identifier>. Leave it as it is: see the warning below;
   • Valid redirect URIs and the Assertion Consumer Service POST Binding URL are Tinct's single sign-on URL (ACS);
   • under Keys, Client signature required is on, with Tinct's signing certificate, and the assertions are encrypted for Tinct. Keycloak's default algorithms (RSA-OAEP and AES-128-CBC) are the ones Tinct accepts: leave them as they are.
3. Click Save.

⚠️ On a SAML client, the Client ID must be Tinct's entity ID, character for character. It is not a name you choose: Tinct sends it in every request, and Keycloak answers Invalid requester when no client carries it. Put a readable name in Name instead.

If you cannot upload a file, create the client by hand instead: Clients → Create client, Client type SAML, Client ID Tinct's Service provider entity ID, Valid redirect URIs Tinct's Single sign-on URL (ACS). Then, in the Keys tab, turn Client signature required on and import our signing certificate as a PEM certificate, and in the Advanced tab paste the ACS into Assertion Consumer Service POST Binding URL.

⚠️ Turning Client signature required on makes Keycloak generate a key pair of its own for the client, whose certificate is named after the Client ID. Keycloak checks Tinct's requests against that certificate until you replace it: click Import key and paste our signing certificate. The certificate shown in the Keys tab must then be Tinct's.

3. Send a persistent NameID

In the client's Settings tab, under SAML capabilities:

• Name ID format: persistent
• Force name ID format: on

Keycloak then gives each person an identifier of their own for Tinct, which does not change when their username or email address does. Click Save.

Leave the Signature and encryption section as the import set it: Sign documents on, with RSA_SHA256.

4. Add the email and the names

Keycloak sends no attribute to a new SAML client. Go to the client's Client scopes tab, open the scope ending in -dedicated, click Configure a new mapper (or Add mapper → By configuration), choose User Property, and create these three:

5. Describe Keycloak in Tinct

1. Back in Tinct, under Values from your identity provider, choose Metadata URL.
2. Paste your realm's SAML metadata address, https://<your Keycloak host>/realms/<realm>/protocol/saml/descriptor. Keycloak also shows it in Realm settings → General → Endpoints → SAML 2.0 Identity Provider Metadata.
3. Click Save identity provider. Tinct reads Keycloak's entity ID, sign-on URL and signing certificate from it.

Leave Attribute names empty: email, firstName and lastName are among the names Tinct looks for.

Test, then enable

1. In the Status card, click Test sign-in. A pop-up opens on Keycloak's sign-in page.
2. Sign in as a user of the realm whose email address is on one of your verified domains.
3. The result page shows the email address and the names Tinct received.
4. Back on the Security page, click Enable.

Every user of the realm can sign in to a Keycloak client. Tinct still only lets in addresses on your verified domains, and, when Create accounts at first sign-in is off, only people you invited.

When you are confident, go on to Require SSO in your workspace.

If something goes wrong

• Keycloak shows Invalid requester (SAML). Either the client's Client ID is not exactly Tinct's entity ID, or the certificate under Keys is not Tinct's signing certificate. The second is the usual one on a client created by hand: Keycloak generated a certificate of its own (see step 2). Keycloak's server log tells them apart: invalid_signature for the certificate. Importing the metadata again gets both right.
• Keycloak shows Invalid parameter: redirect_uri (OpenID Connect). Valid redirect URIs does not hold Tinct's Redirect URI exactly.
• Tinct says no email address was sent. On SAML, the email mapper is missing (step 4). On either protocol, check that the user has an email address in Keycloak.
• Tinct says the address is not on a verified domain. The user's email address in Keycloak is on another domain: verify that domain, or test with another user.
• Tinct says the issuer or the metadata could not be read. The realm's address must be https and reachable from the internet, with /auth in front on Keycloak 16 and older.
• The assertion is refused as expired or not yet valid. Keycloak's clock is more than three minutes off: keep its server synchronised.

When Keycloak's keys change

Keycloak signs with the realm's keys (Realm settings → Keys).

• OpenID Connect: nothing to do. Tinct reads the current keys from Keycloak.
• SAML: Tinct re-reads the metadata address daily and never applies new certificates on its own. When Keycloak's change, your admins get an email and the Signing certificates card offers to apply them. Add the new key alongside the old one in Keycloak, apply it in Tinct, and only then retire the old key: see Rotate without downtime.