Format Policy Reference

This reference documents the format policy for the authorizer service. The format policy parses and formats authorization request data into a structured format that can be processed by other authorizer policies, handling JWT parsing, presentation submission processing, and data normalization.

Policy Overview

The format policy is the foundational component of the authorization workflow that prepares incoming authorization request data for processing. Rather than delegating to external services, this policy performs direct parsing and formatting of the authorization request elements to create a standardized data structure.

The policy’s primary responsibilities include:

• JWT parsing: Parsing and validating ID tokens and VP tokens in JWT format
• Presentation submission processing: Parsing and validating presentation submission data
• Data normalization: Converting different input formats into a consistent structure
• Input validation: Ensuring required authorization request elements are present and well-formed
• Device response handling: Supporting both JWT-based and device response authorization flows

The format policy must succeed before other authorizer policies (validate and verify) can execute, as they depend on the structured data it produces.

Supported Authorization Types

The format policy handles different types of authorization requests based on the presence of specific data elements:

Authorization Type	Description	Key Characteristics	VP Token Handling
JWT-based Authorization	Standard OpenID4VP with JWT VP tokens	VP token is JWT format, optional ID token	Parses JWT structure, extracts audience and nonce
Device Response Authorization	Mobile device authorization flows	Includes nonce parameter, device response format	Treats VP token as device response string

Format Processing Workflow

flowchart TD
    subgraph "Format Policy Processing"
        Input[Authorization Request] --> ParseID[Parse ID Token]
        ParseID --> ParsePS[Parse Presentation Submission]
        ParsePS --> PickPS[Pick Presentation Submission]
        PickPS --> CheckNonce{Nonce Present?}

        CheckNonce -->|Yes| DeviceFlow[Device Response Flow]
        CheckNonce -->|No| ParseVP[Parse VP Token]

        DeviceFlow --> FormatDevice[Format Device Response]
        ParseVP --> FormatJWT[Format JWT Response]

        FormatDevice --> Success[Format Success]
        FormatJWT --> Success

        ParseID -->|Error| IDError[ID Token Error]
        ParsePS -->|Error| PSError[Presentation Submission Error]
        PickPS -->|Error| PickError[Missing Submission Error]
        ParseVP -->|Error| VPError[VP Token Error]

        IDError --> Failure[Format Failure]
        PSError --> Failure
        PickError --> Failure
        VPError --> Failure
    end

    style Input fill:#f9f9f9,stroke:#333,stroke-width:1px
    style ParseID fill:#e1f5fe,stroke:#333,stroke-width:1px
    style ParsePS fill:#e1f5fe,stroke:#333,stroke-width:1px
    style PickPS fill:#e1f5fe,stroke:#333,stroke-width:1px
    style CheckNonce fill:#e1f5fe,stroke:#333,stroke-width:1px
    style DeviceFlow fill:#e8f5e8,stroke:#333,stroke-width:1px
    style ParseVP fill:#fff3e0,stroke:#333,stroke-width:1px
    style Success fill:#dcedc8,stroke:#333,stroke-width:1px
    style Failure fill:#ffcdd2,stroke:#333,stroke-width:1px

When processing authorization requests, the format policy follows these steps:

1. ID Token parsing - Validates and parses optional ID token JWT structure
2. Presentation submission parsing - Processes presentation submission from request or ID token
3. Presentation submission selection - Determines which presentation submission to use
4. Flow type detection - Identifies JWT vs. device response authorization flow
5. VP Token processing - Parses VP token according to detected flow type
6. Data structure creation - Assembles parsed data into standardized format
7. Result generation - Returns formatted data or specific parsing errors

JWT Token Processing

The format policy handles JWT parsing for both ID tokens and VP tokens using a consistent approach:

JWT Parsing Process

1. Header decoding - Validates and extracts JWT header including required kid field
2. Payload decoding - Parses JWT payload using SD-JWT decoding for selective disclosure support
3. Schema validation - Validates payload structure against expected schemas
4. Selective disclosure handling - Processes SD-JWT disclosures when present

ID Token Processing

Processing Step	Description	Validation
Presence check	Handles optional ID token gracefully	Returns undefined if not provided
JWT structure parsing	Validates JWT header and payload format	Ensures well-formed JWT structure
Schema validation	Validates against ID token payload schema	Checks required claims (sub, aud, iss, etc.)
VP token extraction	Extracts _vp_token claim when present	Supports presentation submission in ID token

VP Token Processing

Processing Step	Description	Validation
JWT structure parsing	Validates JWT header and payload format	Ensures well-formed JWT structure
Schema validation	Validates against VP token payload schema	Checks required claims (iss, exp, iat, etc.)
Audience extraction	Extracts optional audience claim	Validates audience format when present
Nonce extraction	Extracts optional nonce claim	Used for verification flow correlation

Presentation Submission Handling

The format policy manages presentation submission data from multiple sources with fallback logic:

Presentation Submission Sources

Source	Priority	Description	Processing
Provided	1	Directly provided in authorization request	Parses JSON string or object format
ID Token	2	Embedded in ID token _vp_token claim	Extracts from parsed ID token payload

Parsing Process

1. Format detection - Determines if submission is JSON string or object
2. JSON parsing - Safely parses JSON string format when necessary
3. Schema validation - Validates against DIF Presentation Exchange schema
4. Source selection - Uses provided submission or falls back to ID token
5. Error handling - Reports missing or malformed presentation submissions

Configuration

The format policy operates without external configuration as it performs direct parsing. However, its behavior is influenced by the authorization request structure and the presence of specific data elements.

Key aspects:

• No skip option: Format policy always runs as other policies depend on its output
• Input-driven behavior: Processing varies based on authorization request contents
• Error handling: Provides detailed error information for debugging

For overall authorizer configuration, see the Authorizer Configuration Reference.

Additional Resources

• Authorizer Configuration Reference
• Service Instances Reference
• Service Roles Reference
• OpenID for Verifiable Presentations - Core authorization standard
• DIF Presentation Exchange - Presentation submission schema
• RFC 7519: JSON Web Token (JWT) - JWT specification
• SD-JWT Draft - Selective disclosure JWT