Tags | SAML | Authentication | SSO | Okta |
ADMIN PRIVILEGES REQUIRED
This documentation is for Stack Overflow for Teams Enterprise. Free, Basic, and Business users can access their documentation here. Find your plan.
Overview
These instructions describe how to integrate your Stack Overflow for Teams Enterprise (SOE) site with Okta as your Identity Provider (IdP) for authentication. Once configured, your users will be able to use Okta and the Security Assertion Markup Language (SAML) for Single Sign-on (SSO) authentication into your site. You can learn more about SAML in our SAML Authentication Overview document.
When setting up SAML authentication, you'll configure your SOE site and the Okta IdP in a back-and-forth process. We recommend having a browser tab open to each site.
NOTE: To configure SSO with Okta, you'll need administrator access to both Okta and SOE.
There are two ways to configure Okta for SSO authentication for your SOE site. We recommend using the Okta app integration method as described below, unless:
You can't (or choose not to) access the Okta App Integration Catalog, or
You need to add the user's job title and/or department SAML attributes
If either of these applies, skip down to the "ALTERNATE MANUAL CONFIGURATION METHOD" section.
OKTA APP INTEGRATION METHOD
Install the SOE SAML application for Okta
In Okta, click Applications, then Browse App Catalog.
Search for "Stack Overflow Enterprise".
On the "General Settings" tab, enter an Application label (we suggest "Stack Overflow Enterprise"). Enter your SOE site's full URL in the Okta subdomain field. Click Done.
Configure SAML settings in SOE
Click to select the "Sign On" tab. Under the "Metadata details" heading, click More details. Keep this tab open for easy access to the metadata values.
In a new browser tab, log in to your SOE instance as an administrator. In the left-hand menu, click Admin settings, then Authentication. Click Use SAML 2.0 (if not already enabled).
On Okta's "Sign On" tab, use the Copy links to add the following values to your SOE settings. If you see a setting that's not listed here, leave it unchanged.
Assertion consumer service URL Enter the SAML 2.0 post URL of your SOE site (https://[your_site].stackenterprise.co/auth/saml2/post).
Single sign-on service URL Copy the Sign On URL value from Okta and paste it here.
Issuer Copy the Issuer value from Okta and paste it here.
Audience restriction Enter the SAML 2.0 post URL of your SOE site (same as above: https://[your_site].stackenterprise.co/auth/saml2/post).
Use Subject/NameID as the user identifier Enable this checkbox.
Fill in the Name value from the Okta "Attribute Statements" tab for each of the following:
Display name assertion displayName
Email address assertion email
Identity provider certificates Click the Okta Signing Certificate Copy link, and paste the results here.
Validate your certificate by clicking Validate Certificate. If your certificate passes verification, you'll see a green box with a success message.
Assign users to the Okta application
On the Okta "Assignments" tab, assign your users (and/or groups) with the Assign button.
NOTE: You can't test your SSO configuration until you've assigned users.
This completes the main Okta application configuration. Jump down to the "Save and test SOE SAML settings" section below to save and verify your settings.
ALTERNATE MANUAL CONFIGURATION METHOD
NOTE: The following steps allow for manual configuration of Okta SSO. Use this process if you can't (or choose not to) access the Okta App Integration Catalog, or need to add the user job title and department data fields.
Create a new Okta SAML application
In Okta, click Applications, then Create App Integration.
Choose SAML 2.0 as Sign-on method.
On the "General Settings" tab, enter an App name. If desired, upload an App logo.
Configure Okta SAML settings
On the "Configure SAML" tab, configure the following fields:
Single sign-on URL Enter your SOE SAML URL (https://[your_site].stackenterprise.co/auth/saml2/post).
Audience URI (SP Entity ID) Enter any unique value. We suggest using your SOE SAML URL (same as above: https://[your_site].stackenterprise.co/auth/saml2/post).
Default Relay State Leave blank.
Name ID format Select Unspecified.
Application username This field identifies the user record, so set this to a user attribute that is unique and will never change (for example: Okta username).
NOTE: It's important to select an Application username source field that is both unique and unchanging. A user's email address, for example, is unique but not unchanging (an updated email address would result in SOE creating a new, duplicated account for that user).
Set attribute statements
Attributes are user information values passed from Okta to SOE as part of the login process. You'll need to define at least two SAML attributes: user email and name. This involves giving each attribute a name (which you'll later enter into SOE) and choosing which Okta values to attach to each attribute.
Define the SAML attributes Name and Value as follows:
email The user's email address. Set Value to user.email.
displayName The user's name as it should appear in SOE. If you have a custom Okta field with the full user name, set Value to that field. You can also concatenate fields with the "+" operator (for example: user.firstName + " " + user.lastName).
You can also define optional user job title and department attributes. Populating and sending these attributes on login allows you to use SOE's Connectivity feature.
jobTitle (optional) The user's job title. Set Value to user.jobtitle.
department (optional) The user's department. Set Value to user.department.
After configuring attributes, click Next.
BOTH METHODS: Save and test SOE SAML settings
To complete the SSO setup, click Save Settings on the SOE authentication settings page.
When saving settings, SOE will first perform an authentication test. If the test succeeds, SOE will apply your new authentication settings. Logged-in users stay logged in, as all active user sessions remain valid.
If the test fails, SOE will not apply the authentication settings. You'll stay on the SAML settings page so you can troubleshoot and correct problems. This test acts as a safety net to keep invalid authentication settings from locking users (yourself included) out of your site.
You can also click Test currently saved SAML configuration to display technical details about your SAML authentication. You'll find these helpful for understanding what information your IdP and SOE exchange.
Properly configuring SAML authentication can be tricky. For more information on troubleshooting, see the SAML Authentication Troubleshooting article. You can also reach out to Stack Overflow support for help.