General Setup

Log into Runn as an account administrator.
Ensure that you are in the "Live" account.
Go to Settings -> Account Settings and press Edit
Turn on SAML SSO
Keep SSO Login Only disabled until after you have tested your SAML SSO set-up and applied additional settings
Press Save
Edit Account Settings again.
You'll see a new Alias field. Set it to a value that identifies your organisation (e.g. my-company). It is used for Service Provider initiated logins, as well as optional subdomain-based logins.
Now scroll down the page and you will see the SAML Settings box.

SAML Setup

Settings vary based on your Identity Provider, see provider-specific setup guides for Okta, Azure AD, etc.

Add the Runn SSO Callback URL to your application.
Optional: Adjust the Issue / Audience / SP Entity value. This needs to match the value in your Identity Provider.
Fill in the SSO Target URL (also called Login URL, Target, or SSO URL)
Email claim and Name claim default to the recommended values (these may be different for your Identity Provider)
Add in the IDP Certificate (also called Signing Certificate, or Security Certificate)
This should be base64 encoded and start with
-----BEGIN CERTIFICATE-----
Press Save on the SAML Settings box.

Additional Settings

Session Timeout

This setting allows you to customise how long a session lasts. As Runn uses web sockets, while the browser window is open and active, sessions are continuously refreshed.

You can choose 15 minutes to meet the highest level of OSWAP, or a more moderate experience so users aren't logged out when taking short breaks or going on lunch. Our default is 2 weeks, which ensures timesheet users who only log in once a week do not need to keep logging in.

SSO Login Only

Ensure you have tested your SAML SSO before turning this on, or you will no longer have access to your account.

This will invalidate logging-in with email addresses and passwords, as well as creating new accounts with email and password.

Testing

For your testing, ensure you're using the email address of a user who has already an account with Runn or has been invited to join Runn.
Sign out of Runn.
Go to app.runn.io and click the Sign in with SSO link on the bottom right of the Runn sign-up page.
Write the Alias that you entered in the SSO setup OR your Runn Account ID.
You will be re-directed to your SAML login page.
If successful, you will be redirected back to Runn either logged-in, or you will be prompted to set-up a new Runn account if you were using the email address of a user that has been invited to Runn.
If you receive an error, ensure the SAML settings are correct and the user logging-in has an account with Runn or an invite to join your Runn account.
If you still have issues, contact Runn via the chat button in the bottom right corner of your Runn account or email help@runn.io for help resolving the issue.

Troubleshooting

I get an error saying "No email found in email claim"

SAML uses claims or attributes to communicate information. We must know the email of the person with comes from an email claim. We default to Microsoft Azure but other services may use different names for this claim/attribute such as "email" or "email_address". Search your SSO providers help for "user claims" or "user attributes" and see what it suggests for the email claim. At the same time you can also update the name claim.

Some of my users can't log in

Identity Provider membership: Ensure that those users are associated with the Identity Provider used for this specific SAML integration. It might be limited to a subset of users on your end?

Invitations: In order to log into Runn, you need to create an invitation for them within Runn (with an email address matching in your Identity Provider). They should be able to login after accepting this invitation email.

Frequently Asked Questions

When you set up your Alias field, you will be able to log in automatically by going to https://app.runn.io/sso/<alias>. We can also provide a subdomain such as https://myapp.runn.io for an additional monthly cost.

Can I log users out of Runn via Single Logout?

Single Logout is not currently supported by Runn. We suggest you use auto logout instead. See above. If you require Single Logout please let us know via the in-app chat in the bottom right corner of your Runn account or email help@runn.io

Where can I find my Runn Account ID?

You can find your Runn Account ID displayed under your Account Settings in Runn.

Can I test SSO in the "Test" account first?

While you can also configure SSO in the "Test" account, there is no "preview" or "staging" functionality. The SSO settings will be applied to all logins for users who last viewed your "Test" account. In order to test SSO before rolling it out to your users, enable it on the "Live" account. Then enable "SSO Login Only" once you are certain it works as intended.

When changing an existing SSO configuration, we recommend coordinating a cutover period with your users (where access to the system is not available).

Do you support Identity Provider (IdP) initiated logins?

Yes. You can use the SSO Target URL shown in "Account > Settings > SAML Settings" in your Identity Provider to create login shortcuts within your intranet or dashboards. In this case, Runn as the Service Provider (SP) expects a SAML payload to be attached to the HTTP POST request.