Setting up SSO with Okta
Connect ilert to Okta over SAML 2.0, mapping each value Okta produces to the field in ilert that expects it.
This guide creates a SAML application in Okta and connects it to ilert. Both sides exchange values, so you will move between the two consoles a few times.
Prerequisites
The Pro plan or higher
The account owner role in ilert — no other role can change login authentication
Administrator access in Okta
Open the ilert side first
In the sidebar, go to Settings → Account settings → Single sign-on and choose SAML (e.g. Okta) from the dropdown.
Under Information to configure your identity provider, ilert shows two read-only values. Keep this tab open — Okta needs both:
SAML Endpoint URL
https://acme.ilert.com/api/sso/saml/acme/consume
Audience Restriction
ilert-acme

Create the SAML app in Okta
Pin the application username
Open the app's Sign On settings and set the application username to a value that does not change when someone's Okta username changes. This keeps ilert accounts bound to the right people later — see account bindings for why it matters.
Copy Okta's values back into ilert
On the app's Sign On tab, click View Setup Instructions. Okta shows three values. Each has a field waiting for it in ilert, under Configure ilert as your service provider:
Identity Provider Single Sign-On URL
Login URL
Identity Provider Issuer
Identity Provider Issuer
X.509 Certificate
X.509 Certificate
Click Save in ilert.
SSO is now configured — but nobody can use it yet, because no one is assigned to the Okta app.
Assign users to the app
In Okta, open the app's Assignments, click Assign, and choose Assign to People or Assign to Groups. Click Assign next to each person who should reach ilert, confirm, and click Done.
To verify, have one assigned user open app.ilert.com, click Login with SSO, and enter your ilert subdomain. They should land in ilert without typing a password.
Optional settings
These sit below the provider fields on the ilert Single sign-on tab.
Provision new users on first sso login
Creates the ilert user automatically on first successful sign-in, with the Responder role. Requires a free seat of that kind. Pass additional attributes to set the role and team instead.
Allow login with username and password
Turn it off to require SSO for everyone except the account owner. Read the warning below first.
Check provisioning attribute
Restricts auto-provisioning to responses carrying a named SAML attribute. See auto provisioning.
Compress AuthnRequests
Deflates the authentication request. Only if Okta's configuration requires it.
Longer sessions
Keeps users signed in longer, as though they had ticked Keep me logged in.
How Okta and ilert stay bound
Okta creates a binding between a user and an app when you assign them. By default that binding uses the Okta username, which is usually the person's primary email address.
ilert reads the value Okta sends in the SAML NameID field and maps it to an internal ilert user ID. That mapping is what keeps someone's ilert account, on-call shifts and history attached to them.
The consequence worth knowing:
Changing a user's email address in Okta does not break their ilert login. The app-level username assignment stays as it was, and ilert's internal mapping does not depend on the address either.
Changing the Okta username itself does not break it either, provided you pinned the application username as described above.
Okta may warn that a renamed user must be deprovisioned from the application manually. You can ignore that warning.
Pass roles and teams from Okta
Beyond NameID, Okta can send attributes that set an ilert user's role, team, and profile details at provisioning time.
Last updated
Was this helpful?