Guides

Features

Advanced

Configuring SSO for Okta

This guide will walk you through the steps to configure Single Sign-On (SSO) between Okta and ALTR. SSO enables ALTR users to log into ALTR though their Identity Provider (IdP) instead of ALTR's standard login.

ALTR-OKTA SSO Overview

ALTR supports the SAML 2.0 protocol for Single Sign-On (SSO), which enables authentication to the ALTR UI through compatible Identity Providers (IdPs) such as Okta. When SSO is enabled for an ALTR organization, all authentication and login activities are deferred to the IdP, enabling users to access ALTR without having to enter an ALTR-specific username, password, and two-factor authentication code.

ALTR supports both Identity Provider-initiated and Service Provider-initiated SSO. This means that, when SSO is enabled, you can sign in from both ALTR (from a "Sign in with SSO" button on ALTR's login page) and your IdP (from a "ALTR" tile, or similar).

ALTR identifies users through their ALTR username. Before configuring SSO, it is critical to ensure that ALTR users' usernames exactly match Okta. This match is case-sensitive. If usernames do not match, users will not be able to sign into ALTR through SSO. Usernames can be overridden in OKTA for your ALTR application (see step 27 below). Existing usernames in ALTR cannot be changed without contacting support@altr.com

When SSO is enabled for an organization, username and password authentication is disabled. All login activities must go through your identity provider. SSO can only be disabled by reaching out to support@altr.com.

To deactivate SSO for an ALTR organization, you must contact support@altr.com. This will include steps for resetting user passwords and two-factor authentication preferences once SSO is disabled.

Prerequisites to configure SSO

You must meet the following requirements to configure SSO for Okta:

  • Your organization must currently subscribe to our ALTR Enterprise Plus tier plan
  • You must have an ALTR login with Superadministrator privileges
  • You must be or have access to your Okta administrator

Guide to Configuring SSO for Okta

Follow the steps below to configure SSO between Okta and ALTR.

  1. In the Okta admin console, create a new Application by selecting "Create App Integration" on the "Applications" page
  2. Select SAML 2.0 as the sign-in method
  3. Click Next
  4. Under "General Settings", assign a name to your application such as "ALTR". If you have multiple ALTR accounts, make sure to set a descriptive name for each application.
  5. (Optional) Under "General Settings" upload an icon and/or enter a description for your ALTR application
  6. Click Next
  7. In a separate tab or browser, log into your ALTR account and navigate to the SSO page (/settings/preferences/sso)
  8. In ALTR, Copy the metadata URL from the SSO page an open it in a new tab. Alternatively, you can download and open the metadata file.
  9. In the metadata file, copy the "Location" field. Paste this field into the "Single Sign On URL" field in Okta.
  10. In Okta, check the box for "Use this for Recipient URL and Destination URL"
  11. In the metadata file, copy the "Entity ID" field. Paste this field into the "Audience URL (SP Entity ID)" field in OKTA.
  12. In Okta, ensure that the "Application username" field is set to "Okta Username".
  13. In Okta, Click Next
  14. In Okta, On the "Create SAML Integration Page" in Okta, select "I'm an Okta customer adding an internal app with Okta"
  15. In Okta, click "Finish"
  16. In ALTR, navigate to the "Administrators" page (/settings/administrators). Select your user and note your username.
  17. In Okta, navigate to the "Assignments" tab for your new application.
  18. In Okta, click "Assign", then "Assign to People". Search for your user and click "Assign".
  19. On the user's detail confirm, ensure that the "User Name" field in OKTA exactly matches - case sensitively - your username in OKTA from step 16. If it does not match, you can override your OKTA username for this application by editing the "User Name" field before hitting "Save and Go Back". Updating your username here will only change it for this application - it will not affect any of your other Okta Applications.
    NOTE: If your username does not exactly match between ALTR and Okta, you will not be able to sign into ALTR with SSO. If usernames do not match, see step 27 below.
  20. In Okta, navigate to the "Sign On" tab for your ALTR application.
  21. In Okta, copy the "Metadata URL".
  22. In ALTR, navigate back to the SSO page (/settings/preferences/sso)
  23. Paste the "Metadata URL" from Okta into the "SSO Provider's Metadata URL" field in ALTR
  24. In ALTR Select "Okta" from the list of IdPs
  25. Click "Enable SSO". It may take several minutes for ALTR to configure SSO. Do not log out of ALTR or close your browser window, even after ALTR successfully activates SSO.
  26. On a separate browser or computer, attempt to sign into your ALTR organization. You should only be presented with a "Sign in with SSO" option. If you can successfully sign in through Okta, you can begin assigning your ALTR application in Okta to all of your ALTR administrators.
    Note: If you cannot successfully sign into-ALTR, make sure that your ALTR username exactly matches your username in Okta. If usernames do not match, see step 27 below.
  27. (Optional) Override your Okta username for the ALTR application to exactly match ALTR. ALTR performs a case-sensitive match between ALTR and Okta usernames. If there is no match, you will not be able to log into ALTR through SSO. If a username does not match between ALTR and Okta, you can override it in Okta from the "Assignments" tab for your ALTR application. This can be done when assigning new users (by editing the "User Name" field before clicking "Save and Go Back" and existing users by clicking the edit button (pencil icon) and updating the "User Name" field. Usernames cannot be changed in ALTR without contacting support@altr.com.
Figure 1. Create App Integration button on the Applications page
Figure 2. Settings page in ALTR to configure SSO
Figure 3a. Example of how the Metadata file will appear (if viewed in a browser) that shows the values to copy
Figure 3b. Fields to paste values in
Figure 4. Finish button
Figure 5. Sign On button
Figure 6. Copy button on the Settings page

Frequently Asked Questions

Question: Now that I've enabled SSO why can't my users log in?

Answer: We will do matching on the username field and there's a requirement that users have an identity with a matching username on both sides (ALTR and their Identity Provider).

First section of content