> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/developer-guide/guides/organization-sso.md).

# Set Up Organization SSO

Connect your organization's Okta app, approve existing workspace members, verify sign-in and email discovery, and understand session and offboarding limits.

Organization SSO lets existing workspace members sign in through your organization's Okta app. Each workspace has one connection, configured with the app and credentials owned by that organization. Use a separate app for each organization's connection and keep its assignments under that organization's control. Configure each production region separately, using the matching [Developer Console](https://docs.concurrence.com/developer-guide/getting-started/regions-and-endpoints.md#identity-and-developer-console).

An Okta assignment, an email match, or control of an email domain does not create workspace access. Sign-in requires an approved mapping between the app's immutable subject and an existing account with active membership in that workspace. A connection adds a sign-in method for approved members. [Managed access](#manage-access-from-okta-groups) requires separate approval and setup.

When creating a workspace, [explicit membership provisioning](https://docs.concurrence.com/developer-guide/platform-api/workspaces.md#membership-provisioning) excludes automatic domain-policy grants during Google sign-in while preserving invitations and authorized administrator grants. This choice does not require SSO. Configure the connection and approve members separately.

<figure><img src="https://1651797362-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2YwM0LHtEGLt9S21OyC3%2Fuploads%2Fgit-blob-8db346bc7bae6963b76ae37d4bf58e8bbdb4bf36%2Forganization-sso-access.svg?alt=media" alt="An organization&#x27;s Okta application authenticates its assigned user. One Concurrence workspace checks the approved subject and email and active membership before issuing a workspace-scoped session. Assignment and email discovery alone do not create workspace access."><figcaption><p>Provider sign-in and workspace access are separate decisions. An approved mapping connects the two.</p></figcaption></figure>

## Before You Start

You need a workspace owner or administrator account, access to administer your Okta application, and an existing active workspace member to verify sign-in. Email discovery also requires access to publish public DNS records for the configured domains.

Sign in to the Console through an independent account method before configuring the connection. Creating or replacing a connection, enabling it, rotating its client secret, and approving a member require this independent sign-in. Keep an independent owner sign-in available to manage the connection if the provider is unavailable. An SSO session can inspect settings, verify discovery domains, disable the connection, and revoke bindings within its existing role authority.

The supported provider profile is an Okta-hosted org issuer, such as `https://example.okta.com`. The supported suffixes are `.okta.com`, `.okta-emea.com`, `.oktapreview.com`, and `.okta-gov.com`. Custom domains, custom authorization-server URLs such as `/oauth2/default`, arbitrary OIDC providers, and SAML are outside this profile.

## Connect Your Okta App

1. In your organization's Okta administration, create an OIDC web application using the Authorization Code grant, required PKCE with S256, and client secret POST authentication (`client_secret_post`). Use RS256-signed ID tokens and provide a verified email address. Retain your organization's sign-in and MFA policies, and assign the intended users. Register only the regional callbacks you use.
2. In the regional Console, select the intended workspace and open **Settings → SSO**. Enter a connection name, the **Okta org URL**, **Client ID**, **Client secret**, and **Email domains**, then select **Save connection**. The connection starts disabled. The saved secret cannot be retrieved from the Console.
3. Copy **Sign-in callback** from the saved connection into the Okta application's allowed sign-in redirect URIs. Register that exact value before enabling SSO. The callback belongs to the Console host, which is separate from the Platform and Identity API hosts.

For the standard regional Console hosts, the callbacks are:

| Production region | Sign-in callback                                           |
| ----------------- | ---------------------------------------------------------- |
| US                | `https://console-us.concurrence.com/api/auth/callback/sso` |
| Canada            | `https://console-ca.concurrence.com/api/auth/callback/sso` |
| Europe            | `https://console-eu.concurrence.com/api/auth/callback/sso` |
| Australia         | `https://console-au.concurrence.com/api/auth/callback/sso` |

Use the value returned for your selected workspace and confirm availability in that deployment. The table does not provision a connection or establish regional availability. Avoid wildcard callbacks and callbacks from a different environment.

## Approve Existing Members

Under **Approved members**, select an existing active **Workspace member** and enter the **SSO subject ID**, then select **Approve member**. Have the Okta administrator confirm the immutable `sub` issued by this application for that person against authoritative account records. Do not substitute an email address or infer identity from a display name.

The member needs an existing account email consistent with the approved mapping, and that email must belong to a configured domain. Approval does not invite a person, create membership, reactivate access, or change a role. Only a workspace owner can manage another owner's SSO binding through the normal workspace administration flow.

If an administrator approved a member before that member became an owner, an owner must approve the same mapping before the binding can carry owner authority. The member must sign in again for that approval to take effect. Changes to a person's provider email or subject require a reviewed binding update. Matching a new email does not transfer access automatically.

### Add Another Owner

An existing workspace owner can add another owner while keeping their own owner access:

1. Sign in using Google or email, then open **Members & Access**.
2. Select **Owner** on the existing active member's row. Review the confirmation and select **Add owner**.
3. If the member's SSO mapping lacks owner approval, open **Settings → SSO → Approved members** and approve the same mapping as described above. Then have the member sign in again through SSO and verify the workspace and role.

Adding an owner resets that member's custom scopes to owner defaults and signs out their active sessions. SSO sign-in can be refused until the mapping has owner approval. The owner role is an independent grant: removing the person's SSO assignment does not revoke it, and existing owners retain their roles.

## Enable and Verify Sign-In

Select **Enable SSO**, then open the displayed **SSO sign-in link** in a separate browser session. This link selects the connection directly and works without DNS discovery.

Verify that sign-in reaches the intended workspace as the expected existing account and role. Use a controlled account without an approved binding to verify that an Okta sign-in alone does not grant workspace access. Keep the independent owner session available while verifying sign-in. If a callback expires or has already been used, start a new sign-in instead of reusing it.

An SSO session is scoped to the connection's workspace. It cannot switch into other workspaces merely because the same person also belongs to them. This setup adds optional SSO, and existing account sign-in methods remain available. Verify sign-in in every region you use, because success in one region does not validate another.

## Switch SSO Workspaces

You can switch from an organization SSO session to another workspace where the same account has active membership and an approved SSO mapping. The destination's connection must be enabled.

1. Open the Console's workspace picker and select **Switch SSO workspace**.
2. Choose the destination workspace and connection. Use the **Search SSO workspaces** field to filter by workspace or connection name. When more destinations are available, searching loads the remaining pages so the filter covers your full list. Select **Load more workspaces** when it is available to see additional destinations.
3. Complete the destination organization's sign-in.

The Console replaces its active session only after the destination sign-in verifies the same account for the selected workspace and connection. Switching does not create membership or change either workspace's assigned roles.

If a switch fails, it does not replace your current session. Use the return link to go back while that session remains valid, or sign in again if it has expired. If a destination is missing, ask its administrator to check the enabled connection, active membership and approved SSO mapping.

## Add Email Discovery

For each configured email domain, copy the displayed **TXT record name** and **TXT record value** into public DNS, then select **Verify domain**. The record name has the form `_concurrence-sso.example.com`. Use the exact connection-specific value shown in Settings.

Only enabled connections with a verified exact domain appear when a person chooses **Continue with SSO** and enters a work email. A subdomain needs its own configured domain and proof. For internationalized domains, copy the canonical ASCII DNS name returned by Settings. If several connections match, the person chooses which one to use.

DNS verification enables discovery. It does not approve members or grant workspace access. If verification has not completed, the direct SSO sign-in link remains available for an enabled connection.

## Rotate, Replace, or Disable a Connection

To rotate a secret, sign in independently, rotate the client secret in Okta, and enter the replacement under **Rotate client secret** in Settings. Existing SSO sessions must sign in again. Confirm a new sign-in before completing your organization's secret-retirement procedure.

To change the org URL, client ID, or email domains, disable SSO and sign in independently, then choose **Replace connection**. Enter the complete replacement settings and confirm. The replacement starts disabled with a new sign-in link, new DNS proofs, and no approved member bindings. Register its callback, approve members again, reverify discovery domains, and verify sign-in again before enabling broad use. Workspace memberships and stored data remain intact. Old links and approvals do not reactivate.

**Disable SSO** stops new sign-ins and session refreshes for the connection. **Revoke** under Approved members withdraws that member's SSO binding. These operations preserve workspace membership and stored data. If another administrator changed the connection, reload its settings before retrying a conflicting update.

## Manage Access from Okta Groups

Managed access lets an explicitly approved Okta group contribute a workspace role for an existing, approved member. It requires a configured directory reader and recurring reconciliation for the same organization and login application. The sign-in application's client secret alone does not configure directory access or start synchronization. Have your implementation owner verify this setup and successful recurring checks before relying on it for access changes.

Keep the directory reader able to read every linked account after it loses a login-app assignment or membership in an access-granting group. If you scope the reader through a group, keep that read scope separate from groups used to grant access. Removing the reader's visibility makes the account's status unavailable. It is not confirmation that access was removed.

Each mapping names one workspace, its current SSO connection and directory configuration, an exact Okta group, and a role: viewer, operator, member or administrator. Group mappings cannot grant owner access. An independently authenticated workspace owner or administrator must approve the mapping. Matching a group name, email or domain does not transfer that approval to another organization, application or workspace.

Saving a mapping leaves it disabled. Approval enables reconciliation. Access requires a successful check of the approved account, application assignment and group membership. Replacing its group, role or source requires separate approval of the replacement. A mapping does not create accounts or workspace memberships, and it does not convert independently granted access into managed access.

<figure><img src="https://1651797362-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2YwM0LHtEGLt9S21OyC3%2Fuploads%2Fgit-blob-c16645ba57861b23aa803e7eebff568b8eb1e302%2Fsso-access-contributions.svg?alt=media" alt="An existing approved member can have independent access, an app-based managed grant, and a group-based managed grant. Each managed grant needs current evidence for its own approved source. The workspace combines the permissions of valid grants; removing one grant leaves any independently valid grants in place."><figcaption><p>Each source contributes its own access. Losing one source does not erase a different valid grant.</p></figcaption></figure>

### Overlapping Access

A member can have independent access, an app-based managed grant and grants from several approved groups. Effective permissions are the union of the valid grants, with the highest supported role among them. The role label does not add permissions beyond that union. For example, removing an administrator group can leave a separately approved member grant in place. Review all sources when the intended outcome is complete offboarding.

Independent grants and owner access are preserved when a group mapping changes. Moving an existing independent grant under provider management is a separate, explicit administrative decision. Creating or approving a group mapping does not make that conversion.

### Review and Convert an Independent Grant

An independently signed-in workspace owner or administrator can review group-managed grants under **Settings → Directory access → Group-managed workspace grants**. Select **Review independent access** for the intended member and group contribution, then check the independent role, scopes and active status.

Conversion is available when the independent grant and active group grant have the same non-owner role. It also requires current evidence for the approved account, application and group membership, and a group grant that covers the independent permissions. If these requirements are met, select **Convert reviewed independent grant**, review the confirmation, and choose **Convert this contribution**.

The confirmation applies to the exact independent grant and group mapping you reviewed. If either changes, refresh the list and review independent access again before trying another conversion. After an uncertain result, refresh and inspect the current state before deciding whether another conversion is needed.

A successful conversion leaves the independent grant visible as an inactive record and retains the group-managed contribution. Other valid grants still contribute access. This decision does not create an app-based grant, change the approved group role, or remove stored workspace data.

### Changes, Removal and Unavailable Evidence

| Change                                                                                                   | Access consequence                                                                                                                                                                                   |
| -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A complete check confirms the person is absent from one group                                            | That group's contribution stops. Other valid group, app and independent grants remain eligible.                                                                                                      |
| A complete check confirms the user is suspended or deactivated, or unassigned from the login application | Managed contributions for that approved account and application stop. Independently granted access requires its own review.                                                                          |
| An administrator disables or replaces a mapping                                                          | Access from the affected mapping is retired. A reviewed approval and fresh reconciliation are required for the enabled mapping to contribute again.                                                  |
| An administrator explicitly removes the member's workspace access                                        | Group reconciliation cannot restore it merely because the person remains in the provider group. Re-enabling a mapping does not undo the removal.                                                     |
| Provider evidence is missing, expired or unavailable                                                     | It cannot authorize access that depends on that source. Another valid grant can still authorize a request within its own permissions. Unavailable evidence is not proof that the person was removed. |

Directory changes take effect through successful reconciliation and current access checks. A failed check does not extend a prior result's validity. A saved schedule is not proof that checks are completing, and there is no fixed propagation guarantee from the schedule alone. Verify a controlled grant, removal, overlapping grant and a case with unavailable source evidence for your deployment. Access changes preserve workspace data and access history.

## Sessions and Offboarding

Removing a binding or disabling the connection prevents new SSO sign-ins, refreshes, and Identity operations that revalidate the binding. Already-issued access tokens can remain valid in other services until their expiry: up to 15 minutes for user tokens and four hours for operator tokens after the last successful issuance. Delegated sessions expire within one hour and no later than their parent. The original SSO session has a fixed seven-day maximum. Refreshing it does not extend that deadline.

For a connection used only for sign-in, removing an Okta assignment does not by itself withdraw the approved binding or independent workspace membership. When managed access is configured, confirmed provider changes affect the corresponding grants as described above. Revoke the approved binding and separately review workspace membership, application credentials and other sign-in methods as part of offboarding. These access changes preserve workspace data.

A downstream client that verifies an access token locally can accept it until its expiry. A successful sign-out does not establish immediate termination of every existing connection. Account for the token lifetimes above when defining an offboarding commitment, and verify each application's behavior.

This workflow uses explicit account mappings. It does not provision accounts through SCIM. Creating independent credentials, inviting or granting workspace access, changing member roles, transferring ownership, and creating personal access tokens require independent account sign-in. SSO administrators retain permitted inspection and revocation operations. A supported SSO device authorization stays pinned to the approved workspace and cannot expand the session's authority.

For application and SDK credentials, use [Choose Credentials](https://docs.concurrence.com/developer-guide/getting-started/credentials.md). The Console's organization sign-in workflow does not replace the credential flow required by an API integration.

## Troubleshooting

| Symptom                                                 | Next check                                                                                                                                                            |
| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| No connection appears after entering an email           | Confirm the connection is enabled and the exact email domain is configured and verified. Try the connection's direct sign-in link to separate discovery from sign-in. |
| Okta rejects the redirect                               | Compare the app's registered URI with **Sign-in callback**, including the region, scheme, host, and full path.                                                        |
| Okta sign-in succeeds but workspace access is refused   | Verify the immutable subject mapping, approved email, active workspace membership, and any required owner approval.                                                   |
| A setup or access-grant action requires another sign-in | Use an independent account sign-in with the required workspace role, then retry the action.                                                                           |
| A login or refresh is temporarily unavailable           | Retry after the service recovers. For a failed browser callback, begin a new sign-in. Use an independent account sign-in if the provider is unavailable.              |

For an escalation, record the deployment, workspace, connection name, operation, time, and visible error. Keep client secrets, authorization codes, tokens, and private identity records out of support messages.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.concurrence.com/developer-guide/guides/organization-sso.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
