Configure a SAML identity provider (IdP)

This guide provides detailed step-by-step instructions on how to configure a SAML-based identity provider, including how SAML metadata is imported and what each configuration option means.

Prerequisites

Administrator access to Single Sign On (SSO) configuration.
A SAML Identity Provider.
Admin credentials for the IdP (for testing).

Configure a SAML identity provider

To configure a SAML identity provider, follow these steps:

In the SSO Configuration screen, select + Provider and select SAML v2.0.
In the Configuring SAML Provider screen:
- Unique name: A unique name for your SAML provider (only letters, numbers, dashes, and underscores are allowed).
- Display name: The name that will be displayed to users during login (for example, ACME Systems).
- Display order: Controls the login display order if using more than one IDP.
Complete all fields manually:
- Service provider entity ID: The service provider ID expected by the IdP. This is a unique identifier for either the IdP or SP (Keycloak) and it’s used by SAML to identify the source and destination of messages. For example, https://idp.example.com/saml
- Identity Provider Entity ID: The globally unique identifier for your SAML identity provider. This value is typically provided in your identity provider’s metadata and uniquely identifies your organization’s SAML service. You can usually find this in your identity provider’s configuration or metadata document.
- NameID policy format: The format of the NameID element that identifies the user. Select Unspecified from the dropdown menu to set the NameID format used in SAML assertions. The Unspecified format allows your identity provider to determine the most appropriate format for user identification, providing flexibility when you don’t need to enforce a specific naming convention.
- Single Sign-On Service URL: The endpoint where authentication requests are sent. It allows Keycloak to redirect users to the IdP to authenticate. For example, https://idp.example.com/saml/sso
- Single Logout Service URL (optional): The endpoint to send logout requests and responses to (if supported by the IdP). It supports federated logout by notifying the IdP. For example, https://idp.example.com/saml/logout
- Send ‘client_id’ in logout requests: Under Show advanced settings, select this option to include the client_id parameter in logout requests. This enables your identity provider to identify which application is requesting the logout, ensuring proper session termination across all connected services.
- Principal type:: Determines where in the SAML assertion Keycloak extracts the user identity (Subject or Attribute). This controls how user login names are derived. The options are as follows:
  - Subject: Uses the Subject element in the assertion for the username.
  - Attribute: Uses a specific SAML attribute (defined in Attribute Mappings) to derive the username.
- Validating X509 certificate: Paste the IdP’s public signing certificate
- Attribute Mappings: Map the user attribute Email by configuring the attribute name and format according to your identity provider’s requirements. This mapping correctly transmits user email addresses from your identity provider to the Chef 360 Platform during authentication.
Configure the additional fields as needed.
Select Save to finalize.

After you complete the SAML configuration, existing users can sign in to the platform using their SAML credentials. You can also invite new users to access the platform through SAML SSO authentication.

Configuration options explained

General settings

Unique name: Internal reference name
Display name: Friendly name in the login User Interface (UI)
Enabled: Enable/disable this IdP

SAML-specific fields

For further details, refer to SAML documentation as needed.

Single Sign-On Service URL: The endpoint where authentication requests are sent. It allows Keycloak to redirect users to the IdP to authenticate. For example, https://idp.example.com/saml/sso
Single Logout Service URL: The endpoint to send logout requests and responses to (if supported by the IdP). It supports federated logout by notifying the IdP. For example, https://idp.example.com/saml/logout
Service provider entity ID: The service provider ID expected by the IdP. This is a unique identifier for either the IdP or SP (Keycloak) and it’s used by SAML to identify the source and destination of messages. For example, https://idp.example.com/saml
NameID policy format: Format of the user identifier (for example, Email address or Persistent)
Principal type: Determines where in the SAML assertion Keycloak extracts the user identity (Subject or Attribute). This controls how user login names are derived. The options are as follows:
- Subject: Uses the Subject element in the assertion for the username.
- Attribute: Uses a specific SAML attribute (defined in Attribute Mappings) to derive the username.
Principal name: The attribute name

Signature and encryption

Require signed authentication requests: Require signed AuthnRequests from Keycloak. This allows the IdP to verify that the request is from a trusted source.
Require signed assertions: Require signed SAML assertions from the IdP. This prevents tampering with the user identity data and validates incoming assertions.
Require encrypted assertions: Requires user data in the SAML assertion to be encrypted (this is optional and advanced). This adds an additional layer of confidentiality for sensitive user data.
Validating X509 certificates: Public certificate used to verify SAML assertion signatures. This ensures the authenticity and integrity of the SAML response. For example, a PEM-formatted certificate block.

Advanced settings

Backchannel logout: Allows the IdP to notify Keycloak of logout

Additional notes

SAML doesn’t support dynamic discovery (unlike OIDC).
Always verify that the NameID format and attribute mappings match your IdP configuration.
Some IdPs require Keycloak’s metadata (available from the IdP config page after saving).