Authentication & SSO Integration
Configure secure enterprise authentication for Prisme.ai with SSO options including OIDC, SAML, and Microsoft Entra ID
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:
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
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
Security Assertion Markup Language is an XML-based authentication protocol.
Compatible with:
- ADFS
- Okta
- OneLogin
- PingIdentity
- Any standards-compliant SAML 2.0 provider
Current limitations:
- Only supports HTTP-POST binding for receiving authentication assertions
- No support for IdP-initiated login
Microsoft Entra ID (formerly Azure AD) provides specialized integration for Microsoft environments.
Compatible with:
- Microsoft Entra ID
- Azure Active Directory
- Microsoft 365 tenants
Configuring OIDC Authentication
Register an Application
Create an OAuth 2.0 client in your OIDC provider.
Key configuration:
- Register a Web OAuth2 client/app
- Configure the authorized redirect URI:
- Request the following scopes (minimum):
- 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 kid
s to PEM certificate strings.
Currently, only the RS256 algorithm is supported.
Create Configuration File
Create an authProviders.config.yml
file with your OIDC provider details.
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 toopenid email
- The minimum required scopes are
openid
andemail
- Add
profile
scope to retrieve additional user attributes like name
Configuring SAML Authentication
Register Service Provider
Register Prisme.ai as a Service Provider (SP) in your Identity Provider.
Key configuration:
- Configure the ACS Endpoint:
- Set the SP EntityID : must match the
audience
configured below - Set Name ID format to
unspecified
(all formats are supported)
Export the IdP metadata XML file containing the signing certificate and entity information.
Create Configuration File
Create an authProviders.config.yml
file with your SAML provider details.
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:
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 :
Add the following volume
and volumeMount
to prismeai-api-gateway
deployment :
Configuring Microsoft Entra ID (Azure AD)
Register an Application
Register a new application in your Microsoft Entra ID tenant.
- Navigate to Azure Portal > App registrations
- Click New registration
- Name the application (e.g., “Prisme.ai”)
- 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
- Set the Redirect URI platform to Web with the value:
- Click Register
Note the Application (client) ID displayed on the overview page.
Generate a Client Secret
Create a secret for authentication.
- Navigate to Certificates & secrets in the left menu
- Click New client secret
- Add a description and select an expiry period
- Click Add
Immediately copy and store the client secret value, as it won’t be visible again.
Configure Environment Variables
Set the required environment variables in the prismeai-api-gateway
service.
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 :
name
must match the<ProviderName>
in your config filelabel
is the text displayed on the sign-in buttonicon
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 :
Disable local signup
Disable local signup with the following environment variable in prismeai-console, prismeai-pages and prismeai-api-gateway :
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:
Attribute Mapping Configuration
Attribute Mapping Configuration
The attributesMapping
section in your provider configuration maps provider-specific attributes to standard Prisme.ai fields.
Only firstName
, lastName
, and email
are supported as native fields.
Common OIDC Mappings:
Common SAML Mappings:
You can inspect available attributes by examining gateway.login.succeeded
events or by reading the {{user}}
variable from a test automation.
Troubleshooting
Common Issues and Solutions
Common Issues and Solutions
1. Redirect URI Mismatch
Symptom: Error message about redirect URI not matching during authentication
Solution:
- Ensure the redirect URI in your IdP exactly matches
https://API_URL/v2/login/callback
for OIDC/SAML orhttps://API_URL/v2/login/azure/callback
for Microsoft - Check for trailing slashes or HTTP vs HTTPS mismatches
2. JWKS Retrieval Failed
Symptom: Authentication fails with JWKS errors
Solution:
- 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 Failed
Symptom: SAML authentication fails after IdP redirect
Solution:
- 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
andwantAuthnResponseSigned: false
SAML options
4. Missing User Attributes
Symptom: User logs in successfully but name fields are empty
Solution:
- 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
Diagnostic Tools
Diagnostic Tools
Event Logs
Authentication 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 Testing
You can validate your SSO configuration by:
- Creating a test user in your IdP
- Attempting authentication with detailed logs enabled
- Examining the request/response data in the Activity logs
Common Error Codes
invalid_request
: Malformed authentication requestunauthorized_client
: The client is not authorized for the requested authentication flowaccess_denied
: The resource owner denied the requestinvalid_token
: JWT validation failedinvalid_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