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

This specification is designed to work with Rich Authorization Requests (RAR) [RFC9396] as the primary mechanism for carrying policy proposals. The rego_policy authorization data type MAY be used with various OAuth 2.0 authorization flows, including but not limited to:¶

• Authorization Code Grant (with or without PAR);¶
• Client Credentials Grant;¶
• Token Exchange [RFC8693];¶
• Resource Owner Password Credentials Grant.¶

Different authorization flows may have different security considerations when using policy proposals. Implementations SHOULD carefully evaluate the security implications discussed in Section 7 based on their specific deployment scenario.¶

1.3. 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 registered in the RAR Authorization Data Types registry (Section 9.4 of RFC 9396). It contains the policy content, entry point, and optional context.¶
• Token Response: The access token includes a policy_ref claim referencing the registered policy. Per RFC 9396 Section 7.1, the token response MAY include enriched authorization information such as the full policy content.¶
• Complementary Use: RAR enables structured authorization requests with type-specific details, while Rego Policy enables expressive, Turing-complete 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 execute.¶
3. Policy Evaluation: AS evaluates the policy against the request context to determine authorization scope. This may involve checking user consent requirements and policy constraints.¶
4. Token Response: AS issues access token with policy_ref claim referencing the registered policy. Per RFC 9396 Section 7.1, the token response MAY include enriched authorization information in additional JSON fields (e.g., policy containing the full policy content) alongside the access token.¶
5. API Request: Client presents token to Resource Server.¶
6. Policy Fetch: RS retrieves the policy via policy_ref from AS (if not cached). The policy may have been returned directly in the enriched token response.¶
7. Policy Evaluation: RS sends policy and request input to OPA for evaluation.¶
8. Enforcement: RS enforces OPA's allow/deny decision.¶
9. 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",
    "token_endpoint": "https://as.example.com/token"
  }
}

5.2. Rego Profile Structure

The rego_profile object contains the following fields:¶

profile_uri:

REQUIRED. URI of the policy profile document that defines the authorization requirements for this resource.¶

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 constraint specifies the data type, description, and whether it is required.¶

confirmation_required:

OPTIONAL. Boolean indicating whether user consent is required. If true, the agent MUST obtain explicit user approval.¶

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

token_endpoint:

REQUIRED. URL of the token endpoint where the agent can request appropriate authorization.¶

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 appropriate policy context.¶
4. If confirmation_required is true, initiate user consent flow.¶
5. Submit the authorization request to the specified token_endpoint.¶

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. 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 a policy_proposal, 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., infinite loops, external HTTP calls in restricted environments).¶
4. Scope Check: Optionally verify the policy does not exceed the client's registered permissions.¶

6.2. Policy Registration

After validation, the AS registers the policy:¶

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

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

When the RS receives an access token with a policy_ref claim, it 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. OPA Integration

The RS evaluates the policy using OPA:¶

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

{
  "input": {
    "user": {
      "id": "user_12345",
      "tier": "premium"
    },
    "action": "add_to_cart",
    "resource": {
      "type": "cart",
      "id": "cart_789"
    },
    "amount": 45.00
  }
}

{
  "result": true
}

7.3. Enforcement Decision

Based on OPA's response:¶

• If result is true: Allow the operation;¶
• If result is false: Deny with 403 Forbidden;¶
• If evaluation fails: Deny with 500 Internal Server Error.¶

8.1. Authorization Code Grant (without PAR)

When using traditional authorization code grant without PAR, the policy proposal and policy_context SHOULD be included in a JWT using the "request" parameter as defined in [RFC9101]. This mechanism, known as JWT-Secured Authorization Request (JAR), is specifically designed for redirect-based flows and provides integrity protection while maintaining consistency with the PAR mechanism.¶

GET /authorize?
  response_type=code&
  client_id=spiffe://agent.example/agent&
  request=eyJhbGciOiJSUzI1NiIsImtpZCI6ImFnZW50LWtleSJ9.ewogICJyZXNwb25zZV90eXBlIjogImNvZGUiLAogICJjbGllbnRfaWQiOiAic3BpZmZlOi8vYWdlbnQuZXhhbXBsZS9hZ2VudCIsCiAgInBvbGljeV9wcm9wb3NhbCI6IHsidHlwZSI6ICJyZWdvIiwiY29udGVudCI6ICIuLi4iLCJlbnRyeV9wb2ludCI6ICJhbGxvdyJ9LAogICJwb2xpY3lfY29udGV4dCI6IHsuLi59LAogICJyZWRpcmVjdF91cmkiOiAiaHR0cHM6Ly9hZ2VudC5leGFtcGxlL2NhbGxiYWNrIiwKICAic3RhdGUiOiAieHl6MTIzIn0.signature&
  state=xyz123 HTTP/1.1
Host: as.example.com

The JWT payload (decoded) contains:¶

{
  "response_type": "code",
  "client_id": "spiffe://agent.example/agent",
  "authorization_details": [
    {
      "type": "rego_policy",
      "policy": {
        "type": "rego",
        "content": "package agent\\ndefault allow = false\\n\\nallow {\\n  input.action == \"read\"\\n}",
        "entry_point": "allow"
      },
      "context": {
        "user": {"id": "user_123"},
        "agent": {"id": "spiffe://agent.example/agent"}
      }
    }
  ],
  "redirect_uri": "https://agent.example/callback",
  "state": "xyz123"
}

Using the JWT request parameter provides the following benefits:¶

• Integrity Protection: The JWT signature prevents tampering with the policy proposal and context;¶
• Privacy: Policy content is not exposed in URLs, server logs, or browser history;¶
• Consistency: Same structure as PAR, just different transport mechanism;¶
• No Length Limits: Avoids URL length restrictions that affect query parameters.¶

Implementations MUST validate the JWT signature before processing the policy proposal. The client's public key can be obtained through pre-registration or dynamic client registration.¶

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/json

{
  "grant_type": "client_credentials",
  "client_id": "spiffe://agent.example/agent",
  "client_secret": "...",
  "authorization_details": [
    {
      "type": "rego_policy",
      "policy": {
        "type": "rego",
        "content": "...",
        "entry_point": "allow"
      }
    }
  ]
}

8.3. Token Exchange (RFC 8693)

When exchanging tokens, a new policy proposal can be provided to refine or extend the authorized operations:¶

POST /token HTTP/1.1
Host: as.example.com
Content-Type: application/json

{
  "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
  "subject_token": "eyJhbGciOiJSUzI1NiJ9...",
  "authorization_details": [
    {
      "type": "rego_policy",
      "policy": {
        "type": "rego",
        "content": "...",
        "entry_point": "allow"
      }
    }
  ]
}

The resulting access token will include both the original permissions and the new policy constraints.¶

8.4. Security Considerations by Flow

Different authorization flows have different security characteristics when using RAR with rego_policy:¶

PAR with RAR (Recommended):

authorization_details is transmitted in the PAR request body with JWT signature protection. Provides integrity and confidentiality. Highest security for policy proposals.¶

Authorization Code with JAR:

When using JWT-Secured Authorization Request (JAR, RFC 9101), authorization_details is protected by the JWT signature. Implementations MUST validate the JWT before processing.¶

Client Credentials:

Direct AS communication with TLS; standard client authentication usually sufficient. authorization_details is in the request body.¶

Token Exchange:

Similar security to Client Credentials; ensure policy binding to the exchanged token subject.¶

General security requirements for all flows:¶

• Integrity Protection: authorization_details SHOULD be signed when transmitted through untrusted channels (e.g., browser redirects). Use JAR or PAR for protection.¶
• Length Considerations: Rego policies may be large. Implementations SHOULD use PAR or JAR to avoid URL length limitations.¶
• RAR Type Validation: AS MUST validate that the type field is "rego_policy" and reject unknown types.¶

9.1. Policy Injection

Rego policies submitted by clients are executable code. The AS MUST:¶

• Validate policy syntax before registration;¶
• Execute policies in sandboxed environments;¶
• Limit policy execution 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.¶

10.1. RAR Authorization Data Type Registration

This specification registers the following authorization data type in the "OAuth Authorization Data Types" registry established by 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¶