Prerequisites
In order to setup SSO, you must:
Have an API Platform Organization with a Custom/Enterprise Billing Plan
Be an owner in this organization
Before proceeding, please review our SSO Overview and User Management documentation pages to ensure you are familiar with our SSO architecture.
If you recently purchased an Enterprise ChatGPT license and are looking to configure SSO on the ChatGPT workspace, please follow the instructions here.
If you previously configured SSO on your Enterprise ChatGPT workspace, your SSO settings should already be ported over and are likely active. In this scenario, you would see the fields pre-populated on your API Platform Identity page, and you just need to ensure the "Single Sign On" button is toggled on for the organization.
⚠️ You and all of your users will be locked out if SSO is not set up correctly!
An incorrect setup can result in you and all your users being locked out. We recommend that you, as the owner of the workspace, keep two separate logged in windows open:
One logged in through an incognito window
One logged in through your standard browser
This allows you to test the login process and your SSO/Domain Verification setup on one window, and to revert the changes if needed via the second window.
Enabling SSO
To get started, navigate to the "Identity" page underneath your Organization settings.
Some of the examples below will showcase the setup in Okta, but the same logic should be applicable to all SAML IdP's.
Domain Verification
In order to enable SSO, we require that you first verify at least one domain.
Important: Remember to review the downstream impact that domain verification may have upon users with that domain once SSO is enabled.
Click the "+ Add Domain" button and enter your DNS to get started:
Once submitted, we provide a key for you to verify ownership of your domain. Navigate to your DNS provider, and add a TXT record with the provided value:
Your TXT record must be reachable via a DNS lookup in order for the verification check to succeed.
After completing this in your DNS provider, return to the setup page and click the "Check" button. If your domain ownership was validated successfully, you will see the status updated to "Verified."
You can add up to 99 verified domains per organization-id, and we provide a 7-day period for you to complete the verification check before marking a domain as expired.
Currently, domains can only be verified on a single organization. If you need to verify the same domain across multiple organizations, please contact Support.
Configuring Your SAML Application
After successfully verifying your domain, you can proceed with the SSO setup.
ACS URL and Entity ID
The ACS URL and Entity ID are standard values required for setting up a SAML application. Once you've verified a domain, you should see the values populated on the Identity page:
While the exact location to place these values will vary depending upon your IdP, the general logic should be consistent. Using Okta as an example, we can create a new SAML 2.0 application and set these two parameters accordingly:
Attribute Mapping
The attribute mapping you define in your SAML application ultimately determines how your users are created/how they appear in the API Platform. Our current user model supports three properties:
Email Address (required in the SAML response)
First Name (optional)
Last Name (optional)
And we use the following attributes in the SAML token that map to the corresponding user properties:
{
"email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
"given_name": [
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
],
"family_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
}
Note: We do not support decrypting the SAML Response. Please ensure that you are not encrypting your response or assertion to guarantee we're able to correctly identify the attributes.
Depending on the attribute mapping of your IdP, you may run into trouble if you aren't passing a valid email address or if you have different values set for the attribute names we expect to see. In Okta, we recommend configurations similar to below:
In order for us to properly identify the attributes, the resulting XML should look something like:
Example XML
Example XML
<?xml version="1.0" encoding="UTF-8"?>
<saml2:Assertion
ID="id000000000000000"
IssueInstant="2025-02-03T21:25:48.584Z"
Version="2.0"
xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
<saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">
http://www.okta.com/abc123
</saml2:Issuer>
<saml2:Subject>
<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">
email@email.email
</saml2:NameID>
<saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<saml2:SubjectConfirmationData
NotOnOrAfter="2025-02-03T21:30:48.587Z"
Recipient="https://auth0.openai.com/login/callback?connection=org-v3lUdEWWfRLfhrmuYmE0k2sb"/>
</saml2:SubjectConfirmation>
</saml2:Subject>
<saml2:Conditions
NotBefore="2025-02-03T21:20:48.587Z"
NotOnOrAfter="2025-02-03T21:30:48.587Z">
<saml2:AudienceRestriction>
<saml2:Audience>
urn:auth0:openai:org-v3lUdEWWfRLfhrmuYmE0k2sb
</saml2:Audience>
</saml2:AudienceRestriction>
</saml2:Conditions>
<saml2:AuthnStatement
AuthnInstant="2025-02-03T21:09:05.759Z"
SessionIndex="id1738617948583.928581830">
<saml2:AuthnContext>
<saml2:AuthnContextClassRef>
urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
</saml2:AuthnContextClassRef>
</saml2:AuthnContext>
</saml2:AuthnStatement>
<saml2:AttributeStatement>
<saml2:Attribute
Name="name"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml2:AttributeValue
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xs:string">
Hugh Mann
</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute
Name="family_name"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml2:AttributeValue
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xs:string">
Mann
</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute
Name="nickname"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml2:AttributeValue
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xs:string"/>
</saml2:Attribute>
<saml2:Attribute
Name="given_name"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml2:AttributeValue
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xs:string">
Hugh
</saml2:AttributeValue>
</saml2:Attribute>
</saml2:AttributeStatement>
</saml2:Assertion>
Alternatively, you can set your attributes like so, but be aware that this is not necessarily going to work on every IdP:
If you are seeing new users come through with their email addresses set to their display name, please review your attribute mapping and confirm that you are not encrypting your responses.
Alternatively, if new users are being asked to enter their name and birthday, this likely indicates we're not identifying a proper name value from your attribute response.
Email Changes
Occasionally, a user's email address may get updated in your IdP, e.g.
A legal name change following a marriage
Their company was acquired and they have a new domain
etc.
This will ultimately result in a new OpenAI user tied to the new email address. In some cases, the previous authentication profile may linger, preventing the new user from successful login. In this scenario, please reach out to Support for assistance.
Primary Email Addresses
In some cases, you may have users with multiple different email addresses. This is a common scenario in larger companies that have distributed mailing systems or in Edu customers with different schools, e.g.
In this situation, we recommend ensuring that your SAML response only includes a single email address in its attributes, as including multiple can cause confusion when we attempt to tie it to a new or existing user.
Additionally, if the users have a static email address (e.g. a UPN), we recommend utilizing this in your attribute mapping to ensure they will have a stable OpenAI user account that will not be impacted when their other email addresses may be changed.
SSO URL and X.509 Certificate
Once you have set these fields in your application, you should be able to obtain a corresponding SSO URL and X.509 Certificate. The SSO URL is used to ensure we're forwarding your users to the proper IdP for authentication, and the x509 Certificate will sign the response. Using Okta as an example, these values can be found here:
Provision IdP Application Access
If you haven't done so already, this is a good point to pause and validate your new API Platform SAML Application's access. For ease of management, we recommend granting users access to the application via a single "API Platform" group rather than adding them to the application individually.
Completing the Setup
Once you've obtained your SSO URL and X.509 Cert from your IdP, and ensured your users have been provisioned access through your IdP, return once more to the ChatGPT Identity page. Click the "Add SAML SSO" button (you will likely be asked to first re-authenticate), and enter the values from your IdP SAML application accordingly:
Once you hit "Create," you will have effectively enabled SSO for your API Platform organization. Users in your IdP group, with corresponding accounts or invitations on the Enterprise workspace, should now be able to login with SSO:
They can navigate to platform.openai.com, enter their email, and then authenticate after we forward them to their IdP
They can use the Tile URL discussed below
If you find that your users are unable to authenticate successfully, and you run into trouble reverting the changes, please reach out to Support for immediate assistance.
Remember that enabling SSO on the API Platform applies the domain verification across all users with that domain. This means that, even if the users do not belong to your Enterprise organization, they will still be required to be part of your IdP group in order to access their personal organizations.
SAML Metadata File
In some cases, your IdP may require the metadata certificate that we use to sign requests rather than just the ACS URL and Entity ID. While this is not natively surfaced in our application, you can obtain the certificate via the following URL:
This should provide you with the necessary XML file to successfully complete the setup within your IdP.
Note: This URL will not populate until a "successful" SSO connection is first created. This can lead to a chicken-and-egg scenario with your setup if you're relying on the XML file to successfully complete the connection.
To get around this, we recommend inserting temporary values for the SSO URL and x509 certificate that are sufficient in mimicking a "healthy" connection. Following this, you can download the XML file and update the values accordingly.
SSO Specific Features
After successfully enabling SSO, you will now have access to additional features.
Enforce SSO
The option to "Enforce SSO" makes it so that users can only authenticate into the Enterprise API Platform organization via SSO (i.e. they can no longer use a social login method, while the ability to use a password was already disabled when the domain was verified). Users will still be able to use Social authentication to log into other organizations that they belong to. If your Enterprise organization includes users with non-verified domains, they can still login without SSO.
In order to enforce SSO for your Enterprise Platform organization, please contact your Account Director or Support.
Tile URL
The IdP Tile URL can be used as a one-click authentication link for your approved users. Most IdP's support tying this URL to the configured application, so your users can authenticate directly into the API Platform from their dashboard view.
Note: Recall that we default to forwarding through the ChatGPT Tile URL [Link to the IdP-Initaited Login Doc section].
If you would like for the Platform Tile URL to correctly redirect to your Enterprise API Platform account instead, please reach out to Support for assistance in updating the default behavior.
Troubleshooting Logins
If after enabling SSO, you're encountering issues logging in, you can review our FAQ and Troubleshooting page for assistance to identify common errors. If you don't find a sufficient answer there, please don't hesitate to reach out to Support.