Skip to main content

Keycloak Integration Guide

Keycloak is an open-source identity and access management server. This guide connects Mixpost to a Keycloak realm for single sign-on.

note

The steps below use the Keycloak 19+ admin console. On legacy distributions (Keycloak 16 and older) the screens differ slightly and the issuer URL contains an extra /auth segment.

1. Create an OpenID Connect client​

  1. Sign in to the Keycloak admin console and select the realm your users live in (or create a dedicated realm).
  2. Go to Clients → Create client.
  3. Client type: OpenID Connect. Choose a Client ID (for example mixpost) and click Next.
  4. Turn Client authentication on (this makes it a confidential client) and keep Standard flow checked. Click Next, then Save.
  5. In the client's Settings tab, set Valid redirect URIs to the Redirect URI shown on Mixpost's Single Sign-On settings page, e.g. https://mixpost.example.com/mixpost/auth/sso/callback.
  6. Open the client's Credentials tab and copy the Client Secret.

2. Configure the connection in Mixpost​

In Admin Console → Settings → Single Sign-On:

  1. Identity provider: Keycloak.
  2. Issuer URL: https://<keycloak-host>/realms/<realm> — for example https://id.example.com/realms/acme. You can confirm it by opening Realm settings → General → Endpoints → OpenID Endpoint Configuration; the issuer field of that document is the value to use. (Legacy Keycloak ≤16 uses https://<host>/auth/realms/<realm>.)
  3. Paste the Client ID and Client Secret.
  4. Enable single sign-on, Save, then click Test connection — Mixpost should list the discovered endpoints.

Your login page now shows the Sign in with Keycloak button.

3. Send groups to Mixpost (optional)​

To use role mapping, Keycloak must include the user's groups in the tokens:

  1. Go to Clients → your client → Client scopes and open the dedicated scope (named <client-id>-dedicated).
  2. Click Add mapper → By configuration → Group Membership.
  3. Set the Token Claim Name to groups (matching Mixpost's Groups claim setting) and turn Full group path off.
  4. Save. Create your groups under Groups and assign users to them.

In Mixpost, add group mapping rows using the plain group names (for example marketing). Leading slashes in Keycloak group paths are handled automatically.

4. Done​

Sign in with a Keycloak user to verify the flow end to end. If something fails, the login page shows the reason, and the troubleshooting section covers the common causes.

On this page