Using Skycloak as a SAML Identity Provider

This guide covers how to use your Skycloak cluster as a SAML 2.0 Identity Provider (IdP) for external services. Keycloak is a fully compliant SAML 2.0 IdP out of the box, which means you can use your Skycloak cluster to authenticate users into services like GitHub Enterprise, AWS Console, Atlassian Cloud, Salesforce, and any other application that supports SAML-based single sign-on.

This is the reverse of connecting an external IdP to Keycloak. Instead of users signing in through an external provider, your Skycloak cluster becomes the authoritative source of identity for external services.

Prerequisites

• An active Skycloak cluster
• A realm with users configured (or federated from an external directory)
• Access to the Keycloak Admin Console for your cluster
• Admin access to the external service you want to connect

Understanding Realms

Finding Your SAML Metadata

Every realm in Keycloak publishes a SAML metadata descriptor. This XML document contains everything an external service needs to configure your Skycloak cluster as its identity provider.

The metadata URL follows this pattern:

https://{your-cluster-url}/realms/{your-realm}/protocol/saml/descriptor

For example, if your cluster URL is auth.example.skycloak.io and your realm is mycompany, the metadata URL would be:

https://auth.example.skycloak.io/realms/mycompany/protocol/saml/descriptor

Open this URL in a browser to view the XML. The key pieces of information that external services typically require are:

Some services allow you to paste the entire metadata URL instead of extracting individual values. Use that option when available – it simplifies setup and keeps the configuration in sync if certificates rotate.

Creating a SAML Client in Keycloak

Each external service that authenticates against your Skycloak cluster needs to be registered as a SAML client in the Keycloak Admin Console.

1. Open the Admin Console for your Skycloak cluster
2. Select the realm you want to use for this integration
3. Navigate to Clients in the left sidebar and click Create client
4. Set Client type to SAML
5. Set the Client ID to the Entity ID (also called Issuer or Identifier) that the external service provides. This value must match exactly what the service sends in its SAML authentication requests
6. Click Next and then Save

After creation, configure the client settings:

• Valid Redirect URIs: Set this to the Assertion Consumer Service (ACS) URL provided by the external service. This is where Keycloak sends the SAML response after authentication
• Name ID Format: Choose the format the external service expects. Common options:
  • persistent – a stable, opaque identifier for the user (recommended for most services)
  • email – the user’s email address (required by some services like GitHub Enterprise)
  • unspecified – lets the service decide
• Sign Assertions: Enabled by default. Most services require signed assertions
• Force POST Binding: Enable this if the external service expects SAML responses via HTTP POST (most do)

Review the Keys tab to verify that the signing key is configured. Keycloak generates a signing key pair automatically when the realm is created.

Example: GitHub Enterprise

GitHub Enterprise (Cloud and Server) supports SAML single sign-on at both the enterprise and organization level. Here is how to configure it with your Skycloak cluster.

Step 1: Gather GitHub’s SAML details

For enterprise-level SAML:

• Entity ID: https://github.com/enterprises/{your-enterprise}
• ACS URL: https://github.com/enterprises/{your-enterprise}/saml/consume

For organization-level SAML:

• Entity ID: https://github.com/orgs/{your-org}
• ACS URL: https://github.com/orgs/{your-org}/saml/consume

Step 2: Create the SAML client in Keycloak

1. Open the Keycloak Admin Console for your cluster
2. Go to Clients > Create client
3. Set Client type to SAML
4. Set Client ID to the GitHub Entity ID from Step 1 (e.g., https://github.com/enterprises/{your-enterprise})
5. Save, then set Valid Redirect URIs to the ACS URL from Step 1
6. Set Name ID Format to persistent

Step 3: Configure GitHub

1. In GitHub, go to your enterprise or organization Settings > Authentication security (or Security > SAML single sign-on for organizations)
2. Enter the following values from your Skycloak SAML metadata:
   • Sign-on URL: The SingleSignOnService URL with HTTP-POST binding
   • Issuer: The entityID from the metadata descriptor
   • Public certificate: The X509Certificate value from the metadata (paste the raw base64 content, without PEM headers)
   • Digest method: SHA-256
   • Signature method: RSA-SHA256
3. Click Test SAML configuration to verify the setup
4. Once the test succeeds, enable SAML SSO

Step 4: Add attribute mappers (optional)

GitHub can use SAML attributes for display name and email. In the Keycloak Admin Console:

1. Go to your GitHub SAML client > Client scopes > Dedicated scope
2. Add mappers for:
   • email – maps the user’s email
   • name – maps the user’s display name
   • groups – maps group memberships (if you want to sync teams)

Example: AWS IAM Identity Center (SSO)

AWS IAM Identity Center (formerly AWS SSO) supports external SAML 2.0 identity providers. The setup follows a similar pattern:

1. In the AWS IAM Identity Center console, go to Settings > Identity source > Change identity source > External identity provider
2. AWS provides its own ACS URL and Issuer URL – use these as the Client ID and Valid Redirect URI when creating the SAML client in Keycloak
3. Download or copy your Skycloak SAML metadata and upload it to AWS
4. AWS requires specific SAML attributes for user provisioning. Add these mappers to the SAML client in Keycloak:
   • Subject (NameID) – typically mapped to email
   • https://aws.amazon.com/SAML/Attributes/RoleSessionName – usually the user’s email
   • https://aws.amazon.com/SAML/Attributes/SessionDuration – session length in seconds (optional)

Refer to the AWS documentation on external identity providers for the full list of required attributes.

Troubleshooting

Certificate mismatch

If the external service rejects the SAML response with a signature validation error, the signing certificate may have changed. Re-export the certificate from the Keycloak SAML metadata descriptor and update it in the external service’s configuration.

Wrong NameID format

Some services are strict about NameID format. If authentication fails with a NameID-related error, verify that the Name ID Format in the Keycloak SAML client matches what the external service expects. GitHub requires persistent, while some services expect email or unspecified.

Clock skew

SAML assertions include timestamp conditions (NotBefore and NotOnOrAfter). If the clocks on your Skycloak cluster and the external service are out of sync by more than a few minutes, authentication will fail. Skycloak clusters use NTP for time synchronization, so this issue typically occurs on the external service side.

Redirect URI mismatch

If Keycloak returns an “Invalid redirect URI” error after authentication, the ACS URL configured in the SAML client does not match the URL the external service is sending. Double-check the Valid Redirect URIs field in the Keycloak client settings. The value must match exactly, including the protocol (https://) and any trailing slashes.

Missing attributes in the assertion

If the external service authenticates users but is missing profile information (name, email, groups), you need to add SAML protocol mappers to the client. Go to the SAML client in Keycloak > Client scopes > Dedicated scope and add the appropriate attribute mappers.

Related Guides

• Enterprise SSO Setup – Connecting external identity providers to Keycloak (the reverse direction)
• Identity Providers – Feature overview of identity provider integrations
• Cluster Management – Managing your Skycloak clusters and accessing the Admin Console