Keycloak OIDC

Marmot supports Keycloak as an OIDC provider for Single Sign-On authentication.

Create a Keycloak client

1. Log in to your Keycloak Admin Console
2. Select the realm you want to use (or create a new one)
3. Navigate to Clients and click Create client
4. Configure the client:
   • Client type: OpenID Connect
   • Client ID: marmot (or your preferred ID)
5. On the next step, enable Client authentication (this makes it a confidential client)
6. Ensure Standard flow is checked
7. Click Save
8. Configure the following under Settings:
   • Valid redirect URIs: https://your-marmot-domain.com/auth/keycloak/callback
   • Web origins: https://your-marmot-domain.com
9. Click Save

After creating the client, note:

• Client ID: The client ID you chose
• Client Secret: Found on the Credentials tab
• Keycloak URL: Your Keycloak base URL (e.g., https://keycloak.example.com)
• Realm: The realm name (e.g., master or your custom realm)

Configure Marmot

You must set MARMOT_SERVER_ROOT_URL to the public URL of your Marmot instance. This is used to build OAuth callback URLs.

export MARMOT_SERVER_ROOT_URL="https://marmot.example.com"

Then set the following environment variables:

export MARMOT_AUTH_KEYCLOAK_ENABLED=true
export MARMOT_AUTH_KEYCLOAK_CLIENT_ID="marmot"
export MARMOT_AUTH_KEYCLOAK_CLIENT_SECRET="your-client-secret"
export MARMOT_AUTH_KEYCLOAK_URL="https://keycloak.example.com"
export MARMOT_AUTH_KEYCLOAK_REALM="your-realm"

Or configure via config.yaml:

auth:
  keycloak:
    enabled: true
    client_id: "marmot"
    client_secret: "your-client-secret"
    url: "https://keycloak.example.com"
    realm: "your-realm"

Marmot constructs the OIDC issuer URL automatically as {url}/realms/{realm} and uses OIDC discovery to configure endpoints.

Restart Marmot and the Keycloak sign-in button appears on the sign-in page.

Team sync

Marmot can automatically sync users to teams based on Keycloak group memberships.

Enable team sync:

auth:
  keycloak:
    team_sync:
      enabled: true
      strip_prefix: "/"
      group:
        claim: "groups"
        filter:
          mode: "regex"
          pattern: ".*"

Keycloak starts group names with /, such as /engineering. Set strip_prefix: "/" so the team is called engineering.

To include groups in the ID token:

1. In your Keycloak Admin Console, navigate to Clients and select your Marmot client
2. Go to the Client scopes tab
3. Click on the marmot-dedicated scope (or your client's dedicated scope)
4. Click Add mapper → By configuration
5. Select Group Membership
6. Configure the mapper:
   • Name: groups
   • Token Claim Name: groups
   • Full group path: Off (recommended to get simple group names)
   • Add to ID token: On
   • Add to access token: On
   • Add to userinfo: On
7. Click Save

Custom TLS configuration

If your Keycloak instance uses a self-signed certificate or a certificate signed by an internal CA, you can configure Marmot to trust it:

auth:
  keycloak:
    enabled: true
    client_id: "marmot"
    client_secret: "your-client-secret"
    url: "https://keycloak.internal"
    realm: "your-realm"
    tls:
      ca_cert_path: "/etc/ssl/certs/internal-ca.pem"

Or via environment variables:

export MARMOT_AUTH_KEYCLOAK_TLS_CA_CERT_PATH="/etc/ssl/certs/internal-ca.pem"

To skip TLS verification entirely (not recommended for production):

export MARMOT_AUTH_KEYCLOAK_TLS_INSECURE_SKIP_VERIFY=true

If your Keycloak instance requires mutual TLS (mTLS), you can provide a client certificate and key:

auth:
  keycloak:
    tls:
      ca_cert_path: "/etc/ssl/certs/internal-ca.pem"
      cert_path: "/etc/ssl/certs/client.pem"
      key_path: "/etc/ssl/private/client-key.pem"

Field	Description
tls.ca_cert_path	Path to a PEM-encoded CA certificate to trust
tls.cert_path	Path to a PEM-encoded client certificate for mTLS
tls.key_path	Path to the client certificate's private key
tls.insecure_skip_verify	Skip TLS certificate verification (default: false)