Custom Applications

Custom Applications extend Prism's single sign-on (SSO) to third-party and in-house services. Register an application once, and your users sign in to it with their Prism credentials instead of a separate account.

Prism supports two protocols:

Protocol	Prism's role	Guide
OIDC (OpenID Connect)	OpenID Provider: the application redirects users to Prism and receives ID and access tokens	OIDC Applications
SAML 2.0	Identity Provider (IdP): the application redirects users to Prism and receives a signed SAML assertion	SAML 2.0 Applications

Prerequisites

• The target application must support OIDC or SAML 2.0 for SSO.
• For OIDC, the application must return users to an https:// address. Mobile and native desktop applications, which return to a private-use scheme such as com.example.app:/oauth2redirect or to an http:// loopback address, cannot be registered. See OIDC Applications.
• You must have administrator access to the target application in order to configure its SSO settings.

Overview

Navigate to Admin Portal > Custom Applications from the sidebar. The page lists every application registered for your organization, and is where you add a new one.

Registering an application is always a two-sided exercise. You give Prism the values it needs to trust the application (where to send the user back to, and where the application lives), and Prism gives you the values the application needs to trust Prism. Neither side works until both have been filled in.

Choosing a Protocol

Use OIDC for anything new. It is what modern application frameworks and single-page applications are built around, and virtually every current authentication library speaks it. Configuration is a single discovery URL rather than a metadata document and a certificate.

Use SAML 2.0 when the application only supports SAML, or when you already have SAML metadata for it and no reason to change. This is common with older enterprise software.

	OIDC	SAML 2.0
Best for	New applications, SPAs, modern libraries	Applications that only support SAML, or where you already have SAML metadata
Configuration handed to the application	A discovery URL, a client ID, and (for confidential clients) a client secret	Metadata XML, a signing certificate, and an SSO URL
Credential to rotate	Client secret	Signing certificate
IdP-initiated SSO	Not supported	Supported

The one real functional difference

SAML supports IdP-initiated SSO; OIDC does not. With SAML, Prism can construct a sign-in and post it to the application unprompted. OIDC has no equivalent: an OIDC login must begin at the application.

In practice this changes very little for your users. For an OIDC application the portal tile deep-links to the application's Home URL; the application then starts its own login, which comes straight back to Prism. Because the user already has a Prism session, they are not asked for credentials again and land in the application without an extra prompt.

It matters only if you have a system that needs to hand a user into the application from outside the application itself. If you do, use SAML for that integration.

Prism Authenticates, Your Application Authorizes

This is the single most important thing to understand before you register an application, and it applies equally to OIDC and SAML.

Assigning users or groups to an application in Prism does not control who can log in to it. An assignment controls two things:

• whether the application's tile appears on that user's portal page, and
• the role claims Prism puts into the tokens or assertion it issues for that user.

It does not gate authentication. Any user in your organization's realm who knows the application's URL can complete a sign-in against it, whether or not they have been assigned to it.

The responsibility is split:

	Responsibility
Prism	Authentication: proving the user is who they say they are, and telling your application who they are and what roles they hold
Your application	Authorization: deciding what that user is allowed to see and do, and rejecting users who should have no access at all

Your application must therefore make its own access decision on every request. Prism gives it the input to do so: for OIDC, the roles you assign appear in resource_access.{clientId}.roles in the access token; for SAML, they arrive as role attributes in the assertion. Read that claim and enforce it. An application that treats "the user authenticated successfully" as "the user is authorized" is open to everyone in your organization.

caution

Never treat a Prism assignment as an access control. If an application must be restricted to a subset of your users, that restriction has to be implemented inside the application, driven by the roles Prism sends.

Where to Go Next

OIDC Applications

Register an OIDC client: redirect URIs, public versus confidential clients, the connection details Prism returns, logout behaviour, and client secret handling.

SAML 2.0 Applications

Register a SAML 2.0 application: ACS URL, signing options, the IdP metadata and certificate to copy into the application.