Single sign-on and SCIM

All docs

Let your team sign in to the CAIN console with your company's identity provider, and let that provider add and remove people automatically. It works with Okta, Microsoft Entra ID, Google Workspace, Auth0, Keycloak, or any OpenID Connect provider. Owners and admins set it up; nobody else can.

1. Register the provider#

In your provider, create an OIDC web application. Set its redirect URI to https://cainstudio.online/sso/callback, then give CAIN the issuer, client id and client secret:

curl -s -X PUT https://cainstudio.online/fabric/sso -H "X-API-Key: $CAIN_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"issuer":"https://acme.okta.com", "client_id":"0oa...", "client_secret":"...",
       "default_role":"viewer", "jit":true, "allowed_domains":["acme.com"]}'

The answer includes login_path, for example /sso/sso_3f9c.../login. That is the sign-in link for your team. The client secret is stored encrypted and never returned.

• jit (off by default) lets anyone your provider signs in with an email on allowed_domains join on their

first sign-in, with default_role (viewer or member). Without jit, people must be invited or provisioned first.

• email_claim defaults to email. Entra tenants that do not send email can use upn or

preferred_username.

2. Sign in#

Opening the sign-in link sends the browser to your provider, then back to CAIN, which opens the console as that person, with their role. Behind the scenes:

• The flow uses the authorization code flow with PKCE, a single-use state and a nonce, and expires after

10 minutes.

• The ID token's signature is checked against your provider's published keys (RSA or EC only, never

none or shared-secret algorithms), along with issuer, audience, expiry and nonce.

• An email your provider marks as unverified is refused.
• Admin is never granted by sign-in. Only the workspace owner grants it, in the console.

3. Provision with SCIM (optional)#

curl -s -X POST https://cainstudio.online/fabric/sso/scim-token -H "X-API-Key: $CAIN_API_KEY"

Give your provider the base URL https://cainstudio.online/scim/v2 and the token, which is shown once. The provider can then create, update, deactivate and delete members (SCIM 2.0 Users). Roles come from roles[].value: viewer or member. A request for admin is refused. Deactivating someone ends their console access on their very next request, and just-in-time joining cannot bring them back.

Limits#

• OIDC only. SAML is not supported yet.
• There is no setting yet that *requires* SSO. Invited members and key holders can still sign in the

existing way.

• Console sessions last 8 hours, after which the person signs in again through the provider.