Skip to main content

Organizations for B2B Single Sign-On OIDC & SAML

Need help?

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 or SAML SSO connections. All members of an organization must use one of the organization's OIDC or SAML 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 or SAML SSO connections.

Some identity providers do not validate email domain ownership. This can lead to situations where Organization login is configured for a specified domain such as @example.com, but due to this lack of this email domain ownership validation by the identity provider, a users with other email domains such as @gmail.com can still authenticate successfully via the identity provider.

This will end up with the user being part of the configured organization in your Ory project, even if the domain does not match any of the configured domains.

Organizations require identifier-first authentication and two-step registration when using Account Experience 2.x or Ory Elements 1.x.

Manage organizations​

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

Authentication → Organizations in the Ory Console.

Create SSO connections for an organization​

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

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

Pre-provisioning identities in an organization​

After creating an organization, you can pre-provision identities in it. This is useful when you need to create related data in your system but need the identity to be created in Ory Network first, before the user logs in for the first time.

To achieve this, set the organization_id property to the ID of the created organization in the identity, either when creating the identity, or by updating the identity's data using the Ory APIs.

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.

  1. Go to Authentication → Organizations 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).
  1. Navigate to your login screen to test the SAML connection.

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

Data mapping​

You can configure the mapping of SAML attributes to Ory's identity schema using Jsonnet. All custom SAML attributes defined at the Identity Provider (IdP) will be available in the raw_claims object within claims. These attributes can then be mapped to the Ory identity schema.

warning

Ensure that the appropriate identity schema is created before mapping attributes. The email attribute is natively available in claims.email, everything else is nested under claims.raw_claims.

Example SAML data mapping​

Mapping firstName and lastName from the SAML Identity Provider to the Ory identity schema (traits).

local claims = std.extVar('claims');

{
  identity: {
    traits: {
      email: claims.email,
      [if std.objectHas(claims, "raw_claims") && std.objectHas(claims.raw_claims, "firstName") then "firstName" else null]: claims.raw_claims.firstName,
      [if std.objectHas(claims, "raw_claims") && std.objectHas(claims.raw_claims, "lastName") then "lastName" else null]: claims.raw_claims.lastName,
    },
  },
}

Self-service organization onboarding​

Need help?

The onboarding portal is a powerful tool designed to simplify complex identity and access management tasks for businesses and their partners.

Streamline organization onboarding​

The onboarding portal simplifies setting up and managing identity connections with external organizations.

The onboarding portal aims to:

  • Simplify complex integrations: A self-service or guided experience removes the need for client IT administrators to be SAML/SCIM experts.
  • Reduce onboarding time: External administrators configure connections directly through a user-friendly interface instead of lengthy manual setup and back-and-forth communication.
  • Enhance security and control: Shareable links don't expose sensitive information. Administrators configure their side securely while maintaining control over their IdP settings.
  • Enable self-service: SaaS providers can let customers manage their own SSO/SCIM connections, freeing up engineering and support teams.
  • Scale B2B integrations: Manual management becomes unsustainable as enterprise clients grow. The portal provides a scalable solution.
  • Validate instantly: Test SSO connections immediately to verify integration before deployment, reducing troubleshooting time.

The onboarding is relevant for SaaS providers serving B2B or B2B2C customers, enterprise IT administrators managing identity providers, and developers building multi-tenant applications.

Provider support:

  • The onboarding portal supports all well known providers. You can also connect any SAML/OIDC compliant provider using the Generic SAML/OIDC IdP option. If you don't find your provider listed, please contact Ory Support.

SCIM support​

The onboarding portal allows you to set up SCIM provisioning. For an organization, you can create, update, and remove SCIM servers. Guided walkthroughs are available for Microsoft Entra ID, Google Workspace, and Okta.

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

On the Edit Organization page, under the Onboarding Portal section, click Generate link. If your project has a custom domain configured, you must choose between the project slug and the custom domain as the link's base URL. You can then share this link with the organization administrators.

https://console.ory.sh/projects/<id>/authentication/organizations/<id>/edit

Onboarding portal link

Expiry​

The link generated from the Ory Network Console expires in 7 days. The API allows you to set an expiration value with a minimum expiry of 1 day. Once the link expires, it no longer works. You can also delete the link and generate a new one.

Handover and using the portal​

Once you generate the link, share it with the organization's administrator. They can access this link multiple times until its expiration to manage SSO and SCIM connections.

https://<your-slug>.projects.oryapis.com/onboarding/<unique-token>

Onboarding portal

Manage SSO​
https://<your-slug>.projects.oryapis.com/onboarding/<unique-token>/sso

Onboarding portal

Manage SCIM​
https://<your-slug>.projects.oryapis.com/onboarding/<unique-token>/scim

Onboarding portal