Stytch's Single Sign On (SSO) product allows your customers to log into your application via third party Identity Providers, like Okta. In this guide, you'll learn how to configure an Okta SAML SSO connection, which is something that your customers will need to complete before their team members will be able to log into your application via SSO.

By the end of this guide, you'll have:

• a new Okta SAML Connection that is fully configured and ready for use.
• a new Okta application that can be used to provision access to your application.
• a Stytch B2B implementation that can use SSO for authentication.

Before you start

• Create a Stytch B2B project via the Stytch Dashboard if you don't have one already. To do so, click on your existing project name in top left corner of the Dashboard, click Create a new project, and then select B2B Authentication.
• Create a new Organization by calling our Create an Organization endpoint:

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"
	}'

Step 1: Create a new SAML connection

Call our Create SAML Connection endpoint in order to create a new SAML Connection. Include the organization_id that you'd like the Connection to belong to and a display_name for the Connection like "Okta".

curl --request POST \
	--url https://test.stytch.com/v1/b2b/sso/saml/{ORGANIZATION_ID} \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	  "display_name": "Okta"
	}'

Save the acs_url, audience_uri, and connection_id values from the connection object in the Create SAML connection response for use in Step 2, where you'll use those values to configure a new Okta Application, and later in Step 4.

Step 2: Create and configure a new Okta Application

1. Log into okta.com and click Create App Integration in the Applications tab:

   

2. Select SAML 2.0.

3. In the General Settings form, enter the name of your application and (optionally) your application's logo.

4. In the Configure SAML form, use these steps for the following fields:

   • Single sign-on URL: Enter the acs_url value from the connection object.

     • Use this for Recipient URL and Destination URL should remain checked.
   • Audience URI (SP Entity ID): Enter the audience_uri value from the connection object.
   • Default RelayState: This value can remain blank.
   • Name ID format: Select EmailAddress.
   • Application username: Any value here should suffice.
   • Attribute Statements: Create these data inputs.

     1. Name: firstName; Name format: Basic; Value: user.firstName
     2. Name: lastName; Name format: Basic; Value: user.lastName

Now that you've created and configured a new Okta Application, you're ready to update the SSO Connection from Step 1 with additional data surfaced by Okta.

Step 3: Configure your SAML Connection

Click the View SAML setup instructions button on the Sign On tab of your newly created Okta application:

You'll need to use the following Okta values:

• Identity Provider Single Sign-On URL
• X.509 Certificate (including the BEGIN_CERTIFICATE and END_CERTIFICATE lines)
• Identity Provider Issuer

Step 4: Call the Update SAML Connection endpoint

In addition to the Okta information in Step 3, you'll also need these parameters in order to call the Update SAML Connection endpoint:

• the organization_id and connection_id from Step 1.
• an attribute_mapping object with the following structure.

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

With all the necessary data, your Update SAML Connection API request should look like this:

curl --request PUT \
	--url https://test.stytch.com/v1/b2b/sso/saml/{ORGANIZATION_ID}/connections/{CONNECTION_ID} \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
		"idp_entity_id": "{IDENTITY_PROVIDER_ISSUER}",
		"idp_sso_url": "{IDENTITY_PROVIDER_SINGLE_SIGN-ON_URL}",
		"x509_certificate": "{X.509_CERTIFICATE}",
        "attribute_mapping": {
		  "email": "NameID",
		  "first_name": "firstName",
		  "last_name": "lastName"
		}
	}'

After a successful Stytch API call, both your Okta Application and your SAML Connection are now fully configured. The only remaining step is to provision access.

Step 5: Provision access to your application

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

You should now be able to successfully complete an SSO login flow via our Start SSO login flow and Authenticate SSO login endpoints using your new Okta Connection!

What's next

Build a user interface that allows users to initiate the SSO login flow. You'll also need a page to handle the redirect back to your application at the end of the SSO flow.

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.