SSO Admin Guide

This guide is for organization administrators who need to configure SSO for their organization using the Admin UI. For platform operators configuring SSO at the gateway level, see the Authentication Configuration reference.

Overview

Per-organization SSO allows each organization in a multi-tenant deployment to configure their own identity provider. This enables:

• Self-service setup - Configure SSO without platform operator involvement
• Domain verification - Prove domain ownership before enabling SSO
• Enforcement modes - Control whether SSO is optional, in test mode, or required
• Email-based discovery - Users enter their email and are redirected to the correct IdP

Prerequisites

Before configuring SSO:

1. Organization exists - Your organization must be created in Hadrian
2. Admin access - You need organization admin role
3. IdP credentials - Have your identity provider's client ID, client secret, and issuer URL ready

Configuring SSO

Navigate to Admin → Organizations → [Your Org] → SSO to access the SSO configuration page.

Creating an SSO Configuration

Click Configure SSO to open the configuration form.

Required Fields

Optional Fields

Identity Provider Setup

Configure your identity provider with these settings:

Provider-Specific Notes

Google Workspace:

• Create credentials in Google Cloud Console → APIs & Services → Credentials
• Enable the "Google Identity" API
• Groups require Google Workspace admin setup

Okta:

• Create a new OIDC Web Application
• Issuer URL format: https://your-org.okta.com
• Groups claim requires adding groups to the ID token in the authorization server

Azure AD / Entra ID:

• Register an application in Azure Portal → App registrations
• Issuer URL format: https://login.microsoftonline.com/{tenant-id}/v2.0
• Groups may require Microsoft Graph API permissions

Keycloak:

• Create a new client with "Standard Flow" enabled
• Issuer URL format: https://keycloak.example.com/realms/{realm-name}
• Groups are included by default in most configurations

Domain Verification

Before enforcing SSO, you must verify ownership of your email domains. This prevents unauthorized organizations from claiming domains they don't own.

Adding a Domain

1. Click Add Domain
2. Enter your domain (e.g., acme.com)
3. You'll receive a DNS TXT record to add

DNS Verification

Add the provided TXT record to your domain's DNS:

Type:  TXT
Host:  _hadrian-verify (or @ for root)
Value: hadrian-verify=abc123xyz...

The record format is:

hadrian-verify={verification_token}

Verification Status

Click Verify to check the DNS record. Failed verifications can be retried after updating DNS.

Blocked Domains

Public email domains cannot be verified:

• gmail.com, googlemail.com
• outlook.com, hotmail.com, live.com
• yahoo.com, icloud.com
• protonmail.com, proton.me

These domains are shared by millions of users and cannot be claimed by a single organization.

Enforcement Modes

SSO enforcement determines whether users must authenticate via SSO to access your organization.

Mode Descriptions

Rollout Strategy

1. Start with Optional - Configure SSO and verify domains without affecting users
2. Enable Test Mode - Monitor logs for users who would be blocked
3. Switch to Required - Enforce SSO after validating test mode results

Domain Requirements for Enforcement

• Optional mode: No domain verification required
• Test mode: At least one verified domain recommended
• Required mode: At least one verified domain required

Users with email addresses matching verified domains will be subject to enforcement. Users with unverified domains can still access the organization through other means.

Just-in-Time Provisioning

JIT provisioning automatically creates user accounts when they first authenticate via SSO.

Configuration

In the SSO configuration form, enable provisioning options:

Attribute Sync

SSO Group Mappings

Map identity provider groups to Hadrian teams for automatic team assignment.

Creating Mappings

Navigate to Admin → Organizations → [Your Org] → SSO Group Mappings.

Priority Resolution

When a user belongs to multiple IdP groups that map to the same team:

1. Mapping with highest priority value wins
2. If tied, alphabetically earlier group name wins
3. If still tied, earlier creation time wins

Example:

A user in Engineers and SeniorEngineers gets lead role (priority 10 > 0). A user in all three groups gets admin role (priority 20 wins).

Testing Mappings

Use the Test Mappings feature to validate your configuration:

1. Enter a list of IdP groups (as they appear in the token)
2. Click Test
3. View which teams/roles would be assigned

This helps identify unmapped groups before users encounter issues.

Import/Export

For large mapping sets:

• Export: Download mappings as CSV or JSON
• Import: Upload mappings with conflict resolution:
  • skip - Skip existing mappings
  • overwrite - Update existing mappings
  • error - Fail if any mapping exists

Troubleshooting

SSO Login Fails

1. Check redirect URI - Must exactly match IdP configuration
2. Verify client credentials - Client ID and secret must be correct
3. Check issuer URL - Must be the exact issuer URL from your IdP
4. Review scopes - Ensure openid scope is included

Domain Verification Fails

1. Wait for DNS propagation - Can take up to 48 hours
2. Check TXT record format - Must be exactly hadrian-verify={token}
3. Verify correct domain - TXT record must be on the domain being verified
4. Check DNS provider - Some providers require specific formatting

Users Not Provisioned

1. Check provisioning enabled - Both "Enable Provisioning" and "Create Users" must be on
2. Verify email domain - User's email domain must be in allowed list (if configured)
3. Check group mappings - User must be in a mapped group to get team membership

Groups Not Mapped

1. Verify groups claim - Must match the claim name in your IdP's token
2. Check exact group names - Mappings are case-sensitive
3. Review IdP token - Use IdP's token debugger to see actual group values

Related Topics