Single sign-on#

Connect your identity provider so people sign in with corporate credentials, and access is removed centrally when they leave. SAML 2.0 and OIDC are supported.

Before you start#

You need to be an owner of the organisation, and an administrator of the identity provider. Have a second owner account signed in on another browser while you configure this, so you are not locked out if something is misconfigured.

Values ObserveIQ gives you#

From Settings → Single sign-on:

Field	Typical value
ACS URL (Reply URL)	`https://app.observeiq.io/api/v1/auth/sso/saml/callback`
Entity ID (Audience)	`https://app.observeiq.io`
Redirect URI (OIDC)	`https://app.observeiq.io/api/v1/auth/sso/oidc/callback`
Start URL	`https://app.observeiq.io/login?org=your-org-slug`

Attributes to send#

Attribute	Required	Notes
`email`	Yes	Must match the invited address. This is the identity key
`firstName`	No	Display name
`lastName`	No	Display name
`groups`	No	Only if you want role mapping

Okta#

Applications → Create App Integration → SAML 2.0.
Set Single sign-on URL to the ACS URL, Audience URI to the Entity ID.
Under Attribute Statements add email mapped to user.email, firstName to user.firstName, lastName to user.lastName.
For role mapping, add a Group Attribute Statement named groups filtering on the groups you use.
Copy the Identity Provider metadata URL and paste it into ObserveIQ. Save, then use Test.

Microsoft Entra ID#

Enterprise applications → New application → Create your own.
Single sign-on → SAML. Set Identifier to the Entity ID, Reply URL to the ACS URL.
Under Attributes and Claims, ensure the email claim is user.mail and that the unique user identifier is the email address, not the object ID.
Copy the App Federation Metadata Url into ObserveIQ.

Warning

Entra sends the object ID as the name identifier by default. If left that way, people authenticate but do not match their invited account. Set the unique user identifier to user.mail.

Google Workspace#

Admin console → Apps → Web and mobile apps → Add custom SAML app.
Copy the SSO URL, Entity ID and certificate into ObserveIQ.
Map Primary email to email, First name to firstName, Last name to lastName.
Turn the app ON for everyone, or for the organisational units that should have access.

Generic OIDC#

Provide the discovery URL, client ID and client secret. The openid, email and profile scopes are required. Register the redirect URI above with your provider.

Mapping groups to roles#

If you send a groups attribute, map group names to ObserveIQ roles under Settings → Single sign-on → Role mapping:

Identity provider group	ObserveIQ role
`observeiq-owners`	Owner
`observeiq-admins`	Admin
`observeiq-users`	Member

Roles are then applied at each sign-in, so a group change in your directory takes effect the next time the person signs in. Without mapping, everyone receives the default role set on the connection.

Enforcing SSO#

Once tested, turn on Require SSO to disable password sign-in for the organisation.

Warning

Test with a second account before enforcing. If the connection is misconfigured and password sign-in is disabled, nobody can get in and it takes a support request to recover. Keep one owner account exempt until you have signed in successfully via SSO at least once.

Provisioning and deprovisioning#

People are created on first successful sign-in if the domain matches your organisation, or they can be invited in advance. Removing someone in your identity provider stops them signing in immediately. It does not remove their ObserveIQ membership record, so also remove them under Settings → Members when they leave, and review any API keys they created.

Troubleshooting#

Symptom	Usual cause
"User not found" after authenticating	Email attribute not sent, or does not match the invited address
Redirect loop	Reply URL or redirect URI mismatch, often a trailing slash
Signs in but wrong role	Group attribute not sent, or role mapping not configured
Certificate error	Identity provider certificate rotated; refresh the metadata