Interaction Diagrams#
Introduction#
The following interaction diagrams visualize the flow of data between components in our architecture as the user interacts with the NCCoE Bank. The flows below are cross-device flows where the user presents their mDL from the digital wallet on their phone to the NCCoE bank through a browser on a secondary device. These flows correspond to three of our wireframes videos - Applying for a Financial Account using an mDL, Setting up Online Access after Application Approval, and Identity Re-verification. The diagrams generally depict user journey “happy paths”, that is, free from error conditions or edge cases. System architects and those in similar roles may find these diagrams useful as a reference when implementing their own solutions for an individual use case.
There are interactions which take place prior to the user journeys which not demonstrated in these flows where:
mDL issuance is out of scope for this project and thus it is assumed the bank applicant has been issued a mobile driver’s license by their state issuer to a digital wallet that supports online presentation.
The Verifier system component has been configured to align with the policies of the banking system to include interaction with a Trust Service to download trusted issuers and configuration of approved wallets.
Viewing the Diagrams#
While the components in the interaction diagrams align with our architecture, they omit some components and subcomponents for brevity and clarity. We used the following color scheme to highlight important protocol interactions.
OpenID Connect
OpenID for Verifiable Presentations
Click the diagram to expand it. Once expanded, you can zoom in or out using your mouse scroll wheel and pan by clicking and dragging the diagram.
Comments and feedback are welcomed.
Flow 1 - Applying for a Financial Account using an mDL#
This flow details what happens when a user applies for a financial account and verifies their identity with an mDL. For a visualization of this process, please view our wireframe video. The account application interactions are divided into three sections:
Part 1 - Initiating the application process in the identity management system triggered by the banking website
Part 2 - mDL verification steps via the Digital Credentials API
Part 3 - Collection of additional user identity information and application completion
The attribute retrieval session identifier referenced in the Part 2 (steps 8-12) interaction diagram is the identifier returned by the Verifier when verification is complete. The session identifier is then used to retrieve the verification results. Refer to our technology partner for additional details.
Cross Device Financial Account Application Flow#
Part 1 - User Initiates Application Process#
%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#1f77b4", "edgeLabelBackground":"#ffffff", "actorTextColor": "#ffffff", "actorBackground": "#2ca02c", "fontSize":"30px"}}}%%
sequenceDiagram
autonumber
%%box Issuing Authority
%% participant sor as System of Record
%%participant iaendpoints as mDL Issuing Endpoints
%%end
box Mobile Device
participant wallet as Wallet App
end
box Web Browser
%% participant browser as Digital Credentials API
participant webapp as Banking Single Page Application
end
box Identity Management System (IDMS)
participant idp as Identity Provider
participant bpl as Bank Provisioning Logic
participant sdk as Verifier SDK
end
box Financial Institution Banking System
participant backend as Banking Backend
%% participant cbs as Core Banking Services
%% participant database as Data Storage
%% participant bankapi as IDMS Provisioning API
%% participant ssn as SSN Validation Service
end
%%box Verifier
%% participant adminendpoints as Tenant Administration Endpoints
%% participant verifier as Verifier Endpoints
%% end
%%box Trust Service
%% participant dts as Digital Trust Service
%%end
%%note over wallet,verifier: ... ↑ ...
note over webapp: Applicant navigates to the banking site to begin the scenario <br />where they choose a banking product application.<br /> The interactions begin with the browser redirect <br /> to the demonstration IDMS.
%%note over wallet,verifier: ... ↓ ...
rect rgb(0,255,0)
backend->>webapp: OpenID Connect Authorization Request redirect response
webapp-)idp: OpenID Connect Authorization Request sent
end
idp->>bpl: Invoke Application form
%%note over wallet,verifier: ... ↑ ...
note over webapp: Applicant completes initial workflow <br /> submitting email and telephone number <br />that are stored in the applicant's <br /> directory entry.
%%note over wallet,verifier: ... ↓ ...
bpl->>webapp: Social Security Number form rendered
webapp->>bpl: Applicant submits Social Security Number
bpl->>bpl: Store Social Security Number in applicant's directory entry temporarily
bpl->>webapp: Application form identity verification workflow rendered
webapp->>bpl: Applicant consent to present mDL to the bank
Part 2 - mDL Verification Using the DC API#
%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#1f77b4", "edgeLabelBackground":"#ffffff", "actorTextColor": "#ffffff", "actorBackground": "#2ca02c", "fontSize":"30px"}}}%%
sequenceDiagram
autonumber
box Issuing Authority
%% participant sor as System of Record
%%participant iaendpoints as mDL Issuing Endpoints
end
box Mobile Device
participant wallet as Wallet App
participant os as Operating System
end
box Web Browser
participant browser as Digital Credentials API
participant webapp as Banking Single Page Application
end
box Verifier
%% participant adminendpoints as Tenant Administration Endpoints
participant verifier as Verifier Endpoints
end
box Identity Management System (IDMS)
participant idp as Identity Provider
participant bpl as Bank Provisioning Logic
participant sdk as Verifier SDK
end
box Financial Institution Banking System
%%participant backend as Banking Backend
%% participant cbs as Core Banking Services
participant database as Data Storage
participant bankapi as IDMS Provisioning API
%%participant ssn as SSN Validation Service
end
box Trust Service
%% participant dts as Digital Trust Service
end
rect rgb(217, 218, 241)
bpl->>bpl: Digital Credentials Query Language object and Challenge prepared
bpl->>sdk: requestCredentials() invoked<br /> with Digital Credentials Query Language<br /> object and Challenge
end
%%note over wallet,verifier: ... ↑ ...
note over sdk: Verifier SDK waits for Applicant to complete verification.
%%note over wallet,verifier: ... ↓ ...
rect rgb(217, 218, 241)
sdk->>browser: SDK invokes Digital Credential API with OpenID4VP Authorization Request
browser->>browser: Authorization Request rendered via QR code
end
%%note over wallet,verifier: ... ↑ ...
note over os: Applicant opens camera or wallet app on their mobile device <br />and scans the QR code presented in the browser.
%%note over wallet,verifier: ... ↓ ...
rect rgb(217, 218, 241)
browser->>os: Wallet app presentation workflow invoked
os->>os: Eligible Wallets displayed to Applicant
end
%%note over wallet,verifier: ... ↑ ...
note over os: Applicant chooses appropriate credential, <br />consents to presenting attributes, <br />and locally authenticates via biometric.
%%note over wallet,verifier: ... ↓ ...
rect rgb(217, 218, 241)
wallet->>verifier: Wallet submits <br />Authorization Response containing <br />requested attributes
end
%%note over wallet,verifier: ... ↑ ...
note over sdk: Verifier SDK callback invoked.
%%note over wallet,verifier: ... ↓ ...
verifier->>sdk: Results retrieval identifier returned
sdk->>bpl: Results retrieval identifier returned
bpl->>bankapi: Bank customer provisioning API invoked with presentation attribute retrieval identifier
%%note over wallet,verifier: ... ↑ ...
%%note over wallet,verifier: ... Azure Function not pictured for clarity ...
%%note over wallet,verifier: ... ↓ ...
bankapi->>verifier: Presentation attributes retrieved via identifier
verifier->>bankapi: Presentation attributes returned
bankapi->>database: Document Number and Issuing Authority <br /> attributes persisted as unique identifier <br /> in new record as keyed hash
bankapi->>database: Record updated with presentation <br />attributes as encrypted JSON Web Token
bankapi->>bpl: Presentation attributes returned
bpl->>bpl: Document Number and Issuing Authority attributes persisted as a keyed hash
Part 3 - Collection of Additional User Identity Information and Application Completion#
%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#1f77b4", "edgeLabelBackground":"#ffffff", "actorTextColor": "#ffffff", "actorBackground": "#2ca02c", "fontSize":"30px"}}}%%
sequenceDiagram
autonumber
box Issuing Authority
%% participant sor as System of Record
%%participant iaendpoints as mDL Issuing Endpoints
end
box Verifier
%% participant adminendpoints as Tenant Administration Endpoints
%%participant verifier as Verifier Endpoints
end
box Mobile Device
%%participant wallet as Wallet App
end
box Web Browser
%% participant browser as Digital Credentials API
participant webapp as Banking Single Page Application
end
box Identity Management System (IDMS)
participant idp as Identity Provider
participant bpl as Bank Provisioning Logic
participant sdk as Verifier SDK
end
box Financial Institution Banking System
participant backend as Banking Backend
%% participant cbs as Core Banking Services
participant database as Data Storage
participant bankapi as IDMS Provisioning API
participant ssn as SSN Validation Service
end
box Trust Service
%% participant dts as Digital Trust Service
end
%%note over wallet,verifier: ... ↑ ...
note over webapp: Applicant returns to bank account application where mDL attributes are displayed. <br /> where the interactions below resume.
%%note over wallet,verifier: ... ↓ ...
webapp->>bpl: Applicant confirms information and submits form
rect rgb(0,255,0)
bpl-)webapp: OpenID Connect Authorization response returned
webapp->>idp: Request OpenID Connect identity token
idp->>webapp: Token returned with <br />Entra GUID and acr value "Completed Account Application"
webapp->>backend: Request redirect URI with retrieved tokens
end
backend->>webapp: "Application complete" webpage rendered
backend->>idp: Graph API lookup for Document Number and Issuing Authority keyed hash via Entra GUID
idp->>backend: Document Number and Issuing Authority keyed hash returned
backend->>database: Lookup record with <br />Document Number and Issuing Authority
database->>backend: Found record returned
backend->>database: Write Social Security Number to encrypted CIP token associated with record
database->>backend: Record updated with encrypted CIP token
backend->>backend: Add record to Social Security Number verification service queue
%%note over wallet,verifier: ... ↑ ...
note over backend: Queue is executed at a predermined interval.
%%note over wallet,verifier: ... ↓ ...
backend->>ssn: Request Social Security Number verification
ssn->>backend: Social Security Number verification result returned
%%note over wallet,verifier: ... ↑ ...
note left of ssn: Social Security Number verification result valid.
%%note over wallet,verifier: ... ↓ ...
backend->>backend: Generate notification with unique URL for Applicant to continue digital enrollment
Flow 2 - Setting up Online Access after Application Approval#
This flow details the user setting up access online access to their financial account, which includes provisioning a passkey. For a visualization of this process, please view our wireframe video. The Digital Enrollment interactions are divided into two sections:
Part 1 - Initiating the digital enrollment process triggered by a notification from the banking system
Part 2 - Passkey registration and linking to the applicant
This flow and wireframe demonstrate an asynchronous process where the user submits their application, waits for approval and returns to financial institute webpage to set up online access, which requires the user to present their mDL again to link their identity with the original account application. This re-verification flow occurs in Flow 2, Part 1, Step 9 and is the same as Flow 1 - Part 2.
Cross Device Setting up Online Access#
Part 1 - Initiating the Digital Enrollment Process Triggered by a Notification from the Banking System#
%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#1f77b4", "edgeLabelBackground":"#ffffff", "actorTextColor": "#ffffff", "actorBackground": "#2ca02c", "fontSize":"30px"}}}%%
sequenceDiagram
autonumber
box Issuing Authority
%% participant sor as System of Record
%%participant iaendpoints as mDL Issuing Endpoints
end
box Mobile Device
%%participant wallet as Wallet App
end
box Web Browser
%% participant browser as Digital Credentials API
participant webauthn as Web Authentication API
participant webapp as Banking Single Page Application
end
box Identity Management System (IDMS)
participant idp as Identity Provider
participant bpl as Bank Provisioning Logic
participant sdk as Verifier SDK
end
box Financial Institution Banking System
participant backend as Banking Backend
%% participant cbs as Core Banking Services
%% participant database as Data Storage
%% participant bankapi as IDMS Provisioning API
%% participant ssn as SSN Validation Service
end
box Verifier
%% participant adminendpoints as Tenant Administration Endpoints
%%participant verifier as Verifier Endpoints
end
box Trust Service
%% participant dts as Digital Trust Service
end
%%note over wallet,verifier: ... ↑ ...
note over webapp: The applicant receives an e-mail stating that the application previously <br /> submitted has been approved. The applicant follows the instructions <br /> in the e-mail and clicks on the enclosed link to setup digital enrollment.
%%note over wallet,verifier: ... ↓ ...
webapp->>backend: Enrollee clicks digital enrollment link in approval email
backend->>backend: Lookup enrollment code and verify application status
backend->>webapp: "Welcome back" webpage rendered
webapp->>backend: Enrollee clicks "Continue"
rect rgb(0,255,0)
backend->>webapp: OpenID Connect Authorization Request redirect response
webapp-)idp: OpenID Connect Authorization Request sent
end
idp->>bpl: Invoke Digital Enrollment form
bpl->>webapp: Digital Enrollment form "Set Up Online Access" rendered
webapp->>bpl: Enrollee clicks "Next" to invoke mDL verification
bpl->>webapp: Identity verification workflow rendered
webapp->>bpl: Enrollee consents to present mDL to the bank
Part 2 - Passkey Registration and Linkage to the Applicant#
%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#1f77b4", "edgeLabelBackground":"#ffffff", "actorTextColor": "#ffffff", "actorBackground": "#2ca02c", "fontSize":"30px"}}}%%
sequenceDiagram
autonumber
box Issuing Authority
%% participant sor as System of Record
%%participant iaendpoints as mDL Issuing Endpoints
end
box Mobile Device
%%participant wallet as Wallet App
end
box Web Browser
%% participant browser as Digital Credentials API
%%participant webauthn as Web Authentication API
participant webapp as Banking Single Page Application
end
box Identity Management System (IDMS)
participant idp as Identity Provider
participant bpl as Bank Provisioning Logic
%%participant sdk as Verifier SDK
end
box Financial Institution Banking System
participant backend as Banking Backend
%% participant cbs as Core Banking Services
participant database as Data Storage
%%participant bankapi as IDMS Provisioning API
%%participant ssn as SSN Validation Service
end
box Verifier
%% participant adminendpoints as Tenant Administration Endpoints
%%participant verifier as Verifier Endpoints
end
box Trust Service
%% participant dts as Digital Trust Service
end
%%note over wallet,verifier: ... ↑ ...
note right of webapp: Enrollee returns to enrollment form and completes mDL verification<br /> flow as documented in the account application flow. <br />Banking Provisioning Logic has retrieved mDL attributes in the interactions below.
%%note over wallet,verifier: ... ↓ ...
bpl->>bpl: Document Number and Issuing Authority keyed hash lookup
bpl->>webapp: "Set up the authentication method" page rendered
webapp->>bpl: Enrollee clicks "Create a Passkey"
bpl->>webapp: Start Passkey creation flow
webapp->>bpl: Invoke navigator.credentials.create() with PublicKey and "platform" option
%%note over wallet,verifier: ... ↑ ...
note right of webapp: Enrollee completes Passkey flow, <br />depending on creation options and target platform.
%%note over wallet,verifier: ... ↓ ...
bpl->>bpl: Passkey public key persisted
bpl->>webapp: "Success" screen rendered
webapp->>webapp: "Passkey saved" notification displayed to the Enrollee
webapp->>bpl: Enrollee clicks "Go to my account"
rect rgb(0,255,0)
bpl-)webapp: OpenID Connect Authorization response returned
webapp->>idp: Request OpenID Connect Access and Identity tokens
idp->>webapp: Token returned with Entra GUID, acr "Completed Digital Enrollment",<br /> and Document Number + Issuing Authority keyed hash value claims
end
webapp->>backend: Request redirect URI with Access and Identity tokens
backend->>database: Lookup customer record <br />with Document Number <br /> and Issuing Authority keyed hash value
database->>backend: Found customer record returned
backend->>backend: Activate customer
backend->>webapp: "Account Balance" webpage rendered
Flow 3 - Re-Verification for Step-Up Flow#
The step-up verification interactions below depicts a transaction that is initially denied due to exceeding a pre-determined threshold and requests reverification of the mDL. For a visualization of this process, please view our wireframe video.
This re-verification flow that occurs at Flow 3, Step 10 and is the same as Flow 1 - Part 2.
Re-verification for Step-Up Flow#
%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#1f77b4", "edgeLabelBackground":"#ffffff", "actorTextColor": "#ffffff", "actorBackground": "#2ca02c", "fontSize":"30px"}}}%%
sequenceDiagram
autonumber
box Issuing Authority
%% participant sor as System of Record
%%participant iaendpoints as mDL Issuing Endpoints
end
box Mobile Device
%%participant wallet as Wallet App
end
box Web Browser
%% participant browser as Digital Credentials API
%%participant webauthn as Web Authentication API
participant webapp as Banking Single Page Application
end
box Identity Management System (IDMS)
participant idp as Identity Provider
participant bpl as Bank Provisioning Logic
%%participant sdk as MATTR SDK
end
box Financial Institution Banking System
participant backend as Banking Backend
%% participant cbs as Core Banking Services
participant database as Data Storage
%%participant bankapi as IDMS Provisioning API
%%participant ssn as SSN Validation Service
end
box Verifier
%% participant adminendpoints as Tenant Administration Endpoints
%%participant verifier as Verifier Endpoints
end
box Trust Service
%% participant dts as Digital Trust Service
end
webapp ->> backend: Sign in request submitted
rect rgb(0,255,0)
backend->>webapp: OpenID Connect Authorization Request redirect response
webapp-)idp: OpenID Connect Authorization Request sent
end
%%note over wallet,verifier: ... ↑ ...
note over webapp: Customer completes Passkey authentication flow, <br />depending on creation options and target platform.
%%note over wallet,verifier: ... ↓ ...
rect rgb(0,255,0)
bpl-)webapp: OpenID Connect Authorization response returned
webapp->>idp: Request OpenID Connect Access and Identity tokens
idp->>webapp: Token returned with Entra GUID and acr "Passkey Authentication" claims
end
%%note over wallet,verifier: ... ↑ ...
note over webapp: Customer returns to bank website <br /> to submit transaction that exceeds threshold
%%note over wallet,verifier: ... ↓ ...
webapp->>backend: Transaction request submitted with Access and Identity tokens
backend->>backend: Evaluate Identity token for acr claim "mDL Verification"
backend->>webapp: Deny transaction and request reverification
rect rgb(0,255,0)
webapp-)idp: OpenID Connect Authorization Request sent with mDL verification request
end
%%note over wallet,verifier: ... ↑ ...
note over webapp: Customer completes mDL verification workflow <br /> as described in Digital Enrollment
%%note over wallet,verifier: ... ↓ ...
rect rgb(0,255,0)
bpl-)webapp: OpenID Connect Authorization response returned
webapp->>idp: Request OpenID Connect Access and Identity tokens
idp->>webapp: Token returned with Entra GUID and acr "mDL Verification" claims
end
webapp->>backend: Transaction request submitted with updated Access and Identity tokens
backend->>backend: Evaluate Identity token acr claim "mDL Verification"
backend->>backend: Invoke transaction with core banking service
backend->>webapp: Transaction approval response rendered