SSO Setup Guide¶

Configure Single Sign-On (SSO) to allow users to authenticate using your organization's identity provider.

Overview¶

CertifyClouds PRO supports SSO via OpenID Connect (OIDC):

Prerequisites¶

Before configuring SSO:

1. PRO tier license - SSO is not available in STARTER tier
2. Admin access to your Identity Provider (IdP)
3. CertifyClouds URL - Your deployment's base URL

Required Information¶

Multiple Environments (Important!)¶

If you access CertifyClouds from different URLs (localhost, ACI, CAE, custom domain), you must register all redirect URIs in your IdP:

Azure AD / Entra ID Setup¶

Step 1: Create App Registration¶

1. Go to Azure Portal → Microsoft Entra ID → App registrations
2. Click + New registration
3. Configure:
4. Name: CertifyClouds SSO
5. Supported account types: Accounts in this organizational directory only
6. Redirect URI:
   • Platform: Web
   • URI: https://YOUR_CERTIFYCLOUDS_URL/api/auth/sso/callback
7. Click Register

Step 2: Configure Authentication¶

1. In your app registration, go to Authentication
2. Under Implicit grant and hybrid flows, ensure:
3. [ ] Access tokens - Unchecked (we use authorization code flow)
4. [ ] ID tokens - Unchecked
5. Under Advanced settings:
6. Allow public client flows: No

Step 3: Create Client Secret¶

1. Go to Certificates & secrets → Client secrets
2. Click + New client secret
3. Configure:
4. Description: CertifyClouds SSO
5. Expires: 24 months (recommended)
6. Click Add
7. Copy the secret Value immediately - it won't be shown again!

Step 4: Configure API Permissions¶

1. Go to API permissions
2. Click + Add a permission → Microsoft Graph → Delegated permissions
3. Add these permissions:
4. openid (Sign users in)
5. profile (View users' basic profile)
6. email (View users' email address)
7. User.Read (Sign in and read user profile)
8. GroupMember.Read.All (Required for group-based role mapping)
9. Click Grant admin consent for [Your Organization]
10. Verify all permissions show green checkmarks

Step 5: Collect Configuration Values¶

Okta Setup¶

Step 1: Create Application¶

1. Go to Okta Admin Console → Applications → Applications
2. Click Create App Integration
3. Select:
4. Sign-in method: OIDC - OpenID Connect
5. Application type: Web Application
6. Click Next

Step 2: Configure Application¶

1. App integration name: CertifyClouds
2. Grant type:
3. [x] Authorization Code
4. [ ] Implicit (unchecked)
5. Sign-in redirect URIs:
6. https://YOUR_CERTIFYCLOUDS_URL/api/auth/sso/callback
7. Controlled access: Select appropriate option
8. Click Save

Step 3: Collect Values¶

Step 4: Assign Users¶

1. Go to Assignments tab
2. Click Assign → Assign to People or Assign to Groups
3. Select users/groups who should access CertifyClouds

Step 5 (Optional): Emit Groups in the ID Token¶

Required only if you want Group-Based Role Mapping to assign admin/user roles automatically from Okta group memberships.

1. Okta Admin Console → Security → API → Authorization Servers
2. Select the authorization server CertifyClouds uses
3. Claims tab → + Add Claim
4. Configure:
5. Name: groups
6. Include in token type: ID Token, Always
7. Value type: Groups
8. Filter: Matches regex / .* (or scope to specific groups)
9. Save

Now Okta will include a groups claim in every ID token listing the user's group memberships as strings. CertifyClouds reads this claim (name configurable via the groupsClaim field - defaults to groups) and maps it against your groupRoleMapping on every login.

Generic OIDC Provider¶

For other OIDC providers (Auth0, Keycloak, PingFederate, Google Workspace, etc.):

Prerequisites¶

Your OIDC provider must support:

• Authorization Code flow
• Standard OIDC claims: sub, email, name
• OIDC Discovery endpoint (/.well-known/openid-configuration)

Configuration¶

Group-Based Role Mapping for Generic OIDC¶

Unlike Azure AD (which CertifyClouds queries via Microsoft Graph), generic OIDC providers deliver group memberships inside the ID token under a claim whose name varies by provider. CertifyClouds supports three claim shapes - most providers fit one without any configuration:

CertifyClouds extracts the names (and, for object form, also the IDs) and matches them against groupRoleMapping keys - first match wins. If your IdP doesn't emit a groups claim by default, every IdP documents how to add one (Okta: see Step 5 above; Auth0: Rules / Actions adding context.user.groups to the ID token; Keycloak: Client Scopes → groups mapper → "Add to ID token").

CertifyClouds Configuration¶

Step 1: Access SSO Settings¶

1. Log in to CertifyClouds as admin
2. Go to Settings → SSO Configuration
3. Click Configure SSO

Step 2: Enter Configuration¶

Step 3: Configure User Provisioning¶

Step 4: Test and Save¶

1. Click Test Connection to verify IdP connectivity
2. If successful, click Save Configuration
3. Test login in a private browser window

Group-Based Role Mapping¶

Automatically assign roles based on Entra group membership. When configured, CertifyClouds checks the user's groups on every login and updates their role accordingly.

Prerequisites¶

Your Entra app registration must have GroupMember.Read.All (delegated) with admin consent granted - see Step 4 above. If your org cannot grant that scope, you can still use this feature - configure the mapping keys as Entra group object IDs instead of display names (see "Match by object ID" below).

How It Works¶

CertifyClouds fetches the user's Entra group display names AND object IDs via Microsoft Graph on each login and maps them to a CertifyClouds role. The first matching group wins. If no group matches, the user keeps their existing role (no downgrade - so a manual admin override survives transient Entra lookup failures).

Match by display name (default)¶

Configure mapping keys to be the Entra group's display name (case-sensitive). Requires the GroupMember.Read.All scope above:

"groupRoleMapping": {
  "CertifyClouds-Admins": "admin",
  "CertifyClouds-Users":  "user"
}

Match by object ID (no extra scope needed)¶

If your tenant cannot grant GroupMember.Read.All consent, configure mapping keys as the Entra group's object ID (the GUID from Entra → Groups → your group → Overview):

"groupRoleMapping": {
  "98c766f5-d951-4d6d-90b8-e112ca0eba53": "admin",
  "0590e87b-bac0-4733-b9c8-54f2c87fcb56": "user"
}

Object IDs flow through the standard User.Read scope on the /me/memberOf response without redaction. Mix the two styles in one mapping if you want - first match wins.

Configure via API or UI¶

The Group→Role mapping editor is available in the SSO settings UI from 1.4.12 (Settings → SSO → IdP config form). Or configure it via the API:

Step 1 - Get a token:

TOKEN=$(curl -s -X POST http://YOUR_INSTANCE/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"YOUR_PASSWORD"}' \
  | jq -r '.access_token')

Step 2 - Read your current SSO config:

curl -s http://YOUR_INSTANCE/api/auth/sso/config \
  -H "Authorization: Bearer $TOKEN" | jq

Step 3 - PUT it back with groupRoleMapping added:

curl -X PUT http://YOUR_INSTANCE/api/auth/sso/config \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "providerType": "azure_ad",
    "azureTenantId": "YOUR_TENANT_ID",
    "oidcClientId": "YOUR_CLIENT_ID",
    "isEnabled": true,
    "autoCreateUsers": true,
    "defaultRole": "user",
    "groupRoleMapping": {
      "CC-Admins": "admin",
      "CC-Users": "user"
    }
  }'

Replace the group names with your actual Entra group display names (case-sensitive). Valid roles are admin and user.

Troubleshooting¶

Common Issues¶

Debug Tips¶

1. Enable SSO debug logging: LOG_SSO_DEBUG=true
2. Test OIDC discovery:

   curl https://YOUR_ISSUER_URL/.well-known/openid-configuration | jq
   

3. Check for required endpoints: authorization_endpoint, token_endpoint, jwks_uri

Security Best Practices¶

1. Use short-lived client secrets - Rotate every 12-24 months
2. Limit application permissions - Only request necessary scopes
3. Enable SSO-only mode - After testing, disable local password login
4. Use conditional access - Configure MFA via your IdP
5. Monitor SSO logins - Review audit logs for unusual activity

Environment Variable Configuration¶

For container deployments, SSO can be pre-configured:

SSO_PROVIDER_TYPE=oidc
SSO_ISSUER_URL=https://login.microsoftonline.com/YOUR_TENANT/v2.0
SSO_CLIENT_ID=your-client-id
SSO_CLIENT_SECRET=your-client-secret
SSO_AUTO_CREATE_USERS=true
SSO_DEFAULT_ROLE=user
SSO_LOGIN_BUTTON_TEXT="Sign in with Azure AD"