Single Sign-on (SSO) Overview

Overview

Single sign-on (SSO) lets people use their existing corporate credentials to access a Stack Internal workspace. Authentication stays under the policies of your identity provider, while Stack Internal applies workspace membership, roles, and permissions after sign-in.

• Federated sign-in through SAML or OIDC connections managed for your organization.
• A consistent sign-in experience across Stack Internal web applications and services.
• Tenant-aware access: the signed-in user is associated with the correct Stack Internal workspace.
• The same enterprise sign-in foundation for supported browser, API, and MCP client workflows.

What WorkOS is

WorkOS is the enterprise identity platform used by Stack Internal to connect to customer-managed identity providers. It is not a replacement for your identity provider. Your organization continues to manage users, credentials, multifactor authentication, conditional-access policies, and other sign-in controls in systems such as Okta, Microsoft Entra ID, or another supported provider.

Within Stack Internal, WorkOS supplies the federation layer and hosted setup experience. It establishes the SAML or OIDC connection, routes users to the correct organization connection, returns verified authentication results, and sends signed events when identity configuration or membership information changes.

How responsibilities are divided

Component	Primary responsibility	What it means for you
Your identity provider	Authenticates users and enforces your corporate sign-in policies.	You retain control of credentials, MFA, and access policy.
WorkOS	Connects the identity provider to Stack Internal using SAML or OIDC and hosts the connection setup flow.	Your identity administrator configures the connection through a guided portal.
Stack Internal Identity	Maps the authenticated person to a workspace user, owns the product session, evaluates roles and permissions, and issues internal JWTs.	Product services receive one consistent identity and authorization format.

How sign-in works

1. A user opens the workspace. Stack Internal identifies the workspace from the sign-in entry point.
2. Stack Internal starts the enterprise login. The user is redirected to the active WorkOS connection for that workspace, or WorkOS routes the user by organization domain where the hosted sign-in flow is used.
3. Your identity provider authenticates the user. Your existing sign-in policies, including MFA and conditional access where configured, remain in force.
4. WorkOS returns a verified result. Stack Internal checks that the returned organization matches the workspace that initiated the login.
5. Stack Internal creates or updates the local user session. The Identity service applies the user's current role and permissions and rejects inactive users.
6. Product services receive an internal token. The external credential is exchanged at the identity boundary for a short-lived, tenant-aware JWT that downstream Stack Internal services validate and trust.

Roles, permissions, and user lifecycle

Authentication answers who the user is. Authorization answers what that user may do. Stack Internal keeps these concerns separate so a successful SSO response does not automatically grant administrative access.

• Roles are bundles of product permissions. The Identity service reads the user's organization role and effective permissions and places them in the internal authorization token.
• The first administrator is preselected during workspace provisioning; the first person to sign in does not automatically become an administrator.
• Role, permission, and organization-membership changes are refreshed through the identity integration so active sessions can use current access information.
• Downstream services authorize against the effective permissions in the Stack Internal token rather than implementing separate SSO logic.

Security model

Stack Internal uses a layered model designed to keep enterprise federation at the identity boundary and application authorization inside Stack Internal.

• Signed state protects the browser login redirect, and the callback verifies that the returned organization matches the workspace that initiated sign-in.
• Stack Internal validates token signature, issuer, audience, lifetime, and required claims before trusting a token.
• Tenant identifiers in the internal token provide the source of truth for workspace context; changing a URL does not change the authenticated tenant.
• WorkOS credentials are exchanged at the identity boundary. Downstream product services receive a Stack Internal-issued JWT rather than the original WorkOS token.
• The internal token carries the effective permissions for the request, allowing services to enforce least-privilege access consistently.
• WorkOS completion and change events are signature-validated before Stack Internal acts on them.

Before you begin

Coordinate with your Stack Overflow contact to confirm that your workspace is provisioned and that the person completing setup is an authorized Stack Internal administrator. Verify:

• Administrator access to your Stack Internal workspace.
• Administrator access to your organization's identity provider.
• For SAML: your identity provider metadata or SSO URL, issuer/entity ID, and signing certificate, as requested by the setup portal.
• For OIDC: the issuer and client credentials or discovery information requested by the setup portal.
• A test user in the same organization who can complete the sign-in flow.

Set up SSO

1. Open the SSO setup page. In Control Center, go to Single Sign On (SSO). You can also start from the Enable SSO step on the Get Started page.
2. Continue to the identity setup portal. Stack Internal displays a notice before redirecting you to the WorkOS-hosted administration experience.
3. Choose and configure your connection. Select the identity provider or connection type and follow the portal instructions for SAML or OIDC. Copy the Stack Internal service-provider or redirect details into your identity provider, then enter the identity-provider details requested by the portal.
4. Assign access in your identity provider. Make the Stack Internal application available to the users or groups who should be able to authenticate, following your organization's normal application-assignment process.
5. Activate and test the connection. Complete the provider's verification steps. The connection must reach an active state before Stack Internal can use it for sign-in.
6. Return to Stack Internal. After WorkOS confirms the active connection, Stack Internal records the completed setup. The Get Started page shows SSO as enabled and, when available, displays the configured authentication method.
7. Complete a real sign-in test. Sign out or use a private browser window, open the workspace URL, and authenticate as the designated test user. Confirm that the user returns to the correct workspace and has the expected role.

Validate the configuration

• Control Center shows the Single sign-on step as complete.
• The displayed authentication method matches the configured provider and protocol when that label is available.
• A test user can start from the workspace URL, authenticate, and return to the correct workspace.
• The initial administrator receives administrator access; a standard test user does not receive administrator-only access.
• Users who are inactive or not assigned to the connection cannot enter the workspace.

Troubleshooting

The setup step is not complete: Confirm that the WorkOS connection is active, allow a short interval for the verified completion event, and refresh Control Center.

The user cannot sign in: Verify application assignment, organization membership, email domain, and active-user status.

The user returns to the wrong place: Start from the correct workspace URL. If the problem persists, note the URL and approximate sign-in time.

The user signs in but lacks access: Check the user's Stack Internal role and permissions; authentication alone does not grant product capabilities.

You already use Stack Internal community SSO: Configure Stack Internal separately because the products maintain independent identity configurations.

Frequently asked questions

Does WorkOS replace our identity provider?
No. WorkOS connects your identity provider to Stack Internal. Your organization continues to control user credentials and corporate sign-in policy.

Can we use SAML or OIDC?
Yes. Stack Internal's identity architecture supports enterprise connections based on SAML and OpenID Connect. The exact setup fields depend on the selected connection.

Does anyone who authenticates become an administrator?
No. Authentication and authorization are separate. Administrator access depends on the user's assigned Stack Internal role and permissions.

If you have any questions or need help, open a ticket on our help center or email us at support@stackoverflow.com.