Single Sign-On (SSO)¶

Riskrunner supports Single Sign-On via OpenID Connect (OIDC). Once configured, users whose email domain matches your SSO domain allowlist are required to log in through your identity provider (IdP) instead of using a password.

SSO is configured per-tenant by admins in Settings > SSO Configuration.

Overview¶

SSO works with any OIDC-compliant identity provider, including Microsoft Entra ID, Google Workspace, Okta, and Auth0.
The required OIDC scopes are: openid, email, profile.
During SSO verification and login, Riskrunner uses the IdP’s stable subject identifier (sub) and accepts these email-like login claims when matching the authenticated user: standard OIDC claims email and preferred_username, plus the commonly-used Microsoft Entra claim upn.
On first SSO login, user accounts are automatically linked to their IdP identity. Name fields are synced from the IdP on each subsequent login.
External collaborators (users whose email domain is not in the SSO domain allowlist) are unaffected by SSO and continue to log in with their password, even when SSO is enabled on the tenant.

Required claims and identifier matching¶

Riskrunner requires a valid OIDC ID token containing:

sub – the user’s stable identity provider subject identifier
at least one standard OIDC login identifier claim: email or preferred_username
or, in Microsoft Entra environments, the commonly-returned upn claim

These claims are used to match the authenticated IdP account to the Riskrunner user.

This is especially important for Microsoft Entra ID tenants. Microsoft may return a user’s sign-in identifier as an alias such as user@tenant.onmicrosoft.com even when their primary business domain is something like user@company.com.

Riskrunner now accepts email, preferred_username, and upn when determining whether the authenticated IdP account matches the Riskrunner user. email and preferred_username are standard OIDC claims; upn is a Microsoft-specific extension commonly returned by Entra. This means SSO can still succeed if one of those claims contains the user’s Riskrunner email address, even if another claim uses an alias domain.

Note

Riskrunner does not query Microsoft Graph or other directory APIs to enumerate every alias on an account during login. At least one of the OIDC claims returned by your identity provider (email, preferred_username, or upn) must match the user’s Riskrunner email address.

Redirect URIs¶

Important

Your identity provider configuration must include both of the following redirect URIs. Without both, either the test flow or the login flow will fail with a redirect mismatch error from the IdP.

Purpose	Redirect URI
User SSO login	`https://riskrunner.app/auth/sso/callback`
Admin SSO test	`https://riskrunner.app/sso_settings/test/callback`

Setting up SSO in Riskrunner¶

Navigate to Settings > SSO Configuration.
Enter the Issuer URL from your identity provider.
Enter the Application (Client) ID from your identity provider.
Enter the Client Secret from your identity provider.
Enter the SSO Domain Allowlist – a comma-separated list of email domains whose users must use SSO (e.g. company.com, subsidiary.org).
Click Save Configuration. This saves your settings but does not enable SSO yet.
Click Test & Enable SSO. You are redirected to your IdP to authenticate. If the test succeeds, SSO is automatically enabled.

Once enabled, all users whose email domain matches the allowlist are required to use SSO. Users with other email domains are unaffected and continue using password login.

Modifying configuration after enabling¶

If you change the SSO configuration (client ID, client secret, issuer URL, or domains) after SSO is enabled, SSO is automatically disabled. You must click Test & Enable SSO again to re-enable it. This ensures that SSO is never active with an untested configuration.

Disabling vs removing SSO¶

Action	What happens	How to re-enable
Disable SSO	SSO is turned off but the configuration is kept. Users revert to password login.	Click Test & Enable SSO.
Remove SSO	The entire configuration is deleted. Users revert to password login.	Set up SSO from scratch.

Identity provider setup¶

The sections below provide step-by-step instructions for two common identity providers. Any OIDC-compliant provider works with Riskrunner – if yours is not listed here, consult your provider’s documentation for creating an OIDC application and use the general settings described above.

Microsoft Entra ID (Azure AD)¶

Go to Azure Portal > Microsoft Entra ID > App registrations > New registration.
Set the name to “Riskrunner SSO” (or any name you prefer).
Under Supported account types, select “Accounts in this organizational directory only”.
Under Redirect URI, select Web as the platform and add the redirect URI’s specified above.
Click Register.
On the app’s overview page, copy the Application (client) ID.
Note the Directory (tenant) ID – you need it for the Issuer URL. The Issuer URL is:
```
https://login.microsoftonline.com/<directory-tenant-id>/v2.0
```
Go to Certificates & secrets > New client secret. Copy the secret Value (not the Secret ID). This is only shown once.
Go to API permissions > Add a permission > Microsoft Graph > Delegated permissions. Select openid, email, and profile, then click Grant admin consent.
Ensure Microsoft Entra returns at least one usable login identifier for each user in the ID token: standard OIDC claims email or preferred_username, or the Microsoft-specific upn claim. Riskrunner accepts any of these when matching the authenticated user.

Back in Riskrunner, enter the Issuer URL, Application (client) ID, and Client Secret, then follow the steps in Setting up SSO in Riskrunner.

Google Workspace¶

Go to Google Cloud Console > APIs & Services > Credentials > Create Credentials > OAuth client ID.
Set Application type to “Web application”.
Set the name to “Riskrunner SSO” (or any name you prefer).
Under Authorized redirect URIs, add the redirect URI’s specified above.
Click Create.
Copy the Client ID and Client Secret from the confirmation dialog.
The Issuer URL for Google is:
```
https://accounts.google.com
```
Ensure your Google Workspace admin has enabled the OAuth app for the organisation.

Back in Riskrunner, enter the Issuer URL, Client ID, and Client Secret, then follow the steps in Setting up SSO in Riskrunner.

Troubleshooting¶

Redirect mismatch error¶

If you see a “redirect URI mismatch” error from your IdP during the test or login flow, verify that both redirect URIs are registered in your identity provider. The test flow and the login flow use different callback URLs. Both must be registered.

SSO was disabled after saving changes¶

This is expected. Any change to the SSO configuration automatically disables SSO. Click Test & Enable SSO to re-enable it with the updated settings.

Users not being prompted for SSO¶

Check that the user’s email domain is included in the SSO Domain Allowlist. Only users whose email domain matches the allowlist are required to use SSO. Others continue to use password login.

Microsoft returns an `onmicrosoft.com` address during SSO setup or login¶

This usually means Microsoft Entra is returning an alias or tenant-default sign-in name in one claim while the user’s normal business address appears in another. Riskrunner accepts the standard OIDC claims email and preferred_username, plus Microsoft’s upn claim, when matching the authenticated user.

If SSO still fails:

Confirm the Riskrunner user is stored with the correct business email address.
Confirm the business domain is included in the SSO Domain Allowlist.
Inspect the ID token claims returned by Microsoft Entra and verify that at least one of email, preferred_username, or upn matches the user’s Riskrunner email address.
If Microsoft only returns the onmicrosoft.com identifier and not the business-domain address in any of those claims, adjust the Entra user/app configuration so the correct login identifier is emitted.