Log in with OAuth

Stytch's OAuth product simplifies the process by abstracting the implementation details of OAuth for developers. While OAuth has many benefits, developers need to understand the OAuth framework well to implement it securely.

In this guide, you'll learn how to set up an OAuth login flow for a specific Organization. By the end, you'll have:

• Set up an OAuth client for a provider (Google or Microsoft).
• Created a client-side OAuth URL to start the login flow.
• Provisioned and authenticated the end user as a Member of the Organization via OAuth.

Before you start

In order to complete this guide, you'll need the following:

• A Stytch B2B project. If you don't have one already, in the Dashboard, click on your existing project name in the top left corner of the Dashboard, click Create a new project, and then select B2B Authentication.
• The project Test environment's project_id and secret from the API keys section. You'll need to pass these values into the Authorization request header for every Stytch API call.

Step 1: Add or update redirect URLs in the Dashboard

As a security precaution, we require that you explicitly set URLs in the Redirect URLs section of the Dashboard. Stytch redirects the end user back to the redirect URLs during the OAuth flow.

By default, all new projects have redirect URLs set to http://localhost:3000/authenticate for the Test environment in the Dashboard.

If your project doesn't have a redirect URL or if you need a different URL, click + Create redirect URL and provide a URL for ALL or individual URLs for Login and Sign-up.

For more information on why this step is necessary, please check out the resource on URL validation.

Step 2: Copy your project's public_token

In the API Keys section of the Dashboard for your project, copy the public_token value under the Public tokens section. You'll need the public_token to complete the OAuth flow.

Step 3: Set up an OAuth client for your project

In the Dashboard for your project, navigate to the OAuth settings under CONFIGURATION. Select Google or Microsoft as the OAuth identity provider of your choice. Click Set up your own and follow the instructions to set up an OAuth client.

Be sure to add the Stytch redirect URI to your provider OAuth setup as an authorized redirect URI. The Stytch redirect URI is where end users are redirected after they have authenticated with the provider.

Step 4: Create a new Organization

If you don't have one, create a new Organization by calling our Create an Organization endpoint.

It requires, at minimum, an organization_name. For the purposes of this guide, you also need to set email_jit_provisioning to RESTRICTED and provide the email_allowed_domains list with an email domain your Members will complete the OAuth login flow with (for example stytch.com or exampleorg.com).

These Organization settings allow end users to be provisioned as Members when signing up for an Organization through OAuth. You can read more about Organization settings here.

curl --request POST \
    --url https://test.stytch.com/v1/b2b/organizations \
    -u '{PROJECT_ID}:{SECRET}' \
    -H 'Content-Type: application/json' \
    -d '{
        "organization_name": "Example Org Inc.",
        "organization_slug": "example-org",
        "email_allowed_domains": ["exampleorg.com"],
        "email_jit_provisioning": "RESTRICTED"
    }'

Copy the organization_id or organization_slug from the response. You'll need one for the next step.

Step 5: Embed the Start OAuth endpoint URL into a UI element

Use the Stytch Start OAuth endpoint to create a client-side URL for Google or Microsoft OAuth login. You need to pass in, at minimum, the public_token from Step 2 and either an organization_id or an organization_slug from Step 3 into the query params.

https://test.stytch.com/v1/b2b/public/oauth/google/start?public_token={PUBLIC_TOKEN}&organization_id={ORGANIZATION_ID}

https://test.stytch.com/v1/b2b/public/oauth/google/start?public_token={PUBLIC_TOKEN}&slug={ORGANIZATION_SLUG}

Embed the URL into a UI element, like a login button, for the end user to click on. For the purposes of this guide, you can paste the client-side URL into the browser to simulate the OAuth login flow as the end user.

Step 6: Log in with the provider

Addressed to the client-side URL, the browser will navigate the end user to the provider's login screen (Google or Microsoft). Once the end user authenticates with their provider's credentials, they are then taken back to the redirect URL defined in Step 1 with additional values in the query parameters.

Your application should have a route and page that handles the redirect URL and its query parameters. The redirect URL will look like this:

{REDIRECT_URL}?slug={ORGANIZATION_SLUG}&stytch_token_type=oauth&token=KQCRsuXM_DVOsHpW4ktcTyJkb06iKwzM9SZkO1JgOGrj

Copy the token query param value.

Step 7: Call the Authenticate OAuth endpoint

Call the Authenticate OAuth endpoint with:

• The token query param's value from Step 6
• An optional session_duration_minutes length to create a Session. If left empty, the default length for session_duration_minutes will be set to 60.

curl --request POST \
    --url https://test.stytch.com/v1/b2b/oauth/authenticate \
    -u '{PROJECT_ID}:{SECRET}' \
    -H 'Content-Type: application/json' \
    -d '{
        "oauth_token": "KQCRsuXM_DVOsHpW4ktcTyJkb06iKwzM9SZkO1JgOGrj",
        "session_duration_minutes": 60
    }'

After a successful API call:

• The end user will be provisioned and a new Member record will be created.
• The end user will be authenticated into the Organization as a Member.
• A Member Session object, session_token, and session_jwt will be returned in the response.

What's next

Build a user interface that allows end users to log in and sign up with OAuth in Step 5. You'll also need to build a page to handle the redirect back to your application in Step 6 after an end user authenticates with their provider.

Clone our B2B Next.js example app for helpful templates that can get you started quickly. Also check out our interactive B2B demo app to see the app in action.