B2B Single Sign-On

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

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.

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.