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).
Integrating your identity provider with Prisme.ai offers several benefits:
Manage access through your existing identity provider
Enforce your organization’s security policies and MFA requirements
Provide one-click access without separate credentials
Streamline user onboarding and offboarding
Prisme.ai supports the following authentication protocols:
OpenID Connect is a modern authentication protocol built on top of OAuth 2.0.
Compatible with:
OpenID Connect is a modern authentication protocol built on top of OAuth 2.0.
Compatible with:
Security Assertion Markup Language is an XML-based authentication protocol.
Compatible with:
Current limitations:
Microsoft Entra ID (formerly Azure AD) provides specialized integration for Microsoft environments.
Compatible with:
Register an Application
Create an OAuth 2.0 client in your OIDC provider.
Key configuration:
profile
scope if you need first name and last nameNote the following credentials:
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.
scopes
field is optional and defaults to openid email
openid
and email
profile
scope to retrieve additional user attributes like nameRegister Service Provider
Register Prisme.ai as a Service Provider (SP) in your Identity Provider.
Key configuration:
audience
configured belowunspecified
(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.
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 :
Register an Application
Register a new application in your Microsoft Entra ID tenant.
Note the Application (client) ID displayed on the overview page.
Generate a Client Secret
Create a secret for authentication.
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:
YourCompany.onmicrosoft.com
) for single-tenant appsorganizations
for multi-tenant organizational accountscommon
for both organizational and personal accountsconsumers
for Microsoft accounts onlyThe AZURE_AD_TENANT
value should match the Supported account types option you selected when registering the app.
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{"name": "local"}
to keep the username/password login optionFor Azure AD, add a "extends":"azure"
option :
Disable local signup with the following environment variable in prismeai-console, prismeai-pages and prismeai-api-gateway :
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.
All authentication methods support mapping identity provider attributes to Prisme.ai user properties:
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.
Common Issues and Solutions
1. Redirect URI Mismatch
Symptom: Error message about redirect URI not matching during authentication
Solution:
https://API_URL/v2/login/callback
for OIDC/SAML or https://API_URL/v2/login/azure/callback
for Microsoft2. JWKS Retrieval Failed
Symptom: Authentication fails with JWKS errors
Solution:
jwks_uri
endpoint is accessible from the Prisme.ai server3. SAML Response Validation Failed
Symptom: SAML authentication fails after IdP redirect
Solution:
issuer
value matches the EntityID expected by the IdPskipRequestCompression: true
and wantAuthnResponseSigned: false
SAML options4. Missing User Attributes
Symptom: User logs in successfully but name fields are empty
Solution:
attributesMapping
configuration matches the actual attribute names provided by your IdPprofile
scope is requested if you need name attributesDiagnostic Tools
Event Logs
Authentication issues can be diagnosed by examining events in the Activity view:
gateway.login.started
events to see authentication attemptsgateway.login.succeeded
events to examine the received user claimsgateway.login.failed
events for error detailsConfiguration Testing
You can validate your SSO configuration by:
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 invalidConfigure 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).
Integrating your identity provider with Prisme.ai offers several benefits:
Manage access through your existing identity provider
Enforce your organization’s security policies and MFA requirements
Provide one-click access without separate credentials
Streamline user onboarding and offboarding
Prisme.ai supports the following authentication protocols:
OpenID Connect is a modern authentication protocol built on top of OAuth 2.0.
Compatible with:
OpenID Connect is a modern authentication protocol built on top of OAuth 2.0.
Compatible with:
Security Assertion Markup Language is an XML-based authentication protocol.
Compatible with:
Current limitations:
Microsoft Entra ID (formerly Azure AD) provides specialized integration for Microsoft environments.
Compatible with:
Register an Application
Create an OAuth 2.0 client in your OIDC provider.
Key configuration:
profile
scope if you need first name and last nameNote the following credentials:
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.
scopes
field is optional and defaults to openid email
openid
and email
profile
scope to retrieve additional user attributes like nameRegister Service Provider
Register Prisme.ai as a Service Provider (SP) in your Identity Provider.
Key configuration:
audience
configured belowunspecified
(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.
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 :
Register an Application
Register a new application in your Microsoft Entra ID tenant.
Note the Application (client) ID displayed on the overview page.
Generate a Client Secret
Create a secret for authentication.
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:
YourCompany.onmicrosoft.com
) for single-tenant appsorganizations
for multi-tenant organizational accountscommon
for both organizational and personal accountsconsumers
for Microsoft accounts onlyThe AZURE_AD_TENANT
value should match the Supported account types option you selected when registering the app.
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{"name": "local"}
to keep the username/password login optionFor Azure AD, add a "extends":"azure"
option :
Disable local signup with the following environment variable in prismeai-console, prismeai-pages and prismeai-api-gateway :
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.
All authentication methods support mapping identity provider attributes to Prisme.ai user properties:
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.
Common Issues and Solutions
1. Redirect URI Mismatch
Symptom: Error message about redirect URI not matching during authentication
Solution:
https://API_URL/v2/login/callback
for OIDC/SAML or https://API_URL/v2/login/azure/callback
for Microsoft2. JWKS Retrieval Failed
Symptom: Authentication fails with JWKS errors
Solution:
jwks_uri
endpoint is accessible from the Prisme.ai server3. SAML Response Validation Failed
Symptom: SAML authentication fails after IdP redirect
Solution:
issuer
value matches the EntityID expected by the IdPskipRequestCompression: true
and wantAuthnResponseSigned: false
SAML options4. Missing User Attributes
Symptom: User logs in successfully but name fields are empty
Solution:
attributesMapping
configuration matches the actual attribute names provided by your IdPprofile
scope is requested if you need name attributesDiagnostic Tools
Event Logs
Authentication issues can be diagnosed by examining events in the Activity view:
gateway.login.started
events to see authentication attemptsgateway.login.succeeded
events to examine the received user claimsgateway.login.failed
events for error detailsConfiguration Testing
You can validate your SSO configuration by:
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