Debug SAML in development using a local keycloak server

Developing or debugging SAML functionality can be a hassle, especially when you need to go back and forth with someone external who is managing the identity provider (IDP).
But you can setup a local keycloak Show archive.org snapshot server to act as your IDP to play around with. This might seam intimidating, but is actually quite simple when using docker and turning off some verification steps.

1. Start a keycloak instance using docker

mkdir -p keycloak_data && docker run --network=host -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin --volume ./keycloak_data:/opt/keycloak/data/h2/ quay.io/keycloak/keycloak:24.0.2 start-dev
The database of the server is persistent and stored in keycloak_data. You can stop the container and restart it without loosing your configuration.
You can access the UI http://localhost:8080/admin/. The default login is admin/admin (from the docker command).

2. Download the IDP metadata and install it in your app

The metadata can be found here http://localhost:8080/realms/master/protocol/saml/descriptor or under Realm Settings -> General -> Endpoints.

3. Add your app as a client

• Go to Clients -> Create client
• Select SAML for the Client Type
• The Client id is the issuer from the devise SAML settings.
• For Valid redirect URLs you can put * or the real url from your app.
• You can disable client signing under Keys -> Signing keys config or place the keys into your app.

Now the basic auth flow should already work.
You can try and sign in through your app. There will likely be no keycloak login promt just a redirect, because you are already signed in as admin. But your app will likely require at least some SAML attributes to be present, so the login should still fail.

4. Adding SAML Attributes the the login response

Your app will require some Attributes to allow a login.

• Edit your admin user and give him a email, first and last name
• Create mappers for SAML attributes, go to Clients -> <your client> -> Client scopes -> Dedicated scope and mappers for this client:
  For example: To map user attributes go to Mappers -> Configure a new mapper -> User Attribute select a attribute of the user and make sure to fill in the SAML Attribute Name.
  For development the Hardcoded attribute might be all you need.