Making use of Users in MATTR VII Issuance workflows

Overview

This guide demonstrates how to leverage the MATTR VII Users concept throughout the credential issuance lifecycle. By properly managing user associations at each phase (before, during, and after issuance) you can maintain relationships between your external user identifiers and credentials, retrieve user-specific claims from external data sources, and trigger downstream business processes based on credential issuance events:

• Before issuing the credential: Ensure the credential is associated with the correct user in MATTR VII.
• During credential issuance:
  • Retrieve user-specific claims from external data sources to populate the issued credential.
  • Create dynamic, user-specific interactions as part of the issuance process.
• After credential issuance: Trigger downstream business processes based on the user associated with the issued credential.

The approach differs depending on whether you're using Pre-Authorized Code flow or Authorization Code flow, as explained in each section below.

Before Issuing the Credential

Ensure that the credential will be associated with the correct user in MATTR VII before initiating the issuance process.

In Authorization Code flows user association happens automatically based on the user identifier returned from the authentication provider.

In Pre-authorized Code flows you must explicitly manage user associations before creating the credential offer. This ensures that multiple credentials issued to the same individual are properly linked to a single user record.

POST /v1/users/search

{
  "claims": {
    "externalUserId": "945214ad-3635-4aff-b51d-61d69a3c8eee"
  }
}

{
  "data": []
}

{
  "data": [
    {
      "id": "19bf8183-a9dc-41cd-9336-1f5d19f1ae3d", 
      "claims": {
        "externalUserId": "945214ad-3635-4aff-b51d-61d69a3c8eee"
      }
    }
  ],
  "nextCursor": "Y3JlYXRlZEF0PTIwM..."
}

POST /v1/users

{
  "claims": {
    "externalUserId": "945214ad-3635-4aff-b51d-61d69a3c8eee"
  }
}

{
  "id": "19bf8183-a9dc-41cd-9336-1f5d19f1ae3d", 
  "claims": {
    "externalUserId": "945214ad-3635-4aff-b51d-61d69a3c8eee"
  }
}

POST /v1/openid/offers/pre-authorized

{
  "credentials": [
    "946c4d4a-289b-4d14-8082-41b6bf749c35"
  ],
  "userId": "19bf8183-a9dc-41cd-9336-1f5d19f1ae3d", 
  "claims": {},
  "claimsToPersist": [],
  "expiresIn": {
    "minutes": 5,
    "seconds": 0
  }
}

Authorization Code Flow

In Authorization Code flows, user association is handled automatically. When a user authenticates, MATTR VII:

1. Receives the authenticated user's subject identifier from the authentication provider.
2. Stores this identifier in the authenticationProvider.subjectId field of the user object.
3. Checks for an existing user with a matching authenticationProvider.subjectId.
4. Creates a new user if no match is found, or uses the existing user if it is found.
5. Associates the credential with this user.

No manual user management is required in this flow.

During Credential Issuance

Retrieve user-specific information from external systems during the issuance process when using a Claims source or an Interaction hook (Interaction hooks are only available in Authorization Code issuance flows).

Pre-Authorized Code Flow

In Pre-Authorized Code flows, include the user's unique external identifier in the credential offer by mapping it into the claims object. When you've configured a Claims Source, MATTR VII can use this external identifier to retrieve user-specific data from your external systems and use them in the credential issuance process.

How It Works

1. A user initiates credential issuance via a Pre-Authorized Code flow.
2. MATTR VII identifies the associated user record using the userId provided in the credential offer.
3. MATTR VII extracts the externalUserId from the user's claims object.
4. MATTR VII calls the configured Claims Source, passing externalUserId as a request parameter.
5. Your Claims Source uses this identifier to look up user-specific data in your systems.
6. The retrieved claims are used in the credential issuance process according to your credential configuration's claim mapping.

Authorization Code Flow

In Authorization Code flows, your Claims Source or interaction hook custom component must be able to map the authenticationProvider.subjectId (the identifier returned from the authentication provider) into the specific user data entry in your external systems.

How It Works

1. A user initiates credential issuance via an Authorization Code flow and authenticates with the configured Authentication provider.
2. MATTR VII identifies the associated user record using the authenticationProvider.subjectId.
3. MATTR VII calls the configured Claims Source, passing the authentication provider's subject identifier.
4. Your Claims Source maps this authentication identifier to your external user identifier.
5. Your Claims Source uses the mapped identifier to look up user-specific data.
6. The retrieved claims are used in the credential issuance process according to your credential configuration's claim mapping.

The same workflow applies when a configured interaction hook component requires user-specific data during the issuance process.

Configuring Your Claims Source Mapping

In your Claims Source configuration, map the user's external identifier claim to a request parameter that will be sent to your Claims Source server:

POST /v1/claim-sources

{
    "name": "My Claims source",
    "url": "<CLAIM_SOURCE_URL>",
    "authorization": {
        "type": "api-key",
        "value": "supersecretapikey"
    },
    "requestMethod": "GET",
    "requestParameters": { 
        "userId": { 
            "mapFrom": "claims.externalUserId"
        } 
    }
}

MATTR VII includes the mapped parameter in the request to your Claims Source. The Claims Source uses it to fetch and return user-specific claims. MATTR VII then applies these claims to populate the credential according to the credential configuration.

For more information on configuring a Claim source, refer to the overview page and the tutorial.

After Credential Issuance

Use Webhooks to trigger downstream business processes and workflows based on credential issuance events. The webhook payload includes information about the user the credential was issued to, which differs based on the issuance flow:

• In Pre-Authorized Code flows, the webhook payload includes the external identifier you provided as part of the credential offer. This allows you to directly correlate the issuance event with your external systems.
• In Authorization Code flows, the webhook payload includes the authenticationProvider.subjectId from the authentication provider. You'll need to map this identifier to the corresponding identifiers in your downstream business systems and processes.

Retrieving User Credentials metadata

Another useful operation after credential issuance is retrieving all credentials associated with a specific user. This can be used to audit issued credentials, manage revocations, or analyze user activity.

POST /v1/users/search

{
  "claims": {
    "externalUserId": "945214ad-3635-4aff-b51d-61d69a3c8eee"
  }
}

GET /v1/users/{userId}/credentials

Implementing Webhook Handlers

MATTR VII can send webhook notifications for successful credential issuance events. These webhook payloads include the user ID and claims, allowing you to trigger business workflows in your downstream applications.

{
  "format": "mso_mdoc",
  "userId": "19bf8183-a9dc-41cd-9336-1f5d19f1ae3d", 
  "credentialProfile": "mobile",
  "credentialConfigurationId": "1d8c7ad7-84ce-4519-8365-7af986e4ee0e",
  "credentialId": "26b902fc-c1bd-4178-a228-4623b1e3ebee",
  "userClaims": {
    "externalUserId": "945214ad-3635-4aff-b51d-61d69a3c8eee" // [!code focus] // Pre-Auth flow
  },
  "credential": "{base64url_encoded_credential}"
}

Best Practices

1. Avoid duplicates: Use existing user records whenever possible instead of creating new ones. When in doubt, search for the user first.
2. Store User IDs Securely: Maintain a secure mapping between your external user identifiers and MATTR VII user IDs in your systems.
3. Include User ID in Pre-Auth Offers: Always include the userId parameter when creating pre-authorized credential offers to ensure proper user association.
4. Use Consistent External Identifiers: Use stable, unique identifiers from your systems (such as GUIDs or user IDs) rather than potentially changing values like email addresses.
5. Implement Idempotent Webhook Handlers: Design your webhook handlers to be idempotent, as webhook notifications may be delivered multiple times.
6. Monitor User Creation Patterns: Regularly review user creation patterns to ensure your integration is working as expected and not creating duplicate users.
7. Handle Race Conditions: In high-concurrency scenarios, implement appropriate locking or conflict resolution strategies when searching for and creating users.