# Single sign-on

> Verify your domains and set up single sign-on for Team Cloud with OIDC (Okta, Microsoft Entra ID, Google Workspace and other OIDC providers), at no extra charge. SAML is coming later.

Source: https://docs.subcloak.com/cloak-proxy/team/sso/

Added in Cloak Proxy 0.7.0.

{/*
  L9 draft. Sources: PLAN 7.17, 9.2, 9.3, 9.5 page 7, 7.14 (Require SSO), 6.4; T5.2 (SSO and joins). SAML is off for
  launch (review R3C-H2, contract v1.5.7): the console offers OIDC only; say "SAML coming later" wherever SSO is described.
  VERIFY(L3) before applying: the redirect URIs to register, the scopes requested, and the console's field labels.
  The IdP steps name the IdPs' own menus as of 2026-10; re-check them in a free Okta developer org (LAUNCH 2.4 step 11).
*/}

Single sign-on (SSO) lets your team sign in to Cloak Proxy and the console with your identity provider (IdP). It's included in Team Cloud at no extra charge. Owners and admins set it up on the console's **SSO & SCIM** page.

Team Cloud supports SSO with OIDC: Okta, Microsoft Entra ID, Google Workspace and other OIDC providers. SAML is coming later.

> **SSO proves who someone is. It never gives a Mac the team's keys unless automatic approval is on.:**
> After signing in with SSO, a new Mac still needs a person to [approve it](https://docs.subcloak.com/cloak-proxy/team/invite-and-approve/) by comparing a code, unless your team turned on [automatic approval after SSO](https://docs.subcloak.com/cloak-proxy/team/invite-and-approve/#approve-macs-automatically-after-sso).

## Verify your domains

{/* PLAN 7.17 domains */}

SSO applies to email addresses in domains your team has verified.

1. On **SSO & SCIM › Domains**, add your domain, for example `acme.com`, and click **Verify**.

2. Add the TXT record the console shows to your DNS:

   ```text
   _cloak-proxy-team.acme.com  TXT  "cloak-team-verify=<token>"
   ```

3. Click **Verify** again once the record is live.

Subcloak re-checks the record daily, so leave it in place. A domain can belong to only one team. Adding, verifying and removing a domain each ask you to confirm with a passkey or a fresh email code, and while **Require SSO** is on a verified domain can't be removed: turn Require SSO off first.

## Set up OIDC

{/* PLAN 7.17 OIDC, 9.3; VERIFY(L3): both redirect URIs */}

In your IdP, create a web application (OpenID Connect, authorization code) with these redirect URIs:

```text
https://console.subcloak.com/api/auth/sso/callback
https://cloud.subcloak.com/v1/auth/sso/oidc/callback
```

The first is for the console, the second for the Cloak Proxy app. Then, on **SSO & SCIM › Single sign-on**, click **Set up OIDC**, enter the **issuer**, **client ID** and **client secret**, and click **Test sign-in**.

**Okta**

1. In the Okta Admin Console, go to **Applications › Applications › Create App Integration**.
2. Choose **OIDC - OpenID Connect** and **Web Application**.
3. Add both redirect URIs under **Sign-in redirect URIs**, and assign the app to the people or groups who use Cloak Proxy.
4. Copy the **Client ID** and **Client secret**. The issuer is your Okta domain, for example `https://acme.okta.com`.

**Microsoft Entra ID**

1. In the Microsoft Entra admin center, go to **App registrations › New registration**.
2. Choose **Accounts in this organizational directory only**, and add the redirect URIs as **Web** platform URIs.
3. Under **Certificates & secrets**, create a client secret and copy its value.
4. The issuer is `https://login.microsoftonline.com/<tenant id>/v2.0`. Subcloak also checks that sign-ins come from that tenant.

**Google Workspace**

1. In the Google Cloud console, under **APIs & Services › Credentials**, create an **OAuth client ID** of type **Web application**.
2. Add both redirect URIs as **Authorized redirect URIs**.
3. Copy the client ID and secret. The issuer is `https://accounts.google.com`. Subcloak also checks that each account belongs to your Workspace domain.

{/* PLAN 7.17: checks iss, aud, exp, nonce, email_verified where sent; domain in verified domains; Google hd; Entra tid */}

Each sign-in is checked for the right issuer, audience, expiry and a one-time value, a verified email where the IdP says so, and an email in one of your verified domains.

## The owner confirms a new identity provider

{/* Review R3C-H1, contract v1.5.7 */}

When an admin sets up or changes the identity provider, a passing **Test sign-in** signs in only that admin. It signs in nobody else until the team's **owner** confirms it on the **SSO & SCIM** page (**Confirm…**, after confirming it's them). When the owner runs the test, it's confirmed at once. Changing the issuer or client ID starts over: test again, and the owner confirms again. The owner and admins get an email at each step.

A sign-in through SSO can only act in your team, with the person's member or admin role there. It never makes anyone the owner or a billing manager, and it can't add or remove passkeys or end the account's other sessions: those need the person's own email code or passkey.

## Where SSO is used

{/* PLAN 7.17 where SSO applies, 9.3 */}

- **The console:** **Sign in with SSO** appears for addresses in a verified domain.
- **The app:** when the team requires SSO, signing in with an address in a verified domain opens your IdP's page in a browser sheet. When you've signed in, it says "Signed in. You can go back to Cloak Proxy."

## Require SSO

{/* PLAN 7.14 Require SSO, 7.17 break-glass */}

The [policy](https://docs.subcloak.com/cloak-proxy/team/policies/) **Require SSO** makes Subcloak's server refuse email-code sign-in for addresses in your verified domains, in the app and the console.

Under Require SSO, the owner and billing managers sign in to the console with a [passkey](#passkeys), or with an email code from **Team owner or billing manager? Email me a code instead**; the owner and admins are told. That way they can always get in if the IdP is down or misconfigured (SSO never gives anyone those roles). The sign-in is also recorded in the audit log. If the owner's address is in one of your verified domains, Require SSO can be turned on only once the owner has a passkey.

## Passkeys

{/* PLAN 9.2 */}

Anyone can add passkeys in the console under **Your account**. Adding or removing one asks you to confirm with an existing passkey or a fresh email code, and sends you an email. The owner should add at least one.

## Related

  - [SCIM](https://docs.subcloak.com/cloak-proxy/team/scim/): Provision and deprovision people from your IdP.
  - [Invite and approve people](https://docs.subcloak.com/cloak-proxy/team/invite-and-approve/): Approving Macs, and automatic approval after SSO.
  - [Policies](https://docs.subcloak.com/cloak-proxy/team/policies/): Require SSO and verified-domain invitations.