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. Click Grant admin consent for [Your Organization]
9. 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

Generic OIDC Provider¶

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

Prerequisites¶

Your OIDC provider must support:

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

Configuration¶

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

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"