Introduction

Consul Enterprise gives users the ability to authenticate to Consul servers using OIDC and SSO methods. One of the most popular OIDC methods that our customers use is Okta as a method to easily control the roles and permissions of users within their organization.

Although most OIDC providers use similar methods to perform the actual authentication there are slight differences that must be made to use each. In this guide I will be focusing solely on integrating Okta with Consul.

Requirements

• Consul Enterprise with ACL's enabled
  • Article is based on Consul v1.17
• Okta access with administrative capabilities 
  • Article is based on Version 2023.11.0 C

NOTE: The versions provided are what were used when this article was written. 

Configuration

Starting from your Okta admin dashboard you will need to setup the new Consul application so it can be configured and assigned to your users. 

• Setup the Consul Application in Okta by setting the sign-in method as "OIDC" and the application type as "Web Application".

• On the next page, you will be able to customize your Web App Integration with Okta. On this page you will primary need to ensure that the "Sign-in redirect URIs" are properly set to your Consul callback addresses.  

http://localhost:8550/oidc/callback
http://localhost:8500/ui/oidc/callback

• • For this example "localhost" can be replaced with the address you use to access Consul via your web browser. 
• The rest of these settings will be dependent upon your needs for the application. 

• Once the app has been created you will see the Client ID and Client Secret, which will be used later to configure Okta within Consul. 

• To ensure that the group mappings are correct and appear within the JWT that Okta provides to Consul, navigate to the "Sign On" tab and enable the "Groups claim filter" under the "OpenID Connect ID Token" section.
• Once enabled the following setting will need to be made:
  • Issuer: Okta URL
    Groups Claim Type: Filter
    Groups Claim filter: groups - Matches Regex - .*

Create Consul policies and roles

After the login procedure confirms the user identity, it has to then give them privileges when creating their ACL token. Auth methods in Consul use binding rules to control that.

Binding rules allow for two ways to assign privileges to a new token:

• Service identities: this approach is better suited for application login and is not suggested for user login.
• Roles: this approach is preferred when enabling user login.

Roles are a named collection of privileges, such as lists of policies and service identities, that can be linked to a token.

In order to assign some privilege to a token via an auth method, you will first define the privilege in a policy and then assign that policy to a role. In this way, the binding rule can reference the role by name.

Define policy for Okta users

• Create a policy named eng-ro to allow full read-only access of any service for service discovery.

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

• • If the command completes successfully, you will receive an output similar to this:

ID:           56c478f2-21a3-dc84-9116-4827e32125ff
Name:         eng-ro
Namespace:    default
Description:
Datacenters:
Rules:
service_prefix "" { policy="read" } node_prefix "" { policy="read" }

Assign a policy to a role

• Next create a role named eng-ro linked to the policy created earlier.
  

  $CONSUL_HTTP_TOKEN=root \
     consul acl role create -name eng-ro -policy-name eng-ro

  • If the command completes successfully, you will receive an output similar to this
    

    Name:         eng-ro
    Namespace:    default
    Description:
    Policies:
      56c478f2-21a3-dc84-9116-4827e32125ff - eng-ro
    

Enable the OIDC auth method for Consul

{
"VerboseOIDCLogging": "true",
"OIDCDiscoveryURL": "OKTA_DOMAIN",
"OIDCClientID": "OKTA_CLIENT_ID",
"OIDCClientSecret": "OKTA_CLIENT_SECRET",
"BoundAudiences": ["OKTA_CLIENT_ID"],
"AllowedRedirectURIs": [
"http://your-consul-addr:8550/oidc/callback",
"http://your-consul-addr:8500/ui/oidc/callback"
],
"OIDCScopes": [
"email",
"profile",
"groups"
],
"ClaimMappings": {
"email": "email"
"first_name": "first_name",
"last_name": "last_name"
},
"ListClaimMappings": {
"groups": "groups",
"email": "email"
}
}

$CONSUL_HTTP_TOKEN=root \
  consul acl auth-method create -type oidc \
    -name okta \
    -max-token-ttl=5m \
    -config=@auth-method-config.json

Once you have configured the auth method, you can automate permissions grants to users using the metadata you defined earlier. This means that once auth method trust is established, Consul can be configured to bind attested identities to roles or services with no additional work beyond what is required to link the identity and the auth method. This can be configured using Consul binding rules.

Grant role permissions with app metadata

• Grant users in the engineering group the role eng-ro.

$CONSUL_HTTP_TOKEN=root \
   consul acl binding-rule create \
       -method=okta \
       -bind-type=role \
       -bind-name=eng-ro \
       -selector='engineering in list.groups'

ID:           7c9d6445-75c0-7d93-bb5e-d56100590950
Namespace:    default
AuthMethod:   okta
Description:
BindType:     role
BindName:     eng-ro
Selector:     engineering in list.groups

This will automatically associate every user with engineering in their app_metadata to Consul eng-ro role that you already associated with an ACL policy.

Grant service permissions with user metadata

If you want to grant users permissions to register services, you can use a service type binding. In this tutorial, you will grant users in the engineering group the ability to register a service in the service mesh with their own name.

$CONSUL_HTTP_TOKEN=root \
   consul acl binding-rule create \
       -method=okta\
       -bind-type=service \
       -bind-name='dev-${value.first_name}-${value.last_name}'\ 
       -selector='engineering in list.groups'

ID:           a5309527-f5e0-8034-0795-ed7a98b961d0
Namespace:    default
AuthMethod:   okta
Description:
BindType:     service
BindName:     dev-${value.first_name}-${value.last_name}
Selector:     engineering in list.groups

Login with OIDC

After the configuration is complete, you can login to Consul using Okta.

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

f110aff6-4d5b-4563-80dd-4da6f74c1067

$consul acl token read -self -token-file=dev.token
AccessorID:       cd887b52-263a-4ae2-8747-725b76d0a79f
SecretID:         f110aff6-4d5b-4563-80dd-4da6f74c1067
Namespace:        default
Description:      token created via OIDC login
Local:            true
Auth Method:      okta
Create Time:      2020-04-28 15:00:49.790370772 -0500 CDT
Roles:   7d3e3a66-8c0f-e528-944e-84df6b36a115 - eng-ro
Service Identities:   dev-kara-danvers (Datacenters: all)