Auth0

Step 1: Create a SAML Application in Auth0

1. Log in to your Auth0 Dashboard.
2. Navigate to Applications > Applications.
3. Click Create Application.
4. Enter an Application Name (e.g., LibreChat) and select Regular Web Application.
5. Click Create.

Step 2: Configure the SAML Add-On

1. Open the newly created application in Auth0.
2. Go to the Addons tab.
3. Click the slider to enable the SAML2 Web App.
4. Click SAML2 Web App panel.
5. Configure the following settings:
   • Application Callback URL: Set this to your LibreChat SAML callback URL: https://YOUR_DOMAIN/oauth/saml/callback
   • Settings (JSON Format): Use the following configuration:

     {
         "audience": "https://your-librechat-domain.com",
         "mappings": {
             "email": "email",
             "name": "username"
         }
     }

     Audience must match SAML_ISSUER

     Set audience to the same string you will use for SAML_ISSUER in Step 4. Leave it out and Auth0 asserts its own default audience, which will not match what LibreChat sends, and the login fails with an audience mismatch.

     note

     If your application requires additional attributes such as given_name, family_name, username or picture, ensure these mappings are properly configured in the Auth0 SAML settings.

6. Click Save.

Step 3: Obtain the Auth0 SAML Metadata

1. Once SAML is enabled, go back to the SAML2 Web App settings.
2. Go to the Usage tab.
3. Click on Identity Provider Certificate: Download Auth0 certificate.
4. Use the Identity Provider Login URL for SAML_ENTRY_POINT.
5. Use the Issuer for SAML_IDP_ISSUER (optional, see the callout below).
6. Copy the downloaded cert file to your project folder.

SAML_ISSUER=https://your-librechat-domain.com

Step 4: Configure LibreChat with SAML

Open the .env file in your project folder and add the following variables:

SAML_ENTRY_POINT=https://dev-xxxxx.us.auth0.com/samlp/aaaaaa

# Your own entity ID, sent to Auth0. Must match the Audience you set in Auth0.
SAML_ISSUER=https://your-librechat-domain.com
# Auth0's Issuer, used to verify incoming assertions (optional)
SAML_IDP_ISSUER=urn:dev-xxxxx.us.auth0.com

SAML_CERT=dev-xxxxx.pem
SAML_CALLBACK_URL=/oauth/saml/callback
SAML_SESSION_SECRET=[JustGenerateARandomSessionSecret]

# Attribute mappings (optional)
SAML_EMAIL_CLAIM=
SAML_USERNAME_CLAIM=
SAML_GIVEN_NAME_CLAIM=
SAML_FAMILY_NAME_CLAIM=
SAML_PICTURE_CLAIM=
SAML_NAME_CLAIM=

# Login button settings (optional)
SAML_BUTTON_LABEL=
SAML_IMAGE_URL=

# Whether the SAML Response should be signed.
# - If "true", the entire `SAML Response` will be signed.
# - If "false" or unset, only the `SAML Assertion` will be signed (default behavior).
# SAML_USE_AUTHN_RESPONSE_SIGNED=