Ana içeriğe geç

Add Keycloak as a SAML provider

This guide explains how to let the users of a Keycloak realm sign in to Casdoor through SAML. Keycloak is an open-source IdP that supports SAML and OpenID Connect and can broker LDAP and other identity providers.

Learning outcomes​

  • Create a SAML client for Casdoor in Keycloak.
  • Add Keycloak as a SAML provider in Casdoor.
  • Sign the authentication request, if Keycloak requires it.

What you need​

  • Administrator access to a Keycloak server
  • Administrator access to the Casdoor admin console

The examples assume the following addresses. Adjust them for your deployment.

ComponentAddress
Casdoor UIhttp://localhost:7001
Casdoor APIhttp://localhost:8000
Keycloakhttp://localhost:8080/auth
SP ACS URL and entity IDhttp://localhost:8000/api/acs

Prepare a realm​

Use the default realm or create one.

Add realm in Keycloak

Realm settings in Keycloak

Create a SAML client in Keycloak​

For all client settings, see SAML clients in the Keycloak documentation.

  1. Go to Clients and click Create. Fill in the Add Client page:

    FieldValue
    Client IDhttp://localhost:8000/api/acs. This is the SP entity ID of Casdoor
    Client Protocolsaml
    Client SAML Endpointhttp://localhost:8000/api/acs, where Keycloak sends SAML requests and responses

    Add Client page

  2. Click Save. The Settings tab opens.

  3. Set the following values and save:

    SettingValue
    NameA friendly name, such as Casdoor
    EnabledOn
    Include Authn StatementOn
    Sign DocumentsOn
    Sign AssertionsOff
    Encrypt AssertionsOff
    Client Signature RequiredOff. See Sign the authentication request
    Force Name ID FormatOn
    Name ID Formatusername
    Valid Redirect URIshttp://localhost:8000/api/acs
    Master SAML Processing URLhttp://localhost:8000/api/acs
    Assertion Consumer Service POST Binding URLhttp://localhost:8000/api/acs, under Fine Grain SAML Endpoint Configuration
    Assertion Consumer Service Redirect Binding URLhttp://localhost:8000/api/acs

    Settings of the client

    The /api/acs endpoint accepts only POST requests, so Keycloak must send the response with the POST binding.

  4. Go to the Installation tab and get the metadata:

    • In Keycloak 5.0.0 and earlier, select the format SAML Metadata IDPSSODescriptor and copy the metadata.
    • In Keycloak 6.0.0 and later, select Mod Auth Mellon files, click Download, unzip the file, and copy the content of idp-metadata.xml.

    Installation tab

    Metadata of the client

Add the provider in Casdoor​

  1. In the Casdoor admin console, go to Identity > Providers and add a provider.

  2. Set Category to SAML and Type to Keycloak.

  3. Paste the metadata into Metadata and click Parse. Casdoor fills in Endpoint, IdP, and Issuer URL.

    Keycloak provider in Casdoor

  4. Save the provider.

  5. Open the edit page of your application, add the provider on the Providers tab, and save.

    Keycloak provider in the application

Sign the authentication request​

To make Keycloak verify the requests of Casdoor:

  1. In Keycloak, turn on Client Signature Required for the client.
  2. Go to Keys > Import, select the archive format Certificate PEM, and upload the certificate of Casdoor. The private key and the certificate of Casdoor are token_jwt_key.key and token_jwt_key.pem in the object directory of the Casdoor source.
  3. In Casdoor, turn on Sign request on the provider.

Verify the result​

Open the sign-in page of the application and click the Keycloak button. After you sign in at Keycloak, you are signed in to Casdoor.

Recording of the sign-in through Keycloak

See also​