Create a SAML 2.0 app in Keycloak, paste the values from this setup, assign your users and share the identity provider metadata with us.
The values in braces, such as {acs_url}, are specific to your connection. The setup link from the application you are connecting shows them with a copy button. The same steps appear there.
-
Create a SAML app
Section titled “Create a SAML app”In the admin console of Keycloak, create a new SAML 2.0 application for this app. Keycloak may call it a custom app, a service provider or a relying party. Give it a name your users will recognize.
-
Enter the ACS URL
Section titled “Enter the ACS URL”Paste
{acs_url}into the assertion consumer service (ACS) URL field, which may be labelled single sign-on URL or reply URL. If the app also has recipient or destination fields, use the same value there.Paste into Keycloak:
- ACS URL:
{acs_url}
- ACS URL:
-
Enter the SP entity ID
Section titled “Enter the SP entity ID”Paste
{sp_entity_id}into the service provider entity ID field, which may be labelled audience, audience URI or identifier.Paste into Keycloak:
- SP entity ID:
{sp_entity_id}
Fixes:
saml_audience_mismatch - SP entity ID:
-
Send the email address as the name ID
Section titled “Send the email address as the name ID”Set the name ID format to email address and send each user’s email address as the name ID.
Fixes:
saml_nameid_missing -
Sign responses with SHA-256
Section titled “Sign responses with SHA-256”Make sure Keycloak signs the SAML response, the assertion or both, and uses SHA-256 (RSA-SHA256) as the signature algorithm.
Fixes:
saml_signature_missing,saml_signature_algorithm_weak -
Send the user attributes
Section titled “Send the user attributes”Add attributes named email with the email address, firstName with the first name and lastName with the last name. To send groups, add an attribute named groups with the user’s group names. Keycloak does not send groups unless you add this attribute.
Fixes:
saml_email_missing -
Assign people to the app
Section titled “Assign people to the app”Assign the people or groups who should sign in to this app with single sign-on.
Fixes:
saml_idp_status_error -
Share the identity provider metadata
Section titled “Share the identity provider metadata”Copy the app’s SAML metadata URL, which has the form “https://your-host/realms/your-realm/protocol/saml/descriptor”, and add it to this setup. If you can only download the file, upload it here instead and do this again whenever the signing certificate changes.
-
Test the connection
Section titled “Test the connection”Run a test sign-in in this setup, signing in as a user you assigned to the app.
Optional: add the standby ACS URL
Section titled “Optional: add the standby ACS URL”If our main network ever has an outage, sign-ins can continue through a standby address, but only if Keycloak accepts it. If the app’s SAML settings take more than one ACS URL, add {standby_acs_url} as a second one and confirm in this setup that you added it. If they take only one, skip this step.
Paste into Keycloak:
- Standby ACS URL:
{standby_acs_url}
This step is optional. See standby route behavior for what the standby address does during an outage.
Sources
Section titled “Sources”- Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0, read on 2026-10-29
- Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0, read on 2026-10-29