Enterprise SSO (SAML / OIDC)

PropelAuth’s Enterprise SSO support allows your users to connect their organizations to their own identity provider, either through SAML or OIDC. We currently provide integrations for Google, Okta, Entra, OneLogin, JumpCloud, Duo, and Rippling. However, we also offer generic integrations that will work with any IdP that supports SAML or OIDC.

One of the best things about our Enterprise SSO integration is that your code doesn’t need to change at all when you close your first enterprise customer. SAML and OIDC are an implementation detail of how an organization manages their users within your product. Any code you write that deals with organizations will work, regardless of the method that organization uses to manage its members.

Enabling Enterprise SSO in Your Project

Enable Enterprise SSO for your PropelAuth project by navigating to the Enterprise SSO / SCIM page in your PropelAuth dashboard. This will add the option to login via Enterprise SSO to your login page.

Enabling Enterprise SSO For Organizations

Once you've enabled Enterprise SSO on the project-level, you can choose which of your organization should have access by going to the Organizations page and select an organization, select Settings, then toggling the "Can this organization set up SAML/OIDC?" setting.

You can also enable Enterprise SSO for organizations in the Enterprise SSO / SCIM page by clicking on the Organization-Specific Settings tab and clicking on the Manage Enterprise SSO by Organization button. You can also use this page to view which organizations have Enterprise SSO enabled in your project.

Alternatively, you can enable Enterprise SSO for an organization programmatically via the Enable SAML for Org API call.

Enterprise SSO Guides for SAML and OIDC

Once Enterprise SSO is enabled for an organization, the connection between your app and your customer's IdP (Okta, Azure/Entra, etc.) must be configured by your customer. Configuration involves an exchange of different URLs and variables between your app and your customer's IdP. Optionally, this process also includes mapping specific attributes to correctly populate user properties and roles in your app.

With PropelAuth this is all done by the Enterprise SSO Setup Page. This page provides multiple IdP-specific guides for both SAML and OIDC, as well as directions on how to map user properties and roles from the IdP to your application. PropelAuth offers guides for the following IdPs:

1. Google (OIDC and SAML)
2. Okta (OIDC and SAML)
3. Entra/Azure (OIDC and SAML)
4. OneLogin (OIDC and SAML)
5. JumpCloud (OIDC and SAML)
6. Duo
7. Rippling
8. Generic (OIDC and SAML)

There are two methods available for your customer to access this page:

From the Org Settings Hosted Page

Any user with a role that includes the Enterprise SSO permission can access the Enterprise SSO Setup Page by navigating to the Organization Settings Page and clicking Enable Enterprise SSO.

If a customer is not seeing the Enable Enterprise SSO button it may be for the following reasons:

1. Enterprise SSO is not enabled for their organization.
2. Their role does not include the Enterprise SSO permission.

From the Enterprise SSO Setup Page Link

Alternatively, you can generate a link to the Enterprise SSO Setup Page that you can send to your customer. This link can be generated via the Create SAML Connection Link API or by navigating to the organization's settings page and clicking on the Generate Link button. This link to the Enterprise SSO Setup Page doesn't require authentication - allowing users who do not have an account or the Enterprise SSO permission to configure the Enterprise SSO connection.

Mapping Roles and User Properties via SAML

Your users have the option to map roles from their IdP to your application. The process for each IdP is different so we offer guides for each provider that we support. These guides will automatically list each of the roles you have configured in your Roles & Permissions page of the PropelAuth Dashboard.

The guides will also instruct your users to map attributes from their IdP to any user property that has the Collect via SAML/SCIM setting enabled.

Mapping roles and custom user properties via OIDC is not yet supported.

Editing Enterprise SSO Login Settings

There are three different options for how the login experience will look for your Enterprise SSO users. You can select these options in the Enterprise SSO / SCIM page in the PropelAuth Dashboard.

• By domain - The default option. When your users visit your login page, they'll first click a Sign in with SSO button. They'll be prompted to enter their email address. If the domain of the email address matches the Organization Domain (found in the org's settings page), they'll automatically be redirected to their identity provider.

• By Org Name - Similar to the above example where the user will first click on a Sign in with SSO button. They'll then be prompted to enter the name of their organization, such as "Acme Inc". If there's a match they'll automatically be redirected to their IdP to login.

• Default to SAML/OIDC login - You can also choose if you want to set SAML/OIDC as the default login method, meaning no Sign in with SSO button. Instead, PropelAuth will automatically check if an email address belongs to a SAML/OIDC enabled org. If it does not, it'll fall back to password login.

Setting Session Durations for Enterprise SSO Users

By default, users that login via Enterprise SSO will have the same session duration as every other user. You can optionally configure a different session duration for Enterprise SSO users by adjusting the Session Durations for SSO Users setting in the Enterprise SSO / SCIM page of the PropelAuth Dashboard.

Redirecting users directly to their Enterprise SSO provider

While our hosted pages have multiple ways to redirect your users to their IdP, sometimes you want to skip the hosted pages and redirect them directly to their Enterprise SSO provider. To do this, you can direct your users to {AUTH_URL}/api/fe/v3/login/saml and then include one of the following query parameters:

• domain - Redirects the user to the SAML login page for an organization with a matching domain
• email - Parses the domain from the email address and redirects the user to the SAML login page for an organization with a matching domain
• org_id - Redirects the user to the SAML login page for the provided organization
• org_name (case sensitive) - Redirects the user to the SAML login page for the provided organization

An example of this would look like so:

{AUTH_URL}/api/fe/v3/login/saml?email=test@acmeinc.com

If the provided organization has Enterprise SSO enabled, the user will be redirected to their IdP. Otherwise, it will fall back to redirecting the user to your login page.

Generic SAML and OIDC

Don't see your customer's IdP on our supported list? Your users also have the option to connect to a generic SAML or OIDC provider.

Generic SAML

We guide your customers through three steps:

1. We provide a ACS URL and SP Entity ID that can be entered into the identity provider during setup.

2. We guide your users into mapping user attributes from the identity provider to your app.

3. We require the user to provide the IDP SSO URL, Entity ID, and Certificate from the identity provider. Note that the names of these variables may differ across providers.

Generic OIDC

We guide your customers through three steps:

1. We require the user to provide the following fields:

• Client ID
• Client Secret
• Authorize URL
• Token URL
• User Info URL
• If PKCE should be used

2. We provide a Redirect URI that can be entered into the identity provider during setup.

3. We guide your users into mapping user attributes from the identity provider to your app.

OIDC URL not supported

Is one of your users running into a "OIDC URL not supported" error when setting up a Generic OIDC connection? If so, please send us an email at support@propelauth.com along with the URLs they're using.

Customer Questions and Copyable Documentation

Did you receive a questionnaire from a customer about Enterprise SSO? Or are you wanting to add a page to your documentation that covers your Enterprise SSO support? See the page here.