OneLogin SSO & SCIM Setup Guide

This guide walks you through configuring OneLogin as your Identity Provider (IdP) for CRA Evidence single sign-on (SAML) and automated user provisioning (SCIM).

Overview

OneLogin offers a free developer sandbox that includes:

• SAML 2.0 SSO - Single Sign-On for enterprise authentication
• SCIM 2.0 Provisioning - Automated user lifecycle management
• Custom SAML Connectors - Flexible configuration for any SAML SP
• Provisioning Rules - Automated user group and attribute mapping

By the end of this guide, you will have:

1. SAML SSO configured so users authenticate through OneLogin
2. SCIM provisioning configured so user accounts sync automatically
3. Domain-based routing so users with your email domain are directed to OneLogin

Prerequisites

Before starting, ensure you have:

---

Part 1: SAML SSO Setup

Step 1.1: Get CRA Evidence SP Information

Before configuring OneLogin, 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:

Step 1.2: Create OneLogin Application

1. Log in to your OneLogin Admin Console
2. Navigate to Applications > Applications
3. Click Add App
4. Search for SAML Custom Connector (Advanced) or SAML Test Connector (IdP w/ attr)
5. Click on the connector to add it

Step 1.3: Configure Application Info

In the Info tab:

Click Save

Step 1.4: Configure SAML Settings

Navigate to the Configuration tab and enter:

SAML Settings:

Click Save

Step 1.5: Configure Attribute Mappings

Navigate to the Parameters tab. Add the following custom attributes:

To add each parameter:

1. Click the + button
2. Enter the field name (e.g., email)
3. Select the mapping value from the dropdown
4. Check Include in SAML assertion
5. Click Save

Important: Ensure the NameID value is set to Email in the SSO tab settings.

Step 1.6: Get OneLogin IdP Information

Navigate to the SSO tab to retrieve:

To download the certificate:

1. Click View Details next to X.509 Certificate
2. Click Download or copy the certificate text
3. The certificate should start with -----BEGIN CERTIFICATE-----

Alternatively, you can download the Issuer URL metadata XML which contains all values.

Step 1.7: Configure CRA Evidence with OneLogin

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

Provisioning Settings (JIT):

1. Click Add Identity Provider

Step 1.8: Add and Verify SSO Domain

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

Verify Domain Ownership:

1. Add a DNS TXT record to your domain:
   • Host: _craevidence-verification (or _craevidence-verification.yourcompany.com)
   • Type: TXT
   • Value: The verification token shown in CRA Evidence
2. Wait for DNS propagation (can take up to 48 hours, usually faster)
3. Click Verify Now in CRA Evidence

Step 1.9: Assign Users in OneLogin

1. In OneLogin Admin Console, go to your CRA Evidence application
2. Click Users in the left sidebar
3. Click Add Users to assign individual users, or
4. Go to Rules to create automatic assignment rules based on groups

Step 1.10: Test SSO Flow

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 OneLogin
5. Authenticate with your OneLogin credentials
6. You should be redirected back to CRA Evidence, logged in

Test IdP-Initiated SSO:

1. Log in to OneLogin
2. Click on the CRA Evidence app icon in your OneLogin portal
3. You should be logged directly into CRA Evidence

---

Part 2: SCIM Provisioning Setup

SCIM (System for Cross-domain Identity Management) automates user lifecycle management. When you add or remove users in OneLogin, they are automatically provisioned or deprovisioned in CRA Evidence.

Step 2.1: Create SCIM Client in CRA Evidence

1. In CRA Evidence, go to Settings > SCIM Provisioning
2. Click Add SCIM Client
3. Fill in the form:

Provisioning Settings:

1. Click Create Client

IMPORTANT: Copy the Bearer Token shown on the next screen. This token is displayed only once. Store it securely as you will need it for OneLogin configuration.

The token will look like: scim_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Note also:

• SCIM Base URL: https://app.craevidence.com/scim/v2

Step 2.2: Enable Provisioning in OneLogin

1. In OneLogin Admin Console, go to your CRA Evidence application
2. Navigate to the Provisioning tab
3. Enable Provisioning

Step 2.3: Configure SCIM Settings in OneLogin

In the Provisioning tab, configure:

SCIM JSON Template (if required):

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "{$user.email}",
  "externalId": "{$user.id}",
  "name": {
    "givenName": "{$user.firstname}",
    "familyName": "{$user.lastname}"
  },
  "displayName": "{$user.display_name}",
  "emails": [
    {
      "value": "{$user.email}",
      "primary": true
    }
  ],
  "active": true
}

Click Save

Step 2.4: Test Provisioning Connection

1. In the Provisioning tab, click Test or Enable
2. OneLogin will attempt to connect to CRA Evidence's SCIM endpoint
3. You should see a success message: "Connection successful"

If the test fails, verify:

• The SCIM Base URL is correct
• The Bearer Token is copied correctly (no extra spaces)
• The SCIM client is enabled in CRA Evidence

Step 2.5: Configure Provisioning Rules

In OneLogin, you can configure what happens during user lifecycle events:

When users are created in OneLogin:

1. Go to Provisioning tab > Entitlements
2. Configure whether new users should be automatically provisioned

When users are deleted/suspended in OneLogin:

1. Go to Provisioning tab
2. Under "When users are deleted..." select:
   • Suspend (recommended) - Deactivates the user in CRA Evidence
   • Delete - Removes org membership (if allowed in SCIM client)

Attribute Mapping:

1. Go to Parameters tab
2. Ensure attributes are mapped for SCIM provisioning:

Step 2.6: Test User Provisioning

Create a Test User:

1. In OneLogin, go to Users > Users
2. Click New User
3. Create a test user with an email from your domain
4. Assign the user to your CRA Evidence application
5. Wait a few moments for sync

Verify in CRA Evidence:

1. In CRA Evidence, go to Settings > Organisation > Users
2. The test user should appear with:
   • Status: Active
   • Provisioned via: SCIM

Check Provisioning Logs:

1. In CRA Evidence, go to Settings > SCIM Provisioning
2. Click on your SCIM client
3. View the Provisioning Logs tab
4. You should see a "create" operation for your test user

---

Part 3: Testing Checklist

Use this checklist to verify your configuration is complete:

SSO Tests

• [ ] SP-Initiated SSO: Enter email at CRA Evidence login, redirected to OneLogin, successfully authenticated
• [ ] IdP-Initiated SSO: Click CRA Evidence app in OneLogin portal, successfully logged into CRA Evidence
• [ ] JIT Provisioning: New user authenticates via SSO and account is created automatically
• [ ] Attribute Sync: User name updates in OneLogin are reflected in CRA Evidence on next login
• [ ] Domain Routing: Email from verified domain triggers SSO redirect

SCIM Tests

• [ ] Connection Test: OneLogin "Test" button shows successful connection
• [ ] User Creation: New user assigned to app appears in CRA Evidence
• [ ] User Update: Name change in OneLogin syncs to CRA Evidence
• [ ] User Deactivation: Suspended user in OneLogin is deactivated in CRA Evidence
• [ ] Provisioning Logs: Operations appear in CRA Evidence SCIM logs

Combined Tests

• [ ] End-to-End Flow: Create user in OneLogin -> User can SSO into CRA Evidence
• [ ] Deprovisioning Flow: Remove user from app in OneLogin -> User cannot access CRA Evidence

---

Part 4: Troubleshooting

SAML SSO Issues

"Invalid SAML Response" Error

Possible causes:

• ACS URL mismatch - Verify the URL matches exactly (check for trailing slashes)
• Certificate expired or incorrect - Re-download from OneLogin
• Clock skew - Ensure OneLogin and CRA Evidence times are synchronized
• Signature validation failed - Ensure certificate is complete including BEGIN/END lines

Resolution:

1. Go to OneLogin > Applications > CRA Evidence > SSO tab
2. Verify the X.509 certificate is current
3. Re-download and re-enter in CRA Evidence if needed

User Not Being Created (JIT)

Possible causes:

• JIT Provisioning not enabled in CRA Evidence
• Email attribute not being sent in SAML assertion
• User already exists with different email case

Resolution:

1. Verify JIT Provisioning is enabled in CRA Evidence IdP settings
2. Check OneLogin Parameters tab - ensure email is mapped and included in assertion
3. Check CRA Evidence for existing user with same email (case-insensitive)

"Domain Not Configured" Message

Possible causes:

• Domain not added or not verified
• Domain spelling mismatch
• DNS propagation incomplete

Resolution:

1. Check Settings > SSO > Domains in CRA Evidence
2. Ensure domain is verified (green checkmark)
3. If pending, wait for DNS propagation or check TXT record

Redirect Loop

Possible causes:

• RelayState configuration issue
• Multiple IdPs configured for same domain
• Browser cookie issues

Resolution:

1. Clear browser cookies and cache
2. Test in incognito/private window
3. Verify only one IdP is linked to your domain

SCIM Provisioning Issues

"401 Unauthorized" Error

Possible causes:

• Bearer token incorrect or expired
• SCIM client disabled
• Token rotated but not updated in OneLogin

Resolution:

1. In CRA Evidence, verify SCIM client is enabled
2. If unsure about token, rotate it: Settings > SCIM > Client > Rotate Token
3. Update the new token in OneLogin immediately

"429 Too Many Requests"

Possible causes:

• Rate limit exceeded (default: 1000 requests/hour)
• Initial sync of large user base

Resolution:

1. Wait for rate limit window to reset (1 hour)
2. For large initial syncs, coordinate with CRA Evidence support to temporarily increase limits

"409 Conflict" - User Already Exists

Possible causes:

• User was created via different method (manual or SAML JIT)
• Duplicate external ID mapping

Resolution:

1. In CRA Evidence, check if user exists under Settings > Organisation > Users
2. If user exists, SCIM will link to existing account on next sync
3. Check SCIM client logs for specific error details

Users Not Syncing

Possible causes:

• User not assigned to application in OneLogin
• Provisioning rules not configured
• SCIM client disabled

Resolution:

1. In OneLogin, verify user is assigned to CRA Evidence app
2. Check Provisioning tab rules in OneLogin
3. Verify SCIM client is enabled in CRA Evidence
4. Check provisioning logs for errors

Attribute Updates Not Syncing

Possible causes:

• "Sync Attributes" disabled in SCIM client
• Attribute not mapped in OneLogin parameters
• Rate limiting

Resolution:

1. Enable "Sync Attributes" in CRA Evidence SCIM client settings
2. Verify attribute mapping in OneLogin Parameters tab
3. Wait and retry if rate limited

Debug Mode

Enable debug logging for troubleshooting:

In CRA Evidence (contact your administrator):

SAML_DEBUG=true

In OneLogin:

1. Go to Activity > Events
2. Filter by application to see SAML and SCIM events
3. Check for error details in event logs

---

Part 5: Optional Configuration

Enable SSO Enforcement

Once testing is successful, require SSO for all organisation 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

Warning: Ensure at least one admin can bypass SSO before enabling enforcement.

Configure Multiple Domains

If your organisation uses multiple email domains:

1. Go to Settings > SSO > Domains
2. Add each domain
3. Link all domains to your OneLogin IdP
4. Verify each domain

Link SCIM to SAML IdP

For better tracking, link your SCIM client to your SAML IdP:

1. Go to Settings > SCIM Provisioning
2. Edit your SCIM client
3. Select your OneLogin IdP under "Link to Identity Provider"
4. Save changes

This helps with:

• Unified audit logging
• Correlation of SAML and SCIM events
• User provisioning source tracking

---

Support

If you encounter issues not covered in this guide:

1. Check the architecture documentation:

   • SAML SSO Architecture
   • SCIM Provisioning Architecture

2. Contact CRA Evidence support:

   • Email: support@craevidence.com
   • Provide:
     • Screenshot of error message
     • OneLogin application configuration (without tokens/certificates)
     • CRA Evidence IdP/SCIM client configuration
     • Relevant log entries

3. OneLogin Support:

   • OneLogin Developer Documentation
   • OneLogin Support Portal

---

Quick Reference

CRA Evidence Endpoints

OneLogin Settings Summary

Required Attributes