Keycloak中‘id’为何被称为‘sub’？‘sub’可安全映射数据库对象吗？

Question #

I'm working with the Keycloak Beta 4 API, and when I call the endpoint to fetch user account information, I noticed that the field displayed as id in the Web UI corresponds to sub in the returned account object. Here's a sample response:

{ 
  "sub": "25a37fd0-d10e-40ca-af6c-821f20e01be8", 
  "name": "Barrack Obama", 
  "preferred_username": "obama@whitehouse.gov", 
  "given_name": "Barrack", 
  "family_name": "Obama", 
  "email": "obama@whitehouse.gov" 
}

I have two questions:

• What does sub stand for and what is its purpose?
• Is it safe to use sub as a UUID to map to database objects?

Answer #

Great question! Let's break this down clearly.

What is sub? #

sub is short for subject—it’s a standard claim defined in the OpenID Connect (OIDC) specification. In OIDC, this claim exists to uniquely identify the user (the "subject") that a token or user info response refers to.

Keycloak, being an OIDC-compliant identity provider, uses this standard field in its API responses (even though the Web UI labels it as id for simplicity). The sub value is a stable, unique identifier tied to the user’s account within a Keycloak realm—once assigned, it won’t change for the entire lifetime of the user account.

Is it safe to use sub as a UUID for database mapping? #

Absolutely, using sub as the identifier to link Keycloak users to your database objects is not just safe—it’s the recommended approach for apps integrated with OIDC. Here’s why:

• Guaranteed uniqueness: Within a single Keycloak realm, sub will always be unique per user. If you’re working across multiple realms, you can combine it with the realm ID for global uniqueness, but for most single-realm setups, it’s more than sufficient.
• Stability: Unlike user-editable attributes like email or username (which can be updated by the user or admin), sub stays constant. This means your database mappings won’t break if a user changes their profile details later on.
• Standard compliance: Following OIDC standards makes your integration more portable. If you ever switch to another OIDC provider, the sub claim will still exist (though its format might differ slightly), so your code won’t need a complete overhaul.

A couple of quick notes to keep in mind:

• Don’t assume sub is always a UUID. While Keycloak uses UUIDs for this field, other OIDC providers might use different formats (like strings or integers). But if you’re only working with Keycloak, the UUID format is consistent.
• When fetching sub via Keycloak’s user info API, make sure your API call is authenticated securely (e.g., using a valid access token) to ensure you’re receiving trusted data. If you’re getting sub from tokens, always validate the token’s signature to prevent tampering.

内容的提问来源于stack exchange，提问作者Jack Murphy