Connect Keycloak

Keycloak is the one provider we have tested ourselves: Keycloak 26.4, connected through OpenID Connect, on a test installation. What we tested is listed below. These are the steps as Tamaat presents them, with Keycloak's names beside them.

Before you begin

• You are an Admin of the Tamaat organization, on the Professional plan or above.
• You can create a client in the Keycloak realm your people sign in to.
• Your Keycloak answers at an https address that Tamaat can reach.
• The people who will sign in have an email address in Keycloak, and it matches the address they are invited to Tamaat with.

1. Create the client in Keycloak

In your realm, create a client for Tamaat with these settings:

Keycloak setting	Value
Client type	OpenID Connect
Client ID	A name of your choice, such as tamaat
Client authentication	On
Standard flow	On
Valid redirect URIs	Leave for now. Tamaat gives you the address in step 3.

Save the client, then copy its client secret from the client's credentials.

2. Add the connection in Tamaat

1. 1

   Open Settings and choose Organization → Single sign-on. Under Connection, choose "Add connection".

2. 2

   Under "Identity provider", choose Keycloak.

3. 3

   Under "From Keycloak", fill in:

   • "Connection name": what your people will see when they sign in, such as your company's name.
   • "Issuer": your realm's address, in the form https://{host}/realms/{realm}. Copy it from Keycloak rather than typing it; it must match exactly.
   • "Client ID": the client ID you chose in step 1.
   • "Client secret": the secret you copied in step 1.
4. 4

   Choose "Save". The form says "Saved." and shows a new step, "Copy into Keycloak".

3. Copy the redirect address into Keycloak

"Copy into Keycloak" shows two values, each with a "Copy" button:

• "Redirect URI": paste it into Valid redirect URIs on the Keycloak client, and save the client.
• "Sign-in address": the address that starts a sign-in through this connection. Keep it to hand out as a bookmark.

4. Test and enable

1. 1

   In Tamaat, choose "Save and test". You are sent to your Keycloak sign-in page.

2. 2

   Sign in as any person in the realm. You come back to the result. "The test did not sign anyone in."

3. 3

   On "Passed", check the lines: "Permanent ID received", "Email received" and "Sign-in time received" should all be present.

4. 4

   Choose "Enable connection". The connection reads "Active".

5. 5

   Under Sign-in policy, choose "Optional": "Password or single sign-on".

Your people can now sign in through Keycloak. Passwords still work.

Email addresses

Tamaat accepts an email address from Keycloak without a further check only when Keycloak marks it as verified. We have not tested each of these cases on Keycloak ourselves. The test result tells you which case you are in:

Test result	What a new person meets
"Email: confirmed by your provider"	They are let in directly.
"Email: people confirm with a code the first time"	They type a code that Tamaat emails them, once.
"The identity provider says this person’s email address is not verified. Verify it at your provider, then ask them to sign in again."	They are not let in until the address is verified in Keycloak.

Groups (optional)

Set this up only if you want to open a published map or dashboard to chosen Keycloak groups. Groups never set a role in Tamaat. We have not tested groups on Keycloak ourselves; the connection test shows whether they arrive.

1. In Keycloak, add a Group Membership mapper to the client. Set Token Claim Name to groups, turn Full group path off and Add to ID token on.
2. In Tamaat, choose "Edit" on the connection. Enter groups under "Where your provider lists groups" and leave "Groups are sent as" on "Names".
3. Choose "Save and test", sign in as someone who is in a group, and look for "Groups: received" with the number of groups.
4. Choose "Enable connection" again so the new version is the one in use.

Keycloak sends group names, and names can be changed. When you narrow a published map or dashboard by name, Tamaat reminds you: "Group names can be changed at your provider. Anyone who can create a group with this name there can open this."

What we tested

On Keycloak 26.4, on a test installation, we tested: adding, testing and enabling a connection; signing in with the policy on Optional; linking an existing Tamaat account; refusing a person who had not been invited; requiring single sign-on with a recovery person; and refusing a password once it was required.

If the test fails

The result shows one sentence that says what to change. The ones met most often with Keycloak:

Sentence	Check
"The identity provider refused our request. Check the client ID, the client secret and the redirect URI."	The Redirect URI is in Valid redirect URIs, and the client ID and secret are the ones on this client.
"The provider’s discovery document names a different issuer. Check the issuer address."	The "Issuer" is your realm's address exactly, with the same host your people use.
"The identity provider could not be reached. Check the issuer address, then try again."	Your Keycloak answers at that address from outside your network.

Troubleshoot Single Sign-On lists every sentence.

Next steps

1. Show members how to sign in
2. Require single sign-on
3. Open a map or dashboard to your company