Tags | Authentication | SSO | SAML |

This documentation is for Stack Overflow for Teams Enterprise. Free, Basic, and Business users can access their documentation here. Find your plan.

Security Assertion Markup Language (SAML) allows sites to securely share user information for authentication, profile updates and more. Stack Overflow Enterprise (SOE) uses SAML 2.0 for authentication, communicating with trusted identity providers like Okta, Entra ID, OneLogin, and others.

Properly configuring SAML is a detailed process. This guide will give you an overview of how SAML works, as well as specifics on setting up SOE for SAML authentication. You'll also want to follow the SOE technical setup guide specific to your identity provider.

THIS ARTICLE APPLIES TO STACK OVERFLOW FOR TEAMS ENTERPRISE ONLY.
Other Stack Overflow for Teams users should read this article instead. Find your plan.

When a user first accesses Stack Overflow, the site collects their login credentials and sends them to an external identity provider. If successful, user information is sent back to Stack Overflow to authorize their login. If the user is new, Stack Overflow creates a new account before logging them in. This two-way flow of information uses the SAML protocol.

Depending on your identity provider, you may be able to implement optional security features. Outgoing SAML requests can be signed with a certificate to verify the identity of the sender. SAML messages can also be encrypted with a certificate to protect the user information. Even without these additional features, however, SAML authentication is a highly secure protocol that uses only encrypted connections.

NOTE: Stack Overflow Enterprise and your identity provider must use encrypted connections (https://) for all SAML communications. Unencrypted connections (http://) will fail.

Here are some of the terms you'll need to know when setting up SAML for your SOE site.

The SAML setup process includes the following steps:

When setting up SAML authentication, you'll configure your SOE site and your IdP in a back-and-forth process. We recommend having a browser tab open to each site.

IdPs require users to register each service provider (site). In this case, you'll give the IdP information about your SOE site. Though each IdP is different, here are some common settings you'll need to configure.

Issuer
A unique identifier that tells the IdP which service provider is making the authentication request (your SOE site). Some IdPs automatically create an issuer ID for you.

URL Whitelist
When sending an authentication request to the IdP, SOE includes a redirect (destination) URL for the user to go to after successful authentication. To prevent malicious redirects, most IdPs allow you to specify a whitelist (approved list) of URLs. If an authentication request comes in with a redirect URL that's not on the whitelist, the IdP will not redirect the user there and authentication will fail.

Signing certificate public key
If you've configured SOE to sign outgoing authentication requests (with a private key), you must provide the corresponding public key to the IdP. The IdP will whitelist, validate, and use the public key to verify the request. See the SAML data examples section for an example.

Encryption certificate public key
If you want the IdP to encrypt successful authentication assertions it sends back to SOE, provide the encryption certificate (public key) it should use. See the SAML data examples section for an example.

NOTE: Signed authentication requests and encrypted SAML responses are optional and rarely used by SOE. See the Advanced setup section for more info.

SOE will interface with many identity providers, each having a slightly different set of parameters and options. You'll need to set SAML options below based on the IdP you use, in consultation with the SOE technical setup guide specific to that IdP.

Access the SAML configuration screen by clicking Admin settings on your SOE site, then Authentication (under the "Access management" heading). If you see other authentication settings (not SAML 2.0), click Configure SAML 2.0. You can also access this screen directly with the URL [your site]/authentication.

Assertion consumer service URL
The URL that the IdP will redirect users back to after successful authentication. Set this value to this specific URL on your SOE site: https://[your site]/auth/saml2/post. The URL must use a secure connection (https://).

Single sign-on service URL
The identity provider URL that SOE will send authorization requests to. You'll get this URL from your IdP. The URL must use a secure connection (https://).

Single sign-on service protocol binding
This is the method we use when we send the authentication request to the IdP. Choose the option that ends in HTTP-Redirect unless instructed differently by Stack Overflow product support.

HTTP-Redirect binding: include SAML encoding parameter in query string
If your IdP requires authentication requests to include a SAMLEncoding parameter, enable this option.

Enforce 80 byte maximum RelayState length?
SOE uses the RelayState value as a redirect URL, telling the IdP where to return the user to after successful authentication. If this redirect URL is too long, the IdP may ignore it and instead return the user to your SOE home page. Consult the technical setup guide for your specific IdP for guidance on this setting.

Issuer
This value identifies your SOE site to the IdP. Some IdPs will provide this to you, while others let you choose your own. Consult the technical setup guide for your specific IdP for guidance on this setting.

Audience restriction
This value will be the same as Issuer above, unless instructed otherwise by the technical setup guide for your specific IdP.

Use Subject/NameID as user identifier
Every SOE user has a unique identifier. In the SAML response, this is usually NameID. Leave this box checked, unless instructed otherwise by the technical setup guide for your specific IdP.

User identifier assertion attribute
If not using the default identifier (Use Subject/NameID as user identifier is NOT checked), this field allows you to specify the identifier in the SAML response. Consult the technical setup guide for your specific IdP for guidance on this setting.

If the guide doesn't specify an identifier, you must choose a unique, unchanging identifier. Common choices are Windows SID, Active Directory ObjectGUID, LDAP uid, or some form of unique employee ID. If SOE finds an existing user with the provided ID, it will log them in. If it doesn't find an existing user, SOE will create a new user account with that ID.

NOTE: You must select a user ID that is both unique and unchanging. User email address, for example, is unique but not unchanging. If you use email address as the unique ID, a new email address entered at the IdP would result in SOE creating a new account for that user.

Display name assertion
The data element in the SAML assertion that holds the user's full name as displayed on the site. You can set SOE to automatically update this field with SAML data on login. See the Update user profile on SAML login) section for more info.

Email address assertion
The data element in the SAML assertion that holds the user's email address. You can set SOE to automatically update this field with SAML data on login. See the Update user profile on SAML login) section for more info.

Job Title assertion
The optional data element in the SAML assertion that holds the user's job title. When configured and included in the SAML response, SOE automatically updates this user data on login.

Department assertion
The optional data element in the SAML assertion that holds the user's department. When configured and included in the SAML response, SOE automatically updates this user data on login.

External ID assertion
The optional data element in the SAML assertion that holds the user's external identifier. This data element has no purpose in SOE, and is provided as a convenience for SOE clients to identify their users (such as with a company employee ID).

You can set SOE to display a user's external ID in their profile with the UserProfile.ShowExternalIdOnProfile site setting.

Enable importing profile image on user creation
Option to tell SOE to download and store a profile picture when it creates a new user profile.

Profile image URL assertion
If Enable importing profile image on user creation is checked above, this tells SOE the name of the data element that holds the user's profile image URL. SOE will download and store the profile picture from this URL when creating a new user account. It will not overwrite the profile picture of an existing user.

Profile image Base64 assertion
If Enable importing profile image on user creation is checked above, this tells SOE the name of the data element that holds the user's Base64-encoded profile image. This is an alternative to the image link above, and will take precedence if the SAML response contains both values.

NOTE: Profile pictures should be square and at least 164x164 pixels, similar to Gravatar image size guidelines.

Disable SP-initiated SAML 2.0 SSO
With a normal SAML authentication flow, SOE collects login information and sends it to the IdP as an authentication request. If this option is checked, SOE will instead prompt the user to log in at their IdP and will not send an authentication request.

NOTE: This option may be useful if your IdP requires a signed authentication request but SOE is unable to generate one (due to a certificate problem, for example).

IDP initiated sign on URL Provides users a link to their IdP if Disable SP-initiated SAML 2.0 SSO is enabled. If you leave this field blank, users will be told to log in at their IdP but SOE will provide no link.

Automatically login If Disable SP-initiated SAML 2.0 SSO is enabled, this redirects the user automatically to their IdP for login (SOE will generate no prompt or link).

Automatic login message If Automatically login is enabled, this message displays as the user is being redirected to their IdP for login.

Update certificates from federation metadata URL
For improved security, some IdPs require certificates (public keys) to be refreshed every hour. These IdPs will supply a URL to retrieve new certificates, which you can enter here. SOE will automatically retrieve and install a new certificate every hour.

NOTE: If Update certificates from federation metadata URL is set, you can manually trigger a certificate update at [your site]/enterprise/support/saml-certupdate (admin access required).

NOTE: A federation metadata URL is recommended for automated certificate management, making identity provider certificates (below) unnecessary. If you enter a federation metadata URL, the "Identity provider certificates" section of the page will disappear to prevent accidental overwrites that could impact user access to your site. To restore these fields and manually update certificates instead, remove the federation metadata URL.

Identity provider certificates
SOE requires that your IdP sign every SAML response it sends. The IdP uses its private key to sign the SAML response, then SOE uses the corresponding public key to verify the sender.

Paste the public key certificate provided by your IdP here, including the "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----" boundaries. You can store multiple certificates with Add another Certificate, as well as remove ones that have expired or been compromised with Remove Certificate.

Click Validate Certificate to verify that a certificate is properly formatted. If the certificate is valid, SOE will show a box with information about the certificate. Pay careful attention to the valid date range. If the certificate's valid end date has passed, it will no longer work. Click Remove Certificate to remove and replace it.

NOTE: If a federation metadata URL has been entered (above), the "Identity provider certificates" section of the page will be hidden to prevent accidental overwrites between automatic and manual certificate updates. To restore these fields and manually update certificates instead, remove the federation metadata URL value.

*NOTE: The certificate used to verify the identity of the IdP response is the only certificate required by SOE. Other uses of certificates and keys fall outside typical SAML usage. See the Advanced setup section for more info.

Managing certificates is a crucial part of the SAML setup process. See the Certificates and keys section for more info.*

Sign outgoing AuthnRequests
Enable this option if your IdP requires SOE to sign each authentication request with a private key. Signed authentication requests are optional and rarely used by SOE. See the Advanced setup section for more info.

Signing certificate for outgoing AuthnRequests
If Sign outgoing AuthnRequests is enabled, use this pull-down menu to choose the certificate SOE should use to sign outgoing authentication requests.

Digest method when signing outgoing requests
The signing digest method you choose affects security, and we recommend using SHA-256 or higher. SOE supports (but doesn't recommend) the less-secure SHA-1 digest method for compatibility with certain IdPs.

How to attach the public key to the signed request
Authentication requests can include the public key for convenience, but not all IdPs support this option. Consult the SAML technical setup guide specific to your IdP for guidance on this setting.

Show additional detail if login fails
Display detailed error information to the user if SAML authentication fails.

Force reauthentication
Ask the IdP to always force a new user login (not use a previous authentication session). Not all IdPs honor this.

Verify the SubjectConfirmation element on a SAML response
Some identity providers don't send a proper SubjectConfirmation. Check this box to verify the parameter.

Enable SAML login troubleshooting page
Display a detailed SAML login troubleshooting page at [your site]/enterprise/support/saml-login. This option has security implications, so enable the page only as long as needed. Learn more in the Troubleshooting section.

Enable SAML Response logging for troubleshooting
Log all SAML responses to the database for troubleshooting. Enable this option if directed to by Stack Overflow product support.

Ensure KeyInfo element on EncryptedKey
Set this if encrypted SAML responses from your IdP fail to decrypt with "Unable to retrieve the decryption key" error. See the SAML data examples section for an example.

Add UTF-8 byte order mark to the EntityDescriptor.xml
If your IdP is rejecting SOE's FederationMetadata.xml file, try enabling this option.

The bottom of the settings page has additional links.

If Enable SAML login troubleshooting page is enabled, the Test currently saved SAML configuration button will take you to the login troubleshooting page ([your site]/enterprise/support/saml-login). Learn more in the Troubleshooting section.

Set up additional access rules
Takes you to the Configure Access Rules for SAML2 page at [your site]/enterprise/support/access-rules. Learn more in the SAML access rules document.

Download SAML 2.0 EntityDescriptor that can be imported into Identity Provider (IdP)
This link downloads a file that certain IdPs will accept for auto-configuration. Learn more in the Identity provider auto-configuration section.

Parse SAML 2.0 EntityDescriptor from Identity Provider (IdP) If Update certificates from federation metadata URL is set and SOE is failing to update certificates hourly, use this link to troubleshoot the response from your IdP. Learn more in the Troubleshooting section.

The SAML standard supports the use of certificates for both signing and data encryption. Properly setting up certificates (and the keys they contain) is one of the more challenging aspects of SAML configuration. Remember: you can always reach out to Stack Overflow product support if you need help.

Because the IdP must sign every response it sends, the SAML response signing certificate is the only required certificate. SOE will check the signature against the public keys uploaded to the server. If the response is not signed, or if SOE can't find a matching public key, authentication will fail and SOE will display an error message to the user.

As part of the setup process, your IdP will create a signing certificate with a public key. It's this public key that you'll upload into your SOE SAML settings page.

NOTE: Even if your IdP provides a URL to automatically update certificates, you should download and save the IdP's public key to SOE for initial setup and testing.

If you've enabled authentication request signing, SOE will use a private key to sign each outgoing authentication request. The receiving IdP uses the corresponding public key to verify the sender identity. Learn more about encrypted authentication requests in the Advanced setup section.

Some IdPs encrypt the SAML assertion (user data portion) of the SAML response. The IdP uses the certificate's public key to encrypt the data, and SOE uses the private key to decrypt it. Learn more about encrypted SAML assertions in the Advanced setup section.

When you've completed your SAML setup or update, click Save settings. This launches a "Test new authentication settings" pop-up. Click Submit to test your authentication settings with a full login flow. If the test fails, you'll remain on the SAML settings page so you can double-check and correct the settings. If the test succeeds, SOE applies your new authentication settings. Logged-in users stay logged in, as all active user sessions remain valid.

This test acts as a safety net to keep invalid authentication settings from locking users out of your site. Until your settings are correct and pass the authentication test, SOE will not apply your changes.

If you need more technical details for your SAML auth flow, use the Test currently saved SAML configuration button to view the SAML response, authentication log, and assertions (requires Enable SAML login troubleshooting page to be on). Learn more about this feature in the Troubleshooting section of this document.

The following settings and links are not commonly used, but may be relevant to your specific IdP and SAML configuration.

If you've enabled optional authentication request signing, SOE will need access to the private signing key. The location of the signing key depends on your SOE deployment type.

NOTE: If your IdP requires signed authentication requests, it will need your SOE public key to verify those requests. Please create a new support ticket to request your public key.

If you've enable optional SAML assertion encryption at your IdP, SOE will need access to your private decryption key. The location of the private decryption key depends on your SOE deployment type.

NOTE: For load-balanced deployments, the certificate needs to exist in every server running SOE.

NOTE: SOE uses the Signing certificate for outgoing AuthnRequests for authentication request signing and decrypting encrypted SAML responses. If your IdP is encrypting SAML responses, you'll need to select a certificate for this setting even if you're not signing outgoing authentication requests.

On successful login, the IdP sends user data back in its SAML response. You can set SOE to automatically update certain user profile fields with this data. If a user changes email address at the IdP, for example, SOE will update the email address in the user profile.

NOTE: To keep IdP and SOE data in-sync, you must disable the user's ability to change profile fields that the IdP will update. You should then instruct users to change those fields at the IdP instead of in SOE.

You can enable IdP update of the Display Name and Verified Email profile fields on successful login. The corresponding site settings are:

As a site admin, follow this process for each profile field you want the IdP to update:

NOTE: Unlike the Display Name and Verified Email profile fields, SOE will never overwrite the Profile Picture of an existing user on subsequent logins. SOE will save a profile picture from the IdP only on initial account creation.

If you allow the IdP to update user profile fields, you need to disallow user changes to those same fields. You'll change the UserProfile.EditableUserProfileFields setting to the appropriate value from the following options.

Follow these steps to update the UserProfile.EditableUserProfileFields field:

Some IdPs will let you upload a data file to automatically configure certain SAML settings. The SAML 2.0 Settings page allows you to create and download this data file with information about your SOE site. Follow this process to auto-configure your IdP:

Because SAML authentication setup can be tricky, SOE provides several means to troubleshoot authentication problems.

You can enable database logging of both successful and unsuccessful SAML authentication responses for quicker troubleshooting. To enable this feature, check Enable SAML Response logging for troubleshooting and save the settings.

Site admins can view the stored logs on the developer log page.

This URL (as well as the Test currently saved SAML configuration button) initiates an authentication request to your SAML identity provider and displays the response.

The SAML test page consists of the following four sections.

Base64-encoded SAML response
The raw (Base64-encoded) data, exactly as received from the IdP. If you're requesting help with your SAML setup, include this raw data with the help ticket as an attachment or pasted text.

Successfully parsed SAML Response to XML
The data as parsed in XML format.

Authentication log
A log of the authentication process, including the processing access rules. You'll find a wealth of useful troubleshooting info in this section.

All Attributes in Assertion
The final product of a successful SAML login: the attributes (user data) returned from the IdP.

NOTE: The SAML test page is meant for initial authentication setup only and should be disabled as soon as your SAML authentication is working. To disable the SAML test page, uncheck the Enable SAML login troubleshooting page box and click Save settings.

If the SAML test page indicates a certificate error, go to the admin errors page to see if a CryptographicException or InvalidOperationException error occurred.

Here are the error messages and potential causes:

The IIS Application Pool identity does not have permission to the private key
See above on how to give permission to the IIS Application Pool to the Private Key
​ Solution: grant the IIS Application Pool identity Read permission on the private key. If the IIS Application Pool uses ApplicationPoolIdentity (the default), you can add it in the form IIS AppPool\NameOfTheAppPool.

The certificate does not have a private key
SOE won't show certificates without a private key in the drop-down list, but it's possible to replace an existing certificate with one that lacks a private key. If a certificate doesn't have a private key, SOE can't use it for signing or decryption.
​ Solution: add a certificate with both public and private keys.

During decryption of a SAML assertion, the certificate does not match
This error can occur on a hosted deployment if the IdP uses one certificate for encryption and a different one for signing.
​ Solution: make sure your IdP is configured to use the same certificate for signing and encryption.

This error can also occur if the Ensure KeyInfo Element on EncryptedKey option is checked and the IdP did not send this element. In this case, we try to use the signing certificate to decrypt in both on-premises and hosted deployments.
​ Solution: uncheck Ensure KeyInfo Element on EncryptedKey

The certificate was not in the right format
SOE public and private keys must be in the RSA format. If you use a self-signed certificate created through IIS Manager or the PowerShell New-SelfSignedCertificate cmdlet, that certificate will have keys in the CNG format.
​ Solution: use a certificate created by a certificate authority, with keys in the RSA format.

Certificate required for decryption does not exist in the certificate store
The SAML response from the IdP was encrypted, but SOE couldn't find a certificate to decrypt it.
​ Solution (on-premises): make sure the certificate exists in the Windows Certificate Store (Local Computer\Personal\Certificates).
​ Solution (hosted): make sure the IdP uses the same certificate that you've uploaded as the signing certificate.

Some IdPs update certificates every hour, providing a link for SOE to download the refreshed certificates automatically. If this process fails, use the Parse SAML 2.0 EntityDescriptor from Identity Provider (IdP) link to troubleshoot the problem.

Enter the Update certificates from federation metadata URL value to test the full download process. If the URL is working but the resulting file is not, paste the contents of the downloaded FederationMetadata.xml file into the EntityDescriptor XML box.

SOE will parse the XML file and display the relevant data, including the authentication request (SSO) URL and signing certificate (public key). You can verify these values against your current SAML settings.

A properly formed FederationMetadata.xml file should look like this:

The section below includes examples of SAML data, both outbound authentication requests and inbound SAML responses.

This example adds the "Signature" XML Element to the AuthnRequest document

No <KeyInfo> under <EncryptedKey>

Contains a <KeyInfo> under <EncryptedKey> telling us which certificate to use for decryption

If you need further support or have questions, contact your site administrator.