SSO

SSO (or Single Sign On) refers to a number of popular authentication frameworks that delegate authentication to an external identity provider (often shortened to IdP) like Okta, Google, or ForgeRock. These external identity providers are owned and managed by IT admins. A user relies on their membership from that provider to sign in instead of creating another password, and developers can enrich their users' experiences with the information shared by the providers.

The Javascript SDK provides methods to start and authenticate SSO flows that you can connect to your own UI.

Once a Member has successfully logged in, the SDK can be used to view and manage SAML and OIDC connections in the Organization if the Member's Role gives them permission to do so.

To learn more about our RBAC implementation, see our RBAC guide.

Methods

Start SSO flow

The sso.start() method starts an SSO flow by redirecting the browser to Stytch's SSO Start endpoint. The method will also generate a PKCE code_verifier and store it in localstorage on the device.

Method parameters

connection_id* string
login_redirect_url string
signup_redirect_url string
import { useStytchB2BClient } from '@stytch/react-native/b2b';

export const Login = () => {
  const stytchClient = useStytchB2BClient();

  const startSSO = () =>
    stytchClient.sso.start({
      connection_id: 'saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9',
      login_redirect_url: 'https://example.com/authenticate',
      signup_redirect_url: 'https://example.com/authenticate',
    });

  return <button onClick={startSSO}>Log in with Okta</button>;
};

Authenticate

The authenticate method wraps the authenticate SSO API endpoint which validates the SSO token passed in.

If there is a current Member Session, the SDK will call the endpoint with the session token. This will add the new factor to the existing Member Session.

If there is an intermediate session token, the SDK will call the endpoint with it. If the resulting set of factors satisfies the organization's primary authentication requirements and MFA requirements, the intermediate session token will be consumed and converted to a Member Session. If not, the same intermediate session token will be returned.

If this method succeeds and the Member is not required to complete MFA, the Member will be logged in, granted an active session, and the session data will be persisted on device.

If this method succeeds and MFA is required, the intermediate session token will be persisted on device.

You can listen for successful login events anywhere in the codebase with the stytch.session.onChange() method or useStytchMemberSession hook.

Method parameters

sso_token* string
session_duration_minutes* int
locale string
import React, { useEffect } from 'react';
import { useStytchB2BClient, useStytchMemberSession } from '@stytch/react-native/b2b';

export const Authenticate = () => {
  const stytchClient = useStytchB2BClient();
  const { session } = useStytchMemberSession();

  useEffect(() => {
    if (session) {
      window.location.href = 'https://example.com/profile';
    } else {
      const token = new URLSearchParams(window.location.search).get('token');
      stytchClient.oauth.authenticate({
        oauth_token: token,
        session_duration_minutes: 60,
      });
    }
  }, [stytchClient, session]);

  return <div>Loading</div>;
};

RESPONSE

{
    "status_code": 200,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
    "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
    "session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
    "session_jwt": "eyJ...",
    "intermediate_session_token": "",
    "member_authenticated": true,
    "mfa_required": null,
    "session": {...},
    "member": {...},
    "organization": {...},
  }

Get SSO Connections

The Get SSO Connections method wraps the Get SSO Connections API endpoint. The organization_id will be automatically inferred from the logged-in Member's session. This method cannot be used to get SSO connections from other Organizations.

import { useStytchB2BClient } from '@stytch/react-native/b2b';

export const GetSSOConnections = () => {
  const stytch = useStytchB2BClient();

  const getSSOConnections = () => {
    stytch.sso.getConnections();
  };

  return <button onClick={getSSOConnections}>Get SSO Connections</button>;
};

RESPONSE

200
{
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "status_code": 200,
    "saml_connections": [{...}, {...}],
    "oidc_connections": [{...}, {...}]
}

Delete SSO Connection

The Delete SSO Connection method wraps the Delete SSO Connection API endpoint. The organization_id will be automatically inferred from the logged-in Member's session. This method cannot be used to delete SSO connections in other Organizations.

Method parameters

connection_id* string
import { useStytchB2BClient } from '@stytch/react-native/b2b';

export const DeleteSSOConnection = () => {
  const stytch = useStytchB2BClient();

  const deleteSSOConnection = () => {
    stytch.sso.deleteConnection('saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9');
  };

  return <button onClick={deleteSSOConnection}>Delete SSO Connection</button>;
};

RESPONSE

200
{
  "connection_id": "saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "status_code": 200
}

Create SAML Connection

The Create SAML Connection method wraps the Create SAML Connection API endpoint. The organization_id will be automatically inferred from the logged-in Member's session. This method cannot be used to create SAML connections in other Organizations.

Method parameters

display_name string
import { useStytchB2BClient } from '@stytch/react-native/b2b';

export const CreateSAMLConnection = () => {
  const stytch = useStytchB2BClient();

  const createSAMLConnection = () => {
    stytch.sso.saml.createConnection({
      display_name: 'Example SAML connection',
    });
  };

  return <button onClick={createSAMLConnection}>Create a SAML Connection</button>;
};

RESPONSE

200
{
	"connection": {
		"acs_url":  "https://test.stytch.com/v1/b2b/sso/callback/saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
		"attribute_mapping": {
			"email": "email",
			"full_name": "name",
		},
		"audience_uri":  "https://test.stytch.com/v1/b2b/sso/callback/saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
		"alternative_audience_uri": "",
		"connection_id": "saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
		"display_name": "",
		"identity_provider": "",
		"idp_entity_id": "",
		"idp_sso_url": "",
		"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
		"signing_certificates": [
			{
				"certificate": "-----BEGIN CERTIFICATE-----\n...base64 blob...\n-----END CERTIFICATE",
				"id": "",
				"created_at": "2023-01-01T00:00:00Z",
				"expires_at": "2033-01-01T00:00:00Z",
				"issuer": "Stytch"
			}
		],
		"status": "pending",
		"verification_certificates": [],
		"identity_provider": "generic"
	},
	"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
	"status_code": 200
}

Update SAML Connection

The Update SAML Connection method wraps the Update SAML Connection API endpoint. The organization_id will be automatically inferred from the logged-in Member's session. This method cannot be used to update SAML connections in other Organizations.

Note that a newly created connection will not become active until all of the following are provided:

  • idp_sso_url
  • attribute_mapping
  • idp_entity_id
  • x509_certificate

Method parameters

connection_id* string
idp_entity_id string
display_name string
attribute_mapping object
idp_sso_url string
x509_certificate string
saml_connection_implicit_role_assignments array[object]
saml_group_implicit_role_assignments array[object]
import { useStytchB2BClient } from '@stytch/react-native/b2b';

export const UpdateSAMLConnection = () => {
  const stytch = useStytchB2BClient();

  const updateSAMLConnection = () => {
    stytch.sso.saml.updateConnection({
      connection_id: 'saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9',
      idp_sso_url: 'https://idp.example.com/51861cbc-d3b9-428b-9761-227f5fb12be9/sso/saml',
    });
  };

  return <button onClick={updateSAMLConnection}>Update SAML Connection</button>;
};

RESPONSE

200
{
  "connection": {
		"acs_url": "https://test.stytch.com/v1/b2b/sso/callback/saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
		"attribute_mapping": {
			"email": "email",
			"full_name": "name"
		},
		"audience_uri":  "https://test.stytch.com/v1/b2b/sso/callback/saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
		"alternative_audience_uri": "",
		"connection_id": "saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
		"display_name": "Example SAML Connection",
		"idp_entity_id": "https://idp.example.com/51861cbc-d3b9-428b-9761-227f5fb12be9",
		"idp_sso_url": "https://idp.example.com/51861cbc-d3b9-428b-9761-227f5fb12be9/sso/saml",
		"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
		"signing_certificates": [
			{
				"certificate": "-----BEGIN CERTIFICATE-----\n...base64 blob...\n-----END CERTIFICATE",
				"created_at": "2023-01-01T00:00:00Z",
				"expires_at": "2033-01-01T00:00:00Z",
				"id": "",
				"issuer": "Stytch"
			}
		],
		"status": "active",
		"identity_provider": "generic",
		"verification_certificates": [
			{
				"certificate": "-----BEGIN CERTIFICATE-----\n...base64 blob...\n-----END CERTIFICATE",
				"created_at": "2023-01-01T00:00:00Z",
				"expires_at": "2033-01-01T00:00:00Z",
				"id": "saml-verification-key-test-5ccbc642-9373-42b8-928f-c1646c868701",
				"issuer": ""
			}
		]
	},
	"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
	"status_code": 200
}

Update SAML Connection by Metadata URL

The Update SAML Connection by Metadata URL method wraps the Update SAML Connection by Metadata URL API endpoint. The organization_id will be automatically inferred from the logged-in Member's session. This method cannot be used to update SAML connections in other Organizations.

Method parameters

connection_id* string
metadata_url string
import { useStytchB2BClient } from '@stytch/react-native/b2b';

export const UpdateSAMLConnection = () => {
  const stytch = useStytchB2BClient();

  const updateSAMLConnection = () => {
    stytch.sso.saml.updateConnectionByURL({
      connection_id: 'saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9',
      metadata_url: 'https://idp.example.com/app/51861cbc-d3b9-428b-9761-227f5fb12be9/sso/saml/metadata',
    });
  };

  return <button onClick={updateSAMLConnection}>Update SAML Connection</button>;
};

RESPONSE

200
{
  "connection": {
		"acs_url": "https://test.stytch.com/v1/b2b/sso/callback/saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
		"attribute_mapping": {
			"email": "email",
			"full_name": "name"
		},
		"audience_uri":  "https://test.stytch.com/v1/b2b/sso/callback/saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
		"connection_id": "saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9",
		"display_name": "Example SAML Connection",
		"idp_entity_id": "https://idp.example.com/51861cbc-d3b9-428b-9761-227f5fb12be9",
		"idp_sso_url": "https://idp.example.com/51861cbc-d3b9-428b-9761-227f5fb12be9/sso/saml",
		"organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
		"signing_certificates": [
			{
				"certificate": "-----BEGIN CERTIFICATE-----\n...base64 blob...\n-----END CERTIFICATE",
				"created_at": "2023-01-01T00:00:00Z",
				"expires_at": "2033-01-01T00:00:00Z",
				"id": "",
				"issuer": "Stytch"
			}
		],
		"identity_provider": "generic",
		"status": "active",
		"verification_certificates": [
			{
				"certificate": "-----BEGIN CERTIFICATE-----\n...base64 blob...\n-----END CERTIFICATE",
				"created_at": "2023-01-01T00:00:00Z",
				"expires_at": "2033-01-01T00:00:00Z",
				"id": "saml-verification-key-test-5ccbc642-9373-42b8-928f-c1646c868701",
				"issuer": ""
			}
		]
	},
	"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
	"status_code": 200
}

Delete SAML Verification Certificate

The Delete SAML Verification Certificate method wraps the Delete Verification Certificate API endpoint. The organization_id will be automatically inferred from the logged-in Member's session. This method cannot be used to delete verification certificates in other Organizations.

You may need to do this when rotating certificates from your IdP, since Stytch allows a maximum of 5 certificates per connection. There must always be at least one certificate per active connection.

Method parameters

connection_id* string
certificate_id* string
import { useStytchB2BClient } from '@stytch/react-native/b2b';

export const DeleteVerificationCertificate = () => {
  const stytch = useStytchB2BClient();

  const deleteVerificationCertificate = () => {
    stytch.sso.saml.deleteVerificationCertificate({
      connection_id: 'saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9',
      certificate_id: 'saml-verification-key-test-5ccbc642-9373-42b8-928f-c1646c868701',
    });
  };

  return <button onClick={deleteVerificationCertificate}>Delete Verification Certificate</button>;
};

RESPONSE

200
{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "certificate_id": "saml-verification-key-test-5ccbc642-9373-42b8-928f-c1646c868701",
}

Create OIDC Connection

The Create OIDC Connection method wraps the Create OIDC Connection API endpoint. The organization_id will be automatically inferred from the logged-in Member's session. This method cannot be used to create OIDC connections in other Organizations.

Method parameters

display_name string
import { useStytchB2BClient } from '@stytch/react-native/b2b';

export const CreateOIDCConnection = () => {
  const stytch = useStytchB2BClient();

  const createOIDCConnection = () => {
    stytch.sso.oidc.createConnection({
      display_name: 'Example OIDC connection',
    });
  };

  return <button onClick={createOIDCConnection}>Create an OIDC Connection</button>;
};

RESPONSE

200
{
  "connection": {
    "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
    "connection_id": "oidc-connection-test-b6c714c2-7413-4b92-a0f1-97aa1085aeff",
    "display_name": "Example OIDC Connection",
    "redirect_url": "https://test.stytch.com/v1/b2b/sso/callback/oidc-connection-test-b6c714c2-7413-4b92-a0f1-97aa1085aeff",
    "status": "active",
    "issuer": "https://idp.example.com/",
    "client_id": "s6BhdRkqt3",
    "client_secret": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4=",
    "authorization_url": "https://idp.example.com/authorize",
    "token_url": "https://idp.example.com/oauth2/token",
    "userinfo_url": "https://idp.example.com/userinfo",
    "jwks_url": "https://idp.example.com/oauth2/jwks",
    "identity_provider": "generic"
    },
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "status_code": 200
}

Update OIDC Connection

The Update OIDC Connection method wraps the Update OIDC Connection API endpoint. The organization_id will be automatically inferred from the logged-in Member's session. This method cannot be used to update OIDC connections in other Organizations.

When the value of issuer changes, Stytch will attempt to retrieve the OpenID Provider Metadata document found at ${issuer}/.well-known/openid-configuration. If the metadata document can be retrieved successfully, Stytch will use it to infer the values of authorization_url, token_url, jwks_url, and userinfo_url. The client_id and client_secret values cannot be inferred from the metadata document, and must be passed in explicitly.

If the metadata document cannot be retrieved, Stytch will still update the connection using values from the request body.

If the metadata document can be retrieved, and values are passed in the request body, the explicit values passed in from the request body will take precedence over the values inferred from the metadata document.

Note that a newly created connection will not become active until all of the following fields are provided:

  • issuer
  • client_id
  • client_secret
  • authorization_url
  • token_url
  • userinfo_url
  • jwks_url

Method parameters

connection_id* string
display_name string
issuer string
client_id string
client_secret string
authorization_url string
token_url string
userinfo_url string
jwks_url string
import { useStytchB2BClient } from '@stytch/react-native/b2b';

export const UpdateOIDCConnection = () => {
  const stytch = useStytchB2BClient();

  const updateOIDCConnection = () => {
    stytch.sso.oidc.updateConnection({
      connection_id: 'oidc-connection-test-b6c714c2-7413-4b92-a0f1-97aa1085aeff',
      client_id: 's6BhdRkqt3',
      client_secret: 'SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4=',
    });
  };

  return <button onClick={updateOIDCConnection}>Update OIDC Connection</button>;
};

RESPONSE

200
{
  "connection": {
    "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
    "connection_id": "oidc-connection-test-b6c714c2-7413-4b92-a0f1-97aa1085aeff",
    "display_name": "Example OIDC Connection",
    "redirect_url": "https://test.stytch.com/v1/b2b/sso/callback/oidc-connection-test-b6c714c2-7413-4b92-a0f1-97aa1085aeff"
    "status": "active",
    "issuer": "https://idp.example.com/",
    "client_id": "s6BhdRkqt3",
    "client_secret": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4=",
    "authorization_url": "https://idp.example.com/authorize"
    "token_url": "https://idp.example.com/oauth2/token"
    "userinfo_url": "https://idp.example.com/userinfo"
    "jwks_url": "https://idp.example.com/oauth2/jwks",
    "identity_provider": "generic"
    },
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "status_code": 200
}