Skip to content

Getting Started

SuperSaaS Auth Connector bridges Keycloak OIDC authentication with SuperSaaS user management. This guide walks you through deploying the connector for the first time.

Prerequisites

Requirement Notes
Container runtime Docker, Podman, or any OCI-compatible runtime
Keycloak ≥ 26 A public OIDC client configured (see Keycloak Setup)
SuperSaaS account An API token with permission to create users

Quick Start

Pull and run the latest image:

podman run --rm \
  -e SSO_SERVER_URL=https://sso.example.com/auth/ \
  -e SSO_REALM=myrealm \
  -e SSO_CLIENT_ID=supersaas-auth-connector \
  -e SUPERSAAS_ACCOUNT_NAME=myaccount \
  -e SUPERSAAS_API_TOKEN=mysecrettoken \
  -e URL=https://auth.example.com \
  -e SECRET_KEY=$(openssl rand -hex 32) \
  -p 8000:8000 \
  ghcr.io/radiorabe/supersaasauthconnector:latest

The service listens on port 8000 by default. Point your Keycloak client's redirect URI to https://auth.example.com/oidc/callback.

Keycloak Setup

  1. Create a new public client (no client secret required).
  2. Set the Valid Redirect URIs to https://auth.example.com/oidc/callback.
  3. Add a Protocol Mapper to the client (or the realm's user profile) that maps the internal Keycloak user attribute uid to the uid token claim:
  4. Mapper type: User Attribute
  5. User Attribute: uid (or the LDAP/federated attribute name you use)
  6. Token Claim Name: uid
  7. Claim JSON Type: String
  8. Add to userinfo: ✅ enabled

Tip

The uid claim is used as the SuperSaaS user identifier (suffixed with fk). Map it to a stable, unique attribute in Keycloak — for example the internal Keycloak user UUID or an LDAP uidNumber.

Compose Example

compose.yaml
services:
  supersaas-auth-connector:
    image: ghcr.io/radiorabe/supersaasauthconnector:latest
    restart: unless-stopped
    environment:
      SSO_SERVER_URL: https://sso.example.com/auth/
      SSO_REALM: myrealm
      SSO_CLIENT_ID: supersaas-auth-connector
      SUPERSAAS_ACCOUNT_NAME: myaccount
      SUPERSAAS_API_TOKEN: ${SUPERSAAS_API_TOKEN}
      URL: https://auth.example.com
      SECRET_KEY: ${SECRET_KEY}
      ERROR_REDIRECT_URL: https://www.example.com
      LOGOUT_REDIRECT_URL: >-
        https://sso.example.com/auth/realms/myrealm/protocol/openid-connect/logout
        ?redirect_uri=https%3A%2F%2Fwww.example.com
    ports:
      - "8000:8000"

Store SUPERSAAS_API_TOKEN and SECRET_KEY in a .env file or your secrets manager — never commit them to source control.

Next Steps