How to authenticate to Consul with Keycloak as IdP using OIDC

$ curl -LO https://github.com/keycloak/keycloak/releases/download/22.0.1/keycloak-22.0.1.tar.gz
$ tar -xzvf keycloak-22.0.1.tar.gz
$ cd keycloak-22.0.1

 

• Start Keycloak 

Start keycloak in dev mode. We will pass the credentials as environment variables for easy set up.

KEYCLOAK_ADMIN=admin KEYCLOAK_ADMIN_PASSWORD=admin ./bin/kc.sh start-dev

 

• Log in to the Keycloak:

Login using Username: admin and Password: admin (credentials set using environment variables in previous step). In this example, the keycloak instance is on a VM with IP 192.168.64.3 on Port 8080.

 

• Create a new Realm.

 

 

• Create a Client:

1. Ensure the redirect URIs match the AllowedRedirectURIs we will configure in the ODIC auth-method config later for Consul.

2. The Client ID in this step will be used for OIDCClientID and BoundAudiences in the OIDC auth-method config.

 

 

• Create Users and Groups:

1. Create a group, say engineering.

 

  2. Set Email verified to Yes so that Keycloak doesn’t force us to validate email on the first login

 

  3. Uncheck Temporary option for password so that Keycloak doesn’t force us to change the password on the first login

 

 

• Create Group Membership Claim mappers.

This step is very important. Not configuring this would result in login failing as the Group Membership won’t be returned to Consul while doing the authentication.

1. Click on the Client dedicated scope to create a mapper.

 

  2. Click on Configure new mapper:

 

  3. Uncheck the Full group path to avoid the groups from having / at the beginning

 

  4. Search one of the users, and use the Evaluate tab to verify the Claim Mappings sent to the clients.

 

Now, We are finished with configuring Keycloak, and now proceed to configure Consul in below steps.

 

 

Configuring Consul:

 

1. In this example, we are going to run a Consul dev agent, with default bootstrap token as root for demo purposes:

consul agent -dev -hcl \
'acl { enabled = true default_policy = "deny" tokens { master = "root" agent = "root" }}'

 

  2. Configure the ACL Roles and Policies. You can refer to the official documentation for a detailed explanation of what these are.

CONSUL_HTTP_TOKEN=root \
  consul acl policy create -name eng-ro \
  -rules='service_prefix "" { policy="read" } node_prefix "" { policy="read" }'
  
CONSUL_HTTP_TOKEN=root \
  consul acl role create -name eng-ro -policy-name eng-ro

 

  3. Create the AuthMethod Config file:

# file: auth-method-config.json
{
 "OIDCDiscoveryURL": "http://192.168.64.3:8080/realms/hashicorp-demo",
 "OIDCClientID": "consul-sso",
 "OIDCClientSecret": "<Secret from Keycloak>",
 "BoundAudiences": ["consul-sso"],
 "AllowedRedirectURIs": [
   "http://localhost:8550/oidc/callback",
   "http://localhost:8500/ui/oidc/callback",
   "http://192.168.64.3:8500"
 ],
 "ClaimMappings": {
   "given_name": "given_name",
   "family_name": "family_name"
 },
 "ListClaimMappings": {
   "groups": "groups"
 },
 "VerboseOIDCLogging": true
}

 

1. Ensure that you set VerboseOIDCLogging to true when you are learning/troubleshooting, as this will log the responses from the OIDC in the Consul Agent logs.

2. The OIDCCLientSecret should be copied from Clients> consul-sso > Credentials > Client Secret inside Keycloak.(as per example)

3. The OIDCDiscoveryURL points to the http[s]://<keycloak address>/realms/<realm-name>

4. The ClaimMappings and ListClaimMappings can be referred to from the Evaluate option shown in Keycloak setup steps under "Group Membership Claim mappers".

 

 

  5. Apply the AuthMethod Config File and create the required role bindings.

$ CONSUL_HTTP_TOKEN=root \
 consul acl auth-method create -type oidc \
   -name keycloak \
   -max-token-ttl=5m \
   -config=@auth-method-config.json
   
   
$ CONSUL_HTTP_TOKEN=root \
 consul acl binding-rule create \
       -method=keycloak \
       -bind-type=role \
       -bind-name=eng-ro \
       -selector='engineering in list.groups'
      
      
$ CONSUL_HTTP_TOKEN=root \
  consul acl binding-rule create \
      -method=keycloak \
      -bind-type=service \
      -bind-name='dev-${value.given_name}-${value.family_name}' \
      -selector='engineering in list.groups'

 

OIDC Login to Consul using Keycloak:

 

Attempt to login from the CLI by running the following command.

consul login -method=keycloak -type=oidc -token-sink-file=dev.token

 

The UI-based login workflow looks like below in screenshots. 

• The User can now authenticate to Consul via UI, and selecting SSO option with correct provider(Keycloak here), and then the User logs in to Consul and access UI based on access level determined by policies applied.
• You can log in to the UI using a privileged token to see the tokens created via the OIDC login, as seen below.

 

 

 

 

 

Outcome:

With the help of above steps we were able to configure Keycloak and Consul to integrate with each other, in order to allow users to login to Consul via OIDC authentication provided by Keycloak.

 

References:

• https://developer.hashicorp.com/consul/docs/secure/acl/auth-method/oidc

• https://www.keycloak.org/docs/latest/server_admin/index.html#assembly-managing-users_server_administration_guide