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 cann 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_urlstring

signup_redirect_urlstring
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 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

localestring
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.

This method is not available for unauthenticated end users. In order to call this method, there must be a valid Member Session containing the necessary Role to complete this action. This method requires the Member to have permission to perform the get action on the stytch.sso Resource.

In addition, Member actions & permissions must be enabled in the SDK Configuration page of the Stytch dashboard. To learn more about our RBAC implementation, see our RBAC guide.

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.

This method is not available for unauthenticated end users. In order to call this method, there must be a valid Member Session containing the necessary Role to complete this action. This method requires the Member to have permission to perform the delete action on the stytch.sso Resource.

In addition, Member actions & permissions must be enabled in the SDK Configuration page of the Stytch dashboard. To learn more about our RBAC implementation, see our RBAC guide.


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.

This method is not available for unauthenticated end users. In order to call this method, there must be a valid Member Session containing the necessary Role to complete this action. This method requires the Member to have permission to perform the create action on the stytch.sso Resource.

In addition, Member actions & permissions must be enabled in the SDK Configuration page of the Stytch dashboard. To learn more about our RBAC implementation, see our RBAC guide.


Method parameters


display_namestring
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": "",
		"idp": "",
		"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": []
	},
	"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

This method is not available for unauthenticated end users. In order to call this method, there must be a valid Member Session containing the necessary Role to complete this action. This method requires the Member to have permission to perform the update action on the stytch.sso Resource.

In addition, Member actions & permissions must be enabled in the SDK Configuration page of the Stytch dashboard. To learn more about our RBAC implementation, see our RBAC guide.


Method parameters


connection_id*string

idp_entity_idstring

display_namestring

attribute_mappingobject

idp_sso_urlstring

x509_certificatestring

saml_connection_implicit_role_assignmentsarray[object]

saml_group_implicit_role_assignmentsarray[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",
		"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.

This method is not available for unauthenticated end users. In order to call this method, there must be a valid Member Session containing the necessary Role to complete this action. This method requires the Member to have permission to perform the update action on the stytch.sso Resource.

In addition, Member actions & permissions must be enabled in the SDK Configuration page of the Stytch dashboard. To learn more about our RBAC implementation, see our RBAC guide.


Method parameters


connection_id*string

metadata_urlstring
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"
			}
		],
		"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.

This method is not available for unauthenticated end users. In order to call this method, there must be a valid Member Session containing the necessary Role to complete this action. This method requires the Member to have permission to perform the update action on the stytch.sso Resource.

In addition, Member actions & permissions must be enabled in the SDK Configuration page of the Stytch dashboard. To learn more about our RBAC implementation, see our RBAC guide.


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.

This method is not available for unauthenticated end users. In order to call this method, there must be a valid Member Session containing the necessary Role to complete this action. This method requires the Member to have permission to perform the create action on the stytch.sso Resource.

In addition, Member actions & permissions must be enabled in the SDK Configuration page of the Stytch dashboard. To learn more about our RBAC implementation, see our RBAC guide.


Method parameters


display_namestring
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"
    },
  "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

This method is not available for unauthenticated end users. In order to call this method, there must be a valid Member Session containing the necessary Role to complete this action. This method requires the Member to have permission to perform the update action on the stytch.sso Resource.

In addition, Member actions & permissions must be enabled in the SDK Configuration page of the Stytch dashboard. To learn more about our RBAC implementation, see our RBAC guide.


Method parameters


connection_id*string

display_namestring

issuerstring

client_idstring

client_secretstring

authorization_urlstring

token_urlstring

userinfo_urlstring

jwks_urlstring
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"
    },
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "status_code": 200
}