Rego Policy Language for OAuth 2.0 Authorization

1.1. Requirements Language

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.¶

1.2. RAR Integration

This specification defines the rego_policy authorization data type for use with Rich Authorization Requests (RAR) [RFC9396]. The policy proposal is carried within the authorization_details parameter as the primary mechanism.¶

Key aspects of the RAR integration:¶

• Authorization Data Type: The rego_policy type is defined for use with the authorization_details parameter per RFC 9396. It contains the policy content, entry point, and optional context.¶
• Token Response: Per RFC 9396 Section 7.1, the access token includes enriched authorization_details as the primary mechanism for carrying policy information. The policy_ref claim MAY be included as a lightweight alternative (see Section 3.2).¶
• Complementary Use: RAR enables structured authorization requests with type-specific details, while Rego Policy enables expressive declarative policy definitions. Implementations MAY combine rego_policy with other RAR types.¶

Implementations SHOULD ensure consistency between authorization_details requirements and Rego policy evaluations. The Authorization Server MAY use RAR types to determine applicable policy templates or validation rules.¶

4.1. Step Details

1. Authorization Request: Client sends authorization request with authorization_details containing an object of type rego_policy, with policy and optional context fields. This leverages RAR (RFC 9396) for structured authorization requests.¶
2. Syntax Validation: AS validates that the Rego policy is syntactically correct and safe to evaluate.¶
3. Policy Scope Check: AS verifies the policy does not exceed the client's registered permissions and checks user consent requirements. The AS does not perform full runtime policy evaluation (which occurs at the RS).¶
4. Token Response: AS issues access token with enriched authorization_details array per RFC 9396 Section 7.1, containing the validated policy.¶
5. API Request: Client presents token to Resource Server.¶
6. Policy Extraction: RS extracts the Rego policy from the enriched authorization_details in the access token.¶
7. Policy Evaluation: RS sends the policy and request input to a Rego-compatible policy engine for evaluation.¶
8. Result: The policy engine returns an allow/deny decision.¶
9. Enforcement: RS enforces the policy engine's decision.¶
10. Response: RS returns result to client.¶

5.1. Error Response Format

When an agent's request lacks sufficient authorization, the resource server returns an HTTP 403 Forbidden response with a JSON body containing a rego_profile object. This object provides machine-readable guidance on the required authorization conditions.¶

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "insufficient_authorization",
  "error_description": "Additional authorization required",
  "rego_profile": {
    "profile_uri": "https://resource.example/policies/purchase",
    "required_scope": ["purchase.create"],
    "required_claims": ["agent_id", "user_id"],
    "constraints": {
      "max_amount": {
        "type": "number",
        "description": "Maximum transaction amount in USD",
        "required": true
      },
      "trigger_source": {
        "type": "string",
        "enum": ["user_initiated", "scheduled"],
        "description": "Source of the operation trigger"
      }
    },
    "confirmation_required": true,
    "evidence_required": true,
    "auth_server": "https://as.example.com"
  }
}

5.2. Rego Profile Structure

The rego_profile object contains the following fields:¶

profile_uri:

REQUIRED. URI identifying the authorization profile for this resource. This URI serves as an opaque identifier; the document at this URI is intended for developer documentation and is not machine-parsed by the agent.¶

required_scope:

OPTIONAL. Array of scope values that the access token MUST include.¶

required_claims:

OPTIONAL. Array of claim names that MUST be present in the token.¶

constraints:

OPTIONAL. Object defining policy constraints that MUST be satisfied. Each key is a constraint name; the value is an object with the following descriptors: type (data type), description (human-readable explanation), enum (allowed values), and required (boolean, whether the constraint must be provided).¶

confirmation_required:

OPTIONAL. Boolean indicating whether user consent is required. If true, the agent MUST obtain explicit user approval. When used with JWT Grant Interaction Response [I-D.parecki-oauth-jwt-grant-interaction-response], this corresponds to the interaction_required error code and interaction flow.¶

evidence_required:

OPTIONAL. Boolean indicating whether authorization evidence recording is required.¶

auth_server:

REQUIRED. Identifier of the authorization server capable of issuing tokens that satisfy these requirements. The agent can discover the token endpoint and other metadata via OAuth 2.0 Authorization Server Metadata (RFC 8414) using this identifier.¶

5.3. Agent Adaptive Behavior

Upon receiving a reverse-guided authorization response, the AI agent SHOULD:¶

1. Parse the rego_profile to understand authorization requirements.¶
2. Verify that the specified auth_server is trusted before proceeding.¶
3. Construct a new authorization request including required scopes, policy proposal satisfying constraints, and any additional parameters required by the resource server.¶
4. If confirmation_required is true, initiate user consent flow.¶
5. Discover the token endpoint via the auth_server's metadata (RFC 8414) and submit the authorization request.¶

This adaptive approach enables agents to "learn" authorization requirements dynamically, reducing the need for pre-programmed knowledge of each resource server's policies.¶

5.4. Security Considerations

Implementations of reverse-guided authorization MUST consider the following security aspects:¶

• Auth Server Verification: Agents MUST verify that the auth_server specified in the rego_profile is trusted before submitting authorization requests. Agents MUST use only the token endpoint discovered from the auth_server's Authorization Server Metadata ([RFC8414]). Blindly following redirects could lead to credential theft.¶
• Constraint Validation: Agents SHOULD validate that constraint values are reasonable before including them in authorization requests. Malicious resource servers might attempt to induce agents to request excessive permissions.¶
• Information Disclosure: The rego_profile reveals authorization requirements, which is acceptable as it only exposes "what is needed" not "why it is needed." This is analogous to OAuth scope definitions.¶
• TLS Protection: All communications MUST use TLS to prevent man-in-the-middle attacks on the error response.¶

6.1. Policy Validation

Upon receiving an authorization_details request containing the rego_policy type, the AS MUST perform the following validation steps:¶

1. Syntax Check: Parse the Rego policy and verify it is syntactically valid.¶
2. Entry Point Check: Verify the policy defines an allow rule.¶
3. Safety Check: Ensure the policy does not contain dangerous operations (e.g., external HTTP calls via http.send, excessive resource consumption).¶
4. Scope Check: Verify the policy does not exceed the client's registered permissions. The AS SHOULD use the common RAR fields (actions, locations) for scope checking rather than analyzing the Rego policy AST (see Section 3.1).¶

6.2. Policy Registration

When the AS issues a policy_ref claim instead of embedding the full policy in authorization_details, the AS MUST register the policy:¶

1. Assign a unique policy identifier;¶
2. Store the policy content;¶
3. Associate the policy with the authorization session;¶
4. Optionally, pre-compile the policy for faster evaluation.¶

When the AS embeds the validated policy directly in the enriched authorization_details (the primary path), explicit registration is not required — the policy travels with the token.¶

6.3. Error Responses

If policy validation fails, the AS MUST return an error:¶

{
  "error": "invalid_request",
  "error_description": "Invalid Rego policy: syntax error at line 5"
}

7.1. Policy Retrieval

The RS obtains the Rego policy from the access token. The primary mechanism is to extract the policy from the enriched authorization_details array included in the token per RFC 9396 Section 7.1.¶

When the token uses the policy_ref claim instead of inline policy content, the RS retrieves the policy using one of the following methods:¶

• Fetch from AS: Use the endpoint URL in the policy_ref to retrieve the policy.¶
• Local Cache: Use a cached copy if available and not expired.¶
• Introspection: Include policy content in token introspection response.¶

7.2. Policy Engine Integration

After extracting the Rego policy from the token, the RS MUST load the policy into a Rego-compatible policy engine before querying it. Common loading mechanisms include:¶

• OPA REST API: PUT /v1/policies/{id} to register the policy, then query the Data API;¶
• OPA Go Library: Load the policy programmatically using the embedded OPA SDK;¶
• OPA Compile API: Submit the policy and input together for ad-hoc evaluation.¶

Once loaded, the RS queries the policy engine with the request context as input:¶

POST /v1/data/agent/allow HTTP/1.1
Host: opa.example.com
Content-Type: application/json

{
  "input": {
    "user": {
      "id": "user_12345",
      "tier": "premium"
    },
    "action": "manage_portfolio",
    "resource": {
      "type": "portfolio",
      "id": "portfolio_001"
    }
  }
}

{
  "result": true
}

7.3. Enforcement Decision

Based on the policy engine's response:¶

• If result is true: Allow the operation;¶
• If result is false: Deny with 403 Forbidden;¶
• If result is undefined (OPA returns an empty object with no result field): Deny with 403 Forbidden. Note that policies following the RECOMMENDED default allow = false pattern (see Section 3.1.3) will always produce a defined boolean result, so undefined only occurs when the default declaration is omitted;¶
• If the policy engine is unreachable or encounters an internal error: Deny with 500 Internal Server Error.¶

8.1. JWT Grant with Interaction Response

The JWT Authorization Grant Interaction Response [I-D.parecki-oauth-jwt-grant-interaction-response] is the RECOMMENDED flow for AI agent scenarios. In this flow, an agent presents a JWT assertion to the token endpoint. If user interaction (e.g., consent) is required before the token can be issued, the AS returns an interaction_required error with an interaction_uri where the user can complete the interaction. The agent then polls for the token.¶

When combined with Rego Policy, the agent includes authorization_details containing the rego_policy type in the JWT grant request. The AS validates the policy proposal, performs scope checks, and determines whether user consent is needed before issuing the token.¶

POST /token HTTP/1.1
Host: as.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&assertion=eyJhbGciOiJSUzI1NiJ9...
&authorization_details=%5B%7B%22type%22%3A%22rego_policy%22%2C
  %22policy%22%3A%7B%22type%22%3A%22rego%22%2C
  %22content%22%3A%22package%20agent%5Cn...
  %22entry_point%22%3A%22allow%22%7D%2C
  %22actions%22%3A%5B%22manage_portfolio%22%2C%22view_reports%22%5D%7D%5D

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "interaction_required",
  "interaction_uri": "https://as.example.com/interact/abc123",
  "interval": 5,
  "expires_in": 600
}

After the user completes the interaction, the agent retries the same JWT grant request. The AS then issues the access token with the enriched authorization_details containing the validated Rego policy.¶

8.2. Client Credentials Grant

In machine-to-machine scenarios using client credentials, the policy proposal can be included in the token request:¶

POST /token HTTP/1.1
Host: as.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=spiffe%3A%2F%2Fagent.example%2Fagent
&client_secret=...
&authorization_details=%5B%7B%22type%22%3A%22rego_policy%22%2C
  %22policy%22%3A%7B%22type%22%3A%22rego%22%2C%22content%22%3A%22...%22%2C
  %22entry_point%22%3A%22allow%22%7D%7D%5D

8.3. Token Exchange (RFC 8693)

When exchanging tokens [RFC8693], a new policy proposal can be provided to refine or restrict the authorized operations:¶

POST /token HTTP/1.1
Host: as.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
&subject_token=eyJhbGciOiJSUzI1NiJ9...
&subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token
&authorization_details=%5B%7B%22type%22%3A%22rego_policy%22%2C
  %22policy%22%3A%7B%22type%22%3A%22rego%22%2C%22content%22%3A%22...%22%2C
  %22entry_point%22%3A%22allow%22%7D%7D%5D

The resulting access token will include the new, more restrictive policy constraints that MUST be a subset of the original token's permissions.¶

9.1. Policy Injection

Rego policies submitted by clients are evaluable policy definitions. Although Rego is declarative and guarantees termination, the AS MUST:¶

• Validate policy syntax before registration;¶
• Evaluate policies in sandboxed environments;¶
• Limit policy evaluation time and resource usage;¶
• Restrict dangerous built-in functions (e.g., http.send).¶

9.2. Policy Scope Escalation

Clients MUST NOT be able to propose policies that exceed their registered permissions. The AS SHOULD maintain policy templates or scope hierarchies to enforce this.¶

9.3. Policy Integrity

The policy_ref in access tokens MUST reference policies stored securely by the AS. Resource Servers MUST fetch policies only from trusted sources.¶

9.4. Policy URI Fetching

When the policy.uri field is present, the AS fetches policy content from a client-provided URI. This introduces Server-Side Request Forgery (SSRF) risks. The AS MUST:¶

• Reject URIs pointing to private/internal network addresses (e.g., 10.0.0.0/8, 169.254.0.0/16, 127.0.0.0/8, ::1);¶
• Enforce HTTPS for all policy URIs;¶
• Set strict timeouts and size limits on fetched content;¶
• Validate that the fetched content is syntactically valid Rego before any evaluation.¶

9.5. Policy Size Limits

Rego policies embedded inline within authorization_details can significantly increase token request and access token size. Implementations MUST enforce limits on:¶

• Maximum policy source size (RECOMMENDED limit: 4 KB for inline policies). Note that JWT access tokens are typically carried in HTTP Authorization headers, where many proxies and load balancers enforce an 8 KB total header size limit;¶
• Maximum policy complexity (e.g., nesting depth, number of rules);¶
• Total authorization_details payload size in token requests.¶

For policies exceeding these limits, clients SHOULD use pre-registered policies referenced via policy_ref rather than inline policy content.¶

10.1. RAR Authorization Data Type Registration

This specification defines the following authorization data type for use with the authorization_details parameter defined in RFC 9396:¶

Type Name:

rego_policy¶

Description:

A Rego policy for fine-grained authorization decisions, including policy content, entry point, and optional evaluation context.¶

Change Controller:

IETF¶

Specification Document:

Section 3 of this document¶

10.2. JWT Claims Registration

This specification registers the following claims in the "JSON Web Token Claims" registry:¶

Claim Name:

policy_ref¶

Claim Description:

A reference to a registered Rego policy in access tokens.¶

Change Controller:

IETF¶

Specification Document:

Section 3.2 of this document¶

10.3. OAuth Extensions Error Registration

This specification registers the following error code in the "OAuth Extensions Error" registry established by RFC 6749:¶

Error Name:

insufficient_authorization¶

Error Description:

The request requires higher authorization privileges than provided by the access token. The resource server MAY include a rego_profile object in the response body to guide the client toward obtaining sufficient authorization.¶

Change Controller:

IETF¶

Specification Document:

Section 5.1 of this document¶