Users

Overview

Users in MATTR VII are entities that represent credential holders within the issuance system. They are created and managed automatically as part of OpenID for Verifiable Credential Issuance (OID4VCI) flows, providing a link between credentials issued by MATTR VII and the individuals or entities that hold them.

Every credential that is issued through MATTR VII via OID4VCI is associated with a specific user. This association enables issuers to maintain a relationship between the MATTR VII user and external systems, supporting various business workflows and integrations.

Possible use cases

Associating credentials with users in MATTR VII provides several important capabilities:

• Credential Tracking: Keeping an organized record regarding who has been issued which credentials.
• External Identity Mapping: Link MATTR VII users with external user identifiers in your existing systems.
• Claims Retrieval: Retrieve claims from external data stores (Claims Sources) for specific users during issuance.
• Business Workflow Integration: Trigger different business processes when credentials are issued to specific users.
• System Updates: Update external datastores when credentials are issued.
• Notifications and Billing: Trigger user-specific notifications or billing operations based on credential issuance events.

User Object Structure

A user object in MATTR VII contains the following elements:

{
  "id": "0c3fad74-a8df-4a2d-8e75-f2d356b413ba",
  "claims": {
    "externalUserId": "0c3fad74-a8df-4a2d-8e75-f2d356b413ba"
  },
  "authenticationProvider": {
    "providerId": "41458e5a-9092-40b7-9a26-d4eb43c5792f",
    "url": "https://example-university.au.auth0.com",
    "subjectId": "example-university-oauth2|123456789"
  }
}

• id: A unique identifier (UUID) for the user within MATTR VII. This ID is used to reference the user in API operations and is associated with all credentials issued to this user.

• claims: An object containing custom claims about the user. This object is dynamic and can include any key-value pairs relevant to the user. A common use case is to include an externalUserId claim that maps the MATTR VII user to an identifier in an external system. As the contents of the claims object are persistent, it is recommended to avoid including sensitive information here when creating users.

• authenticationProvider: Information about the authentication provider used to verify the user's identity (only applicable for users who have claimed credentials issued via OID4VCI Authorization code flows):

  • providerId: The unique identifier of the configured authentication provider in MATTR VII.
  • url: The URL of the authentication provider.
  • subjectId: The unique identifier for this user within the authentication provider's system.

User Creation by Issuance Workflow

User creation in MATTR VII differs based on the OID4VCI flow being used. Understanding these differences is important for properly managing users in your implementation.

Authorization Code Flow

In the Authorization Code flow, the user's identity is only known after they interact with the credential offer and complete authentication. This workflow follows these rules:

• You cannot and should not include a userId in the credential offer. The system has no way to know the user's identity until they authenticate.
• The userId is automatically allocated based on the user's unique identifier with the authentication provider (authenticationProvider.subjectId):
  • The user authenticates with the configured authentication provider.
  • MATTR VII receives the subjectId from the authentication provider.
  • The system checks for an existing user with a matching authenticationProvider.subjectId.
  • If no matching user is found, a new user is created.
  • The credential is then associated with the existing or newly created user.

This ensures that all credentials issued to the same authenticated user are associated with a single user record in MATTR VII.

Pre-Authorized Code Flow

In the Pre-Authorized Code flow, the user's identity should be known before they interact with the credential offer. This allows you to control user association explicitly.

The userId parameter in the API request to create a pre-authorized credential offer is optional, but its usage significantly affects user management.

• If you do not include a userId when creating the credential offer:
  • There is no way for MATTR VII to associate multiple credentials with the same user.
  • A new user record is created immediately when the credential offer is created, even if the credential is never claimed.
• If you do include a userId when creating the credential offer:
  • If a user already exists with this id, no new user is created, and the credential is associated with the existing user.
  • If no user exists with this id, a 400 Bad Request error is returned, indicating that the specified user does not exist.

For Pre-Authorized Code flow, it is recommended to always include a userId in your credential offer when you want to associate multiple credentials with the same user. This gives you full control over user management and enables proper tracking of credentials issued to specific individuals.