VOTPort
Let’s talk
Menu

Configure sign-in and offboarding

Set up OIDC, match group claims to roles, and revoke access promptly.

On this page

OIDC application

Register an authorization-code application with your identity provider. Its callback is https://YOUR-HOST/api/admin/callback. Configure:

VOTPORT_OIDC_ISSUER: "https://idp.example.com"
VOTPORT_OIDC_CLIENT_ID: "your-client-id"
VOTPORT_OIDC_CLIENT_SECRET: "your-client-secret"
VOTPORT_OIDC_ADMIN_GROUP: "votport-admins"
VOTPORT_OIDC_AUDITOR_GROUP: "votport-auditors"

Use your actual issuer and group claim values. Omitting the administrator group makes every authenticated principal an administrator, so set it deliberately.

Members of the admin group are administrators. Members of a configured auditor group receive audit-only access without links, files, grants, or settings. Other principals are read-only viewers. Administrator membership takes precedence over auditor membership.

VOTPort supports one OIDC client ID. A token's authorized-party (azp) claim, when present, must match it.

Provider details

For Authentik, use the application's OIDC issuer and include the required groups in the groups claim. For Entra ID, use the tenant's v2 issuer, register the web callback, create a client secret, and configure group claims. Entra commonly emits group object IDs; use those IDs in VOTPort's group settings when that is what the token contains.

Discovery happens on first SSO use. A failed discovery retries after a 30-second cooldown. Successful discovery remains loaded until restart; restart after changing provider metadata when needed.

Connect a SAML identity provider

VOTPort speaks OIDC directly. To use a SAML-only identity provider, place an identity broker such as Keycloak between it and VOTPort. The broker accepts SAML from your identity provider and exposes an OIDC application to VOTPort.

  1. Configure the broker to trust your SAML identity provider, including its metadata, signing certificates, and required attribute mappings.
  2. Create an OIDC authorization-code client in the broker with VOTPort’s https://YOUR-HOST/api/admin/callback redirect URI.
  3. Set VOTPort’s OIDC issuer, client ID, and secret to the broker’s values, not the upstream SAML provider’s values.
  4. Map the upstream identity and groups into the broker’s OIDC claims. Configure explicit administrator and auditor groups, and align the subject claim with SCIM if provisioning is enabled.
  5. Test administrator, auditor, and viewer access, then test offboarding with an existing session before opening access to your team.

The bridge is a separately configured identity service, not a native SAML endpoint in VOTPort. SSO is included with every licensed port; operating the bridge and any identity-provider charges belong to your identity infrastructure. Preserve local recovery access and follow the revocation steps below when offboarding users.

Local recovery access

The local administrator password remains available when the identity provider is unreachable. System can collapse the local form behind Use local password, but does not disable that recovery route. Protect this credential even when everyone normally uses SSO.

Sessions and immediate revocation

SSO sessions default to seven days. VOTPORT_SSO_SESSION_SECS or System / Sign-in changes their lifetime; the saved setting overrides the environment. Local recovery sessions retain a fixed seven-day lifetime.

Tenant and role claims are captured at login. Removing an identity-provider group takes effect at the next login, bounded by the session lifetime. For immediate offboarding, also revoke the principal from Tenants. Existing sessions then fail on their next request and further SSO sign-ins are refused until the principal is unblocked. Unblocking requires a fresh sign-in; it does not revive old cookies.

SCIM provisioning

VOTPort exposes SCIM Users and Groups under /scim/v2 when a SCIM token is configured. Provisioning userName must match the subject VOTPort uses at sign-in. Set VOTPORT_OIDC_SUBJECT_CLAIM to sub, email, or preferred_username to match the provider's mapping.

Use Require SCIM provisioning when only provisioned principal rows should be allowed to sign in. Local recovery access is unaffected. Deactivating or deleting a SCIM user blocks the principal and ends access on the next request. Group membership changes take effect on a new sign-in.

Token rotation can retain a previous SCIM token during provider cutover. Clear the previous token after confirming that the provider uses the new one. Clearing the current token disables the endpoint.

Read as Markdown