ADMIN PRIVILEGES REQUIRED

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

Overview

These instructions describe how to integrate your Stack Internal Enterprise 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 Stack Internal Enterprise site and the Okta IdP in a back-and-forth process. We recommend having a browser tab open to each site.

THIS ARTICLE APPLIES TO STACK INTERNAL ENTERPRISE ONLY.
Other Stack Internal users should read this article instead. Find your plan.

NOTE: To configure SSO with Okta, you'll need administrator access to both Okta and Stack Internal Enterprise.

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 Stack Internal Enterprise SAML URL (https://[your_site].stackenterprise.co/auth/saml2/post).
Audience URI (SP Entity ID) Enter any unique value. We suggest using your Stack Internal Enterprise 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 Stack Internal Enterprise creating a new, duplicated account for that user).

Set attribute statements

Attributes are user information values passed from Okta to Stack Internal Enterprise 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 Stack Internal Enterprise) 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 Stack Internal Enterprise. If you have a custom Okta field with the full user name, set Value to that field. You can also concatenate fields using the ${user.firstName} ${user.lastName} formula.

You can also define optional user job title and department attributes. Populating and sending these attributes on login allows you to use Stack Internal Enterprise'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.

Check This is an internal app that we have created, then click Finish.

Navigate to the "Sign On" tab. Under the "Metadata details" heading, click More details. You're now ready to configure Stack Internal Enterprise.

Configure Stack Internal Enterprise SAML settings

Open a new tab in your browser and log in to Stack Internal Enterprise as an administrator. Click Admin settings in the left-hand menu, 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 Stack Internal Enterprise 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 Stack Internal Enterprise 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 Copy the Audience Restriction value from Okta (from the "General" tab) and paste it here.
Use Subject/NameID as user identifier Enable this checkbox.
Fill in the Name value from the Okta "Attribute Statements" tab for each of the following:
- Display name
- Job Title
- Department
- External ID
Identity provider certificates Click View SAML setup instructions in the bottom right corner of the "Sign On" tab. Copy the entire value shown in the X.509 Certificate field and paste it here.

Validate your certificate by clicking Validate Certificate. If your certificate passes verification, you'll see a green box with a success message.

Save and test Stack Internal Enterprise SAML settings

To complete the SSO setup, click Save Settings.

When saving settings, Stack Internal Enterprise will first perform an authentication test. If the test succeeds, Stack Internal Enterprise will apply your new authentication settings. Logged-in users stay logged in, as all active user sessions remain valid.

If the test fails, Stack Internal Enterprise 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 Stack Internal Enterprise 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.