Skip to content

OAuth / OIDC Single Sign-On

PuppyGraph supports single sign-on (SSO) through any OpenID Connect (OIDC) identity provider (IdP), including Okta, Auth0, Google Workspace, Azure AD / Microsoft Entra ID, and Keycloak. With SSO enabled, users authenticate against your IdP and their PuppyGraph role can be assigned automatically from IdP groups (see Role-Based Access Control).

The login flow is the standard OIDC Authorization Code flow with PKCE: PuppyGraph redirects the browser to your IdP, exchanges the returned authorization code for an ID token, and verifies the token's signature, issuer, audience, and nonce. The configured SSO_CLAIM_AS_USER_ID claim becomes the user's identity (prefixed sso:); the configured groups claim drives RBAC role assignment.

Want a runnable demo first?

Two step-by-step tutorials walk through the flow against a local Keycloak so you can try it without a production identity provider:

The rest of this page is the configuration reference you'll need when wiring your own IdP.

Configuration

Set the following environment variables on the control plane (the node started with CONTROLPLANE=true, or the controlplane service in a multi-service compose file). SSO request handling lives only on the control plane. Leader and compute nodes do not need the SSO_* variables, but they still need the cluster-wide auth settings (RBAC_ENABLED, GREMLINSERVER_AUTHENTICATION_ENABLED, BOLTSERVER_AUTHENTICATION_ENABLED, AUTHENTICATION_JWT_SECRETKEY) so JWTs minted by the control plane validate on the query path.

Required variables

Variable Description
SSO_ENABLED Set to true to turn SSO on.
SSO_CLIENT_ID Client ID issued by your IdP.
SSO_CLIENT_SECRET Client secret issued by your IdP. Treat as a secret.
SSO_ISSUER The IdP's issuer URL (e.g. https://your-tenant.okta.com/oauth2/default). Used to verify the ID token's iss claim.
SSO_CALLBACK_URL The publicly reachable callback URL, e.g. https://puppy.example.com/sso_callback. Must exactly match the redirect URI registered with the IdP.

When registering PuppyGraph in your IdP, set the redirect URI to <your-puppygraph-base-url>/sso_callback, allow the authorization_code grant, and authorize the openid, profile, and email scopes (plus your provider's groups scope if you plan to use group mapping).

Endpoint configuration

PuppyGraph does not auto-discover endpoints from the OIDC discovery document. There are exactly two ways for PuppyGraph to know where the authorization and token endpoints are:

  1. Okta-style fallback. If SSO_URL and SSO_ACCESS_TOKEN_URL are unset, PuppyGraph constructs them from SSO_ISSUER using Okta's path convention:
  2. Authorization endpoint: <SSO_ISSUER>/v1/authorize
  3. Token endpoint: <SSO_ISSUER>/v1/token

This fallback works for Okta and other providers that happen to follow the same URL shape. It does not work for Auth0, Google, Azure AD, Keycloak, etc.

  1. Explicit URLs. For every other provider, set the endpoint URLs explicitly:
Variable Description
SSO_URL Authorization endpoint URL (where the browser is redirected to log in).
SSO_ACCESS_TOKEN_URL Token endpoint URL (used server-to-server to exchange the authorization code).
SSO_USERINFO_URL Userinfo endpoint URL. Optional; consulted only when SSO_CLAIM_AS_USER_ID is missing from the ID token. Other claims (including the groups claim used for role mapping) are read from the ID token, never from userinfo.
SSO_JWKS_URL JWKS endpoint URL for ID token signature verification. If unset, PuppyGraph falls back to the default Okta-style verifier driven by SSO_ISSUER and SSO_CLIENT_ID.

Look these URLs up in your IdP's admin console or its <issuer>/.well-known/openid-configuration document.

Optional variables

Variable Default Description
SSO_SCOPE openid profile email Space-separated OAuth scopes. Add your provider's groups scope (e.g. openid profile email groups) if you use group mapping.
SSO_CLAIM_AS_USER_ID email JWT claim that becomes the PuppyGraph user identifier. Typical values: email, preferred_username, sub.
SSO_GROUPS_CLAIM groups JWT claim containing the user's group memberships. Used for group-based role mapping.
SSO_SESSION_NAME sso_session Cookie name for the SSO session.
SSO_RESPONSE_TYPE code OIDC response type. Only code is supported.
SSO_HTTP_TIMEOUT 10s Timeout for outbound HTTP calls to the IdP.
SSO_JWKS_FETCH_TIMEOUT 10s Timeout for fetching the JWKS document.
SSO_JWKS_CACHE_TTL 5m How long PuppyGraph caches the JWKS document.

Provider recipes

The values below are templates; substitute your tenant ID, domain, and client credentials. For Keycloak, the Setting Up SSO with Keycloak tutorial is a fully worked example.

Okta

SSO_ENABLED=true
SSO_CLIENT_ID=0oa...example
SSO_CLIENT_SECRET=...
SSO_ISSUER=https://your-tenant.okta.com/oauth2/default
SSO_CALLBACK_URL=https://puppy.example.com/sso_callback
SSO_SCOPE="openid profile email groups"
SSO_CLAIM_AS_USER_ID=email
SSO_GROUPS_CLAIM=groups

Add a Groups claim to the Okta authorization server so the groups claim is included in the ID token. Endpoints are derived from the issuer automatically.

Auth0

SSO_ENABLED=true
SSO_CLIENT_ID=...
SSO_CLIENT_SECRET=...
SSO_ISSUER=https://your-tenant.auth0.com/
SSO_URL=https://your-tenant.auth0.com/authorize
SSO_ACCESS_TOKEN_URL=https://your-tenant.auth0.com/oauth/token
SSO_JWKS_URL=https://your-tenant.auth0.com/.well-known/jwks.json
SSO_CALLBACK_URL=https://puppy.example.com/sso_callback
SSO_CLAIM_AS_USER_ID=email

Auth0 does not include groups on the ID token by default. Add an Action or Rule that copies app_metadata.groups (or your custom claim) onto the ID token under the claim name you set in SSO_GROUPS_CLAIM.

Google Workspace

SSO_ENABLED=true
SSO_CLIENT_ID=...apps.googleusercontent.com
SSO_CLIENT_SECRET=...
SSO_ISSUER=https://accounts.google.com
SSO_URL=https://accounts.google.com/o/oauth2/v2/auth
SSO_ACCESS_TOKEN_URL=https://oauth2.googleapis.com/token
SSO_JWKS_URL=https://www.googleapis.com/oauth2/v3/certs
SSO_CALLBACK_URL=https://puppy.example.com/sso_callback
SSO_CLAIM_AS_USER_ID=email

Google does not emit a groups claim on the ID token. Use explicit role assignment per user in Settings → Users, or proxy groups through a custom claim provider.

Azure AD / Microsoft Entra ID

SSO_ENABLED=true
SSO_CLIENT_ID=...
SSO_CLIENT_SECRET=...
SSO_ISSUER=https://login.microsoftonline.com/<tenant-id>/v2.0
SSO_URL=https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize
SSO_ACCESS_TOKEN_URL=https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
SSO_JWKS_URL=https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys
SSO_CALLBACK_URL=https://puppy.example.com/sso_callback
SSO_CLAIM_AS_USER_ID=preferred_username
SSO_GROUPS_CLAIM=groups

In the Azure AD application registration, configure the optional groups claim under Token configuration so group object IDs (or names) appear on the ID token.

Relationship to RBAC

SSO governs authentication (who you are). Role-Based Access Control governs authorization (what you can do). After a successful SSO login, the user's role is determined in this order:

  1. Explicit role assignment by an admin in Settings → Users.
  2. Group mapping based on the IdP's groups claim (see Configuring SSO group mappings).
  3. Default role from RBAC_DEFAULT_ROLE (defaults to Analyst).

SSO users always appear in the Users tab with a sso: prefix on their internal identifier so they cannot collide with local users.

Trusting a private or self-signed certificate

PuppyGraph fetches your identity provider's signing keys (the JWKS document) over HTTPS and verifies the provider's certificate against its trust store. This covers SSO_JWKS_URL and the jwksUrl of every trusted issuer used for bearer-token login. If the provider's certificate is signed by a private CA, or is self-signed, add that certificate to PuppyGraph's trust store. Do not turn off certificate verification. Use CERTIFICATE_BASEPATH as described below. With the Helm chart in cluster mode, also see Helm chart in cluster mode for the versions this needs.

  1. Save the CA certificate in PEM format as a file ending in .crt, for example keycloak.crt. For a self-signed certificate, save the certificate itself. PuppyGraph reads only .crt files: a .pem file or any other name is skipped, with a Skip file warning in the log.
  2. Mount the directory that holds it and set CERTIFICATE_BASEPATH to that directory. At startup, PuppyGraph adds every .crt file there to its trust store, alongside the public CAs it already trusts. It reads the directory only at startup, so restart PuppyGraph after adding or changing a certificate.

With Docker:

docker run ... \
  -v ./certs:/home/ubuntu/tls-certs \
  -e CERTIFICATE_BASEPATH=/home/ubuntu/tls-certs \
  puppygraph/puppygraph:<version>

With the Helm chart in single-node mode, add the certificate to the chart's configuration files, which are mounted at /etc/config/puppygraph, and point CERTIFICATE_BASEPATH there. In your values file:

env:
  singleNode:
    CERTIFICATE_BASEPATH: /etc/config/puppygraph

Then pass the certificate on this and every later helm upgrade:

helm upgrade $RELEASE_NAME puppygraph/puppygraph -n $NAMESPACE -f values.yaml \
  --set-file 'config.files.keycloak\.crt'=./keycloak.crt

If the upgrade changes nothing but the certificate, Helm does not restart the pod, and the certificate is not loaded. Restart it yourself (kubectl get statefulsets -n $NAMESPACE lists the name):

kubectl rollout restart statefulset -n $NAMESPACE <single-node-statefulset>

The startup log then shows Skip file: ..data and similar warnings for the mount's internal entries. They are harmless.

The certificate must also be valid for the hostname in the JWKS URL.

Helm chart in cluster mode

In cluster mode, the controlplane pod fetches the signing keys. With chart version 1.2.0 or later and PuppyGraph 1.18.0 or later, the steps are the same as in single-node mode, with CERTIFICATE_BASEPATH set for the controlplane. In your values file:

env:
  controlplane:
    CERTIFICATE_BASEPATH: /etc/config/puppygraph

Then pass the certificate with --set-file 'config.files.keycloak\.crt'=./keycloak.crt on this and every later helm upgrade, as in single-node mode. If the upgrade changes nothing but the certificate, restart the controlplane yourself (kubectl get statefulsets -n $NAMESPACE lists the name):

kubectl rollout restart statefulset -n $NAMESPACE <controlplane-statefulset>

Earlier chart or PuppyGraph versions

Earlier chart versions do not mount the configuration files on the controlplane pod, and before 1.18.0 the controlplane does not install certificates from CERTIFICATE_BASEPATH. Instead, mount the certificate on the controlplane pod and point SSL_CERT_DIR at its directory. The public CAs the pod already trusts are still trusted. These steps keep working after you upgrade the chart.

  1. Create a ConfigMap holding the certificate in PEM format, in the release's namespace:

    kubectl create configmap idp-ca -n $NAMESPACE --from-file=keycloak.crt=./keycloak.crt
    
  2. Add the following to your values file, then run helm upgrade:

    env:
      controlplane:
        SSL_CERT_DIR: /etc/puppygraph-ca
    controlplane:
      extraPodSpec:
        volumes:
          - name: idp-ca
            configMap:
              name: idp-ca
      extraContainerSpec:
        volumeMounts:
          - name: data
            mountPath: /data
          - name: idp-ca
            mountPath: /etc/puppygraph-ca
            readOnly: true
    

    Keep the data entry. The chart's own /data mount is replaced by the volumeMounts list you set here, and without it the controlplane loses its stored configuration when the pod restarts.

The upgrade that adds these values restarts the controlplane pod. The certificate is read only at startup, so if you later change the ConfigMap, restart the controlplane as shown above.

Troubleshooting

Symptom Likely cause What to check
Browser shows redirect_uri_mismatch The IdP's registered redirect URI does not match SSO_CALLBACK_URL exactly. Confirm the scheme, host, port, and path match. The path must be /sso_callback.
SSO authorization endpoint is not configured error SSO_ISSUER is empty and SSO_URL is not set. Set SSO_ISSUER for issuers with the Okta URL convention, or set SSO_URL explicitly.
invalid issuer: … after IdP redirect The iss claim in the ID token does not match SSO_ISSUER. Inspect the ID token at the IdP and copy the exact issuer value (trailing slash matters for some providers).
Token verification fails Signing key cannot be found. Set SSO_JWKS_URL to your IdP's JWKS endpoint. Confirm the JWKS document is reachable from PuppyGraph.
Bolt or Gremlin bearer-token login fails, and with AUTHENTICATION_JWT_DIAGNOSTICS_ENABLED=true the log shows JWT exchange rejected ... reason=jwks_tls_untrusted PuppyGraph does not trust the certificate of the trusted issuer's JWKS endpoint, typically a private CA or self-signed certificate. Add the certificate to PuppyGraph's trust store. See Trusting a private or self-signed certificate.
Users log in but always get the default role Groups claim missing from the ID token or under a different name. PuppyGraph reads groups from the ID token claims (not from the userinfo endpoint). Confirm the IdP includes the groups claim on the ID token and that SSO_GROUPS_CLAIM matches the claim name.
Users log in with the wrong identifier (e.g. an opaque sub) SSO_CLAIM_AS_USER_ID does not match the claim you want as the username. Set SSO_CLAIM_AS_USER_ID to email, preferred_username, or whichever claim your IdP exposes for end-user identity.