Venelx Docs
AI setupSign up

SSO and SCIM (beta)

Beta. OIDC single sign-on and SCIM 2.0 provisioning are implemented and unit-tested, but have not yet been tested against a real Okta or Microsoft Entra tenant. There is no dashboard UI for them yet: you configure them through the API. Email domains are not DNS-verified, so enabling SSO is done by Venelx. Expect rough edges and contact us before relying on it.

SSO lets the people on a team sign in with your company identity provider (IdP). SCIM lets the IdP create and remove those people automatically.

SupportedNot supported
OIDC (authorization code with PKCE)SAML
SCIM 2.0 Users: create, read, update, deactivateGroups, role mapping, bulk operations
Okta and Microsoft Entra ID (by design)Enforcing SSO-only sign-in

Before you start

  • You must be an owner or admin of the team that will own the SSO configuration.
  • Create a personal API token with the write scope and use it as the Authorization: Bearer header in the requests below.
  • Enabling SSO needs a Venelx platform admin, because the email domain is not verified by DNS. You can create the configuration yourself (it stays disabled), then ask Venelx support to enable it. Self-service enabling is off on the hosted service.

1. Create the OIDC app in your IdP

Create an OIDC web application with:

  • Redirect URI: https://api.venelx.com/api/sso/callback
  • Scopes: openid email profile
  • Note the issuer, client ID and client secret.

Issuer examples: Okta https://<your-org>.okta.com (or your custom authorization server URL); Entra ID https://login.microsoftonline.com/<tenant-id>/v2.0. The issuer must be https.

2. Save the configuration in Venelx

bash
curl -X POST https://api.venelx.com/api/sso/teams/<teamId>/config \
  -H "Authorization: Bearer $VENELX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain":"acme.com","issuer":"https://acme.okta.com","clientId":"...","clientSecret":"..."}'

The client secret is stored encrypted and never returned. A domain can belong to only one team. Ask Venelx support to enable it; after that, users with an @acme.com email can sign in. GET on the same URL shows the saved configuration, and DELETE removes it.

3. Sign in

The sign-in entry point is https://api.venelx.com/api/sso/login?domain=acme.com, which redirects to your IdP and back. On success the callback returns the same access and refresh tokens as a normal login. It is not yet wired into the dashboard sign-in page.

Rules to know:

  • The email domain from the IdP must match the configured domain.
  • If an account with that email already exists, SSO only signs it in when it is already a member of the team or was provisioned through SCIM. Otherwise sign-in is refused; ask a team admin to invite the person or provision them via SCIM.
  • Password sign-in still works for those accounts.

4. Provision users with SCIM (optional)

SCIM creates and removes accounts for your email domain, so it is set up with Venelx support. A SCIM token can only be created by a Venelx platform admin, and only after SSO is configured and enabled for the team (that is where your domain is verified). Ask support to create it; it is shown once:

bash
curl -X POST https://api.venelx.com/api/sso/teams/<teamId>/scim-tokens \
  -H "Authorization: Bearer $VENELX_TOKEN" -H "Content-Type: application/json" \
  -d '{"label":"okta"}'

Then in your IdP use:

  • SCIM base URL: https://api.venelx.com/api/scim/v2
  • Authentication: HTTP header, Bearer <the SCIM token>
  • Unique identifier: userName (the user's email)

Okta: add a SCIM 2.0 app, authentication mode HTTP Header, and enable Create Users, Update User Attributes and Deactivate Users. Entra ID: Enterprise application, Provisioning, Automatic, with the Tenant URL and Secret Token above; map userPrincipalName to userName.

What happens:

  • Provisioning creates the user (if new) and adds them to the team.
  • Deactivating (or deleting) removes the person's team membership. For accounts that SCIM created, the account is also disabled; accounts that already existed only lose the membership. Nothing is hard-deleted, and reactivating restores access.
  • The team owner can't be deprovisioned.
  • Domain rule: SCIM only manages accounts whose email is in the team's configured SSO domain (exact match). It can't create, link or change accounts in other domains, can't move an account to an address outside your domain, and never links Venelx platform admin accounts. A token for a team without an enabled SSO configuration is rejected.
  • Changing a user's email through SCIM also cancels any pending password-reset link for that account.
  • Removing someone from the team (SCIM or manually) also detaches any build workers they had added to the team's pool.
  • Only email, display name, external ID and active status are stored. Filters support a single expression such as userName eq "x".

List or revoke SCIM tokens with GET and DELETE on /api/sso/teams/<teamId>/scim-tokens.

← Plans & LimitsBuild Workers →