Auth0 SSO Setup Guide

This guide walks you through configuring Auth0 as your Identity Provider (IdP) for CRA Evidence single sign-on.

Overview

Auth0 provides robust SAML 2.0 support that integrates with CRA Evidence's SSO system. This guide covers the free and paid tier configurations.

What You'll Configure

• SAML SSO: Full single sign-on with automatic user provisioning
• JIT Provisioning: Users automatically created on first login
• Attribute Mapping: User profile sync from Auth0

Auth0 Plan Considerations

Note: SCIM (System for Cross-domain Identity Management) for automated user provisioning and deprovisioning requires Auth0 Enterprise plan. This guide focuses on SAML SSO, which works with all Auth0 plans.

Prerequisites

• Auth0 account (Sign up at auth0.com)
• CRA Evidence organisation admin access
• Your company email domain (e.g., company.com)

Step 1: Get CRA Evidence SP Information

Before configuring Auth0, gather the Service Provider (SP) information from CRA Evidence:

1. Log in to CRA Evidence as an organisation admin
2. Go to Settings > Single Sign-On
3. Note the following values:
   • Entity ID (Issuer): https://app.craevidence.com
   • ACS URL: https://app.craevidence.com/api/v1/saml/acs
   • Metadata URL: https://app.craevidence.com/api/v1/saml/metadata

Step 2: Create Auth0 Application

1. Log in to your Auth0 Dashboard (https://manage.auth0.com)
2. Navigate to Applications > Applications
3. Click + Create Application
4. Configure the application:
   • Name: CRA Evidence
   • Choose an application type: Regular Web Applications
5. Click Create

Step 3: Enable SAML2 Web App Addon

1. In your CRA Evidence application, go to the Addons tab
2. Find SAML2 WEB APP and click to enable it
3. A configuration modal will appear

Settings Tab

In the Settings tab of the SAML2 addon, configure:

Settings JSON (Advanced)

In the settings JSON, paste the following configuration:

{
  "audience": "https://app.craevidence.com",
  "mappings": {
    "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
    "name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
    "given_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
    "family_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
  },
  "nameIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "nameIdentifierProbes": [
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
  ]
}

Click Save (or Enable if first time).

Step 4: Get Auth0 IdP Information

After enabling the SAML addon:

1. In the SAML2 addon modal, go to the Usage tab
2. You will find:
   • Identity Provider Login URL - Your SSO URL
   • Issuer - Your IdP Entity ID
   • Identity Provider Certificate - Download this

Alternatively, download the Identity Provider Metadata XML file which contains all values.

Extracting Values from Metadata

If you download the metadata XML, look for:

Example Entity ID format:

urn:your-tenant.auth0.com

Example SSO URL format:

https://your-tenant.auth0.com/samlp/CLIENT_ID

Step 5: Configure CRA Evidence

1. In CRA Evidence, go to Settings > Single Sign-On
2. Click Add Identity Provider
3. Fill in the form:

Provisioning Settings:

1. Click Add Identity Provider

Step 6: Add SSO Domain

1. In CRA Evidence SSO settings, go to Domains
2. Click Add Domain
3. Enter your email domain (e.g., company.com)
4. Select the Auth0 IdP you just created
5. Click Add Domain

Verify Domain Ownership

1. Add a DNS TXT record:
   • Host/Name: _craevidence-verification
   • Value: (the verification token shown in CRA Evidence)
2. Wait for DNS propagation (up to 48 hours)
3. Click Verify Now in CRA Evidence

Step 7: Configure Auth0 Users

Auth0 offers multiple ways to manage users:

Option A: Auth0 Database (Default)

Users can sign up directly or be created in Auth0 Dashboard:

1. Navigate to User Management > Users
2. Click + Create User
3. Enter email and password
4. Users will authenticate via Auth0's login page

Option B: Social Connections

Enable Google, Microsoft, GitHub, etc.:

1. Go to Authentication > Social
2. Enable desired connections
3. Users can login with these providers through Auth0

Option C: Enterprise Connections

Connect to your company directory:

1. Go to Authentication > Enterprise
2. Configure Active Directory, LDAP, or other SAML IdPs
3. Auth0 acts as an identity broker

Step 8: Test SSO

1. Open a new incognito/private browser window
2. Go to https://app.craevidence.com/login
3. Enter an email address from your SSO domain
4. You should be redirected to Auth0's login page
5. Authenticate with your credentials
6. You should be redirected back to CRA Evidence, logged in

Optional: Enable SSO Enforcement

Once testing is successful, you can require SSO for all users:

1. Go to Settings > Single Sign-On > Enforcement
2. Enable Require SSO for all users
3. Optionally enable Allow admins to bypass SSO
4. Click Save Settings

Advanced: Auth0 Actions for Custom Claims

Auth0 Actions allow you to customize the SAML assertion with additional user data.

Add Custom Attributes

1. In Auth0 Dashboard, go to Actions > Library
2. Click + Create Action and select Build from scratch
3. Name it: CRA Evidence SAML Attributes
4. Select Trigger: Login / Post Login

Example Action code:

exports.onExecutePostLogin = async (event, api) => {
  // Only apply to CRA Evidence SAML application
  if (event.client.name !== 'CRA Evidence') return;

  // Add custom attributes to SAML assertion
  api.samlResponse.setAttribute('department', event.user.app_metadata?.department || '');
  api.samlResponse.setAttribute('employee_id', event.user.app_metadata?.employee_id || '');

  // Add roles if defined in user metadata
  const roles = event.user.app_metadata?.roles || ['member'];
  api.samlResponse.setAttribute('roles', roles.join(','));
};

1. Click Deploy
2. Go to Actions > Flows > Login
3. Drag your new Action into the flow
4. Click Apply

Role Mapping Example

To map Auth0 roles to CRA Evidence roles:

exports.onExecutePostLogin = async (event, api) => {
  if (event.client.name !== 'CRA Evidence') return;

  // Map Auth0 roles to CRA Evidence roles
  const auth0Roles = event.authorization?.roles || [];

  let craVaultRole = 'member'; // default

  if (auth0Roles.includes('cra-evidence-admin')) {
    craVaultRole = 'admin';
  } else if (auth0Roles.includes('cra-evidence-viewer')) {
    craVaultRole = 'viewer';
  }

  api.samlResponse.setAttribute('cra_evidence_role', craVaultRole);
};

Testing Checklist

Before rolling out to all users, verify:

• [ ] SSO Login Flow: Users can log in via Auth0 and access CRA Evidence
• [ ] JIT Provisioning: New users are created on first login
• [ ] User Attributes: Name and email sync correctly to CRA Evidence
• [ ] Logout: Users can sign out (both SP and IdP initiated)
• [ ] Error Handling: Invalid credentials show appropriate error
• [ ] Domain Routing: Email domain correctly triggers SSO flow

Troubleshooting

"Invalid SAML Response" Error

Causes and Solutions:

• ACS URL mismatch: Verify the Callback URL in Auth0 exactly matches https://app.craevidence.com/api/v1/saml/acs
• Audience mismatch: Ensure Audience is set to https://app.craevidence.com
• Certificate issue: Re-download the certificate from Auth0 and update in CRA Evidence

"Unable to validate signature" Error

• Download a fresh certificate from Auth0 (Usage tab in SAML addon)
• Ensure you're copying the full certificate including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----
• Check that no extra whitespace or line breaks were added

User Not Being Created

• Confirm JIT Provisioning is enabled in CRA Evidence IdP settings
• Verify the email attribute is being sent (check Auth0 logs)
• Ensure the user has an email address in Auth0

Auth0 Login Page Shows "Unauthorized"

• In Auth0, go to Applications > CRA Evidence > Connections
• Ensure at least one connection (Database, Social, or Enterprise) is enabled
• Verify the user exists in an enabled connection

"Domain Not Configured" in CRA Evidence

• Verify the domain is added and verified in CRA Evidence SSO settings
• Check exact spelling (e.g., company.com vs Company.com)
• Ensure DNS verification is complete

Clock Skew Errors

• Auth0 servers are time-synchronized, but your browser or CRA Evidence server might have clock drift
• CRA Evidence allows up to 2 minutes of clock drift by default
• Contact support if issues persist

Debugging with Auth0 Logs

1. In Auth0 Dashboard, go to Monitoring > Logs
2. Filter by your CRA Evidence application
3. Look for Success Login or Failed Login events
4. Click on an event for detailed information including SAML assertion

Security Recommendations

1. Enable MFA in Auth0: Go to Security > Multi-factor Auth to require additional verification
2. Configure Brute Force Protection: Enabled by default in Auth0
3. Set Up Anomaly Detection: Auth0 can detect suspicious login patterns
4. Use Custom Domain (Paid plans): Presents your domain instead of *.auth0.com
5. Review Connection Settings: Only enable authentication methods you need

Upgrading to Enterprise

Auth0 Enterprise plan adds:

• SCIM Provisioning: Automatic user provisioning and deprovisioning with CRA Evidence
• Advanced SAML Options: Including encrypted assertions
• Custom Enterprise Connections: Full LDAP/AD integration
• Extended SLAs and Support: Priority support channels
• SSO Dashboard: Centralized SSO management

For SCIM integration with CRA Evidence, contact your Auth0 representative and refer to the CRA Evidence SCIM documentation once upgraded.

Reference

Auth0 SAML Configuration Summary

Expected SAML Attributes

Support

If you encounter issues:

1. Check the SAML SSO Architecture documentation
2. Review Auth0 logs for detailed error information
3. Contact CRA Evidence support at support@craevidence.com
4. Provide:
   • Error message shown
   • Screenshot of Auth0 SAML addon configuration
   • Auth0 log entry for the failed login attempt
   • CRA Evidence IdP configuration (without certificate)