B2B Single Sign-On & SAML

info

Organizations are only available in Ory Network and are not supported in self-hosted Ory Kratos. If you have any questions, or if you would like more information about transitioning to Ory Network, please don't hesitate to reach out.

Organizations are a way to group users within one project. An organization always belongs to one Ory project. Within a project, an identity can belong to an organization or remain without an organization. Organizations contain multiple OIDC SSO connections. All members of an organization must use one of the organization's OIDC SSO connections to log in.

An organization can have multiple domains. Registrations for email addresses with a domain that belongs to an organization must go through one of the organization's OIDC SSO connections.

Manage organizations

Ory Console

To create, update, or delete organizations via the Ory Console, go to

Authentication → Enterprise SSO in the Ory Console.

API

Organizations can also be managed using the Ory API. To authenticate your requests, create a workspace API key.

All examples below use curl to make HTTP requests. You can use any HTTP client to make these requests.

Before copy & pasting the following examples, export your PROJECT_ID and WORKSPACE_API_KEY:

export PROJECT_ID="..."
export WORKSPACE_API_KEY="ory_wak_..."

List organizations

curl -X GET --location "https://api.console.ory.sh/projects/$PROJECT_ID/organizations" \
     -H "Authorization: Bearer $WORKSPACE_API_KEY"

Create an organization

curl -X POST --location "https://api.console.ory.sh/projects/$PROJECT_ID/organizations" \
     -H "Authorization: Bearer $WORKSPACE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "label":  "Hello demo",
           "domains": ["test.example.com"]
         }'

Get an organization

curl -X GET --location "https://api.console.ory.sh/projects/$PROJECT_ID/organizations/$ORGANIZATION_ID" \
     -H "Authorization: Bearer $WORKSPACE_API_KEY"

Delete an organization

curl -X DELETE --location "https://api.console.ory.sh/projects/$PROJECT_ID/organizations/$ORGANIZATION_ID" \
     -H "Authorization: Bearer $WORKSPACE_API_KEY"

Create SSO connections for an organization

After creating an organization, continue by adding one or more SSO OIDC connections.

Ory Console

Go to Authentication → Enterprise SSO in the Ory Console and continue by configuring the selected organization.

API

The SSO connections are part of the project configuration. To authenticate, use the same workspace API key as for managing organizations. The examples use curl to make HTTP requests and jq to parse JSON response.

Create an SSO connection

curl -X PATCH --location "https://api.console.ory.sh/projects/$PROJECT_ID" \
     -H "Authorization: Bearer $WORKSPACE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '[
           {
             "op": "add",
             "path": "/services/identity/config/selfservice/methods/oidc/config/providers/-",
             "value": {
               "client_id": "...",
               "client_secret": "...",
               "id": "ory-GPx1yPH4",
               "issuer_url": "https://example.org",
               "label": "My OIDC provider",
               "mapper_url": "base64://ZnVuY3Rpb24oY3R4KSBjdHg=",
               "organization_id": "6bb1c7d1-3b3e-4995-9e09-35649dc45a2b",
               "provider": "generic",
               "pkce": "auto", # or "force", "never", see note on redirect URL below
               "scope": ["openid", "offline_access", "email"]
             }
           }
         ]' \
   | jq ".project.services.identity.config.selfservice.methods.oidc.config.providers"

Some notes on the fields of the JSON payload:

• client_id and client_secret are the credentials of the OIDC provider.
• id is a unique identifier for the connection, and part of the redirect URL, and can be a random string. This is $PROJECT_ID below.
• organization_id is the ID of the organization to which the connection belongs, and part of the redirect URL. This is $ORGANIZATION_ID below.
• mapper_url is the URL to a JSONnet file that maps the OIDC provider's claims to Ory's identity schema. You can use the base64 scheme to embed the JSONnet file directly in the JSON payload.
• pkce determines whether Ory Identities will use PKCE during the OIDC flow. See the note below and the PKCE documentation for details.

tip

The redirect URL to be set in the external OIDC provider's configuration is https://$PROJECT_SLUG.projects.oryapis.com/self-service/methods/oidc/organization/$ORGANIZATION_ID/callback/$PROVIDER_ID.

If you set pkce: force, you must whitelist a different redirect URL with the OIDC provider: https://$PROJECT_SLUG.projects.oryapis.com/self-service/methods/oidc/callback.

See the PKCE documentation for details.

List SSO connections

curl -X GET --location "https://api.console.ory.sh/projects/$PROJECT_ID" \
     -H "Authorization: Bearer $WORKSPACE_API_KEY" \
   | jq ".services.identity.config.selfservice.methods.oidc.config.providers"

Result:

[
  {
    "client_id": "...",
    "client_secret": "...",
    "id": "ory-GPx1yPH4",
    "issuer_url": "https://example.org",
    "label": "My OIDC provider",
    "mapper_url": "https://storage.googleapis.com/bac-gcs-production/94292215dbabe405bebff988b5356663fcf5cba35b10fc6ca2cfea7bc7049e906e01d271a3daeb844203efdfbf2cff356274daa63d5afc2a379bbe93b8b40e63.jsonnet",
    "organization_id": "6bb1c7d1-3b3e-4995-9e09-35649dc45a2b",
    "provider": "generic",
    "scope": ["openid", "offline_access", "email"]
  }
]

Delete an SSO connection

To delete an organization, you need to specify the index of the connection in the path field. The index is the position of the SSO connection in the list of connections.

curl -X PATCH --location "https://api.console.ory.sh/projects/$PROJECT_ID" \
     -H "Authorization: Bearer $WORKSPACE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '[
           {
             "op": "remove",
             "path": "/services/identity/config/selfservice/methods/oidc/config/providers/0"
           }
         ]' \
   | jq ".project.services.identity.config.selfservice.methods.oidc.config.providers"

Note that the organization_id field contains the organization ID to which the connection belongs.

See it live

After having set up everything, go to your registration page. Entering an email that ends with the organization's domain, such as @my.example.com from the example above, shows a Sign in with SSO button instead of the password field. Clicking it will take you to sign in with the SSO connection. The SSO connection is not visible for email addresses that are not managed by the organization.

SAML

SAML (Security Assertion Markup Language) is an XML-based open standard used for exchanging authentication and authorization data between parties. The SAML integration in Ory Network uses the B2B Organization feature.

SAML via Ory Network

This guide will walk you through the steps required to set up SAML Single Sign-On (SSO) with Ory Network.

Prerequisites

Before proceeding, ensure you are on a plan that supports SAML SSO. SAML is available exclusively on select Enterprise plans. Contact us if you need SAML support.

Ory Console

1. Go to Authentication → Enterprise SSO in the Ory Console to create an organization.
2. Select "Add a new Enterprise SAML SSO connection" and follow the instructions to configure the SAML connection. Fill out the following form fields:

• Label: A descriptive name for the SAML connection. This will be displayed to users.
• Data mapping: A mapping from the SAML attributes to Ory's identity schema.
• Raw IDP metadata XML: The XML metadata file from your SAML Identity Provider (IdP).

3. Navigate to your login screen to test the SAML connection.

API

Create an organization

curl -X POST --location "https://api.console.ory.sh/projects/$PROJECT_ID/organizations" \
     -H "Authorization: Bearer $WORKSPACE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "label":  "SAML organzation",
           "domains": ["example.com"]
         }'

Enable SAML authentication

curl -X PATCH --location "https://api.console.ory.sh/projects/$PROJECT_ID" \
     -H "Authorization: Bearer $WORKSPACE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '[
           {
             "op": "replace",
             "path": "/services/identity/config/selfservice/methods/saml/enabled",
             "value": true
           }
         ]' \
   | jq ".project.services.identity.config.selfservice.methods.saml"

Create a SAML connection

curl -X PATCH --location "https://api.console.ory.sh/projects/$PROJECT_ID" \
     -H "Authorization: Bearer $WORKSPACE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '[
           {
             "op": "add",
             "path": "/services/identity/config/selfservice/methods/saml/config/providers/-",
             "value": {
               "id": "some-provider-id",
               "label": "My SAML provider",
               "mapper_url": "base64://...",
               "raw_idp_metadata_xml": "base64://...",
               "organization_id": "$ORGANIZATION_ID"
             }
           }
         ]' \
   | jq ".project.services.identity.config.selfservice.methods.saml"

• label: A descriptive name for the SAML connection. This will be displayed to users.
• mapper_url: A mapping from the SAML attributes to Ory's identity schema.
• raw_idp_metadata_xml: The XML metadata file from your SAML Identity Provider (IdP).

The SAML application callback URL to set at our SAML Identity Provider is: https://api.console.ory.sh/saml/api/oauth/saml

SAML via BoxyHQ

note

Previously a third party integration provided SAML SSO in Ory Network. The third party BoxyHQ integration is still supported for backwards compatibility, but the native SAML support in Ory Network is recommended for new projects. Please contact us Ory Support for any questions.

Prerequisites

Before proceeding, ensure you have the following:

• Access to Ory Network
• An active account with BoxyHQ
• Ory CLI

Configuration

To set up the integration, you'll need to get your Ory Network session token:

• Install the Ory CLI on your system.
• Run ory auth to sign into your Ory Network account.
• Locate the session token in the .ory-cloud.json file in your home folder. This token starts with the prefix ory_st. You can use cat ~/.ory-cloud.json | grep 'ory_st' to find it.

You'll also need your Ory Project ID. You can find this in your Ory Network settings.

Next, you'll configure the session token and Project ID in BoxyHQ.

Follow these steps:

• Log into your BoxyHQ account.
• Create a new Product if you haven't already.
• Navigate to Settings > Ory Integration.
• Paste your session token and Project ID into the respective input fields and save the configuration.

Once configured, the integration between BoxyHQ and Ory Network will automatically set up a new Organization and a generic OIDC connection whenever you create a new SSO connection on BoxyHQ. All user management will then flow through Ory Network.

To verify the integration, navigate to your Ory Account Experience UI and enter an email associated with the domain you configured. If successful, the "Sign in with SSO" button should appear.