# Introduction

WorkOS Vault is a developer-friendly EKM to encrypt and optionally store data including tokens, passwords, certificates, files, and any other customer content. Ideal for scaling encryption in cloud applications, it minimizes key exposure and simplifies compliance.

## Key features

### Encrypted Key-Value Storage

Each secret stored with Vault uses a unique encryption key and is cryptographically isolated based on user-provided context. Envelope encryption enhances security by encrypting data with a data encryption key (DEK), which is then encrypted with a key encryption key (KEK). This approach ensures sensitive data remains protected while allowing secure key management and access control.

### Enterprise Key Management (EKM)

The Enterprise Key Management features of Vault centralize control over encryption keys used for customer data in multi-tenant architectures. It streamlines key lifecycle management, access policies, and auditability while integrating seamlessly with your existing applications. Key segmentation by organization, user, or any provided context ensures cryptographic keys are isolated, reducing risk and enforcing access control at boundaries that make sense for your business.

### Bring-Your-Own-Key (BYOK)

With Vault you can provide keys either from your own environment or directly linked to your customers' cloud environments. BYOK gives you full control over encryption keys while integrating seamlessly with your own security tooling such as cloud SIEMs. It ensures your keys stay protected in your custody while enabling secure access for encryption operations, perfect for compliance-driven workloads. BYOK integration is available for many popular key management services, including Amazon Web Service KMS, Google Cloud Compute KMS, Azure Key Vault, and HashiCorp Vault.

## Common Use Cases

### Organizational secrets

Sensitive data in a B2B application is often linked to specific organization. This can be shared secrets, API keys, OAuth credentials, or even data generated by your application. Vault protects this information and easily links each secret with the organization it belongs to in order to provide full cryptographic separation from other organizations within your application.

### User secrets

User data such as Personally Identifiable Information (PII) or Protected Health Information (PHI) is highly sensitive and can have strict regulatory requirements including strong encryption, access controls, and data minimization. The risk for mishandling this data is very high - both financially and reputationally. Vault lets you store this data using unique encryption keys without needing to manage the complex lifecycle of key hierarchies.

### Application secrets

With short-lived dynamic workloads in the cloud, static credentials represent a huge security risk. Secrets can get spread out across many services, making rotation difficult and increasing the risk of a leak. Vault can encrypt and store application data such as API keys, database credentials, and PKI certificates in a centralized service and provide them to your application at runtime.

### Bring Your Own Key (BYOK)

Allow your customers to use their own encryption keys with WorkOS Vault for enhanced security and compliance.

Bring Your Own Key (BYOK) allows your customers to use their own customer-managed keys (CMKs) with WorkOS Vault instead of relying solely on WorkOS-managed keys. This feature enables you to offer your customers additional control over their encryption keys and help them meet specific compliance requirements.

## Overview

With BYOK, your customers maintain control over their key material while still leveraging Vault's encryption and data management capabilities. Customer-managed keys are used as key-encrypting keys (KEKs) in place of WorkOS-managed KEKs, providing an additional layer of security and compliance for your application's users.

## How BYOK works

When Vault is configured with BYOK:

1. **Key Matching**: Encryption operations are matched to customer CMKs based on the [key context](/vault/key-context) provided
2. **Envelope Encryption**: Customer CMKs encrypt data-encrypting keys (DEKs), not the data directly
3. **Automatic Fallback**: Operations that don't match a customer's CMK configuration will use WorkOS-managed KEKs

### Key Context Matching

BYOK uses the same key context mechanism as standard Vault operations. When a customer's CMK is configured for specific context values, Vault automatically uses that key for matching operations.

**Example Configuration:**

- Customer CMK `key_abc` configured for `organization_id: "org_123"`
- Key context `{"organization_id": "org_123"}` → Uses customer CMK `key_abc`
- Key context `{"organization_id": "org_456"}` → Uses WorkOS-managed KEK

## Benefits

### Enhanced Security

- **Key Control**: Your customers maintain complete control over their encryption keys
- **Isolation**: Customer keys remain separate from other tenants' data
- **Audit Trail**: Customers have full visibility into their key usage and access patterns

### Compliance

- **Regulatory Requirements**: Help customers meet compliance standards that require customer-controlled keys
- **Data Sovereignty**: Enable customers to ensure encryption keys remain within their control
- **Risk Management**: Reduce customer dependency on third-party key management

## Use Cases

### Multitenant Applications

Allow different customers to use their own CMKs while maintaining a single Vault integration:

```javascript
// Customer A data - uses Customer A's CMK
await vault.createObject({
  name: 'customer-a-pii',
  value: '{"fullname": "customer_a_name"}',
  context: { organization_id: 'customer_a' },
});

// Customer B data - uses Customer B's CMK
await vault.createObject({
  name: 'customer-b-pii',
  value: '{"fullname": "customer_b_name"}',
  context: { organization_id: 'customer_b' },
});
```

### Compliance Sensitive Data

Allow customers to apply stricter key controls to specific data types:

```javascript
// PCI data - uses customer's CMK
await vault.createObject({
  name: 'customer-123-payments',
  value: '{"creditCard": "4111-1111-1111-1111"}',
  context: {
    organization_id: 'customer_123',
  },
});

// General data - uses WorkOS-managed keys
await vault.createObject({
  name: 'customer-123-preferences',
  value: '{"preference": "dark_mode"}',
  context: {
    data_type: 'preferences',
  },
});
```

### Geographic Data Residency

Allow customers to ensure their encryption keys remain in specific regions:

```javascript
// EU data - uses customer's EU-based CMK
await vault.createObject({
  name: 'customer-789-pii',
  value: '{"userEmail": "user@example.eu"}',
  context: {
    organization_id: 'customer_789',
  },
});
```

## Configuration

BYOK configuration is managed through your WorkOS dashboard and admin portal. Contact your WorkOS representative to enable BYOK for your application.

### Prerequisites

- Your customers must have compatible key management systems (AWS KMS, Azure Key Vault, Google Cloud KMS)
- Proper IAM permissions for WorkOS Vault to access customer keys

### Generate Admin Portal link

Navigate to the organization of your customer who will configure their CMK. Generate a unique portal link by clicking "Invite admin" and selecting "Bring Your Own Key" from the feature selection.

![Generate admin portal link](https://images.workoscdn.com/images/d374bc73-7cdc-441c-b177-82c4ae604db7.png?auto=format&fit=clip&q=80)

### Share link with your customer's IT team

The admin portal will walk an IT admin through the setup and configuration of the CMK. It includes screenshots for using the cloud provider of choice to create a key and set the appropriate permission in IAM policies to allow Vault to use the key.

![Share link with IT](https://images.workoscdn.com/images/7f237529-584b-4a98-b17e-2ce4bf6c1e08.png?auto=format&fit=clip&q=80)

### Confirm successful admin portal setup

The final step of the admin portal setup flow will validate that Vault can use the CMK the IT admin configured. If they see "Setup is complete", Vault will use the customer's CMK whenever an operation includes their organization id as context.

![Confirm CMK setup success](https://images.workoscdn.com/images/f46f7009-3cf5-4706-a37e-691768d63440.png?auto=format&fit=clip&q=80)

### View CMK under Organization details

A Key details card will appear under Organization details, which shows configuration information, CMK active state, and the key context associated with the CMK.

![View key details](https://images.workoscdn.com/images/54c026c7-f3b0-497a-bb48-83661ba1ae3e.png?auto=format&fit=clip&q=80)


## Single Sign-On {#sso}

### Test SSO

Learn how to test your Single Sign-On integration end-to-end.


## Testing with the Test Identity Provider

To confirm your Single Sign-On integration works correctly you can use the Test Identity Provider to simulate login flows end-to-end. Your staging environment includes a default Test Organization and active SSO connection configured with the Test Identity Provider.

![WorkOS Test Identity Provider](https://images.workoscdn.com/images/f3b0d507-2d6f-4ed8-a12f-e026c8a2987c.png?auto=format&fit=clip&q=80)

### Getting started

Log into the [WorkOS Dashboard](https://dashboard.workos.com/) and navigate to the _Test SSO_ page to get started with the Test IdP. This page outlines a number of different SSO scenarios you can follow and provides all the necessary information to complete the tests.

![Test SSO WorkOs Dashboard](https://images.workoscdn.com/images/7b7407d7-dcc7-4fd4-859f-4ee4214d69c2.png?auto=format&fit=clip&q=80)

### Service provider-initiated SSO

This case is likely the first [login flow](/sso/login-flows/sp-initiated-sso) you would test when implementing SSO in your app. The test simulates users initiating authentication from your sign-in page. In this scenario, the user enters their email in your app, gets redirected to the identity provider, and then is redirected back to your application.

### Identity provider-initiated SSO

This test simulates users initiating authentication from their identity provider. It is a common [login flow](/sso/login-flows/idp-initiated-sso) that developers forget to consider. In the scenario, users log in to the identity provider directly, select your application from their list of SSO-enabled apps, and are redirected to your application upon successful authentication.

> Ensure [AuthKit is disabled](https://dashboard.workos.com/authentication) before testing.

### Guest email domain

This test simulates users authenticating with an email domain different from the verified domain of the test organization, `example.com`. A relevant scenario is authenticating freelance users, whose email domain is not owned by the company.

### Error response

This test simulates a generic [error response](/reference/sso/get-authorization-url/error-codes) from the user’s identity provider. In this scenario, SSO authentication has failed for the user. Below is an example of the error-related parameters passed to the [redirect URI](/sso/redirect-uris) in your application.

---

## Testing with other identity providers

Test Identity Provider saves time by providing an out of the box experience compared to the configuration process that someone using a real identity provider would have to go through to enable Single Sign-On for your app.

If your integration works with the Test Identity Provider, you can be sure it will work with other identity providers. However, it may be helpful to also learn about the setup process that your customers will go through on their side, which varies depending on a specific identity provider.

### (1) Create an organization

To get started, you will need to [create an organization](https://dashboard.workos.com/organizations) in the WorkOS Dashboard. Organizations in WorkOS represent your customer, so by creating an organization, you can test your SSO connection the way your customers will experience it.

![Create an organization dialog](https://images.workoscdn.com/images/2ef3565c-526a-42e6-9830-622e83b67ee5.png?auto=format&fit=clip&q=80)

### (2) Create a connection

Go to the organization you created and click _Invite admin_. Select _Single Sign-On_ from the list of features. In the next step, enter an email address to send the setup link to, or click _Copy setup link_.

The setup link goes to Admin Portal, where your customers get the exact instructions for every step they need to take to enable Single Sign-On with your app.

> You can also integrate [Admin Portal](/admin-portal) directly into your app to enable self-serve setup of Single Sign-On and other enterprise features for your users.

![Invite an admin dialog](https://images.workoscdn.com/images/b9ab80fc-606a-417c-bade-3483ef48c2ae.png?auto=format&fit=clip&q=80)

### Follow the Admin Portal instructions

To complete the integration, you’ll have to also create an account with the identity provider you want to test with. After you have signed up with an identity provider of your choice, follow the corresponding Admin Portal instructions from the setup link. Once done, you can start testing your SSO integration with that identity provider.

![Admin Portal setup instructions](https://images.workoscdn.com/images/0ee15c3d-5356-4f41-a26a-440f95355b28.png?auto=format&fit=clip&q=80)

The setup instructions you’ve seen in the Admin Portal are also available directly in the docs if you want to create a connection manually:



---

### Single Logout

Learn how to implement Single Logout with WorkOS

> Currently, Single Logout is only supported for [OpenID Connect connections](/integrations/oidc) and limited scenarios.
> If you are looking to implement this feature, please reach out to [WorkOS support](mailto:support@workos.com).

## RP-initiated Logout

With an Relying-Party-initiated (RP-initiated) logout, a user is logged out of your application and all other applications they are
logged into via the identity provider. This is achieved by redirecting the user to the [Logout Redirect](/reference/sso/logout/redirect) endpoint.

Before redirecting the user, you need to generate a logout token by calling the
[Logout Authorize](/reference/sso/logout/authorize) endpoint with the user’s profile ID which can be obtained
from the [User Profile](/reference/sso/profile/get-profile-and-token) endpoint.

Next, pass the logout token as a query parameter to the [Logout Redirect](/reference/sso/logout/redirect) endpoint.

![RP-initiated logout](https://images.workoscdn.com/images/63a9710b-ff61-456b-aea7-d572b3621271.png?auto=format&fit=clip&q=50)

By following these steps, the user will be securely logged out of your application and all other associated
applications through the identity provider.

Note that, this feature is only supported for OpenID Connect providers that brings the
`revocation_endpoint` and `end_session_endpoint` in the OIDC discovery document.

---

## IdP-initiated Logout

For the Identity-Provider-initiated (IdP-initiated) logout, WorkOS provides the `https://auth.workos.com/sso/oidc/idp-logout/:external_key` endpoint
which needs to be registered in the customer's Identity Provider as the logout endpoint for your application.

When a user logs out of your application via the IdP, the IdP should call this endpoint which will redirect
to a logout endpoint in your application. This logout endpoint should clear all the cookies in your application.

You should contact [WorkOS support](mailto:support@workos.com) for both:

- obtaining the `https://auth.workos.com/sso/oidc/idp-logout/:external_key` for registering in your customer's IdP
- informing the logout endpoint in your application.

![IdP-initiated logout](https://images.workoscdn.com/images/aeda8074-7e61-4a3c-850e-278acd510bd8.png?auto=format&fit=clip&q=50)

### SAML Signing Certificates

Verify the authenticity of SAML responses and requests.

SAML signing certificates are X.509 certificates used in SAML responses to allow the [Service Provider (SP)](/glossary/sp) to verify the authenticity of a SAML response. Some [Identity Providers (IdP’s)](/glossary/idp) may require or provide the option to use a SAML signing certificate for the SAML request as well. In these cases the IdP verifies the authenticity of the SAML request.

![SAML Flow Diagram](https://images.workoscdn.com/images/d9771da5-ee40-4e41-bc96-f393ee0af577.png?auto=format&fit=clip&q=80)[border=false]

SAML response signing certificates are generated by your customer’s IdP and must then be uploaded to WorkOS manually or using a monitored metadata URL. Your customer can either upload the certificate themselves via the Admin Portal, or you can upload it for them via the WorkOS Dashboard if your customer provides it to you.

Unlike SAML response signing, for request signing you will need to provide your customer with a metadata URL called the SP metadata URL. Your customer will then upload the SP metadata URL to their IdP, where it will either be monitored for updates automatically made by WorkOS, or it will be manually updated by your customer in their IdP.

---

## SAML Response Signing Certificate

When the IdP sends a SAML response, the SP must verify the authenticity of the response, and that it has not been tampered with by an unauthorized third party. The SAML response signing certificate allows the SP to perform this verification.

### Sample scenario

Consider the fictional SaaS company _HireOS_, which offers recruiting software to other businesses. _HireOS_ is an online application that allows its customers to track leads, candidates, and interviews. _HireOS_ is referred to as the SP by SAML.

Now let’s consider _HireOS_’ newest enterprise customer: _Enterprise Corp_. _Enterprise Corp_ is a large enterprise company that wants to use _HireOS_ to manage their recruiting. _Enterprise Corp_ IT admins need recruiters and other employees who will use _HireOS_ to log in using _Enterprise Corp_'s identity provider, Okta. Okta is one of many companies known as an IdP to SAML.

### Verifying the SAML response

After identifying the user—whether from the SAML request or from IdP initiated SSO—Okta SAML will generate the SAML response, which includes SAML assertions, the X.509 certificate, and the signature value. Upon receiving the response from Okta SAML, _HireOS_ will verify that the response came from Okta SAML by decrypting the signature, using the public key on the X.509 certificate, and checking if the hash values match.

![SAML Response Diagram](https://images.workoscdn.com/images/96ec0449-2080-4b84-8574-43d1bc24c24a.png?auto=format&fit=clip&q=80)[border=false]

### Planning considerations

When planning your SAML integration, there are a few things to consider related to SAML response signing certificates.

### Certificate expiration

Your SAML response signing certificate will eventually expire and must be kept up to date in order to maintain service. Your certificate’s expiration time will vary, but typically, response certificates are valid anywhere from 1-5 years. If your certificate is uploaded in the WorkOS Dashboard, you can see when it expires by going to Organizations, selecting the Organization, and then clicking on the Connection containing the response certificate. If your company has a shared Slack channel with WorkOS, we will help ensure that your SAML response signing certificates stay up to date by automatically sending a notification before a certificate expires.

![WorkOS Dashboard UI showing a SAML certificate expiration date](https://images.workoscdn.com/images/eee34072-6363-498e-bb10-cc4f2171c98b.png?auto=format&fit=clip&q=90)

### Monitored metadata versus manual upload

There are two options to upload your response certificate to a Connection, both of which can be done either in the WorkOS Dashboard, or by your customer using the Admin Portal.

### Renewing certificates

To facilitate certificate renewal, WorKOS offers the ability to renew SAML certificates through the Admin Portal. When a certificate is nearing expiration (within 90 days), or has already expired, a notification will appear on the Dashboard Overview page with details about the certificate.

![Notification for expired certificate](https://images.workoscdn.com/images/5eba5473-fa61-4d57-bf60-bb9359d61797.png?auto=format&fit=clip&q=50)

Alternatively, you are also able to filter connections that have either expired or expiring connections directly from the Organization page's filters.

![Organization page expired filter](https://images.workoscdn.com/images/f306979d-ab49-4c2a-832c-895d16a86041.png?auto=format&fit=clip&q=50)

From the Connection page you can generate an Admin Portal link that WorkOS can email directly to the IT admin. By entering the IT admins' email address, WorkOS will email them with a certificate
renewal Admin Portal link, and they will be notified about future
expiring certificates. Alternatively, you can copy the link and share it with them directly.

![Connection page for an expiring certificate](https://images.workoscdn.com/images/c7896f7f-fcde-4440-9f66-8f3dc8445568.png?auto=format&fit=clip&q=50)

The IT admin will be guided to a step by step flow to renew their certificate; the exact steps will vary based on the IdP.

![IT admin flow for Entra ID](https://images.workoscdn.com/images/2c8334f2-3784-4e7d-8ba9-f4896da336cb.png?auto=format&fit=clip&q=50)

### Monitored metadata

To streamline this process, you can instead choose to upload a metadata URL to WorkOS that we will automatically keep updated as metadata changes. If your customer's IdP refreshes a certificate, WorkOS will automatically pull in the updated metadata. Your customer can upload a metadata URL to the Admin Portal during setup. Alternatively, they can provide it to your to manually upload via the Dashboard.

![WorkOS Dashboard UI configuring a connection's metadata URL](https://images.workoscdn.com/images/6407b054-9f84-45cf-81bd-35c25b7af0b5.png?auto=format&fit=clip&q=90)

### Manual upload

SP metadata such as the Entity ID, IdP SSO URL, and SAML response signing certificate can be uploaded manually through the Dashboard or the Admin Portal. This may be done either by uploading an XML metadata file, or by individually inputting metadata values. When metadata becomes out of date, such as an X.509 certificate expiring, new information must manually be uploaded. If you would like to upload the data for your customer, they must first send the relevant metadata to you. You can then upload it via the WorkOS Dashboard by navigating to the Organization and selecting the specific Connection.

![WorkOS Dashboard UI manually configuring a connection's Entity ID, IdP URL, and X509 certificate](https://images.workoscdn.com/images/5002b5ca-d94e-40a9-9dec-71575ba24a91.png?auto=format&fit=clip&q=90)

---

## SAML Request Signing Certificate

When the SP sends a SAML request, the IdP must verify that the request is actually coming from the SP and has not been tampered with by an unauthorized third party. IdP’s choose to handle this verification in different ways, and some use a SAML request signing certificate. Microsoft AD FS SAML uses a relying party trust, which is similar to a SAML request signing certificate, and the concepts covered in this article are applicable. In WorkOS, Connections that take advantage of a request certificate will expose an SP metadata URL that can be sent to the IdP in order to give it access to the signing certificate.

### Sample scenario

Once again, let’s consider the fictional SaaS company _HireOS_, which offers recruiting software to other businesses. _HireOS_ is referred to as the SP by SAML.

_HireOS_’ newest enterprise customer is called _Enterprise Corp_. _Enterprise Corp_ IT admins need recruiters and other employees who will use _HireOS_ to log in using _Enterprise Corp_'s identity provider, Okta. Okta is one of many companies known as an IdP to SAML.

### Verifying the SAML request

In SP initiated SSO, _HireOS_ will first send a SAML request to Okta SAML. If a request certificate is being used, then the X.509 certificate along with a signing signature will be attached to the request. Upon receiving the request, Okta SAML will verify that the request came from _HireOS_ by decrypting the signature using the public key on the X.509 certificate and confirming the hash values match.

![SAML Request Diagram](https://images.workoscdn.com/images/6f244bd0-3f76-434f-99c3-be8bcf65d3da.png?auto=format&fit=clip&q=80)[border=false]

### Planning considerations

When planning your SAML integration, there are a few things to consider related to SAML request signing certificates.

### Certificate expiration

Your SAML request signing certificate will eventually expire and must be kept up to date in order to maintain service. WorkOS will automatically update the request signing certificate on the SP metadata URL before it expires. It is up to your customer and their IdP to either monitor the SP metadata URL, or manually keep it up to date. If your company has a shared Slack channel with WorkOS, you will automatically be notified when the X.509 certificate on the SP metadata URL is updated, so that you can check with your customer that they have the latest metadata.

### Monitored metadata versus manual upload

There are potentially two options for your customer to upload SP metadata, and will vary based on their IdP. In both cases, you will need to provide your customer with the SP metadata URL, which can be found in the WorkOS Dashboard by going to Organizations, selecting the Organization, and then selecting the Connection.

![WorkOS Dashboard UI with SP metadata URL](https://images.workoscdn.com/images/5bab9063-e0cd-4bca-abe6-68db5162be5e.png?auto=format&fit=clip&q=90)

### Monitored metadata

To streamline this process, your customer instead may choose to monitor our SP metadata URL. Their IdP will regularly check our URL for updates to the metadata. When WorkOS makes an update, such as refreshing an X.509 certificate that is expiring soon, their IdP will automatically make the change.

### Manual upload

Your customer can manually download the SP metadata document from the URL, extract the certificate, and upload it to their IdP. When the certificate is getting ready to expire, they can repeat this process to give their IdP the most up to date certificate.

## Implementing SSO with WorkOS

This document offers guidance to integrate Single Sign-On with our standalone API into your existing auth stack. You might also want to look at [AuthKit](/authkit), a complete authentication platform that leverages Single Sign-On functionality out of the box, following best practices.

### Sign-in Consent

Learn about the sign-in consent screen, an extra layer of protection against login CSRF attacks and phishing attempts.

The sign-in consent screen is an extra layer of protection against login CSRF attacks or phishing attempts.

A user may click a link that appears legitimate, but which unknowingly leads them to signing in through a malicious identity provider controlled by an attacker. The sign-in consent screen mitigates this risk by displaying the user's email and the identity provider's domain, ensuring the user is aware of how they are signing in to the application.

## How it works

The sign-in consent screen is an interstitial page that appears during the Single Sign-on flow, after the user has gone through the identity provider (IdP), before redirecting to the application.

![Sign-in consent screen](https://images.workoscdn.com/images/32760d6d-eb42-480f-92bc-fe6d2e8709ea.png?auto=format&fit=clip&q=80)

This page displays to the user the `email` returned from the IdP, as well as the IdP origin. With this information, the user must either consent to or deny the sign-in flow.

- **Consenting sign-in** leads to completing the SSO flow, where the authorization code is forwarded to the application callback.
- **Denying the sign-in** will result in an SSO session failure and the user will be redirected to the application callback with a `signin_consent_denied` error.

## Enabling sign-in consent

In order to activate the sign-in consent protection, you should go to the **Authentication** section and enable the sign-in consent checkbox in the Single Sign-On settings.

![Enable sign-in consent checkbox](https://images.workoscdn.com/images/0ab5bb9f-6acb-45d0-a351-468a7e57a428.png?auto=format&fit=clip&q=80)

## Handling the `signin_consent_denied` error

We recommend using the `signin_consent_denied` error code to display useful information to the user, so that they can contact their admin and your support team for information about a possible phishing attempt.

When a user denies the sign-in consent, your application's callback will receive an error response:

```url title="Redirect URI with signin_consent_denied error"
https://your-app.com/callback?error=signin_consent_denied&error_description=User%20cancelled%20the%20authentication%20request&state=123456789
```

For more information about error handling, see the [Get Authorization URL error codes](/reference/sso/get-authorization-url/error-codes) documentation.

## When sign-in consent is displayed

WorkOS determines whether the sign-in consent screen should be displayed, based on the identity provider, user fingerprint, and SSO flow parameters.

Once a user accepts the sign-in consent screen, the system remembers this approval and avoids displaying the page again for a better user experience.

The sign-in consent screen is always displayed in the following scenarios:

- **IdP-initiated flows**: The sign-in consent screen is always displayed for IdP-initiated flows (i.e. users clicking on a tile in their IdP), regardless of the identity provider, if the user has not previously approved it.
- **Custom SAML or OIDC connections**: The sign-in consent screen is displayed for custom connections if the user has not previously approved sign-in consent.

## Branding

The sign-in consent screen automatically inherits the Admin Portal branding and is served through your custom authentication API domain, if available. Ensure you review the primary button color and logos before enabling this feature. This ensures a trusted experience for your customers.

## Availability

The sign-in consent is currently only available for Enterprise SSO users, not AuthKit.

> If you're using AuthKit and would like to enable the sign-in consent screen, please reach out to [WorkOS support](mailto:support@workos.com).

### SAML Security Considerations

Learn about additional SAML features that WorkOS supports.

SAML requests and responses each have their own unique confidentiality and integrity features.
To use [SAML](/glossary/saml) with WorkOS, the only requirement is that the Identity Provider ([IdP](/glossary/idp)) signs the assertions within the SAML authentication response.

However, you may have customers that have stricter configuration requirements or you may simply want to raise the security bar by following recommendations.
This document details what security features are available, how they can benefit you, your customer and their identity provider.

The parties involved in a SAML authentication request and response flow are:

- Identity Provider
- Service Provider ([SP](/glossary/sp))
- User Agent, i.e. a browser

---

## SAML Binding Methods

WorkOS uses the HTTP Redirect binding to transmit SAML authentication requests from the SP to the IdP, and the HTTP POST binding to receive SAML responses from the IdP back to the SP:

- Redirect binding sends the request via HTTP GET, with the SAML message included in the URL.
- POST binding delivers the response via HTTP POST, with the SAML message in the form body.

---

## SP to IdP security features

The SAML authentication request is a way for the SP to request confirmation that the user they're presented with is who they're claiming to be.
It is relayed to the IdP via the user agent.

![SAML authentication request options](https://images.workoscdn.com/images/dc5df10c-50dc-4bb0-bede-26d16b197f20.png?auto=format&fit=clip&q=80)

### SAML request signing

To address the opportunity to spoof or tamper with a SAML request to the IdP, the IdP may require that all SP's sign the request.
To accommodate this there needs to be a pre-existing relationship between the SP and IdP where a key-pair is shared.
The IdP holds the public key (for verifying the request) and the SP holds the private key (for signing the request).

WorkOS recommends SAML request signing, this is especially important in cases where HTTPS is terminated or interrupted prior to reaching the IdP.

All of our requests embed the `` timestamp to allow the IdP to reject stale requests, however to mitigate tamper of this value request signing must be used.\
(See [SAML 2.0 Security Considerations](https://docs.oasis-open.org/security/saml/v2.0/saml-sec-consider-2.0-os.pdf) sections 5.2.1.2, 6.5.1 for more detail).

| Supported by WorkOS | Enabled by default | Usage recommendation              |
| ------------------- | ------------------ | --------------------------------- |
| Yes                 | No                 | Use with any IdP that supports it |

WorkOS supports SAML request signing for all compatible connection types. Please [contact WorkOS support](mailto:support@workos.com) to enable it.

---

## IdP to SP security features

The SAML response is an XML document provided by an IdP containing details about a user so that an SP can authenticate them.
It is relayed to the SP via the user agent.

![SAML authentication response options](https://images.workoscdn.com/images/f888365e-fa7d-4c1e-a76d-a19777e6cbb2.png?auto=format&fit=clip&q=80)

For reference in understanding the following features, below is a simplified hierarchy of the XML elements in a SAML Response:

```xml title="SAML response"

```

### Signed response assertions

This is **required** by WorkOS for all SAML connections. It is a core requirement for SAML IdPs to implement as of SAML 2.0 (see [SAML 2.0 Profiles](https://docs.oasis-open.org/security/saml/v2.0/saml-profiles-2.0-os.pdf) section 4.1.3.5).

| Supported by WorkOS | Enabled by default | Usage recommendation                    |
| ------------------- | ------------------ | --------------------------------------- |
| Yes                 | Yes                | All WorkOS SAML connections must use it |

Signed response assertions are enabled in the setup steps when you [create a SAML connection](/integrations/saml).

### Signed response message envelope

This is the complete signature over the SAML response payload.
In combination with an assertion signature it will provide additional integrity protection and is recommended by WorkOS (For details on threats addressed see [SAML Security Considerations](https://docs.oasis-open.org/security/saml/v2.0/saml-sec-consider-2.0-os.pdf) sections 7.1.1.6, 7.1.1.7).

| Supported by WorkOS | Enabled by default | Usage recommendation              |
| ------------------- | ------------------ | --------------------------------- |
| Yes                 | No                 | Use with any IdP that supports it |

Please [contact WorkOS support](mailto:support@workos.com) to enable signed response message envelope.

### Encrypted response assertion

The SAML assertions in the SAML response may contain sensitive data, and therefore there is an option to encrypt them to preserve confidentiality.

This feature is recommended in scenarios where the SAML response travels through HTTPS termination, so that accidental logging of sensitive data can be mitigated.

| Supported by WorkOS | Enabled by default | Usage recommendation              |
| ------------------- | ------------------ | --------------------------------- |
| Yes                 | No                 | Use with any IdP that supports it |

Please [contact WorkOS support](mailto:support@workos.com) to enable encrypted response assertion.

### Encrypted response attributes

The attribute statement is a sub-element of the assertion, some or all of the attributes in the statement can be encrypted as part of the SAML authentication protocol.

| Supported by WorkOS | Enabled by default | Usage recommendation                 |
| ------------------- | ------------------ | ------------------------------------ |
| No                  | No                 | Use **encrypted assertions** instead |

WorkOS does not currently support encrypted response attributes. It is recommended to use assertion encryption to envelope all the attributes if confidentiality is required.

## Implementing SSO with WorkOS

This document offers guidance to integrate Single Sign-On with our standalone API into your existing auth stack. You might also want to look at [AuthKit](/authkit), a complete authentication platform that leverages Single Sign-On functionality out of the box, following best practices.

### Redirect URIs

Learn what a redirect URI is and how it relates to Service Provider and Identity Provider initiated login flows.

## Introduction

With a [WorkOS Service Provider (SP) initiated login flow](/sso), there are a series of exchanges that take place between a Service Provider (your application), WorkOS, and the IdP that’s being used to authenticate the user as shown in the diagram below. The [Redirect URI](/glossary/redirect-uri) is the location to which the user gets returned to after successfully completing the authentication with their [Identity Provider (IdP)](/glossary/idp).

With an Identity Provider (IdP) initiated login flow, the approach is similar but the user will begin the login flow by clicking on the tile within their IdP platform instead of from your application.

![Authentication Flow Diagram](https://images.workoscdn.com/images/90b84f08-3363-446a-8610-f7b2bd2ee2ca.png?auto=format&fit=clip&q=80)

In WorkOS Production Environments, the Redirect URI to your application cannot use HTTP or localhost, however, Redirect URIs that use HTTP and localhost are allowed in Sandbox Environments.

There should be at least one redirect URI configured and selected as a default for a WorkOS Environment. This can be done from the [Redirects](https://dashboard.workos.com/redirects) page in the WorkOS dashboard. If you try to route the authorization flow to a Redirect URI that is not yet defined in the Dashboard it will result in an error and users will be unable to sign in, so it’s important to define them in the dashboard first.

![Dashboard Redirect URIs](https://images.workoscdn.com/images/6da31d23-c823-4557-8403-b38b2700e4d2.png?auto=format&fit=clip&q=50)

The Redirect URI can also be included directly in the Get Authorization URL call as a redirect_uri parameter. When the Redirect URI is set in this fashion, it will override the default Redirect URI that is set in the WorkOS Dashboard.

---

## Wildcard characters

WorkOS supports using wildcard characters in Redirect URIs.

![Dashboard updating the redirect URIs to use a wildcard in staging](https://images.workoscdn.com/images/12f99da0-ef62-4b09-acf8-b3d05b48f9e3.png?auto=format&fit=clip&q=50)

The `*` symbol can be used as a wildcard for subdomains; however, it must be used in accordance with the following rules in order to properly function.

- The protocol of the URL **must not** be `http:` in production environments.
- The sole exception is the use of `http://127.0.0.1` in production environments to support native clients.
- The wildcard **must** be located in a subdomain within the hostname component. For example, `http://*.com` will not work.
- The wildcard **must** be located in the subdomain which is furthest from the root domain. For example, `https://sub.*.example.com` will not work.
- The URL **must not** contain more than one wildcard. For example, `https://*.*.example.com` will not work.
- A wildcard character **may** be prefixed and/or suffixed with additional valid hostname characters. For example, `https://prefix-*-suffix.example.com` will work.
- A URL with a valid wildcard **will not** match a URL more than one subdomain level in place of the wildcard. For example, `https://*.example.com` will not work with `https://sub1.sub2.example.com`.
- In production environments, wildcards cannot be used with [public suffix domains](https://publicsuffix.org). For example, `https://*.ngrok-free.app` will not work.
- The wildcard will match a sequence of letters (`A` – `Z`, `a` – `z` ); digits (`0` – `9`), hyphens (`-`), and underscores (`_`).
- A URL with a wildcard cannot be set as the default redirect URI.

## Implementing SSO with WorkOS

This document offers guidance to integrate Single Sign-On with our standalone API into your existing auth stack. You might also want to look at [AuthKit](/authkit), a complete authentication platform that leverages Single Sign-On functionality out of the box, following best practices.

### Login Flows

Learn the differences between SP‑initiated and IdP‑initiated SSO.

The instructions in the [Quick Start guide](/sso) focus on setting up Service Provider (SP)-initiated SSO. In these scenarios, when a user attempts to login, they navigate to an application (a service provider) and are then redirected to the [Identity Provider (IdP)](/glossary/idp) for authentication, via the WorkOS API.

Alternatively, most users are able to start the process from the Identity Provider itself. Organizations will often provide an IdP dashboard where employees can select any of the eligible applications that they can access via the IdP, similar to the screenshot below. Clicking on a tile results in an IdP-initiated login flow, since the user initiates the login from the Identity Provider, not the application.

![Screenshot of the Okta dashboard](https://images.workoscdn.com/images/1489f46f-bbcd-4e47-a217-3a45f0f795aa.png?auto=format&fit=clip&q=50)

---

## SP-initiated SSO

With an SP-initiated login flow, the user begins the authentication process from your application. You can control where the user will be redirected after login by specifying the `redirectURI` parameter when making the [Get Authorization URL](/reference/sso/get-authorization-url) call. Additionally, this call can take an optional `state` parameter - this parameter will be returned in the callback after authentication, where your application can use it to verify the validity of the response or to pass any state from the originating session. One common practice is to route requests from different Organizations to a single Redirect URI, but instead utilize the `state` parameter to deep link users into the application after the authentication is completed.



## Implementing SSO with WorkOS

This document offers guidance to integrate Single Sign-On with our standalone API into your existing auth stack. You might also want to look at [AuthKit](/authkit), a complete authentication platform that leverages Single Sign-On functionality out of the box, following best practices.

### Launch Checklist

Make sure you’re ready to take your app to production.

## Implement complementary enterprise features

- Integrate the WorkOS [Admin Portal](/admin-portal) to enable your users to onboard and set up SSO themselves.
- Integrate the WorkOS Directory Sync API for automatic user updating, provisioning, and deprovisioning.

### Before you start

This document offers guidance to integrate Single Sign-On with our standalone API into your existing auth stack. You might also want to look at [AuthKit](/authkit), a complete authentication platform that leverages Single Sign-On functionality out of the box, following best practices.

## Create an IP Allowlist

WorkOS makes use of Cloudflare to ensure security and reliability of all operations. If you are looking to create a list of allowed IP addresses for redirect requests, you can use the IP Ranges listed in the [Cloudflare documentation](https://www.cloudflare.com/ips/).

## Go-live checklist

- [ ] Implement an SSO UI/UX. See our guide for ideas – [UI/UX Best Practices for IdP & SP-Initiated SSO](https://workos.com/blog/ui-ux-best-practices-for-idp-and-sp-initiated-sso)
- [ ] [Test the end-to-end SSO](/sso/test-sso) experience in your Staging environment.
- [ ] Unlock your Production environment by adding your billing information
  > Only enterprise connections in your Production environment will be charged. OAuth connections in Production will be free.
- [ ] Set your Production Client’s ID and API Key as environment variables
- [ ] Secure your Production Project’s API key
- [ ] Configure production redirect URI(s) in your Product Project. Verify the default redirect URI is correct
- [ ] Ensure that your application can receive redirects from WorkOS.
      Depending on your network architecture, you may need to allowlist incoming redirect traffic from `api.workos.com`.
- [ ] Add Connections for your customers in the Production Environment

## Frequently asked questions

### How should an application handle the first time a user authenticates using WorkOS?

If a user is authenticating to your application for the first time via SSO and doesn’t have an account, you can implement just-in-time provisioning to create a user when authentication is complete.

You can also leverage [Directory Sync](/directory-sync) to pre-provision users with API endpoints or webhooks. In this case, the user will already be created in your application when they authenticate for the first time.

### Can we add SSO authentication for a current user in an application?

If a user is authenticating to your application via SSO, but already has an account (with username/password for example), you can “upgrade” them to SSO. Usually the emails are the same for both methods of authentication, so you can match on email address. Once SSO via WorkOS is enabled, you can restrict users to sign in with only SSO.

### How does WorkOS manage user attributes from an identity provider?

WorkOS normalizes user attributes so you can expect known values such as `id`, `email`,`firstName`, and `lastName`.

### Is the user attribute mapping configurable in WorkOS?

Yes. For example, let’s say the `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` attribute contains the user email rather than the `surname` as the attribute name suggests. In these edge cases, WorkOS will identify any attributes that are misconfigured and recommend correct mapping in the “Attribute Mapper“ section of the “Connection info” page.

### What does the “Allow Profiles Outside Organization” option do?

By default, WorkOS restricts user profiles for SAML Connections to profiles that have email domains that are in the set of [User Email Domains](/reference/organization-domain) on the Organization.

Enabling this option removes this restriction and allows user profiles with any email address to sign in through Connections under this Organization.

If this option is enabled, your code can not exclusively trust the returned `email` attribute on user profiles to be a verified email address. Instead, you must use the `organization_id` or `connection_id` in order to verify that the profile belongs to whom it claims.

### What does “There are 0 profiles awaiting reconciliation” refer to?

This refers to the number of user profiles that have inconsistent attribute mappings, and that need to be updated in order to successfully authenticate.

### How do I integrate WorkOS SSO with my native mobile application?

When it comes to mobile applications, our typical advice in implementing SSO authentication goes like this:

1. Generate the authentication URL and route the user to a browser or browser fragment in order to authenticate.
2. The end user authenticates via the native UI of their IdP within that browser.
3. Upon successful authentication, deep-link the user back into your native application.

### Just-In-Time User Provisioning

Learn how to provision users in your app using Just-In-Time user provisioning.

## Introduction

User provisioning is the process of creating a user account and associated identity information. There are various ways for an application to provision users. This guide explores user provisioning strategies and offers a deep dive into SSO-based just-in-time (JIT) user provisioning.

## Definitions

**User provisioning**
: Provisioning is the process of creating a user and setting attributes for them inside an app.

**JIT user provisioning**
: Just-in-time user provisioning creates a user in an app when the user attempts to sign in for the first time. The account and respective role don’t exist until the app creates them – just-in-time.

**Identity**
: An identity is a collection of attributes associated with a user or entity in an identity provider. For example, an identity includes at least one unique identifier, such as id, and user profile attributes, such as name and email.

**Role**
: A primitive in your app that defines specific permissions for the users. Roles are often defined as an ability or a job title, for example, “Editor” or “Accountant”.

## User provisioning strategies

User provisioning is the process of creating a user account with associated identity data in your app. Your app needs to determine a unique identifier for an identity, create a unique account for that user, and link the identity profile attributes to that user’s account. There are many strategies to provision users in an app, but the main three are:

1. Self-registration
2. Provisioning users via [Directory Sync](/directory-sync)
3. JIT provisioning via SSO

The type of provisioning needed will depend on your app’s architecture and level of enterprise feature support:

| Strategy               | Description                                                           | Usage                                                                                                |
| ---------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Self-registration      | Users fill out a registration form to create an account in the app    | For users that don’t have an SSO service, usually the first authentication mechanism built in an app |
| Pre-provisioning users | Use a service like Directory Sync to create users in the app          | Required by large enterprises to automatically provision users                                       |
| JIT provisioning       | Create a user account when a user signs in via SSO for the first time | Leverage user identity from an SSO provider to create an account in your app                         |

## What is JIT provisioning?

JIT provisioning creates a user account with associated identity information when a user authenticates via SSO for the first time. IT admins often use JIT provisioning to quickly set up accounts in an app. Typically, apps that implement only SSO will have JIT provisioning support as the alternative is self-registration by individual users or manual entry of all users by the IT admin.

### Sample scenario

Consider the fictional SaaS company _HireOS_, which offers recruiting software to other businesses. _HireOS_ is an online app allowing customers to track leads, candidates, and interviews.

_HireOS_ has integrated SSO using WorkOS and supports JIT provisioning. For example, a _HireOS_ customer would like their users to have accounts automatically provisioned in _HireOS_ when they first log in. The customer’s IT admin will only need to assign the users to the _HireOS_ SAML app in their identity provider. When users log into _HireOS_ via SSO, they will have accounts created in _HireOS_, just in time.

A usual account setup flow using JIT provisioning follows these steps:

1. An IT admin self-registers via username and password to create a team account in _HireOS_.
2. The IT admin configures the _HireOS_ team account to use SSO as the authentication mechanism.
3. The IT admin enables JIT provisioning for this team account by clicking the "Enable JIT Provisioning" checkbox.
4. The IT admin adds the users that should get access to _HireOS_ to the app in the identity provider.
5. When a user logs into _HireOS_ with the correct email domain and authenticates via SSO, _HireOS_ creates the user account upon successful first-time login.

## JIT provisioning with WorkOS SSO

When a user authenticates to your app via SSO for the first time, and JIT provisioning is enabled, your app provisions a new user account. You can create the account by saving the identity information (the WorkOS SSO profile) directly on your app's user account. Or, you can create a separate identity from the WorkOS SSO profile related to this new user account. This logic allows users to have multiple identities if your app supports several login methods per user.

You can use the WorkOS SSO profile `id` attribute as the unique identifier for this identity from WorkOS. WorkOS ensures the profile is unique per SSO connection via the `idp_id`. In addition, your app can use either the `connection_id` or `organization_id` to tie the identity to a team account.

```json language="json" title="SSO user profile"
{
  "object": "profile",
  "id": "prof_01DMC79VCBZ0NY2099737PSVF1",
  "connection_id": "conn_01E4ZCR3C56J083X43JQXF3JK5",
  "connection_type": "OktaSAML",
  "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "email": "todd@example.com",
  "first_name": "Todd",
  "last_name": "Rundgren",
  "idp_id": "00u1a0ufowBJlzPlk357",
  "role": {
    "slug": "admin"
  },
  "raw_attributes": {}
}
```

You may want to grant new users roles in your application via JIT provisioning. For more information on mapping role data between the IdP and your app, see the [Mapping Roles](/sso/identity-provider-role-assignment) guide.

### New account creation

When your app receives a WorkOS SSO profile, it is standard to perform the following series of checks:

1. Find an identity with the profile `id` or `idp_id`. If found, log in the corresponding user.
2. If you cannot find an identity, try to find a user with the same `email` as the profile. If found, create an identity for the user and log them in.
3. Otherwise, create a new identity using the WorkOS SSO profile, create a new user, and associate this identity with the user account.

### Linking an existing user

If an admin adds SSO authentication to their team account after they've had users register, your app can link these new SSO identities to the current user accounts, just-in-time.

A linking field (e.g. `email`) should be established to find a current user with the incoming WorkOS SSO Profile. Then, the identity information can be linked with the existing user account via a persistent identifier in case of an email change later.

## Implementing SSO with WorkOS

This document offers guidance to integrate Single Sign-On with our standalone API into your existing auth stack. You might also want to look at [AuthKit](/authkit), a complete authentication platform that leverages Single Sign-On functionality out of the box, following best practices.

### FAQ for IT teams

Answers to common questions from your customer’s IT team.

## What is WorkOS?

WorkOS is a software company that provides a suite of products to make an app enterprise-ready. These products include Single Sign-On, Directory Sync, and AuthKit (user management), among others.

Developers integrate WorkOS services into their apps in order to provide a secure authentication and user provisioning experience. It’s trusted by companies like Webflow, Plaid, Vercel, and many others.

## What data does WorkOS store?

For Single Sign-On, WorkOS stores the user profile from the identity provider. This includes the user's name, email and IP address.

For Directory Sync, WorkOS will store the data that the identity provider sends. The shape and content of that data is at the discretion of the identity provider.

For more information, view our [Privacy Policy](https://workos.com/legal/privacy)

## How do developer apps communicate with WorkOS?

Developers integrate with WorkOS using its Rest API and the related SDKs. You can find a list of all WorkOS API endpoints in the [API reference](/reference).

## What IP addresses does WorkOS use?

WorkOS uses Cloudflare to ensure security and reliability of all operations. If you are looking to create a list of allowed IP addresses for the WorkOS API, you can use the IP ranges listed in the [Cloudflare documentation](https://www.cloudflare.com/ips/).

## Is WorkOS certified for SOC 2 Type II, SOC 3 and SIG Lite?

Yes, WorkOS is compliant with all the above and regularly undergoes penetration testing.

## Is WorkOS GDPR compliant?

Yes, WorkOS is GDPR compliant. Reach out to [support](mailto:support@workos.com) to request deletion of data.

### Single Sign-On

Facilitate greater security, easier account management, and accelerated application onboarding and adoption.

## Choose your integration approach

There are two ways to integrate Single Sign-On (SSO) with WorkOS:

### (A) With the standalone SSO API

The standalone API (covered in this document), is a standalone API for integrating into an existing auth stack.

### (B) Using WorkOS AuthKit

[AuthKit](/authkit) is a complete authentication platform which includes SSO out of the box.

## How Single Sign-On works

Single Sign-On is the most frequently asked for requirement by organizations looking to adopt new SaaS applications. SSO enables authentication via an organization’s [identity provider (IdP)](/glossary/idp).

This service is compatible with any IdP that supports either the [SAML](/glossary/saml) or [OIDC](/glossary/oidc) protocols. It’s modeled to meet the [OAuth 2.0](/glossary/oauth-2-0) framework specification, abstracting away the underlying authentication handshakes between different IdPs.

![Authentication Flow Diagram](https://images.workoscdn.com/images/90b84f08-3363-446a-8610-f7b2bd2ee2ca.png?auto=format&fit=clip&q=80)[border=false]

WorkOS SSO API acts as authentication middleware and intentionally does not handle user database management for your application.

## What you’ll build

In this guide, we’ll take you from learning about Single Sign-On and POC-ing all the way through to authenticating your first user via the WorkOS SSO API.

## Before getting started

To get the most out of this guide, you’ll need:

- A [WorkOS account](https://dashboard.workos.com/)
- A local app to integrate SSO with.

Reference these [example apps](/sso/example-apps) as you follow this guide.

## API object definitions

[Connection](/reference/sso/connection)
: The method by which a group of users (typically in a single organization) sign in to your application.

[Profile](/reference/sso/profile)
: Represents an authenticated user. The Profile object contains information relevant to a user in the form of normalized and raw attributes.

## (1) Add SSO to your app

Let’s build the SSO authentication workflow into your app.

### Install the WorkOS SDK

WorkOS offers native SDKs in several popular programming languages. Choose a language below to see instructions in your application’s language.



### Set secrets

To make calls to WorkOS, provide the API key and, in some cases, the client ID. Store these values as managed secrets, such as `WORKOS_API_KEY` and `WORKOS_CLIENT_ID`, and pass them to the SDKs either as environment variables or directly in your app’s configuration based on your preferences.

```plain title="Environment variables"
WORKOS_API_KEY='sk_example_123456789'
WORKOS_CLIENT_ID='client_123456789'
```

> The code examples use your staging API keys when [signed in](https://dashboard.workos.com)

### Add an endpoint to initiate SSO

The endpoint to initiate SSO via the WorkOS API is responsible for handing off the rest of the authentication workflow to WorkOS. There are a couple configuration options shown below.

You can use the optional `state` parameter to encode arbitrary information to help restore application state between redirects.

- | Using organization ID

  Use the organization parameter when authenticating a user by their specific organization. This is the preferred parameter for SAML and OIDC connections.

  The example below uses the Test Organization that is available in your staging environment and uses a mock identity provider. It’s created to help you test your SSO integration without having to go through the process of setting up an account with a real identity provider.

  

- | Using connection ID

  You can also use the connection parameter for SAML or OIDC connections when authenticating a user by their connection ID.

  

- | Using provider

  The provider parameter is used for OAuth connections which are configured at the environment level.

  > The supported `provider` values are `GoogleOAuth`, `MicrosoftOAuth`, `GitHubOAuth`, and `AppleOAuth`.

  

If there is an issue generating an authorization URL, WorkOS will return the redirect URI as is. Read the [API Reference](/reference/sso/get-authorization-url) for more details.

### Add a callback endpoint

Next, let’s add the redirect endpoint which will handle the callback from WorkOS after a user has authenticated with their identity provider. This endpoint should exchange the authorization code returned by WorkOS with the authenticated user’s profile. The authorization code is valid for 10 minutes.



When adding your callback endpoint, it is important to always validate the returned profile’s organization ID. It’s unsafe to validate using email domains as organizations might allow email addresses from outside their corporate domain (e.g. for guest users).

---

## (2) Configure a redirect URI

Go to the [Redirects](https://dashboard.workos.com/redirects) page in the dashboard to configure allowed redirect URIs. This is your callback endpoint you used in the previous section.

Multi-tenant apps will typically have a single redirect URI specified. You can set multiple redirect URIs for single-tenant apps. You’ll need to be sure to specify which redirect URI to use in the WorkOS client call to fetch the authorization URL.

> More information about wildcard characters support can be found in the [Redirect URIs](/sso/redirect-uris/wildcard-characters) guide.

![Redirects in the Dashboard](https://images.workoscdn.com/images/195dbff3-adbf-4010-b07c-ffc73ceeca68.png?auto=format&fit=clip&q=90)

### Identity provider-initiated SSO

Normally, the default redirect URI you configure in the WorkOS dashboard is going to be used for all identity provider-initiated SSO sessions. This is because the WorkOS client is not used to initiate the authentication flow.

However, your customer can specify a separate redirect URI to be used for all their IdP-initiated sessions as a `RelayState` parameter in the SAML settings on their side.

Learn more about configuring IdP-initiated SSO in the [Login Flows](/sso/login-flows/idp-initiated-sso/configure-idp-initiated-sso) guide.

---

## (3) Test end-to-end

If you followed this guide, you used the Test Organization available in your staging environment to initiate SSO. With that, you can already test your integration end-to-end.

![Test SSO WorkOs Dashboard](https://images.workoscdn.com/images/7b7407d7-dcc7-4fd4-859f-4ee4214d69c2.png?auto=format&fit=clip&q=80)

Head to the _Test SSO_ page in the [WorkOS Dashboard](https://dashboard.workos.com/) to get started with testing common login flows, or read on about that in detail in the next guide.

### Identity Provider Role Assignment

Learn how to map role data from identity providers to roles in your app with SSO.

## Introduction

A role represents a logical grouping of permissions, defining access control levels for users within your application. Roles are identified by a unique, immutable slug and are assigned to [SSO user profiles](/reference/sso/profile) through their identity provider group memberships. These group role mappings can be configured on the WorkOS dashboard.

To utilize Identity Provider (IdP) role assignment, you must first [configure roles](/rbac/configuration).

## SSO group role assignment

Users are assigned to groups via the identity provider. Groups usually correspond to roles in your app. Therefore, IT admins will often map a group one-to-one to a role.

During authentication, a user's identity provider group memberships can be read via attributes. This enables you to define SSO groups that correspond to IdP groups and set role assignments for those groups in the WorkOS Dashboard.

Based on these settings, SSO user profiles returned from WorkOS will include a role attribute that reflects their highest priority group membership. The SSO user profile role is calculated during each sign-in.

![Session page showing user profile with role defined](https://images.workoscdn.com/images/ceea13ba-bf6b-4ea1-a25c-0a08e8833fb0.png?auto=format&fit=clip&q=50)

> Supported in both SAML and OIDC-based connection types, except for Google OIDC due to [a limitation](https://issuetracker.google.com/issues/133774835?pli=1) with the groups claim.

### Sample scenario

Consider the fictional SaaS company _HireOS_. _HireOS_ has set up an SSO Connection and configured group-based role assignment. For example, a _HireOS_ customer would like to assign their engineering team to the application. The customer’s IT admin would take the following steps:

1. Create an “Engineering” group using their identity provider.
2. Configure the `groups` attribute in their SAML app to return the group memberships.
3. Provide the developer with the IdP ID for the "Engineering" group.

In the WorkOS dashboard, the developer can then assign users of that group to the role "Engineer".

1. Navigate to the _Connection_ section of the WorkOS dashboard.

![SSO group role assignment card](https://images.workoscdn.com/images/28606b9b-fd5b-4219-8b8f-3a640295e784.png?auto=format&fit=clip&q=50)

2. Create an SSO group defining the IdP ID for the "Engineering" group. Then, assign this group to the "Engineer" role.

![Dialog to create connection group with role assignment](https://images.workoscdn.com/images/648410f3-1b82-4ebd-97f3-a8f6edbdd27e.png?auto=format&fit=clip&q=50)

From this point on, whenever a user in the "Engineering" group authenticates via SSO, they will be granted the "Engineer" role for that session from the WorkOS API. The role will be returned in the [profile response](/reference/sso/profile).

```json language="json" title="SSO user profile"
{
  "object": "profile",
  "id": "prof_01DMC79VCBZ0NY2099737PSVF1",
  "connection_id": "conn_01E4ZCR3C56J083X43JQXF3JK5",
  "connection_type": "OktaSAML",
  "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "email": "todd@example.com",
  "first_name": "Todd",
  "last_name": "Rundgren",
  "idp_id": "00u1a0ufowBJlzPlk357",
  "role": {
    "slug": "engineer"
  },
  "roles": [
    {
      "slug": "engineer"
    },
  ]
  "raw_attributes": {}
}
```

> When a user is not a member of any groups or their groups do not match any SSO group role assignments, the user will be granted the [default role](/rbac/configuration/configure-roles/default-role) in the SSO profile.

### Multiple roles

When [multiple roles is enabled](/rbac/configuration/configure-roles/multiple-roles), a user can be assigned multiple roles from their identity provider group memberships. If a user belongs to multiple mapped groups, they will receive all corresponding roles in their SSO profile.

For example, if a user is a member of both "Engineering" and "Design" groups, and both groups are mapped to roles, the user will receive both the "Engineer" and "Designer" roles. If a user is not a member of any groups with explicit mappings, they will receive the [default role](/rbac/configuration).

#### Use cases

By default, multiple roles is disabled and users can only have a single role per entity. It's recommended to start with a single-role setup for simplicity, where it's easier to maintain consistent and correct access patterns.

You might want to enable multiple roles when you need:

- **Cross-department collaboration**: e.g., designers who need some engineering permissions.
- **Additive, disjoint permissions**: independent permission sets that should stack.
- **Temporary access**: grant time-bound extra capabilities without creating hybrid roles.

### Role assignment in Admin Portal

Once [roles](/rbac/configuration) are configured for your application, enable SSO group role assignment in [Admin Portal](/admin-portal) to allow IT admins to assign roles to groups during SSO connection setup. If enabled, all Admin Portal sessions for SSO connections will have the ability to configure and assign roles to groups.

![Enable SSO group role assignment dashboard setting](https://images.workoscdn.com/images/04f86ccc-87a1-4db6-bd54-54a685d409ef.png?auto=format&fit=clip&q=50)

This is an environment-level setting, but can be configured per organization via the _Roles_ tab under an organization in the WorkOS Dashboard.

## Considerations

Your customers will store role information in different forms, depending on their preferred provisioning workflow. WorkOS allows for flexibility in how you source role data. However, there are some considerations to keep in mind when using SSO-based connection groups for role assignment.

### Drawbacks

**Strictly** assigning roles during [JIT user provisioning](/sso/jit-provisioning) has a few caveats:

- Your customer must explicitly map the SAML `groups` attribute in the SSO setup so that you can retrieve that attribute in the SSO profile.
- SSO groups need to be manually defined.
- Your app will receive updates to this user’s group data only once they sign-in with SSO again. This delay can allow unauthorized users to access resources using a stale role.

### Directory group role assignment

Directory Sync supports [group-based role assignment](/directory-sync/identity-provider-role-assignment/directory-group-role-assignment) and avoids the pitfalls mentioned above. For organizations with a directory, this method of group-based role assignment is preferred.

It’s recommended to use only one method of role assignment—either from a Directory or an SSO Connection—to avoid overlap.

### Example Apps

View sample Single Sign-On apps for each SDK.

You can view minimal example apps that demonstrate how to use the WorkOS SDKs to authenticate users via SSO:


  
  
  
  
  
  
  
  
  
</ExampleApps.Root>

### Domains

Understand how Organization domains are used with SSO.

## Organizations

When an [Organization](/reference/organization) is created in the WorkOS Dashboard or the [Create Organization API](/reference/organization/create), one or more domains can be associated with the organization.

Domains added to an organization need to be verified in order to activate SSO. When creating an organization via the API, domains can be initially added as either `'verified'` if already trusted, or `'pending'` if further verification is required.

If added as `'pending'`, the domain can later be verified manually via the [Domain Verification API](/domain-verification/api) or WorkOS Dashboard, or by an IT admin via the self-serve [Admin Portal](/domain-verification/) flow.

> Domains manually added in the WorkOS Dashboard are automatically considered verified.

## Email validation

During authentication, WorkOS uses these domains to verify the user signing in through the organization's [Connection](/reference/sso/connection) belongs to one of these domains. If the domain of the user's email address does not match one of the organization's domains (or the organization has no verified domains) they will be sent to your [Redirect URI](/sso/redirect-uris) with a [`profile_not_allowed_outside_organization`](/reference/sso/get-authorization-url/error-codes) error.

Rejecting users with non-matching email domains prevents the impersonation of users in other organizations. This would otherwise be possible since many Identity Providers allow IT admins to create user accounts with _any_ email address, regardless of whether the IT admin actually controls the email address or its domain.

For example, an IT admin of an organization with the domain `foo.com` can create a user account for `user@bar.com` in their Identity Provider and then sign in as that user. If the application were to receive the profile and naively look up the user record using _only_ the email address, then the IT admin will have gained access to the `user@bar.com` account.

Since WorkOS cannot guarantee every application handles this scenario correctly, **the default behavior is to reject profiles when its email address does not match the associated organization's domains.**

## Allowing any domain

Some applications may have organizations whose users sign in using a list of domains that cannot be statically defined, or a set of domains so large as to be cumbersome to configure.

A common use-case is non-domain guests. Imagine an organization hires a design consultancy and requires the designers to sign in using the organization's IdP. While the organization can create accounts in their IdP for these guests, they cannot add the designer's domain to the WorkOS organization since they cannot verify ownership of it. The default organization domain verification policy will prevent these designer's from signing in.

If your application has a similar use-case, [contact support](mailto:support@workos.com) and we can work with you to relax the default organization domain verification policy. SSO will no longer require any domains to be added to the organization. This change can be made for any of your environments and will affect all organizations in the environment.

## Implement profile validation

Your application will be responsible for validating the email addresses of users using SSO, and checking the appropriate fields from the SSO profile.

Important data from the SSO profile includes the `id` and the `organization_id`. Generally applications will store the Profile `id` alongside its users, such as a column on a `users` table. Similarly, the `organization_id` will be stored on the matching entity, such as a `teams` or `workspace` table; whichever represents a collection of users that are related to each other.

```json language="json" title="SSO profile"
{
  "object": "profile",
  "id": "prof_01DMC79VCBZ0NY2099737PSVF1",
  "connection_id": "conn_01E4ZCR3C56J083X43JQXF3JK5",

  // Your application should restrict any email-based JIT user
  // provisioning to within the organization that matches this ID.
  "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",

  // Only match based on email or email domain unless you are
  // filtering potential matches by the organization ID above.
  "email": "todd@example.com"

  // ...
}
```

Here's an updated version of the WorkOS callback endpoint from the [Quick Start guide](/sso/1-add-sso-to-your-app/add-a-callback-endpoint) with examples of these checks added:

```javascript langauge="JavaScript" title="WorkOS callback"
const { WorkOS } = require('@workos-inc/node');
const workos = new WorkOS(process.env.WORKOS_API_KEY);

app.get('/callback', async (req, res) => {
  const { profile } = await workos.sso.getProfileAndToken({
    code: req.query.code,
    clientId: process.env.WORKOS_CLIENT_ID,
  });

  // Your application should have a resource that is analogous to the WorkOS
  // organization, like a "team" or "workspace".
  const team = TeamsService.findByWorkOsOrganizationId(profile.organizationId);

  if (!team) {
    return res.status(401).send({
      message: 'Unauthorized',
    });
  }

  // Your application should use the Profile ID to determine whether there is an
  // existing user linked to the SSO profile, within the scope of the "team" or
  // "workspace" associated with the WorkOS organization.
  //
  // If none is found, you can then fall back to the `email` address. If one is
  // found you should link the profile ID to the user for subsequent sign-ins.
  //
  // Finally, if no user exists with the email either, you can implement
  // JIT-provisioning and create a new user record, persisting both the `email`
  // and the ID from the profile.
  const { user } = team.users.findOrCreateByWorkOsProfile(profile);

  // Make sure to verify the user's email address. You may choose to skip
  // email verification in order to improve UX, but should only do so if
  // the new user's email address matches an expected domain for the "team".
  if (!user.emailVerified) {
    res.redirect('/verify-email');
  } else {
    // Start a session for the user.
    // ...

    res.redirect('/');
  }
});
```

> The above example makes use of JIT-provisioning, which you can read more about in more our dedicated [JIT-provisioning guide](/sso/jit-provisioning).

With the above checks in place, your application can safely sign in and verify users through SSO from any domain.

## Custom ACS domains

While your users will authenticate with SSO using your application, they might briefly see the WorkOS [ACS URL](/glossary/acs-url). This can be configured in the production environment to a custom domain of your choosing. For more information see the [Custom Domains](/custom-domains) documentation.

### Profile Attributes

Configure how attributes map from identity providers to SSO Profiles.

## Introduction

WorkOS automatically normalizes a standard set of attributes from identity providers (IdPs) into the [Single Sign-On (SSO) Profile](/reference/sso/profile) object. More unique cases can be mapped by your customer admins. In this guide, we’ll explain how to map data from identity providers to the SSO Profiles.

## Definitions

**Standard attributes**
: The most common user information, normalized across providers.

**Predefined attributes**
: Detailed user attributes for specific use cases, normalized across providers. You can opt-in to each attribute you'd like organization admins to map during SSO connection configuration.

**Custom attributes**
: For unique cases, you can create custom attributes your customers can map when setting up an SSO connection.

## Standard attributes

Every SSO Profile comes with the following standard attributes. These are the core set of attributes that are common across all identity providers. These are structured fields with a guaranteed schema in the top-level SSO Profile payload.

| Attribute    | Description                                                                                                            |
| ------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `idp_id`     | The user’s unique identifier, assigned by the identity provider. Different identity providers use different ID formats |
| `email`      | The user’s email                                                                                                       |
| `first_name` | The user’s first name                                                                                                  |
| `last_name`  | The user’s last name                                                                                                   |

---

## Custom attributes

For more detailed user information, you can opt-in to additional predefined attributes and define your own custom attributes. These attributes will appear in the custom attributes field on [SSO Profile](/reference/sso/profile) objects and can be configured in the [WorkOS Dashboard](https://dashboard.workos.com/).

### Predefined attributes

When enabled, organization admins will be asked to map these attributes during SSO configuration in [Admin Portal](/admin-portal). These fields are always optional if enabled. These fields are named and schematized by WorkOS – they cannot be renamed.

| Attribute               | Type and description                                                                                                            | Status   |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `addresses`             | The user’s list of address objects (`street_address`, `locality`, `region`, `postal_code`, `country`, `primary`, `raw_address`) | Optional |
| `cost_center_name`      | The user’s cost center name                                                                                                     | Optional |
| `department_name`       | The user’s department name                                                                                                      | Optional |
| `division_name`         | The user’s division name                                                                                                        | Optional |
| `emails`                | The user’s list of email objects (`type`, `value`, `primary`)                                                                   | Optional |
| `employee_type`         | The user’s employment type                                                                                                      | Optional |
| `employment_start_date` | The user’s start date                                                                                                           | Optional |
| `job_title`             | The user’s job title                                                                                                            | Optional |
| `manager_email`         | The email address for the user’s manager                                                                                        | Optional |
| `username`              | The user’s username                                                                                                             | Optional |

#### Enable or disable a predefined attribute

Predefined attributes can be enabled or disabled in the [WorkOS Dashboard](https://dashboard.workos.com/) on the Identity Provider Attributes page.

![WorkOS Dashboard UI showing editing predefined attributes](https://images.workoscdn.com/images/73b775ed-c3ef-4c81-bb56-7b040d3d073a.png?auto=format&fit=clip&q=50)

> For SSO Profiles, making changes to IdP attributes will take effect upon next sign-in.

### Custom attributes

Custom attributes can be utilized to enrich SSO Profiles with additional data from the identity provider. You can create attributes that appear as fields in the [Admin Portal](https://workos.com/admin-portal). Your customers can map these fields to the correct values in their system when setting up SSO with their identity provider.

#### Create a custom attribute

Custom attributes can be created in the [WorkOS Dashboard](https://dashboard.workos.com/) on the Identity Provider Attributes page.

![WorkOS Dashboard UI showing custom attribute creation](https://images.workoscdn.com/images/c1d00c4c-4dea-415e-a8f8-c870317410df.png?auto=format&fit=clip&q=50)

> For SSO Profiles, making changes to IdP attributes will take effect upon next sign-in.

#### Delete a custom attribute

When a custom attribute is deleted, [SSO Profiles](/reference/sso/profile) will retain these existing attribute values until the next sign-in.

#### Editing attribute mappings

If attribute data for a particular SSO connection has changed and is no longer mapped properly, you or the organization admin can edit the attribute mappings via the [WorkOS Dashboard](https://dashboard.workos.com/) connection page or [Admin Portal](https://workos.com/admin-portal), respectively.

![WorkOS Dashboard UI showing editing attribute mappings for a connection](https://images.workoscdn.com/images/09395b6c-d037-440f-a17e-ef0507868532.png?auto=format&fit=clip&q=50)

### Custom attribute mapping in Admin Portal

You can control the visibility of custom attribute mapping for Directory Sync and Single Sign-On flows in the Admin Portal at the environment and organization level.

The environment-level setting is controlled on the Identity Provider Attributes page in the [WorkOS Dashboard](https://dashboard.workos.com/).

![WorkOS Dashboard UI showing editing custom attribute mapping in Admin Portal setting](https://images.workoscdn.com/images/23ee5439-6cbb-4c18-ac39-0870d63bfc0b.png?auto=format&fit=clip&q=50)

Organization-level settings are controlled on an individual organization's Attributes tab in the [WorkOS Dashboard](https://dashboard.workos.com/). Organizations mirror the environment-level settings by default.

## Frequently asked questions

### Which identity providers support mapping additional predefined and custom attributes?

Additional predefined and custom attributes are supported for all SAML SSO connections.

### Can our customers add their own custom attributes outside of what is defined in the WorkOS Dashboard?

We do not currently support this functionality. Custom attributes must be defined in the WorkOS Dashboard first. Please reach out to [support](mailto:support@workos.com) if you have a specific use case that you would like to discuss.

### What happens if an attribute cannot be mapped from the IdP?

Attributes that cannot be mapped for a particular [SSO Profile](/reference/sso/profile) will result in a `null` value for the attribute.

### Sign-In UX

User experience considerations for Single Sign-On.

## Introduction

Now that we’ve seen how the Single Sign-On (SSO) APIs work, you may want to consider how to best integrate this new flow in the sign-in experience for your users. This guide will walk you through a few different approaches you could take in your application:

- Separate SSO flow
- Separate email and password fields
- Auto-hide the password field

Throughout this guide, let’s consider the following scenario:

- You are building an app called _Demo App_
- An organization named _Foo Corp_ is using Single Sign-On with Okta as the [IdP](/glossary/idp)

### Implementing SSO with WorkOS

This document offers guidance on UX best practices when integrating SSO with the standalone API. You might instead consider [WorkOS AuthKit](/authkit), a complete authentication platform which handles all of the UX complexity for you.

## Separate SSO flow

A basic approach would be to create a link or button on your login page with a **Sign in with SSO** or **Use Single Sign-On** option. This method differentiates the flows for the user explicitly.

You may still look up the domain if they try to sign in with their corporate email and redirect them to the appropriate flow too—see the demo below as an example.



As this adds yet another button, one thing to be mindful with this approach is the [NASCAR problem](https://indieweb.org/NASCAR_problem) where a cluster of 3rd party branded buttons creates both visual noise and confusion. Consider only offering a couple of options that are relevant to your user base.

## Separate email and password fields

Instead of asking users for their email and password in one screen, you could first ask them for their email. This method gives you an opportunity to check if a particular domain is SSO-enabled and redirect the user to the appropriate SSO flow. It is a very popular approach employed by many applications (including WorkOS itself, Apple, and Google).



## Auto-hide the password field

Finally, as an extension to the previous approach, you can automatically hide the password field if the user’s domain is SSO-enabled. This feature is a bit more complicated to implement, but provides a more seamless experience for users.


## Sdks {#sdks}

### ruby

## Installation

### python

## Installation

### php

## Installation

### node

## Installation

### laravel

## Installation

### java

## Installation

### go

## Installation

### elixir

## Installation

### dotnet

## Installation


## API Reference {#reference}

### Testing the API