For more details on available features in other plans, click here.
Terms to Know
- Identity Provider - The tool that your team uses to provide Single Sign-On functionality. For this article, we'll be exploring a setup process for Okta.
- Metadata - Typically an XML file which tells the tools involved with handling your login process how to complete and validate the requests.
- Enforced SAML/SSO - A setting which specifies SAML/SSO as the primary login method for all users on your team and default login method for all new users.
As an Account Admin on a Professional or Enterprise plan, you have the option to setup single sign-on authentication method for your team. In the following article, we will explore how you can quickly and smoothly setup Okta as your team's SAML/SSO authentication method.
Setting Up Single Sign-On with Okta
Step 1 - Getting Started in Okta
- From your Okta homepage, click into the Applications menu.
- In the page that appears, select the green Add Application button in the top-left of your Applications list.
- In the Add Application repository, type "Roadmunk" into the search bar at the top of the page.
- Select the first option, which should be labelled as Roadmunk and should be marked with both SAML and SWA on the right-hand reference list.
- In the Roadmunk application page, select the green Add button at the top of the left-hand details column to navigate into the setup workflow.
Step 2 - Setup the Roadmunk Application Settings in Okta
- When the setup workflow begins, you'll land on a General Settings page.
- In the General Settings page, check the option for Do not display application icon in the Okta Mobile App. As Roadmunk doesn't offer a mobile option, this prevents any confusion for users.
- Directly below that, uncheck the option for Automatically login when user lands on login page. Since Roadmunk uses a two-step login process, this option may not always work as expected.
- Once 2 & 3 have been completed, click Next to continue the setup process.
Step 3 - Defining Sign-On Options in Okta
- After clicking Next, you should land on the Sign-On Options page.
- Under Sign-On Methods we're going to select SAML 2.0 to reveal the SAML options.
- In the yellow notice below the setup panel, you should see a link to your Identity Provider Metadata file. Click into this link to open your metadata file in a new tab.
- Once loaded, copy the page URL for your Identity Provider (IP) Metadata file.
- Important Note: Please leave this page on Okta open in another tab or window before moving on to Step 4 below.
Step 4 - Getting Setup in Roadmunk
- In Roadmunk, click on your avatar in the bottom left corner and navigate to Account Settings.
- In the Account Settings menu, click into the Company tab.
- Locate the SAML/Single Sign-On (SSO) option at the bottom of the tab and click to toggle it on.
- In the menu options that appear, select Enter your IDP XML URL in Step 1 and paste the IP Metadata file URL that we copied in Step 3. Once pasted, select the Save URL option.
- Saving the URL should generate a Service Provider (SP) Metadata file under Step 2. Select the Copy URL button to copy this file's location to the clipboard.
Step 5 - Finalizing the Setup in Okta
- Navigating back into Okta, scroll down to the Advanced Sign-On Settings section of the page.
- In the Metadata URL field, we're going to past the SP Metadata file that we copied in Step 4.
- In the Credentials Details section below that, select the Email option in the Application user Format drop-down menu.
- Clicking on the green Done button a the bottom will save these settings.
- Once saved, you will be taken to the application's assignments page. Users and Groups in your organization can be assigned to this application by clicking the green Assign button in the top-right corner of the Assignments list.
Step 6 - Finalizing the Roadmunk Setup
- Navigating back to Roadmunk, head into the Account Settings menu once more.
- Click into the Security tab to access your active login methods.
- Clicking into the blue + Login Method button in the top-right corner of your Authentication Methods list, we can now see and select the new SSO option that appears at the bottom of the menu.
- Clicking into this will open an Okta login screen where you can attach your Okta login to Roadmunk. If you're already logged into Okta when attempting this attachment, it should complete automatically.
- If the Authentication Methods list doesn't refresh automatically, you can close out of the Account Settings and reopen them from your avatar in the bottom-left corner of your app.
Enabling Multi-Factor Authentication with Okta Single Sign-On
Okta supports a number of additional authentication layers which can help to provide an extra level of security for you and your team. A great guide on setting up app-level multi-factor authentication in Okta can be found here on Okta's Help Center and easily applied to your team's Roadmunk app.