SSO & Authentication

Path: /settings/single-sign-on

SSO configuration requires the Infrastructure Enterprise or Ultimate tier, except Google OAuth which is available on all tiers.
Access: Admins only.

Realm9 supports single sign-on via two working providers: Google OAuth and Azure AD (SAML 2.0). Once configured, users can sign in with their identity provider credentials and are automatically provisioned on first login (JIT provisioning).

---

Supported Providers

---

Setting Up Google OAuth

1. Navigate to Settings → Single Sign-On → Configurations
2. Click Add Provider and select Google
3. Fill in the required fields:

4. Click Save, then Test Connection to verify

Getting Google credentials:

1. Go to Google Cloud Console → APIs & Services → Credentials
2. Create an OAuth 2.0 Client ID (Web application)
3. Add your Realm9 callback URL as an authorised redirect URI: https://<your-realm9-instance>/api/auth/sso/google/callback

---

Setting Up Azure AD (SAML)

1. Navigate to Settings → Single Sign-On → Configurations
2. Click Add Provider and select Azure AD (SAML)
3. Download the SP Metadata XML from the dialog and upload it to your Azure AD Enterprise Application
4. Import your IdP metadata — either paste the metadata URL from Azure AD or upload the metadata XML file. Realm9 parses the following from the metadata:
   • IdP Issuer
   • SSO URL
   • Single Logout URL
   • IdP Certificate

5. Click Save, then Test Connection to verify

Azure AD setup steps:

1. In Azure Portal → Enterprise Applications → New Application → Create your own
2. Set up SAML single sign-on
3. Upload the SP Metadata XML downloaded from Realm9 — this populates the Entity ID and Reply URL automatically
4. Copy the App Federation Metadata URL and paste it into Realm9's metadata URL field

Updating the certificate: Azure AD certificates expire periodically. To update, re-import the IdP metadata — Realm9 parses the latest certificate from the metadata file automatically.

---

JIT Provisioning

When a user signs in via SSO for the first time, Realm9 automatically creates their account — no admin invite required.

How it works:

• The user's email domain must match a verified domain on your organisation with auto sign-up enabled
• New users are created with the User role by default (overridden by role mapping if configured)
• If Require Approval is enabled on the domain, the new user gets Pending Approval status and cannot access Realm9 until an admin approves them
• Existing users can always sign in via SSO regardless of domain settings

Configure domain auto sign-up and approval settings at Settings → Organisation → Domain Management.

---

Role Mapping

Role mapping automatically assigns Realm9 roles to users based on their Azure AD group memberships, applied at every login.

Enable Role Mapping on the provider configuration and provide a JSON mapping:

{
  "groups": {
    "realm9-admins": "ADMIN",
    "realm9-provisioners": "PROVISIONER",
    "realm9-viewers": "VIEWER"
  }
}

Behaviour:

• Group names are matched against the groups claim in the SAML assertion
• The highest-privilege matching role is applied
• For existing users: role mapping only upgrades privileges — it never downgrades
• For new JIT-provisioned users: the mapped role is set directly
• If no groups match, the user keeps their current role (or gets the default User role if new)

---

Health Monitoring

Path: /settings/single-sign-on/health

The health dashboard monitors the status of all SSO providers and automatically manages a circuit breaker to protect your users from a degraded IdP.

Health Statuses

Circuit Breaker States

The circuit breaker opens automatically after 5 consecutive failures and attempts recovery after 1 minute.

Actions

• Check Now — trigger an immediate health check on any provider
• Open Circuit — manually block SSO logins for a provider (requires a reason)
• Close Circuit — manually reset the circuit breaker and restore SSO logins

The health dashboard auto-refreshes every 30 seconds and shows last check time, next scheduled check, consecutive failure count, and the last error message per provider.

---

SSO Migrations

Path: /settings/single-sign-on/migrations

Requires Infrastructure Enterprise or Ultimate tier.

SSO Migrations let you move users from one identity provider to another in a controlled, reversible way — for example, migrating from Google to Azure AD.

Migration Flow

1. Plan — select source and target providers, configure batch size, strategy, and whether to run as a dry run first
2. Execute — Realm9 processes users in batches, updating their SSO provider link
3. Rollback (if needed) — revert all migrated users back to the source provider

Migration Settings

Migration Statuses

---

SCIM Provisioning

Path: /settings/single-sign-on/scim

Requires Infrastructure Enterprise or Ultimate tier.

SCIM 2.0 allows your identity provider (Azure AD, Okta, etc.) to automatically provision, update, and deprovision users in Realm9.

Setup

1. Navigate to Settings → Single Sign-On → SCIM
2. Click Create Token, enter a name and optional expiry
3. Copy the token — it is shown only once
4. In your IdP, configure SCIM provisioning with:
   • SCIM Base URL: https://<your-realm9-instance>/api/scim/v2
   • Authentication: Bearer token (paste the token you just copied)

Default Provisioning Role

Set the role automatically assigned to users provisioned via SCIM. Options: Viewer, User, Provisioner, Admin. This role can be overridden per user via group-to-role mapping on login.

Supported Operations

SCIM group changes automatically recalculate user roles based on the group-to-role mapping configured on your SSO provider.

Token Management

• Tokens are stored as hashed values — the plain token is shown only at creation
• Each token shows: name, status (active / expired), created date, last used date, expiry date
• Delete a token to immediately revoke access

---

Role-Based Access

---

Next Steps

• Manage Members
• Configuration
• Audit Logs