Single Sign On with Okta SAML

This feature is only available to Enterprise account

Last Updated: 2021-10-08

The setup process for Okta may have changed since this 
was created, and you may need to follow slightly different
instructions.

Set up Runn

1. Visit Account Settings and press Edit

2. Add an Alias, which is used for easily identifying your account.

3. Turn on SAML SSO

4. Press Save

5. Edit account settings again, and you will see the SAML Settings box.

6. Keep this page open and visit Okta in a new window.

Set up Okta

1. Goto Applications and select Create App Integration

2. To create a SAML integration select SAML 2.0 as the Sign-on Method

3. Select your app name as Runn and press next

4. For Single sign on URL copy the Runn SSO Callback URL from Runn's settings page. It will look something like https://app.runn.io/users/auth/saml/callback?account=r7nh3nd

5. For Audience URI (SP Entity ID) copy the Issuer field from Runn's settings page. It should be your account name with underscores.

6. For Name ID format select EmailAddress

7. Add two Attribute Statements

   1. Name: emailaddress Value: user.email

   2. Name: name Value: user.displayName

8. Click the Next button

9. Skip the feedback.

10. Change to the Sign On tab if you aren't there already. Then click "View Setup Instructions"

11. Copy the Identity Provider Single Sign-On URL and paste it into the Runn's setting page under SSO Target URL

12. Ignore the Identity Provider Issuer

13. Copy the X.509 Certificate and paste it into Runn's setting page under IDP Certificate

Finish setup Runn

1. In the Runn setting page

2. Update Email Claim to emailaddress

3. Update Name Claim to name

4. Press the Save on the SAML Settings box

Testing

1. Logout of the account

2. On the login page, click Sign in with SSO

3. Enter the Account Alias you selected earlier

4. After pressing Sign In you should be redirected to Okta. If this fails it means something went wrong in the setup process.

5. After logging in via Okta you should be redirected to Runn's planner. If you are redirected to an error page. See if there is an error message in the bottom right of the page that has more information.

Trouble Shooting

1. The SSO url being incorrect. Ensure the Sign on URL looks like this, including the ?account= part.
   https://app.runn.io/users/auth/saml/callback?account=r7nh3nd

2. The email and name claim being incorrect. Ensure they are the same attribute values between Okta and Runn

3. There is no user with that email address in the account

4. There is no invitation to the user in that account. Sign sign on only works for current account users and invited account users.