Skip to content

Provision Custom Enterprise Authentication for Client in Auth0

Internal Documentation - stacksync Support Team

This guide covers how to set up a customer's Azure Entra ID SSO and SCIM provisioning in Auth0 when they provide their Azure metadata.

Table of Contents

Overview

This process sets up: - ✅ SAML-based Single Sign-On via Auth0 - ✅ Automatic user provisioning via SCIM - ✅ Role-based access control (viewer/editor) - ✅ Domain-based SSO routing

Estimated time: 20-30 minutes per customer

Prerequisites

Before you begin, ensure you have: - [ ] Auth0 admin access to the stacksync tenant - [ ] Access to stacksync database for domain mapping - [ ] Customer's workspace ID where users will be provisioned

Step 1: Receive Customer Information

The customer should send you via email:

Required: - Federation Metadata XML file (downloaded from Azure) - Company name - Company email domain (e.g., acme.com) - Workspace ID (or workspace name if ID needs to be looked up)

Email format from customer: 

Subject: Azure SSO Setup - [Company Name]

Attachments: AzureMetadata.xml
Company Domain: acme.com
Workspace: [workspace-name or ID]

Step 2: Extract Configuration from Azure Metadata

2.1: Open the Metadata XML File

Open the customer's AzureMetadata.xml file in a text editor.

2.2: Extract Sign In URL (SSO URL)

Search for: <SingleSignOnService

You'll find something like: 

<SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" 
Location="https://login.microsoftonline.com/24fe1fa1-afe8-4ac0-a20d-19d00fb5fd9b/saml2"/>

Copy the Location URL. This is the customer's Sign In URL.

Example: 

https://login.microsoftonline.com/24fe1fa1-afe8-4ac0-a20d-19d00fb5fd9b/saml2

Note: Each customer has a unique tenant ID (the GUID in the URL).

2.3: Extract X509 Certificate

Search for: <X509Certificate> (it appears multiple times - use the first occurrence)

You'll find: 

<X509Certificate>MIIC8DCCAdigAwIBAgIQC845309758BD74EC273EED0676...</X509Certificate>

Copy everything between the tags (the long certificate string).

2.4: Create Certificate File

Create a new file named customer-name-cert.pem with this format: 

-----BEGIN CERTIFICATE-----
MIIC8DCCAdigAwIBAgIQC845309758BD74EC273EED0676
59926DE39BDEC4MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A
[... rest of certificate string ...]
-----END CERTIFICATE-----

Important: - Include the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines - The certificate string should be the complete value from the XML - No need to format line breaks - Auth0 handles this

Save this file - you'll upload it to Auth0.

2.5: Which certificate to use in Federation Metadata XML

When the Azure Federation Metadata XML contains multiple certificate blocks, select the signing certificate under the Role with type fed:ApplicationServiceType. In practice:

  • Look for:
  • RoleDescriptor xsi:type="fed:ApplicationServiceType" ...
  • Inside it, find KeyDescriptor use="signing" → X509Certificate
  • This is the certificate Azure uses to sign the assertions for the enterprise app. Use this cert in our SP.
  • If Azure has rotated the token‑signing certificate, the “Active” certificate’s thumbprint in Azure SSO blade should match the certificate you extract here.
  • Prefer configuring the “App Federation Metadata Url” in our SP so the certificate auto‑updates on rotation.

Example source reference: in stacksync-exampleFederationMetadata (1).xml lines 125‑126, the RoleDescriptor with xsi:type="fed:ApplicationServiceType" is where to extract the signing X509Certificate.

Step 3: Create Auth0 SAML Connection

3.1: Navigate to Auth0 Dashboard

  1. Log into Auth0 Dashboard: https://manage.auth0.com
  2. Select the stacksync tenant
  3. Go to Authentication → Enterprise → SAML

[Screenshot: Auth0 Enterprise Connections page]

3.2: Create New Connection

  1. Click + Create Connection
  2. Connection name: Use format: azure-[company-slug]-[workspace-id]-[environment]
  3. Examples:
    • azure-acmecorp-3603-prod (Acme Corp, workspace 3603, production)
    • azure-techstartup-9876-staging (Tech Startup, workspace 9876, staging)
    • azure-globalco-42-dev (Global Co, workspace 42, dev)
  4. All lowercase, no spaces, only hyphens as separators
  5. Click Create

[Screenshot: Auth0 new SAML connection form]

3.3: Configure Connection Settings

Fill in the following fields:

Sign In URL

Paste the Sign In URL extracted from the metadata XML: 

https://login.microsoftonline.com/[CUSTOMER-TENANT-ID]/saml2

X509 Signing Certificate

  1. Click Choose File
  2. Upload the .pem certificate file you created in Step 2.4

User ID Attribute

Leave as default: 

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier

Other Settings

  • Enable Sign Out: Leave OFF (disabled)
  • Debug Mode: Leave OFF (disabled)

3.4: Save and Copy Connection Details

  1. Click Save
  2. Provide the customer the Reply URL (ACS) in this format:

Reply URL (ACS): 

https://stacksync/login/callback?connection=azure-[connection-name]
- Replace [connection-name] with the exact Auth0 connection name you created (e.g., azure-test-1).

Example: 

https://stacksync/login/callback?connection=[connection-name]

  1. Provide the customer the Entity ID (this is not shown in the Auth0 page; you must define it using the connection name):

Entity ID: 

urn:auth0:stacksync:azure-[connection-name]

[Screenshot: Auth0 connection setup complete showing callback URL and Entity ID]

3.5: Enable Connection for stacksync Application

  1. In the same connection settings, go to the Applications tab
  2. Toggle ON for the Stacksync application
  3. Toggle ON for the frontend-logics-prod application
  4. Click Save

[Screenshot: Applications tab showing stacksync enabled]

Step 4: Send Configuration to Customer

5.1: Prepare Email to Customer

📧 Send the following email to the customer:

Subject: stacksync Azure SSO Configuration - Action Required

Body: 

Hi [Customer Name],

Thank you for sending your Azure metadata. Your SCIM connection has been created.

Please complete the following steps to finalize the setup:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

STEP 1: Configure SAML Settings in Azure

1. Go to Azure Portal: https://portal.azure.com
2. Navigate to: Microsoft Entra ID → Enterprise applications → stacksync
3. Click: Single sign-on → Basic SAML Configuration → Edit
4. Enter these values:

   Identifier (Entity ID):
   urn:auth0:stacksync:azure-[company-slug]

   Reply Url:
   https://stacksync/login/callback?connection=[connection-name]

   Reply URL (Assertion Consumer Service URL):
   https://stacksync.eu.auth0.com/login/callback

   Sign on URL:
   https://stacksync.com/login

5. Click Save

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

STEP 2: Configure SCIM Provisioning in Azure

1. In the same stacksync application, go to: Provisioning → Get started
2. Set Provisioning Mode to: Automatic
3. Enter Admin Credentials:

   Tenant URL:
   https://api.stacksync.com/v1/workspaces/[WORKSPACE-ID]/scim/v2

   Secret Token:
   [SCIM-TOKEN]

4. Click "Test Connection" - you should see success
5. Click Save

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

STEP 3: Complete Remaining Setup

Please follow the complete setup guide for the remaining steps:
https://docs.stacksync.com/features/security/sso-and-scim/azure-entra-id

The guide covers:
- Creating app roles (viewer/editor)
- Configuring attribute mappings
- Assigning users with roles

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

IMPORTANT: Store your Secret Token securely - it cannot be retrieved later.

If you need assistance, reply to this email or contact support@stacksync.com.

Best regards,
stacksync Support Team

Replace: - [Customer Name] - Customer contact name - [company-slug] - The slug you used (e.g., acmecorp) - [WORKSPACE-ID] - Customer's workspace ID - [SCIM-TOKEN] - The plaintext token you generated

Step 5: Customer Completes Azure Configuration

The customer should now complete these steps on their end (using the public GitBook documentation):

  1. ✅ Configure Basic SAML settings (Entity ID, Reply URL)
  2. ✅ Configure SCIM provisioning (Tenant URL, Secret Token)
  3. ✅ Create App Roles (viewer, editor)
  4. ✅ Configure attribute mappings (including roles)
  5. ✅ Assign users with appropriate roles
  6. ✅ Enable provisioning

Wait for customer confirmation before testing.

Step 6: Testing

Troubleshooting

Issue: Users Not Being Provisioned

Possible causes: - SCIM token incorrect or expired - Provisioning not enabled in Azure - Users not assigned to the application

Solution: 1. Verify SCIM token is correct 2. Check Azure provisioning status is "On" 3. Verify users are assigned to stacksync app in Azure 4. Check provisioning logs in Azure

Issue: Wrong Role Assigned

Possible causes: - Role mapping not configured correctly - App role display names are capitalized (should be lowercase) - Default role not set

Solution: 1. Verify attribute mapping for roles: - Expression: SingleAppRoleAssignment([appRoleAssignments]) - Target: roles[primary eq "True"].value - Default: viewer 2. Verify app roles in Azure App registrations: - Display name: viewer (not Viewer) - Value: viewer

Issue: Email Not Being Sent to stacksync

Possible causes: - Email attribute mapping missing or incorrect - Test user doesn't have mail attribute set in Azure

Solution: 1. Check attribute mapping: - Source: userPrincipalName (more reliable than mail) - Target: emails[type eq "work"].value 2. Verify test user has email or userPrincipalName set

Issue: Certificate Invalid or Expired

Possible causes: - Certificate extracted incorrectly from metadata - Certificate format incorrect - Certificate expired

Solution: 1. Re-download metadata XML from Azure 2. Extract certificate again (use first X509Certificate occurrence) 3. Ensure .pem file has correct format with BEGIN/END lines 4. Upload new certificate to Auth0

Support Escalation

If issues persist after troubleshooting:

  1. Collect logs:
  2. Auth0 logs (Monitoring → Logs)
  3. Azure provisioning logs

  4. stacksync API logs for SCIM requests

  5. Gather info:

  6. Customer name and domain
  7. Auth0 connection name
  8. Exact error messages

  9. Screenshots if applicable

  10. Escalate to:

  11. Engineering team via Slack #sso-support
  12. Or create ticket in JIRA with label sso-issue

Appendix

A: Auth0 Connection Naming Convention

Use consistent naming for Auth0 connections:

Format: azure-[company-slug]-[workspace-id]-[environment]

Examples: - azure-acmecorp-3603-prod - Acme Corporation (workspace 3603, production) - azure-techstartup-9876-staging - Tech Startup Inc (workspace 9876, staging) - azure-globalco-42-dev - Global Company LLC (workspace 42, development)

Rules: - All lowercase - No spaces (use hyphens) - No special characters except hyphens - Keep it short but recognizable

D: Metadata XML Structure Reference

For quick reference, here's what to look for in the metadata XML: 

<EntityDescriptor entityID="https://sts.windows.net/TENANT-ID/">
  <!-- SSO URL -->
  <SingleSignOnService 
    Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" 
    Location="https://login.microsoftonline.com/TENANT-ID/saml2"/>

  <!-- Certificate (use first occurrence) -->
  <X509Certificate>MIIC8DCCAdig...</X509Certificate>
</EntityDescriptor>

Document Version: 1.0
Last Updated: 2025-11-21
Maintained By: stacksync DevOps Team