Configuring Auth0

Auth0 SAML Integration Setup Guide

This guide will help you configure Auth0 to work with Apiboost's SSO authentication system.

Prerequisites

• Access to Auth0 Dashboard with administrative privileges

• Your Apiboost application URL (e.g., <https://your-domain.com)>

• Basic understanding of SAML authentication concepts

Step-by-Step Configuration

Step 1: Create a New Application in Auth0

1. Log in to Auth0 Dashboard

   • Navigate to Auth0 Dashboard

   • Sign in with your Auth0 account credentials

2. Create Application

   • Click "Applications" in the left sidebar

   • Click "+ Create Application" button

   • Enter an application name (e.g., "Apiboost SAML Integration")

   • Select "Regular Web Applications" as the application type

   • Click "Create"

Step 2: Enable SAML2 Web App Addon

1. Navigate to Addons

   • In your newly created application, click on the "Addons" tab

   • Find "SAML2 Web App" and toggle it ON

2. Configure Basic SAML Settings

   • In the SAML2 Web App settings popup, you'll see a JSON configuration

   • Replace the existing configuration with the following:

{
  "audience": "https://YOUR-DOMAIN.com/auth/auth0/YOUR-SP-ENTITY-ID",
  "recipient": "https://YOUR-DOMAIN.com/auth/auth0/consume", 
  "mappings": {
    "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
    "first_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
    "last_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",
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
  ],
  "signatureAlgorithm": "rsa-sha256",
  "digestAlgorithm": "sha256",
  "destination": "https://YOUR-DOMAIN.com/auth/auth0/consume",
  "lifetimeInSeconds": 3600,
  "signResponse": false,
  "createUpnClaim": false,
  "passthroughClaimsWithNoMapping": false,
  "mapUnknownClaimsAsIs": false,
  "mapIdentities": false
}

3. Update Placeholder Values

   • Replace YOUR-DOMAIN.com with your actual Apiboost application domain

   • Replace YOUR-SP-ENTITY-ID with the Service Provider ID configured in your Apiboost admin. This value can be copied from the SP Entity ID field on your Apiboost SSO configuration.

4. Save Configuration

   • Click "Save" to apply the SAML settings

Step 3: Configure Application Settings

1. Navigate to Settings Tab

   • Click on the "Settings" tab of your Auth0 application

2. Configure Callback URLs

   • In the "Allowed Callback URLs" field, add:

     https://YOUR-DOMAIN.com/auth/auth0/consume

3. Configure Logout URLs (Optional)

   • In the "Allowed Logout URLs" field, add:

     https://YOUR-DOMAIN.com/user/login

4. Save Settings

   • Scroll down and click "Save Changes"

Step 4: Obtain SAML Configuration Details

1. Get Identity Provider Metadata

   • Go back to "Addons" → "SAML2 Web App"

   • Click on "Usage" tab

   • Copy the following information for your Apiboost configuration:

   Required Information:

   • Identity Provider Login URL: Copy the URL from "Identity Provider Login URL"

   • Identity Provider Logout URL: Copy the URL from "Identity Provider Logout URL"

2. Note Your Entity ID

   • The Entity ID will be in format: urn:YOUR-AUTH0-DOMAIN.auth0.com

   • Example: urn:dev-2naeh00zkchu23q3.us.auth0.com

Step 5: Configure User Attributes (Optional)

1. Set Up Rules or Actions

   • If you need to map additional user attributes or modify claims

   • Navigate to "Auth Pipeline" → "Rules" (for older tenants) or "Actions" → "Flows" (for newer tenants)

   • Create custom rules/actions to add additional user attributes if needed

Step 6: Test Configuration

1. Enable Application

   • Ensure your application is enabled in Auth0

   • Check that users have access to this application

2. Test Authentication Flow

   • Navigate to your Apiboost application

   • Attempt to log in using the Auth0 SSO option

   • Verify successful authentication and redirect

Issue 1: "Name ID does not match a valid email address"

Solution: Verify that nameIdentifierProbes has emailaddress as the first item in the array.

Issue 2: Callback URL Mismatch

Solution: Verify that callback URLs match exactly between Auth0 configuration and Apiboost backend configuration.

Issue 3: User Not Found After Authentication

Solution: Check that the email mapping is correct and that users exist in your Apiboost system with matching email addresses.

Security Recommendations

1. Use HTTPS Only: Ensure all URLs use HTTPS in production

2. Validate Certificates: Always use proper SSL certificates for production

3. Limit Application Access: Configure Auth0 application access rules to limit which users can authenticate

4. Regular Certificate Rotation: Plan for regular rotation of signing certificates

5. Monitor Authentication Logs: Regularly review Auth0 and Apiboost authentication logs

Support

If you encounter issues during setup:

1. Check Auth0 Logs: Navigate to "Monitoring" → "Logs" in Auth0 Dashboard

2. Verify Configuration: Double-check all URLs and certificate content

3. Test with SAML Tools: Use online SAML validation tools to test your configuration

4. Contact Support: Reach out to your Apiboost support team with specific error messages and configuration details

Note: This guide assumes your Apiboost application is properly configured to handle SAML authentication. Contact your Apiboost administrator to ensure the backend SSO configuration matches the Auth0 setup.