Skip to main content
Prisme.ai provides robust support for enterprise authentication requirements, allowing you to integrate with your existing identity providers through industry-standard protocols. This guide covers the configuration options for Single Sign-On (SSO) integration using OIDC, SAML, and Microsoft Entra ID (formerly Azure AD).

​
Authentication Overview

Integrating your identity provider with Prisme.ai offers several benefits:

Centralized Identity Management

Manage access through your existing identity provider

Enhanced Security

Enforce your organization’s security policies and MFA requirements

Simplified User Experience

Provide one-click access without separate credentials

Automated Provisioning

Streamline user onboarding and offboarding

​
Supported Authentication Methods

Prisme.ai supports the following authentication protocols:
  • OIDC
  • SAML
  • Microsoft Entra ID
OpenID Connect is a modern authentication protocol built on top of OAuth 2.0.Compatible with:
  • Google Workspace
  • Okta
  • Auth0
  • Keycloak
  • Any standards-compliant OIDC provider

​
Configuring OIDC Authentication

1

Register an Application

Create an OAuth 2.0 client in your OIDC provider.Key configuration:
  1. Register a Web OAuth2 client/app
  2. Configure the authorized redirect URI: 
    https://API_URL/v2/login/callback
  3. Request the following scopes (minimum): 
    openid email
  4. Add profile scope if you need first name and last name
Note the following credentials:
  • Client ID
  • Client Secret
  • Auth URL (authorization_endpoint)
  • Token URL (token_endpoint)
  • Certificate URL (jwks_uri)
The JWKS URI might not be shown with client details as it is generally global to the IdP or tenant. This URL can return either a standard JWKS or an object mapping kids to PEM certificate strings.Currently, only the RS256 algorithm is supported.
2

Create Configuration File

Create an authProviders.config.yml file with your OIDC provider details.
providers:
  <ProviderName>:
    type: oidc
    config:
      client_id: "your client id"
      client_secret: "your client secret"
      authorization_endpoint: "idp authorization_endpoint"
      token_endpoint: "idp token_endpoint"
      jwks_uri: "idp public certificates endpoint"
      scopes: "openid email profile"
    attributesMapping:
      firstName: 'given_name'
      lastName: 'family_name'
      email: 'email'
Choose your <ProviderName> carefully, as this name will be used in front-end services and injected into user authData, making it potentially difficult to change later.
  • The scopes field is optional and defaults to openid email
  • The minimum required scopes are openid and email
  • Add profile scope to retrieve additional user attributes like name

​
Configuring SAML Authentication

1

Register Service Provider

Register Prisme.ai as a Service Provider (SP) in your Identity Provider.Key configuration:
  1. Configure the ACS Endpoint: 
    https://API_URL/v2/login/callback
  2. Set the SP EntityID : must match the audience configured below
  3. Set Name ID format to unspecified (all formats are supported)
Export the IdP metadata XML file containing the signing certificate and entity information.
2

Create Configuration File

Create an authProviders.config.yml file with your SAML provider details.
providers:
  <ProviderName>:
    type: saml
    config:
      idp_metadata_filepath: "/path/towards/idp-saml-metadata.xml"
      audience: "Service Provider entity id"  
      issuer: "Issuer entity id, can be set to audience value"  
    attributesMapping:
      firstName: 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname'
      lastName: 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname'
      email: 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'
Choose your <ProviderName> carefully, as this name will be used in front-end services and injected into user authData, making it potentially difficult to change later.
If no XML file is available, you can configure individual parameters:
providers:
  <ProviderName>:
    type: saml
    config:
      entryPoint: "https://idp.example.org/SAML2/SSO/Redirect"
      idpCert: "-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----"
      audience: "Service Provider entity id"
      issuer: "Service Provider entity id"
See node-saml documentation for complete configuration options.

​
Mount Configuration File

Whether you configured an OIDC or SAML provider, you can now mount the configuration file inside the prismeai-api-gateway container at /www/services/api-gateway/authProviders.config.yml.
You can customize the file location with the AUTH_PROVIDERS_CONFIG environment variable. For Kubernetes, store the configuration file in a configmap : 
apiVersion: v1
kind: ConfigMap
metadata:
  name: prismeai-api-gateway-authproviders
  namespace: core
data:
  authProviders.config.yml: |-
    providers:
      providerName:
        ...
Add the following volume and volumeMount to prismeai-api-gateway deployment : 
volumes:
  - name: gateway-authproviders
    configMap:
      name: prismeai-api-gateway-authproviders

volumeMounts:
  - name: gateway-authproviders
    mountPath: /www/services/api-gateway/authProviders.config.yml
    subPath: authProviders.config.yml

​
Configuring Microsoft Entra ID (Azure AD)

1

Register an Application

Register a new application in your Microsoft Entra ID tenant.
  1. Navigate to Azure Portal > App registrations
  2. Click New registration
  3. Name the application (e.g., “Prisme.ai”)
  4. Select the appropriate Supported account types:
    • Accounts in this organizational directory only
    • Accounts in any organizational directory
    • Accounts in any organizational directory and personal Microsoft accounts
    • Personal Microsoft accounts only
  5. Set the Redirect URI platform to Web with the value: 
    https://API_URL/v2/login/azure/callback
  6. Click Register
Note the Application (client) ID displayed on the overview page.
2

Generate a Client Secret

Create a secret for authentication.
  1. Navigate to Certificates & secrets in the left menu
  2. Click New client secret
  3. Add a description and select an expiry period
  4. Click Add
Immediately copy and store the client secret value, as it won’t be visible again.
3

Configure Environment Variables

Set the required environment variables in the prismeai-api-gateway service.
# Microsoft Entra ID Configuration
AZURE_AD_CLOUD_INSTANCE_ID=https://login.microsoftonline.com/
AZURE_AD_TENANT=YourCompany.onmicrosoft.com
AZURE_AD_APP_ID=your-application-id
AZURE_AD_CLIENT_SECRET=your-client-secret
For the AZURE_AD_TENANT value:
  • Use your tenant domain (e.g., YourCompany.onmicrosoft.com) for single-tenant apps
  • Use organizations for multi-tenant organizational accounts
  • Use common for both organizational and personal accounts
  • Use consumers for Microsoft accounts only
The AZURE_AD_TENANT value should match the Supported account types option you selected when registering the app.

​
Enable the Provider in UI

Configure the sign-in buttons by setting environment variables. For both prismeai-console and prismeai-pages microservices, add this environment variable : 
ENABLED_AUTH_PROVIDERS='[{"name": "local"}, {"name": "<ProviderName>", "label": "Sign in with Provider", "icon": "https://path/to/provider-icon.png"}]'
  • name must match the <ProviderName> in your config file
  • label is the text displayed on the sign-in button
  • icon is the URL to the provider’s logo image
  • Include {"name": "local"} to keep the username/password login option
For Azure AD, add a "extends":"azure" option : 
ENABLED_AUTH_PROVIDERS='[{"name":"local"},{"name":"custom","extends":"azure","label":{"fr":"Connexion avec Microsoft","en":"Sign in with Microsoft"},"icon":"https://path/to/microsoft-logo.png"}]'

​
Disable local signup

Disable local signup with the following environment variable in prismeai-console, prismeai-pages and prismeai-api-gateway : 
DISABLE_LOCAL_SIGNUP='true'

​
Configure products SSO access

Update workspaces to automatically grant access to certain products to SSO-authenticated users :
Whenever you change your PAGES_HOST environment variable, make sure to trigger a workspace update (e.g., by changing its description) to register the new redirect URI with your identity provider.

​
Custom Attribute Mapping

All authentication methods support mapping identity provider attributes to Prisme.ai user properties:
The attributesMapping section in your provider configuration maps provider-specific attributes to standard Prisme.ai fields.
providers:
  <ProviderName>:
    type: oidc  # or saml
    # ... other config ...
    attributesMapping:
      firstName: 'provider_first_name_field'
      lastName: 'provider_last_name_field'
      email: 'provider_email_field'
Only firstName, lastName, and email are supported as native fields.Common OIDC Mappings:
attributesMapping:
  firstName: 'given_name'
  lastName: 'family_name'
  email: 'email'
Common SAML Mappings:
attributesMapping:
  firstName: 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname'
  lastName: 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname'
  email: 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'
You can inspect available attributes by examining gateway.login.succeeded events or by reading the {{user}} variable from a test automation.

​
Troubleshooting

1. Redirect URI MismatchSymptom: Error message about redirect URI not matching during authenticationSolution:
  • Ensure the redirect URI in your IdP exactly matches https://API_URL/v2/login/callback for OIDC/SAML or https://API_URL/v2/login/azure/callback for Microsoft
  • Check for trailing slashes or HTTP vs HTTPS mismatches
2. JWKS Retrieval FailedSymptom: Authentication fails with JWKS errorsSolution:
  • Verify the jwks_uri endpoint is accessible from the Prisme.ai server
  • Check for correct formatting of the JWKS endpoint URL
  • Ensure the signing algorithm is RS256
3. SAML Response Validation FailedSymptom: SAML authentication fails after IdP redirectSolution:
  • Confirm the IdP certificate in the configuration is correct and not expired
  • Verify the IdP is sending responses via HTTP-POST binding
  • Check that the issuer value matches the EntityID expected by the IdP
  • Try adding skipRequestCompression: true and wantAuthnResponseSigned: false SAML options
4. Missing User AttributesSymptom: User logs in successfully but name fields are emptySolution:
  • Check that the attributesMapping configuration matches the actual attribute names provided by your IdP
  • For OIDC, ensure the profile scope is requested if you need name attributes
  • Examine the authentication events to see what claims are actually being received
Event LogsAuthentication issues can be diagnosed by examining events in the Activity view:
  • Look for gateway.login.started events to see authentication attempts
  • Check gateway.login.succeeded events to examine the received user claims
  • Investigate gateway.login.failed events for error details
Configuration TestingYou can validate your SSO configuration by:
  1. Creating a test user in your IdP
  2. Attempting authentication with detailed logs enabled
  3. Examining the request/response data in the Activity logs
Common Error Codes
  • invalid_request: Malformed authentication request
  • unauthorized_client: The client is not authorized for the requested authentication flow
  • access_denied: The resource owner denied the request
  • invalid_token: JWT validation failed
  • invalid_grant: The provided authorization grant is invalid

​
Security Considerations

Token Validation

  • Always validate JWT signatures using the IdP’s public keys
  • Verify token expiration and issuance times
  • Confirm the audience and issuer claims match your application

Secure Storage

  • Store client secrets securely using environment variables or secrets management
  • Never hardcode secrets in configuration files or source code
  • Rotate secrets periodically according to your security policy

TLS Encryption

  • Ensure all authentication traffic uses HTTPS
  • Configure proper TLS versions and cipher suites
  • Validate certificates in production environments

Access Controls

  • Implement proper RBAC after authentication
  • Don’t assume authenticated users should have access to all resources
  • Regularly audit user access and permissions
⌘I