Understanding Login Token Naming Behaviour in Consul UI for OIDC Auth Methods

Avatar
Suyash Kumar
  • Updated

Introduction

When users authenticate to HashiCorp Consul using an OIDC-based ACL auth method (for example with Auth0), the Consul UI displays a username derived from the token’s Accessor ID, rather than a human-readable identity.

This article explains why this behavior occurs, what is configurable today, and what limitations exist with respect to login token naming in the Consul UI.

 

Scenario

An organization or user has configured OIDC authentication in Consul and defined:

  • Claim mappings to map OIDC claims (e.g., first_name, last_name, groups) to Consul identity attributes.

  • ACL binding rules that use templating via -bind-name to create meaningful token names.

Example binding rule:

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

 

Observed Behavior

  • After a successful login via OIDC:

    • The Consul UI header (in the left panel right side user display) shows a value derived from the first 8 characters of the token Accessor ID.

    • Navigating to ACL → Tokens in the Consul UI:

      • The same token correctly displays the templated name (dev-firstname-lastname) defined via -bind-name.

 

Key Point

Even though:

  • Claim mappings are configured correctly, and

  • Token names are templated successfully,

The Consul UI login identity does not reflect the templated token name.

 

 

Recommendation

Current State (Expected Behavior)

At present, Consul does not support customizing the displayed login username in the UI for OIDC-authenticated users.

  • The UI login identity is always derived from the token Accessor ID

  • -bind-name:

    • Affects token metadata

    • Does not affect the UI login display name

This is a known limitation in Consul.

Comparison with Nomad

In HashiCorp Nomad, administrators can explicitly control token naming via:

-token-name-format

 

Practical Guidance

  • Use -bind-name templating to ensure:

    • Tokens are easily identifiable in:

      • ACL → Tokens

      • Auditing

      • Operational workflows

  • Treat the UI login display as:

    • A technical identifier, not a user-friendly name

  • If UI-level identity clarity is required:

    • Track tokens via metadata and token lists instead of relying on the UI header.

 

Additional Information

Relevant Documentation

Feature Gap / Supportability Note

  • A feature request to support customizable, human-readable login token naming in the Consul UI for OIDC-based auth methods has been raised internally within HashiCorp. Once this capability is introduced, it will be documented in the corresponding Consul release notes and changelogs, which should be referenced to track availability.

Articles in this section

See more