---
title: "Set up single sign-on and directory sync"
description: "Let a client's people sign in to the portal with their Microsoft Entra, Google, or Okta work account, and keep portal groups and leavers in step."
url: "https://support.outpostplatform.com/client-portal/sso/"
product: "depot"
type: "how-to"
status: "draft"
ai_summary: "MSP plan. Client portal tab > SSO and directory: add the client's email domains, signing in through the Outpost sign-in service (Entra, Google), the MSP's own app from Settings > Client portal > SSO apps, or the client's own identity provider connection (also Okta). SSO signs in only invited people. Optional trust of the IdP's MFA. Directory sync maps groups and suspends leavers."
availability:
  plans: ["msp"]
  permission: "clientportal:manage"
  preview: false
source: "https://gitlab.com/outpostplatform/docs/-/edit/main/src/content/docs/client-portal/sso.md"
license: "CC BY 4.0"
---

# Set up single sign-on and directory sync

With single sign-on (SSO), a client's people sign in to the portal with the
work account they already use, so they have no portal password to remember.
Directory sync also keeps portal groups in step with the client's directory
groups, and suspends people who leave. This page shows how to set up both.

## Before you begin

- You need `clientportal:manage`.
- The people who will sign in are invited to the portal. SSO never creates
  portal users: only people already invited can sign in. See
  [Invite and manage portal users](/client-portal/users/).
- Decide how the client signs in:

  | Signs in through | Use it when | You set up |
  | --- | --- | --- |
  | **The Outpost sign-in service** | The client uses Microsoft Entra ID or Google Workspace, and you want nothing to register. This is the default. | Nothing. The client's administrator consents to the Outpost app once. |
  | Your own app, on **SSO apps** | You want your own Entra or Google app registration, under your name on the consent screen, for every client. | An app registration of your own. See [Use your own app for every client](#use-your-own-app-for-every-client). |
  | **The client's own connection** | The client registered its own app, or uses Okta. | A connection on the client's **SSO and directory** page. See [Use the client's own connection](#use-the-clients-own-connection). |

## How sign-in works

The person enters their work email on the portal's sign-in page. When the
address is at one of the client's SSO domains, the portal sends them to their
own sign-in page at Microsoft, Google, or Okta. What happens next:

- **A person invited with no portal account yet.** Their first SSO sign-in
  links their work account to the invitation, when the work account's email
  address is verified and matches the invitation. This works only for email
  domains you have routed to this client's sign-in.
- **A person who already has a portal account**, for example for another of
  your clients. SSO never links an existing account by email. The sign-in page
  says **An account already exists for that address. Sign in with your
  password and authenticator, then link your company sign-in from your
  profile.** They sign in as usual and select **Link your work account** under
  **Company sign-in** on their security page. See
  [Manage your sign-in and security](/portal-guide/sign-in-and-security/#link-your-work-account).
- **Anyone not invited** is refused.

## Add the client's email domains

1. Select **Clients**, then **Record** on the client's row, then the **Client
   portal** tab.
2. Select **SSO and directory**.
3. Under **Sign in with the client's accounts**, select **Add a domain**.
4. In **Email domain**, enter the domain the client's addresses use, such as
   `example.com`.
5. In **Provider**, choose **Microsoft Entra**, **Google**, or **Okta**.
6. In **Signs in through**, choose **The Outpost sign-in service**, or **The
   client's own connection** and then the **Connection**. Okta always uses the
   client's own connection.
7. Optionally, in **Tenant**, enter the client's Entra tenant id or primary
   domain, or their Google Workspace domain. Sign-ins from any other tenant
   are then refused.
8. Select **Save domains**.

An email domain can belong to one client only. With no domains, everybody at
the client signs in with a portal password and a second factor.

## Use your own app for every client

By default, the Outpost sign-in service signs clients in with an app Outpost
has registered with Microsoft and Google. To use your own instead:

1. Register an app with Microsoft Entra or Google. For Entra, make it
   multi-tenant so your clients' tenants can sign in, and add the optional ID
   token claims `email` and `xms_edov`. See the caution under
   [Use the client's own connection](#use-the-clients-own-connection).
2. In the console, select **Settings** > **Client portal**, then **SSO apps**.
3. On the provider's card, choose **Your own app**.
4. Enter the **Client ID** and **Client secret**, and optionally the date the
   **Secret expires**. Outpost raises a reminder alert before that date, on
   the reminder lead times in **Documentation** > **Settings**. See
   [Track expirations](/documentation/expirations/#alerts).
5. Copy **Redirect URI to add to your app** into your app registration. Add
   the same path on every custom portal domain you use.
6. Select **Save**.

The card then shows **Your own app, configured**. Every client domain that
signs in through the Outpost sign-in service for that provider now uses your
app. The secret is stored write-only. Type a new one only to replace it.

## Use the client's own connection

Use this when the client has registered its own app with their identity
provider, or uses Okta.

1. On the client's **SSO and directory** page, under **The client's own
   sign-in connections**, select **Add a connection**.
2. Enter a **Name** and choose the **Provider**, then the provider's own
   field: **Tenant ID** (the client's Entra tenant GUID) for Microsoft Entra,
   **Workspace domain** for Google, or for Okta the **Issuer**, the Okta org
   URL such as `https://example.okta.com`. For Entra and Google, **Issuer** is
   filled in for you.
3. Enter the app's **Client ID** and **Client secret**.
4. In the client's app registration, add the redirect URI the page shows, and
   the same path on every custom portal domain.
5. Select **Add connection**.
6. Under **Sign in with the client's accounts**, choose **The client's own
   connection** for the domain, pick the connection, and select **Save
   domains**.

To change a connection, select **Edit**. Its stored secret is never shown.
Managing connections needs `clientportal:manage`.

:::caution
For a Microsoft Entra app, yours on **SSO apps** or the client's own, add the
optional ID token claims `email` and `xms_edov` in the app registration's
token configuration. Outpost treats an Entra email address as verified only
when `xms_edov` says so. Without it, invited people cannot complete their
first SSO sign-in.
:::

## Accept the identity provider's second factor

By default, the portal asks for its own second factor after an SSO sign-in.
To rely on the client's identity provider instead:

1. Under **Second factor from the identity provider**, read **Who is
   responsible**.
2. Turn on **Accept the client's identity provider sign-in as the second
   factor**.
3. Select **Save**.

With it on, the portal skips its own second factor when the identity provider
reports that the sign-in used multi-factor authentication. When the provider
does not report it, the portal still asks for its own. Whether the sign-in
really used MFA is then the client's identity provider's job, under the
client's own policies, so turn it on only when you know the client enforces
MFA there. It also lets the portal open inside Microsoft Teams without sending
people to a browser.

The setting is per client. A person who belongs to several of your clients'
portals is asked for their own portal second factor when they switch to an
organization that does not trust its identity provider's MFA.

## Sync the client's directory

Directory sync reads the client's directory each night and at every SSO
sign-in:

- People in a mapped directory group join the matching portal group, and
  leave it when they leave the directory group.
- Anybody disabled or deleted in the directory is suspended in the portal,
  with their remote access revoked.
- Only portal users with an address at one of the client's SSO domains are
  affected.

Directory sync reads only. It never changes the client's directory. First give
Outpost read access, in the way that matches how the client signs in.

### Microsoft Entra through the Outpost sign-in service

1. On **SSO and directory**, under **Microsoft tenant**, select **Connect
   Microsoft tenant**.
2. The page shows an admin consent link. It works once, until the time shown.
   Select **Open it now** if you administer the client's tenant, or send the
   link to the client's administrator.
3. The administrator signs in to Microsoft and approves. They need to be a
   Global Administrator, Privileged Role Administrator, Cloud Application
   Administrator, or Application Administrator.
4. Select **Check again**. The tenant shows **Connected**.

### Microsoft Entra with the client's own connection

1. In the client's app registration, add Microsoft Graph application
   permissions to read users and group memberships, such as `User.Read.All`
   and `GroupMember.Read.All`, and grant admin consent.
2. Under **Directory credentials**, select **Add** for Microsoft Entra.
3. Enter the **App (client) id**, the **Client secret**, and the **Entra
   tenant**.
4. Select **Store credential**.

### Google Workspace

Google directory sync uses a service account in the client's own Google Cloud
project, with read-only domain-wide delegation.

1. In the client's Google Cloud project, create a service account and a JSON
   key for it.
2. In the client's Google Admin console, give the service account domain-wide
   delegation for these scopes:
   `https://www.googleapis.com/auth/admin.directory.user.readonly` and
   `https://www.googleapis.com/auth/admin.directory.group.readonly`.
3. Under **Directory credentials**, select **Add** for Google.
4. Paste the key into **Service account key (JSON)**.
5. In **Workspace administrator it acts as**, enter the email address of a
   Google Workspace administrator.
6. Select **Store credential**.

A stored secret is never shown again. To change one, select **Replace** and
paste it whole.

### Map groups and turn sync on

1. Create the portal groups first, with the roles each should give. See
   [Invite and manage portal users](/client-portal/users/#manage-groups).
2. Under **Directory groups to portal groups**, for each portal group, choose
   **Microsoft Entra group** or **Google group**, and enter the **Directory
   group id**: the group's object id in Entra, or its id in the Google Admin
   SDK.
3. Select **Save mappings**.
4. Under **Directory sync**, turn on **Keep portal users in step with the
   client's directory**, then select **Save**.

A mapped group's members are decided by the directory, so they cannot be
changed in the console or the portal.

## Verify

- An invited user at the domain enters their email on the sign-in page and is
  sent to their own sign-in page.
- Under **Directory sync**, **Last run** and **Result** show **Completed**
  after the first run, or **Failed** with the reason.

## Next steps

- [Set portal roles, groups, and the permission ceiling](/client-portal/roles-and-ceiling/)
- [Add the portal to Microsoft Teams](/client-portal/teams/)