Custom Applications

Custom Applications allow you to extend Prism's single sign-on (SSO) capabilities to third-party services that support SAML 2.0. By configuring custom SAML applications, users can access external services using their Prism credentials without needing separate accounts.

Prerequisites

• The target application must support SAML 2.0 for SSO.

Overview

Prism acts as a SAML Identity Provider (IdP), and custom applications are configured as SAML Service Providers (SPs). When a user accesses a custom application, the application redirects the user to Prism for authentication. After successful authentication, Prism sends a SAML assertion back to the application, granting the user access.

Available Actions

Action	Description	Link
Add Application	Configure a new SAML application	Create SAML Application

How SAML SSO Works

1. A user navigates to the custom application.
2. The application detects that the user is not authenticated and redirects to Prism's SAML endpoint.
3. If the user is not already logged in to Prism, they are prompted to authenticate.
4. Prism generates a SAML assertion containing the user's identity and attributes.
5. The SAML assertion is sent to the application's Assertion Consumer Service (ACS) URL.
6. The application validates the assertion and grants the user access.

info

Custom application configurations in Prism are translated to internal SAML client configurations.

---

Create SAML Application

Configure a new SAML 2.0 application in Prism to enable single sign-on for a third-party service. This allows your users to access the application using their Prism credentials.

Prerequisites

• You must have administrator access to the target application to configure its SAML settings.
• You need the application's SAML metadata, including the Assertion Consumer Service (ACS) URL.

Step-by-Step Guide

Part 1: Gather Application Metadata

Before configuring the SAML application in Prism, collect the following information from the target application:

1. Log in to the target application's admin console.
2. Navigate to the SSO or SAML configuration section.
3. Note the following values:
   • ACS URL (Assertion Consumer Service URL) -- The URL where Prism sends the SAML assertion after authentication.
   • Single Logout URL (optional) -- The URL for SAML Single Logout.
4. Some applications also provide a SAML metadata XML file or URL that contains this information.

Part 2: Configure the Application in Prism

1. Navigate to Admin Portal > Custom Applications from the sidebar.
2. Click the Create Application button.
3. Fill in the application details:
   • Application Name -- Enter a descriptive name for the application.
   • Client ID -- Enter a unique identifier or URL for the application. This cannot be changed after creation.
   • Description (optional) -- Enter a description for the application.
   • Application Icon (optional) -- Upload an icon for the application (PNG, JPEG, SVG, or WebP; max 512KB).
   • Assertion Consumer Service URL -- Enter the application's ACS URL where Prism sends SAML responses.
   • Single Logout URL (optional) -- Enter the application's Single Logout URL.
   • IDP Initiated SSO Relay State (optional) -- URL to redirect users to after SAML authentication.
   • Name ID Format -- Select the Name ID format (e.g., Persistent).
4. Configure the toggle options as needed:
   • Enabled -- Enable or disable the application.
   • Sign Assertions -- Whether Prism signs SAML assertions.
   • Sign Response -- Whether Prism signs the SAML response.
   • Client Signature Required -- Whether the application must sign its requests.
5. Click Create to save the application.

Part 3: Configure the Target Application

After creating the SAML application in Prism, you need to configure the target application to trust Prism as its Identity Provider:

1. From the Prism application configuration page, download or copy the following:
   • IdP Metadata -- The SAML metadata for Prism's Identity Provider.
   • Certificate -- The X.509 signing certificate used by Prism to sign SAML assertions.
   • SSO URL -- The Prism SAML endpoint URL.
2. Enter these values in the target application's SAML configuration.
3. Save the configuration in the target application.

Field Reference

Field	Type	Required	Description
Application Name	Text	Yes	A descriptive name for the application in Prism (e.g., "Jira", "Confluence", "Slack").
Client ID	Text	Yes	A unique identifier or URL for the application. Cannot be changed after creation.
Description	Text	No	A description of the application's purpose.
Application Icon	Image	No	An icon for the application. Accepts PNG, JPEG, SVG, or WebP (max 512KB).
Assertion Consumer Service URL	URL	Yes	The ACS URL where Prism sends SAML responses after authentication.
Single Logout URL	URL	No	The application's Single Logout endpoint for SAML logout.
IDP Initiated SSO Relay State	URL	No	URL to redirect users to after SAML authentication. Used for IdP-initiated SSO flows.
Name ID Format	Select	Yes	The format of the Name ID in SAML assertions (e.g., Persistent, Email, Transient).
Enabled	Toggle	Yes	Whether the application is active. Defaults to enabled.
Sign Assertions	Toggle	Yes	Whether Prism signs individual SAML assertions. Defaults to enabled.
Sign Response	Toggle	Yes	Whether Prism signs the overall SAML response. Defaults to enabled.
Client Signature Required	Toggle	Yes	Whether the application must sign its SAML requests. Defaults to disabled.

warning

The Assertion Consumer Service URL must be an HTTPS URL. SAML assertions contain sensitive authentication data and must be transmitted securely.

What Happens Next

After creating a SAML application:

1. The application appears in the Custom Applications list.
2. Prism provides its IdP metadata, certificate, and SSO URL for you to configure in the target application.
3. Once both sides are configured, users can access the target application using their Prism credentials.
4. Users will see the application as an available SSO option.

Troubleshooting

Issue	Solution
SAML assertion validation fails	Verify that the certificate configured in the target application matches the one provided by Prism.
ACS URL mismatch	Ensure the ACS URL in Prism exactly matches what the target application expects.
Entity ID mismatch	Verify the Entity ID matches between Prism and the target application configuration.
User attributes not mapped	Check that the SAML attribute mapping in the target application matches the attributes sent by Prism (e.g., email, name).

tip

Start by testing with a single user before rolling out to the entire organization. This allows you to verify the SAML configuration without impacting all users.