Keycloak SAML
Use Keycloak as a SAML IdP for Hanzo IAM sign-in.
Keycloak is an open-source IdP that supports SAML and OpenID Connect and can broker LDAP or other SAML IdPs. This guide configures a Keycloak SAML client and Hanzo IAM so Keycloak users can sign in to Hanzo IAM.
Configure Keycloak
Example assumptions:
- Hanzo IAM: UI at
http://localhost:7001, API athttp://localhost:8000. Adjust for your deployment. - Keycloak: UI at
http://localhost:8080/auth. - SP ACS URL and Entity ID:
http://localhost:8000/api/acs.
:::note
The /api/acs endpoint only accepts POST requests. Ensure Keycloak is configured to use HTTP POST binding for SAML responses.
:::
Use the default realm or create a new one.
Add a client entry in Keycloak
:::info See Keycloak client SAML configuration. :::
Click Clients in the menu and then click Create to go to the Add Client page. Fill in the fields as follows:
- Client ID:
http://localhost:8000/api/acs- This will be the SP Entity ID used in the Hanzo IAM configuration later. - Client Protocol:
saml. - Client SAML Endpoint:
http://localhost:8000/api/acs- This URL is where you want the Keycloak server to send SAML requests and responses. Generally, applications have one URL for processing SAML requests. Multiple URLs can be set in the Settings tab of the client.
Click Save. This action creates the client and brings you to the Settings tab.
The following are part of the settings:
- Name — e.g.
Hanzo IAM; any friendly name for the Keycloak UI. - Enabled - Select
on. - Include Authn Statement - Select
on. - Sign Documents - Select
on. - Sign Assertions - Select
off. - Encrypt Assertions - Select
off. - Client Signature Required - Select
off. - Force Name ID Format - Select
on. - Name ID Format - Select
username. - Valid Redirect URIs - Add
http://localhost:8000/api/acs. - Master SAML Processing URL -
http://localhost:8000/api/acs. - Fine Grain SAML Endpoint Configuration
- Assertion Consumer Service POST Binding URL -
http://localhost:8000/api/acs. - Assertion Consumer Service Redirect Binding URL -
http://localhost:8000/api/acs.
- Assertion Consumer Service POST Binding URL -
Save the configuration.
:::tip
To sign the authn request: enable Client Signature Required and upload your certificate. Hanzo IAM’s private key and certificate (token_jwt_key.key, token_jwt_key.pem) are in the object directory. In Keycloak open Keys → Import → Archive Format → Certificate PEM and upload the certificate.
:::
Click Installation tab.
For Keycloak <= 5.0.0, select Format Option - SAML Metadata IDPSSODescriptor and copy the metadata.
For Keycloak 6.0.0+, select Format Option - Mod Auth Mellon files and click Download. Unzip the downloaded.zip, locate idp-metadata.xml, and copy the metadata.
Configure in Hanzo IAM
Create a new provider in Hanzo IAM.
Select category as SAML, type as Keycloak. Copy the content of metadata and paste it into the Metadata field. The values of Endpoint, IdP, and Issuer URL will be generated automatically after clicking the Parse button. Finally, click the Save button.
:::tip
If Client Signature Required is enabled in Keycloak and you uploaded a certificate, enable Sign request in Hanzo IAM.
:::
Edit the application you want to configure in Hanzo IAM. Select the provider you just added and click the Save button.
Test
Open the application’s login page; a Keycloak option appears. Click it to sign in via Keycloak; after success you are logged into Hanzo IAM.
How is this guide?
Last updated on