Credential Refresh
Credential refresh is offered as a closed beta feature, and is not generally available yet. As such, functionality may be limited, may not work in all scenarios, and could change or break without prior notice. If you are interested in participating in the closed beta, please contact us.
Overview
Credential Refresh enables a wallet to claim new instances of credentials without requiring the user to authenticate again.
This capability supports several use cases:
- Validity extension: Silently refresh credentials before they expire to extend their validity period.
- Data synchronization: Obtain credentials with the most up-to-date information as the issuer's data changes.
- Improved user experience: Eliminate repeated authentication flows for credential re-issuance.
Credential Refresh behavior depends on the holder implementation. For example, a silent refresh only occurs if the wallet’s authentication policy allows it without user interaction. Issuers should assess holder capabilities and security policies before enabling Credential Refresh.
How it works
To understand how Credential Refresh works, you need to understand the orchestration steps that occur between a wallet and an issuer in OpenID for Verifiable Credential Issuance (OID4VCI):
- The wallet calls the Token endpoint with an Authorization Code (provided with the credential offer in Pre-authorized Code flows or from the authentication provider in Authorization Code flows).
- If the Authorization Code is valid, the issuer returns an access token.
- The wallet uses this access token to call the Credential endpoint, which triggers the issuance workflow and returns the issued credential to the wallet.
Enabling Credential Refresh
MATTR VII issues a credential as refreshable when two conditions are met:
- The credential configuration enables refresh: Set
refreshPolicy.enabledtotruein the credential configuration to define that issued credentials are refreshable. - The wallet provides a DPoP token: When calling the Token endpoint with their Authorization Code, the wallet must provide a DPoP (Demonstrating Proof-of-Possession) token.
DPoP is critical for credential refresh because it cryptographically binds tokens to the wallet's key material. This ensures that refresh tokens can only be used by the specific wallet that originally claimed the credential, preventing token theft and replay attacks.
The refresh flow
Once the above conditions are met:
- When the wallet hits the token endpoint, the MATTR VII issuance tenant returns a refresh token alongside the issued credential. The refresh token is specific to the claiming wallet and credentials included in the credential configuration.
- The wallet can later call the Token endpoint again with a DPoP token, but instead of providing an Authorization Code, they provide the refresh token received from the issuer.
In this scenario, the issuer would also return a new refresh token alongside the newly issued access token, allowing the wallet to continue refreshing in the future.
- The issuer validates the combination of DPoP and refresh token, and issues a new credential based on the same credential configuration.
- The new credential includes the most up-to-date information available based on:
- The claims mapping in the credential configuration.
- Validity dates.
- Any information stored in configured claim sources.
- In Authorization Code flows, any updated information from the authentication provider is not available during refresh.
- Any ephemeral claims passed during the original issuance flow would also not be available upon refresh.
Refresh tokens remain valid until revoked. However, if the credential configuration is changed to no longer support refresh, credential refresh would fail even if the refresh token has not been revoked.
How would you rate this page?