OAuth 2.0 Entity Profiles

1.1. Conventions and Definitions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

This specification uses the Augmented Backus-Naur Form (ABNF) notation of [RFC5234].¶

1.2. Terminology

This document uses the terms "User", "Resource Owner", "Client", "Authorization Server", "Resource Server", and "Access Token" defined in [RFC6749] and the terms "JSON Web Token (JWT)", "Claim", "Claim Name" defined in [RFC7519].¶

• Entity Profile:

  A string-valued descriptor classifying an OAuth entity (client or subject) according to its operational role or context.¶

• Client Profile:

  An Entity Profile that characterizes the client software or application initiating the OAuth flow (e.g., web app, native app, AI agent, etc.).¶

• Subject Profile:

  An Entity Profile that characterizes the entity represented by the token subject (e.g., user, AI agent, service account, etc.).¶

• Actor Profile:

  An Entity Profile that characterizes the acting entity within an act Claim node [RFC8693].¶

3.1. Standardized Entity Profiles

The following is a list of Entity Profile values defined by this specification. These identifiers are not intended to be exhaustive, and additional profiles can be defined by implementers or through other specifications. The values defined herein are an intentionally small set that covers the most common scenarios.¶

3.2. Private or Custom Entity Profiles

Entity Profiles can be defined at will by those using this specification. However, in order to prevent collisions, any new Entity Profile should either be registered in the IANA OAuth Entity Profiles registry (see Section 14.1) or be a collision-resistant value. The definer of the value needs to take reasonable precautions to ensure they are in control of the part of the namespace they use to define the Entity Profile.¶

3.3. Representation in Token Claims and Metadata

The value of an Entity Profile, whether appearing as a Claim in JWT tokens or as a parameter in metadata or introspection responses, is expressed as a space-delimited, case-insensitive list of strings. Each string represents a classification of the entity (either a client or a subject) and MUST adhere to the syntax defined below.¶

Multiple values MAY be included if the entity fits into more than one category. The order of values is insignificant, and there is no implicit hierarchy or relationship between the values. When multiple Entity Profiles are present, each value is interpreted independently. Values SHOULD NOT be duplicated within a single Entity Profile list; receivers SHOULD ignore duplicate values. When including multiple values, the Entity Profile combinations SHOULD be semantically meaningful and validated against expected usage patterns. Conflicting profiles (e.g., user service) SHOULD be avoided unless a clear operational justification exists (e.g., user ai_agent to indicate an AI agent acting as a digital employee).¶

entity-profile = profile-token * ( SP profile-token )
profile-token = 1*( ALPHA / DIGIT / "-" / "_" / "." )

Examples:¶

• "user"¶

• "ai_agent"¶

• "service ai_agent"¶

All profile values MUST either:¶

• Be registered in the OAuth Entity Profiles IANA registry (see Section 14.1), or¶

• Be privately defined (see Section 3.2).¶

When processing these values, Authorization Servers and Resource Servers MUST NOT assume any implicit relationships or hierarchies between the Entity Profiles unless explicitly agreed upon by the Authorization Server and the Resource Server or if defined in a different specification. Entity Profiles are also orthogonal to the client's confidentiality classification (public or confidential) as defined in Section 2.1 of [RFC6749]; the same Entity Profile value may apply to both public and confidential clients.¶

Authorization Servers that process tokens containing Entity Profile values they do not recognize SHOULD preserve those values unchanged when producing derived tokens (e.g., during token exchange or delegation). This allows unrecognized profiles to be propagated through the token chain, enabling Resource Servers that do recognize those profiles to make informed decisions based on them.¶

For example, a token might include the Entity Profiles ai_agent acme_verified_robot, where acme_verified_robot is a vendor-defined profile used to identify industrial automation clients from ACME Corp. These two profiles are independent — the presence of both does not imply that one is a subtype of the other, nor that they share privilege or trust levels. Treating acme_verified_robot as a subclass of ai_agent, or vice versa, could result in incorrect access decisions.¶

4.1. client_profile Claim

The client_profile (Client Profile) Claim indicates the Entity Profile(s) of the Client identified by the client_id (Client ID) Claim in a JWT. If included, the value of this Claim MUST conform to the rules defined in Section 3.3. Use of this Claim is OPTIONAL.¶

4.2. sub_profile Claim

The sub_profile (Subject Profile) Claim indicates the Entity Profile(s) of the Subject represented by the sub (Subject) Claim in a JWT. If included, the value of this Claim MUST conform to the rules defined in Section 3.3. Use of this Claim is OPTIONAL.¶

The sub_profile Claim also appears within act (Actor) Claim nodes [RFC8693] to identify the Entity Profile of the acting entity at each step in a delegation chain. This allows acting entities in delegation scenarios to be classified using the same Entity Profile vocabulary. The value MUST conform to the same syntax and registry requirements defined in Section 3.3.¶

Below is a non-normative example illustrating how the new Entity Profile Claims can appear within a JWT access token. Other standard Claims are omitted for brevity:¶

{
  "sub": "user123",
  "sub_profile": "user",
  "client_id": "client456",
  "client_profile": "service ai_agent"
}

Below is a non-normative example illustrating how sub_profile appears within an act Claim node in a delegation context. Other standard act members such as iss are omitted for brevity.¶

{
  "sub": "user123",
  "sub_profile": "user",
  "client_id": "client789",
  "client_profile": "ai_agent",
  "act": {
    "sub": "client789",
    "sub_profile": "ai_agent"
  }
}

8.1. Registration

Clients implementing this specification:¶

• MAY declare client_profile at registration when using OAuth Dynamic Client Registration¶

• MUST use registered or private Entity Profiles¶

• MUST NOT attempt to register with Entity Profiles that do not match their actual nature¶

In environments where clients are manually registered or configured (e.g., enterprise deployments), client_profile provided MUST accurately represent the nature of the client. The value MUST be a registered Entity Profile or follow the naming conventions for private Entity Profiles.¶

Clients are incentivized to declare accurate client_profile values because authorization and access policies rely on them. Misrepresenting profiles may cause stricter enforcement, failed authorizations, or rejection due to incompatible policy constraints. Moreover, Authorization Servers and Resource Servers should monitor client behavior to ensure consistency with the declared profile, with deviations potentially resulting in penalties or revocation of access.¶

9.1. Client Registration

During client registration (dynamically or otherwise), Authorization Servers implementing this specification:¶

• MUST verify the client_profile value during client registration, if present in the registration request.¶

• MUST ensure that the client_profile value conforms to the rules defined in Section 3.3.¶

• MUST reject registration requests with syntactically invalid client_profile values or values that are neither registered in the OAuth Entity Profiles registry nor valid private Entity Profiles.¶

• SHOULD provide clear error messages when rejecting registration requests due to invalid or unrecognized client_profile values.¶

• MAY log Client Profile information for auditing and monitoring purposes.¶

• MAY restrict clients from updating their client_profile after registration or limit the frequency of such updates, depending on their policies.¶

9.2. Subject Profile Assignment

The Authorization Server MAY determine the sub_profile value based on:¶

• Attributes of the subject (e.g., user, service account, AI agent) as provided during registration.¶

• Subject attributes returned during authentication.¶

• The grant type used (e.g., client_credentials implies service account).¶

• Preconfigured mappings.¶

The client’s declared profile or request parameters MUST NOT directly influence or determine the value of sub_profile to prevent manipulation or unauthorized elevation of subject classification.¶

9.3. JWT Issuance

Authorization Servers implementing this specification:¶

• MAY include sub_profile and client_profile Claims in access tokens and ID tokens, according to their policies and client registration metadata. When included, these Claims MUST conform to the rules defined in Section 3.3.¶

• SHOULD only issue Entity Profile values in their registered usage locations as defined in the OAuth Entity Profiles registry (Section 14.1).¶

• MAY automatically include Entity Profile Claims for certain categories of clients, such as always providing client_profile for autonomous AI agent clients.¶

• SHOULD include these Claims when explicitly requested by clients through supported mechanisms (e.g., OpenID Connect Claims parameter [OIDC], specific scope requests).¶

• SHOULD populate these Claims consistently using verified Entity Profile information obtained during client registration or other trusted validation methods.¶

• When issuing refreshed or exchanged tokens, Authorization Servers SHOULD re-evaluate the Entity Profiles and update them if context or identity has changed. Entity Profiles MUST NOT be assumed to persist across sessions without validation.¶

This specification does not prescribe how clients request Entity Profile Claims. In practice, Authorization Servers may enforce the inclusion of these Claims, especially for high-risk or privileged profiles such as AI agents, to ensure consistent and secure policy enforcement. For other entity profiles, to reduce token size and privacy exposure, Claims may be omitted by default and included only when explicitly requested. This approach balances the need for security and efficient token management, while preventing clients from arbitrarily adding or omitting Entity Profile information to manipulate access control decisions.¶

In OpenID Connect deployments, clients MAY use the claims request parameter [OIDC] to request Entity Profile Claims. The following is a non-normative example of requesting both client_profile and sub_profile in an access token:¶

{
  "access_token": {
    "client_profile": null,
    "sub_profile": null
  }
}

9.4. Token Introspection Responses

Authorization Servers implementing this specification:¶

• SHOULD include sub_profile and client_profile parameters in token introspection responses. If included, Authorization Servers MUST ensure that the values of these parameters conform to the rules defined in Section 3.3.¶

• MAY include sub_profile within act nodes in introspection responses when the token is associated with a delegation context and the Authorization Server has assigned an Actor Profile to the acting entity.¶

9.5. Validation Requirements

Authorization Servers:¶

1. MUST verify that Entity Profile values are either registered in the OAuth Entity Profiles registry or follow proper namespaced private conventions per the rules defined in Section 3.3.¶

2. SHOULD ensure that Entity Profile assignments are trustworthy and not based solely on unverified self-assertion. The mechanisms for these verifications are out of scope for this specification, but it is recommended that Authorization Servers implement appropriate checks based on their security policies and operational context.¶

3. MUST enforce authentication assurance and policy requirements appropriate to the Entity Profile.¶

If validation fails during:¶

• Client registration: Authorization Servers SHOULD return invalid_client_metadata (as defined in [RFC7591]).¶

• Token issuance: Servers MAY refuse to issue tokens or omit the invalid profile Claims.¶

• Token introspection: Servers SHOULD ensure introspection results match stored profile metadata and MUST NOT fabricate or guess unknown profiles.¶

• JWT authorization grant processing: Servers SHOULD return invalid_grant as defined in Section 3.1 of [RFC7523] if the assertion contains syntactically invalid or unrecognized Entity Profile values.¶

Clear, actionable error responses MUST be returned in accordance with OAuth and OpenID Connect error handling frameworks.¶

Authorization Servers MAY:¶

1. Log Entity Profile assignments to support auditing and forensic analysis.¶

2. Incorporate Entity Profiles into rate limiting and other risk-based controls.¶

3. Return clear, descriptive error messages if Entity Profile validation fails.¶

10.1. Handling Multiple Entity Profiles in Authorization Policies

When multiple Entity Profiles are present, authorization policies associated with each should be evaluated in combination. Entity Profiles do not define an inherent hierarchy or ordering; no profile is automatically "more trusted" than another. However, when policy outcomes conflict, deployments SHOULD apply the most restrictive outcome to avoid unintended privilege escalation. Implementers should avoid writing Entity Profile checks that override previous decisions imperatively, as this can lead to inconsistent behavior.¶

Here is a non-normative pseudo-code example of how these values can be used for enforcing authorization policies at a Resource Server:¶

raw_client = token.get("client_profile", "").strip()
client_profiles = set(raw_client.split()) if raw_client else set()

raw_sub = token.get("sub_profile", "").strip()
sub_profiles = set(raw_sub.split()) if raw_sub else set()

# Define applicable policies
policies_to_apply = []

if "service" in client_profiles:
    # Add service-specific policies
    policies_to_apply.append(apply_service_policy)

if "ai_agent" in sub_profiles:
    # Add AI agent-specific policies
    policies_to_apply.append(apply_ai_agent_policy)

if "user" in sub_profiles:
    # Add user-specific policies
    policies_to_apply.append(apply_user_policy)

# Evaluate combined policies (e.g., intersection of permissions or most restrictive)
final_decision = evaluate_combined_policies(policies_to_apply, mode="most_restrictive")

12.1. Trust and Verification

Entity Profile Claims should only be trusted when issued by verified and trusted authorities. Without proper validation, self-asserted or spoofed Claims may result in misclassification and undermine security policies. Authorization Servers should enforce strict validation during client registration and token issuance.¶

12.2. Entity Profile Spoofing

Malicious clients may attempt to register or use false Entity Profiles to bypass access controls. To mitigate this, Authorization Servers should require verification for all profiles, especially privileged types like "ai_agent", and restrict dynamic registration of sensitive profiles unless additional validation is performed.¶

Implementations are encouraged to monitor client behavior for consistency with the declared profile, applying penalties or revoking access when discrepancies indicate potential abuse or security risks.¶

12.3. Entity Profiles in JWT Authorization Grant Assertions

When Entity Profile Claims are conveyed in JWT authorization grant assertions [RFC7523], the Authorization Server receives classification information from an external issuer rather than from its own registration or authentication processes. This introduces additional trust considerations. Authorization Servers must not accept sub_profile values from JWT assertions at face value and should verify these values against independent knowledge of the subject or the issuer's attestation trustworthiness.¶

An attacker who compromises or forges a JWT assertion could include a misleading sub_profile value (e.g., user for a service account) to obtain access privileges not intended for the actual entity type. Authorization Servers should apply the same level of scrutiny to Entity Profile Claims in JWT assertions as they do to other assertion Claims such as sub and aud.¶

12.4. Consistency and Semantics

Authorization Servers, Resource Servers, and Clients must interpret Entity Profile Claims consistently. To avoid misclassification or policy errors they should follow the definitions and semantics outlined in the specification, and not infer additional meanings or relationships beyond the defined Entity Profiles. This consistency is crucial for interoperability and security.¶

12.5. Separation from Authentication and Assurance

Entity Profile Claims are intended solely for classification and do not convey authentication strength or assurance. It is advised not to use these Entity Profile Claims as replacements for Claims such as acr (Authentication Context Class Reference [OIDC]). Authorization decisions should incorporate authentication context Claims alongside Entity Profiles to ensure robust access control.¶

Different Entity Profiles may require different levels of authentication assurance. It is recommended that Authorization Servers define minimum assurance requirements per Entity Profile, express these through the acr Claim, and reject authorization requests that do not meet the required assurance level. This alignment helps prevent unauthorized access by weakly authenticated entities.¶

12.6. Layered Policy Enforcement

It is recommended that Entity Profile Claims be used as one element within a multi-layered authorization policy. Relying exclusively on Entity Profile Claims can create brittle or exploitable policies. Implementers should combine Entity Profile Claims with scopes, roles, authentication assurance, and other contextual information.¶

12.7. Audit and Monitoring

It is recommended that Entity Profile Claims be incorporated thoughtfully into logging, telemetry, and audit trails to improve visibility into system behavior and support forensic investigations. However, implementers should balance these benefits against potential privacy concerns, ensuring that sensitive classification information is not overexposed or retained longer than necessary. Careful access controls and data minimization practices are advised when handling logs containing Entity Profile details.¶

12.8. Default Handling

While it is recommended to apply conservative or restrictive policies when Entity Profile Claims are missing, Resource Servers should also consider backward compatibility. Many existing tokens and systems may not include these Claims, so resources might need to accept requests without them. In such cases, applying default or fallback policies that balance security and usability is advised. Monitoring and logging requests missing Entity Profile Claims can help identify when stronger enforcement or client registration updates are needed.¶

12.9. Misclassification Risks

Entity Profile Claims can be misclassified or misinterpreted, leading to incorrect access control decisions. It is recommended that implementers validate Entity Profile Claims against known registries or trusted sources to ensure accurate classification. Implementers should also consider the implications of misclassification and implement fallback mechanisms or default policies to mitigate risks.¶

12.10. Token Bloating

Entity Profile Claims can increase the size of JWT access tokens or ID tokens, especially when multiple profiles are included. This can lead to performance issues, particularly in environments with limited bandwidth or storage. Implementers should consider the impact of token size on their systems and apply data minimization principles, only including Entity Profile Claims when necessary. Implementers should enforce reasonable limits on both the number of Entity Profile values in a single Claim and the length of individual profile value strings. Excessively large profile values could increase token sizes, degrade performance, or be exploited as a denial-of-service vector.¶

12.11. Actor Profile Verification in Delegation Chains

When sub_profile values appear within act Claim nodes [RFC8693], they introduce additional classification assertions about acting entities in a delegation chain. Authorization Servers and Resource Servers must not trust sub_profile values in act nodes without verifying them against the issuing authority's knowledge of those entities. Unverified actor profiles may enable privilege escalation — for example, an attacker could craft a delegation chain where an inner act node claims sub_profile value of "user" when the actual actor is a "service", potentially causing a Resource Server to apply user-level permissions to a service.¶

12.12. Delegation Chain Depth

Deeply nested act chains can contain many sub_profile values, increasing token size and processing complexity. Implementers should impose a maximum chain depth appropriate to their deployment context to prevent resource exhaustion. A depth limit of 3 to 5 levels is generally sufficient for most delegation scenarios.¶

12.13. Confused Deputy Risk in Delegation

When a token carries both a top-level sub_profile and a different sub_profile within an act node (e.g., sub_profile of "user" at the top level and sub_profile of "ai_agent" in act), Resource Servers must evaluate both classifications when making authorization decisions. Relying on only one of these values without considering the other may lead to a confused deputy scenario where the acting entity obtains access beyond what the delegation context warrants.¶

13.1. Fingerprinting

Entity Profile Claims can potentially be used to fingerprint clients or subjects based on their operational context. It is recommended that implementers consider the privacy implications of exposing Entity Profile information in tokens, especially when these Claims are accessible to untrusted parties. It is recommended to only include Entity Profile Claims when necessary, and assess whether their inclusion could enable cross-context tracking or re-identification.¶

13.2. Profiling and Behavioral Inference

Entity Profile Claims may unintentionally support profiling of users or clients, enabling assumptions about behavior, preferences, or roles. It is recommended that implementers carefully consider the potential for behavioral inference and ensure that Entity Profile Claims are not used to make unwarranted assumptions about user behavior or preferences. Implementers should also be cautious about exposing sensitive Entity Profile information in tokens that could be accessible to untrusted parties.¶

13.3. Minimization

Implementers should apply data minimization principles when including Entity Profile Claims in tokens. This means only including Entity Profile information that is necessary for the intended purpose and avoiding overexposure of sensitive classification details. Implementers should also consider whether Entity Profile Claims are needed in all contexts or if they can be omitted in certain scenarios to reduce privacy risks.¶

13.4. Data Exposure

Entity Profile Claims may reveal sensitive information about system architecture or user categories. It is advised to carefully consider the exposure of these Claims in tokens accessible to untrusted parties. Limiting or anonymizing Entity Profile information can reduce the risk of unintended data disclosure.¶

13.5. Delegation Chain Exposure

When sub_profile values are present within nested act Claim nodes [RFC8693], the resulting token preserves the Entity Profile of each principal in the delegation chain. This may reveal sensitive information about organizational structure, internal service topology, or delegation patterns across domains. Implementers should consider whether the full delegation chain needs to be present in tokens presented to Resource Servers, or whether a truncated representation is sufficient. Data minimization principles from Section 13.3 apply to sub_profile values within act nodes as well.¶

14.1. OAuth Entity Profiles Registry

This specification requests the creation of a new IANA registry titled "OAuth Entity Profiles Registry" within the "OAuth Parameters" group. This registry will contain the string identifiers used to represent the Entity Profiles described in this specification.¶

NOTE: Private or vendor-specific Entity Profiles may use namespaced values and do not require IANA registration.¶

14.2. JWT Claims Registration

This document requests registration of the following Claims in the "JSON Web Token Claims" registry:¶

14.3. Authorization Server Metadata Registration

IANA is requested to register the following fields in the "OAuth Authorization Server Metadata" [RFC8414] registry:¶

14.4. Dynamic Client Registration Metadata Registration

IANA is requested to register the following field in the "OAuth Dynamic Client Registration Metadata" registry:¶

14.5. Token Introspection Response Registration

IANA is requested to register the following fields in the "OAuth Token Introspection Response" [RFC7662] registry:¶

15.1. Normative References

[OIDC]

"OpenID Connect Core 1.0", December 2023, <https://openid.net/specs/openid-connect-core-1_0.html>.

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC5234]

Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008, <https://www.rfc-editor.org/rfc/rfc5234>.

[RFC6749]

Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, <https://www.rfc-editor.org/rfc/rfc6749>.

[RFC6750]

Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, DOI 10.17487/RFC6750, October 2012, <https://www.rfc-editor.org/rfc/rfc6750>.

[RFC7519]

Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, <https://www.rfc-editor.org/rfc/rfc7519>.

[RFC7523]

Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 2015, <https://www.rfc-editor.org/rfc/rfc7523>.

[RFC7591]

Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", RFC 7591, DOI 10.17487/RFC7591, July 2015, <https://www.rfc-editor.org/rfc/rfc7591>.

[RFC7662]

Richer, J., Ed., "OAuth 2.0 Token Introspection", RFC 7662, DOI 10.17487/RFC7662, October 2015, <https://www.rfc-editor.org/rfc/rfc7662>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

[RFC8414]

Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, June 2018, <https://www.rfc-editor.org/rfc/rfc8414>.

[RFC8693]

Jones, M., Nadalin, A., Campbell, B., Ed., Bradley, J., and C. Mortimore, "OAuth 2.0 Token Exchange", RFC 8693, DOI 10.17487/RFC8693, January 2020, <https://www.rfc-editor.org/rfc/rfc8693>.

[RFC9068]

Bertocci, V., "JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens", RFC 9068, DOI 10.17487/RFC9068, October 2021, <https://www.rfc-editor.org/rfc/rfc9068>.

15.2. Informative References

[RFC8628]

Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, "OAuth 2.0 Device Authorization Grant", RFC 8628, DOI 10.17487/RFC8628, August 2019, <https://www.rfc-editor.org/rfc/rfc8628>.

B.1. draft-01

• Introduced Actor Profiles to classify acting entities in delegation contexts¶

• Extended Entity Profile use to JWT authorization grant assertions¶

• Added Karl McGuinness as co-author¶

• Clarified DCR behavior when the AS modifies or omits a requested client_profile¶

• Refined RS behavior to condition enforcement on entity_profiles_supported advertisement¶

• Editorial refinements to definitions and examples¶

B.2. draft-00

• Initial draft¶