Hosted Kumo.io

On hosted Kumo.io, single sign-on belongs to your Kumo.io account, not to one workspace. Set it up at https://account.kumo.io/settings/sso (Single Sign-On in your Kumo.io account). In a workspace, the Your Kumo.io Account group in Settings links there.

• Plan. OpenID Connect single sign-on needs the Team plan or above. On a plan without it, the page shows "Your plan does not include OpenID Connect sign-on, so these settings are read-only. Sign-in keeps working, and you can still disable the connection." If you move to a plan without it, a connection you already have keeps signing people in. You can't edit it or enable it again, but you can still Disable it and turn Require single sign-on off.
• Role. Only an account owner can see and change these settings.

Register Kumo.io with your identity provider

Create an OpenID Connect web application with these settings:

Connect it

On the OpenID Connect card, enter the Issuer URL, the Client ID and the Client secret, then select Save OIDC Connection. The connection is live as soon as you save it, and the card shows Active. Edit, Disable and Enable work as described for self-hosted below.

How people sign in

People start from your workspace's address, https://kumo.io/@<workspace-address>. When they log in, Kumo.io's login page offers Continue with Single Sign-On, which sends them to your identity provider and back, signed in. If you require single sign-on, they go straight to your identity provider.

Kumo.io recognises people by their account at your identity provider, not by email address. The first time someone signs in this way, they join your Kumo.io account as a Member. Someone who was removed from the account is refused.

Require single sign-on

Require single sign-on is at the top of the same page. While it's on and a SAML or OpenID Connect connection is active:

• password login to the account's workspaces is refused, and people are sent to your identity provider;
• your Kumo.io account's members, single sign-on and provisioning pages can only be used from a session that came through your identity provider.

You can only turn it on from a session that came through your identity provider: "To turn this on, log in through your identity provider first. That proves the connection works, so nobody is locked out." Log out, sign in to your workspace with Continue with Single Sign-On, then come back to this page.

There is no password fallback for owners. If your identity provider becomes unavailable while single sign-on is required, contact Kumo.io support.

The rest of this page applies to self-hosted installations.

Before you start

• Plan. On a self-hosted installation, OpenID Connect single sign-on is part of Enterprise (Licensed). On a plan without it, the card shows a plan notice instead of the form.
• Role. You need the sso.manage permission, which the Account owner and Account admin roles include.
• Public address. Set KUMO_EXTERNAL_URL on the installation to the address people use to reach Kumo.io. Kumo.io builds the redirect URI your identity provider needs from it (without it, from the address your browser used).

Register Kumo.io with your identity provider

In your identity provider, create an OpenID Connect web application for Kumo.io:

You don't have to build the redirect URI yourself: the OpenID Connect card shows it under Register These at Your Identity Provider, with a copy button, before you save anything. Kumo.io computes it the same way it does when your identity provider sends people back, so it always matches. The API returns it too: GET /v1/accounts/{accountId}/sso/setup (oidc.redirectUri).

Note the application's issuer URL, client ID and, if it has one, client secret.

Kumo.io reads the person's email address from the email claim and their name from the name claim. It finds your identity provider's endpoints from the issuer's standard discovery document, and checks the signature, issuer, audience and expiry of every ID token.

Connect it in Kumo.io

1. Open Settings › SSO & Integrations.
2. On the OpenID Connect card, enter the Issuer URL, the Client ID and the Client secret.
3. Select Save OIDC Connection.

The connection is live as soon as you save it. The card shows Active and switches to a summary of the issuer, the client ID and whether a client secret is set. Kumo.io stores the client secret encrypted and never shows it again. If saving fails, the error appears on the OpenID Connect card itself.

Log in with SSO

On the Log In page:

1. Select Log in With Single Sign-On.
2. Enter the Account ID.
3. Select Continue.

Kumo.io sends you to your identity provider, then back to Kumo.io, signed in.

Anyone your identity provider signs in this way becomes a member of the account. Signing in grants no permissions: a new member has no role until someone gives them one. Read Roles and permissions.

Test single sign-on with a second browser or a private window before you change anything else, so you keep a working session.

Require SSO

Require single sign-on, at the top of Settings › SSO & Integrations, applies to the whole account and to both kinds of connection: while it's on and any SAML or OpenID Connect connection is active, people who try to log in with an email address and password are refused, before any two-factor step. It isn't part of the OpenID Connect form, so you can turn it on or off without touching the connection.

• You can't turn it on until a connection is active.
• If every connection is later disabled, password log-in works again and the setting shows "Not in force" until a connection is active again.
• There is no password back door for owners. If your identity provider is unavailable, an owner with a session that is still signed in, or a Read and Write API token, can turn Require SSO off or disable the connection.

Before you turn it on, make sure SSO login works for you and for at least one other Account owner.

The API is PUT /v1/accounts/{accountId}/auth-policy with {"requireSso": true}; turning it on with no active connection returns 409 with the reason sso_not_configured.

Change the connection

Select Edit on the OpenID Connect card to change the issuer, client ID or secret. The form opens with the current values; leave Client secret blank to keep the stored one ("(leave blank to keep)"). Disable and Enable switch the connection off and on without re-entering anything.

Kumo.io's API can also change the scopes Kumo.io asks for and the claim it reads the email address from. Use PUT /v1/accounts/{accountId}/sso/oidc with the fields issuer, clientId, and optionally clientSecret, scopes, emailClaim and status. Read the API reference.

Changes to the OpenID Connect configuration are recorded in the audit log.

Related

• SAML single sign-on
• SCIM provisioning