SSO Provider Setup

This guide provides step-by-step instructions for setting up SSO connections with various Identity Providers (IdPs) in Stytch.

If you're configuring a SAML connection, you'll need to perform the following steps:

0. Before you begin

• Ensure you have your organization_id and a SAML connection created in Stytch
• Ensure you have admin access to your IdP

1. Copy from Stytch

• acs_url and audience_uri from your SAML connection

2. Configure in your IdP

Create an application in your IdP.

• Enter the acs_url and audience_uri in their respective fields. Some IdPs call these SP SSO URL and SP Entity ID.
• Set up attribute mapping so the IdP returns at least email and name fields. We recommend passing a unique identifier as well.

3. Copy from your IdP

• Metadata URL, or...
• IdP SSO URL, IdP Entity ID, and X.509 Certificate

4. Configure in Stytch

Configure your IdP metadata with Stytch using one of two ways.

• If your IdP provides a metadata URL, add that via the Stytch Dashboard or the Update SAML Connection by Metadata URL route.
• If your IdP does not provide a metadata URL, add the IdP SSO URL, IdP Entity ID, and X.509 certificate via the Stytch Dashboard or the Update SAML Connection route.

Configure your attribute mapping in Stytch. Map email to the email field, first_name to the first name, last_name to the last name, and full_name to the full name. You only need either full_name or both first_name and last_name. You can do this in the Dashboard or via Update SAML Connection.

Example attribute mapping:

{
  "email": "NameID",
  "first_name": "firstName",
  "last_name": "lastName"
}

Expected result: Your SAML connection shows as Active in Stytch.

If you're configuring an OIDC connection, you'll need to perform the following steps:

0. Before you begin

• Ensure you have your organization_id and an OIDC connection created in Stytch
• Ensure you have admin access to your IdP

1. Copy from Stytch

• redirect_url from your OIDC connection

2. Configure in your IdP

Create a web application in your IdP.

• Select Authorization Code as the grant type and add the Stytch redirect_url as a Sign-in Redirect URI.
• Optionally add a Sign-out Redirect URI pointing to your app’s logout handler.

3. Copy from your IdP

• Client ID and Secret, as well as your Issuer URL (generally this is your IdP hostname)

4. Configure in Stytch

Configure your IdP client with Stytch.

• Add your Client ID, Secret, and Issuer URL via the Stytch Dashboard or the Update OIDC Connection route.

Expected result: Your OIDC connection shows as Active in Stytch.

If you don't already have an Okta admin account, the easiest way to do this is by creating an Okta Workforce Identity Cloud Developer Edition account. Once you're logged in to the Okta Admin Dashboard click Create App Integration in the Applications tab:

Select SAML 2.0 and continue to the General Settings form, enter the name of your application and (optionally) your application's logo.

In the Configure SAML form:

• Input the acs_url from your Stytch SSO Connection as the Single sign-on URL
• Input the audience_uri from your Stytch SSO Connection as the Audience URI (SP Entity ID)
• For Name ID format select EmailAddress
• For Application username select Email
• In Attribute Statements create three inputs:
  • Name: firstName; Name format: Basic; Value: user.firstName
  • Name: lastName; Name format: Basic; Value: user.lastName
  • Name: id; Name format: Basic; Value: user.id

Your configuration page should look like the following:

Save and continue, indicating that this is an internal application on the last screen.

Copy the Metadata URL from the Sign On Settings tab in your newly created Okta application.

In the Stytch Dashboard, click "configure" on your SSO Connection, and in the modal input the Metadata URL you just copied, and the following JSON for the Attribute Mapping.

{
    "email": "NameID",
    "first_name": "firstName",
    "last_name": "lastName",
    "idp_user_id": "id"
}

Click save. You should now see the SSO Connection as "Active". In the SSO Connections JIT Provisioning settings section above, select "Anyone" can JIT Provision through SSO Connections and save.

On the Assignments tab under your application in Okta, assign the application to team members who should have access to it by clicking Assign:

If you don't already have an Okta admin account, the easiest way to do this is by creating an Okta Workforce Identity Cloud Developer Edition account. Once you're logged in to the Okta Admin Dashboard and click Create App Integration in the Applications tab:

Select OIDC - OpenID Connect and Web Application:

Enter the name of your application and (optionally) your application's logo.

Under Grant type, select Authorization Code:

In the Sign-in redirect URIs section, add the redirect_url value from the Stytch connection object.

For the purposes of this guide, you do not need to add any Sign-out redirect URIs. In the future, you can (optionally) add a URI corresponding to a page in your application that logs the user out by revoking their Stytch session.

Under Controlled access, select Allow everyone in your organization to access and Enable immediate access with Federation Broker Mode and save. You may change these settings later, if desired.

In the General tab of your newly created Okta application, locate the Client ID in the Client Credentials section and Secret in the Client Secrets section:

In the Stytch Dashboard, click "configure" on your SSO Connection and input the Client ID and Secret from above and set the Issuer value to your Okta instance URL. This URL should look like https://dev-111111.okta.com and is viewable in the top right hand corner drop down under your email address. You can alternatively call the Update OIDC Connection endpoint with the client_id, client_secret and issuer fields.

Click save. You should now see the SSO Connection as "Active". In the SSO Connections JIT Provisioning settings section above, select "Anyone" can JIT Provision through SSO Connections and save.

Log into the Google Workspace Admin Console. Navigate to the Web and mobile apps tab under Apps:

Select Add custom SAML app from the Add app dropdown:

Enter the name of your application and (optionally) a description and your application's logo. Click Continue.

Copy the following information under Option 2 and input into your Stytch SSO Connection by clicking "configure":

• IdP Entity ID: the Entity ID from Google
• IdP SSO URL: the SSO URL from Google
• X.509 certificate: the Certificate from Google
• Attribute Mapping: input the below JSON:

{
    "email": "NameID",
    "first_name": "firstName",
    "last_name": "lastName"
}

Your Stytch SSO configuration view should look like the following:

Click save. You should now see the SSO Connection as "Active". In the SSO Connections JIT Provisioning settings section above, select "Anyone" can JIT Provision through SSO Connections and save.

In the Google Admin Console, enter the following information from the Stytch SSO Connection into the Service provider details form and then click Continue:

• ACS URL: acs_url from the Stytch SSO Connection
• Entity ID: audience_uri from the Stytch SSO Connection
• Name ID format: EMAIL
• Name ID: Basic Information > Primary email

On the next screen add the following two Attributes:

• Google Directory attributes: First name; App attributes: firstName
• Google Directory attributes: Last name; App attributes: lastName

Click Finish.

Navigate to the User access page for your new Google Workspace app:

Grant access to the Groups or Organizational Units of your choice. For the purposes of this guide, you can also simply set the Service status to ON for everyone in the All users in this account tab:

Log into Microsoft Entra Admin Center, navigate to Enterprise applications and select to create a new application.

Select create your own application at the top.

Name your application and select Integrate any other application you don't find in the gallery (Non-gallery) and then click Create.

Once your application is created, navigate to the Single Sign-On setup page and select SAML.

Click Edit on Basic SAML Configuration and add the following values from the SSO Connection you created in Stytch:

• Identifier (Entity ID): the Audience URI from your Stytch SSO Connection
• Reply URL (Assertion Consumer Service URL): the ACS URL from your Stytch SSO Connection

Leave the other values blank and click Save.

Next, edit the Attributes & Claims section. Click on the Unique User Identifier (Name ID) under Required Claim, and change the Source attribute to use user.primaryauthoritativeemail

Under Additional claims, delete the preconfigured options and create the following three claims:

• Claim Name: firstName Value: user.givenname
• Claim Name: lastName Value: user.surname
• Claim Name: id Value user.objectid Save.

Click

In the Stytch Dashboard (or with the UpdateSAMLConnection API) click "configure" on your SSO Connection and set the Metadata URL as the App Federation Metadata Url from the SAML Certificates section in your Entra app.

For Attribute Mapping on your Stytch SSO Connection set the following JSON:

{
  "email": "NameID",
  "first_name": "firstName",
  "last_name": "lastName",
  "idp_user_id": "id"
}

Click save on your Stytch SSO Connection, and you should now see the status as "Active". In the SSO Connections JIT Provisioning settings section above, select "Anyone" can JIT Provision through SSO Connections and save.

The last step is to add users to your application in Entra, which you can do by navigating to Users and groups and selecting "Add user/group".

Log into Microsoft Entra Admin Center, navigate to App registrations and select to create a New registration

Input a name and select Accounts in this organizational directory only for Supported account types and click Register

Navigate to the Authentication section and select "Add a platform" under Platform configurations

Select web and input the Redirect URI from the Stytch SSO Connection you created earlier. Leave the rest blank and click "Configure"

Navigate to Certificates & secrets and select "New client secret". Enter a description of your new secret key, select your desired secret expiration length, and click Add.

In the Stytch Dashboard, click "configure" on your SSO Connection and input the secret value as the Client Secret in Stytch

For Client ID and Issuer, navigate back to the Entra Overview section and copy over the following values into the Stytch OIDC Connection you are configuring:

• Client ID in Stytch: set to the Application (client) ID from Entra
• Issuer in Stytch: set to URL format https://login.microsoftonline.com/<YOUR_DIRECTORY_ID>/v2.0 where <YOUR_DIRECTORY_ID> is replaced with the Directory (tenant) ID from the Overview section

Click save. You should now see the SSO Connection as "Active". In the SSO Connections JIT Provisioning settings section above, select "Anyone" can JIT Provision through SSO Connections and save.