Authentication Flows
How It Works
In Stytch’s B2B product there are two different versions of the OAuth authentication flow:
- Organization-specific Authentication: used when you already know the Organization that the end user is trying to log into.
- Discovery Authentication: used for self-serve Organization creation or login prior to knowing the Organization context.
Both flows support OAuth, allowing end users to accept pending invites or Just-in-Time (JIT) Provision by email domain, and finish with the end user authenticated in a specific Organization. However, Discovery involves one additional step to surface the end user's "discovered organizations" that they are eligible to login to and also allows self-serve organization creation.
Learn more about Discovery vs Org-Specific Authentication in our B2B Basics Overview.
Summary of Key Differences
Each guide walks through both OAuth flows in detail for the integration method chosen. However, for a quick overview of differences see the table below:
Discovery | Organization-Specific | |
|---|---|---|
OAuth Start Initiated With | public_token | public_token and organization_id OR slug |
Redirect URL Used for Callback | Discovery | Login or Sign-up |
Stytch Token Type | discovery_oauth | oauth |
Authenticate Method | oauth.discovery.authenticate() | oauth.authenticate() |
Access and Refresh Token | Retrieve via Get Access Token APIs after organization selection | Returned in oauth.authenticate() response, or can retrieve via Get Access Token APIs |
Just-In-Time Provisioning in Discovery Flows
Enabling JIT Provisioning for OAuth Tenants
If a workspace is configured to use Slack, HubSpot, or GitHub as identity providers for OAuth, organizations can enable Just-in-Time (JIT) Provisioning of end users based on tenant ID. A tenant ID is a unique identifier for a subgroup within one of these OAuth providers; e.g. Slack's Workspace ID, HubSpot's Hub ID, or GitHub's organization ID.
An end user who completes a Discovery OAuth flow where the tenant ID of the provider they authenticated with matches a tenant ID in an organization's Allowed Tenants list will have that organization surfaced in their Discovery response and will subsequently be allowed to authenticate into that organization.
See our guide for finding your provider's tenant ID in our OAuth setup guide.
If the tenant ID does not match any of the organization's Allowed Tenants, the end user will have to undergo further authentication of their email (i.e. a step-up) before being permitted to perform certain actions in Stytch, such as JIT provisioning by email domain or creating a new organization. You can read about step-up requirements in the section below.
Understanding Step-Up Requirements in OAuth Discovery
If the tenant ID of the provider matches a tenant ID in the organization's Allowed Tenants, the end user will be fully authenticated after completing an OAuth flow.
If the tenant ID of the provider does not match any of the Allowed Tenants, but an end user is still eligible to join the organization via their email domain, an end user wishing to authenticate using Slack, HubSpot, or GitHub as identity providers are required to do a “step-up” form of primary authentication before being able to receive a full session and fully authenticate as a member. An end user can step-up via one of the following methods:
Active members (members that have been pre-created in an organization or have previously completed step-up authentication) and members whose tenant ID match the organization's Allowed Tenants are allowed to sign-in via these providers without undergoing any step-up requirements.
When an end user authenticates via Slack/HubSpot/GitHub OAuth and opts to JIT Provision into an organization they are eligible to join based on the email domain returned from Slack/HubSpot/GitHub, fields are provided in the authentication response that inform the developer whether an end user needs to step-up and how to satisfy the step-up requirement:
- member_authenticated: will be false to indicate that the end user requires step-up authentication.
- primary_required: details actions that the member must take in order to meet the step-up requirement for the organization in question.
- intermediate_session_token: this will be populated with the same token the end user received when completing OAuth authentication.