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 TypeDescriptionKey CharacteristicsVP Token Handling
JWT-based AuthorizationStandard OpenID4VP with JWT VP tokensVP token is JWT format, optional ID tokenParses JWT structure, extracts audience and nonce
Device Response AuthorizationMobile device authorization flowsIncludes nonce parameter, device response formatTreats VP token as device response string

Format Processing Workflow

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 StepDescriptionValidation
Presence checkHandles optional ID token gracefullyReturns undefined if not provided
JWT structure parsingValidates JWT header and payload formatEnsures well-formed JWT structure
Schema validationValidates against ID token payload schemaChecks required claims (sub, aud, iss, etc.)
VP token extractionExtracts _vp_token claim when presentSupports presentation submission in ID token

VP Token Processing

Processing StepDescriptionValidation
JWT structure parsingValidates JWT header and payload formatEnsures well-formed JWT structure
Schema validationValidates against VP token payload schemaChecks required claims (iss, exp, iat, etc.)
Audience extractionExtracts optional audience claimValidates audience format when present
Nonce extractionExtracts optional nonce claimUsed for verification flow correlation

Presentation Submission Handling

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

Presentation Submission Sources

SourcePriorityDescriptionProcessing
Provided1Directly provided in authorization requestParses JSON string or object format
ID Token2Embedded in ID token _vp_token claimExtracts 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