Identity mapping

This guide describes how to use Verified Orchestration identity references, which are used by issuances and presentations to reliably link back to your organisation's own identities (e.g., internal users, partners, and customers).

Verified Orchestration identity reference

The Verified Orchestration platform minimises holding personal data. Instead, it stores and uses minimal identity references to link back into your organisation's own identity system.

This allows identity-linked issuances and presentations to be resolved by identity references, facilitating abilities such as:

Reliably resolving your organisation's own identity data (e.g. internal users, partners and customers).
- To all issued credentials and presentations.
- To the identity of the presenter in a presentation.
The ability to find data by navigating between relations when using the API, including the relations of issuances, presentations and identities.
The ability to revoke all credentials for an identity reference.

tip

In the Composer, identity references are labelled as "Issuees".

How does it work?

Verified Orchestration assumes that your organisation has one or more identity stores. With each store having:

A unique identifier for the store. For example in Entra ID, the Tenant ID uniquely identifies the store and is available within an Entra ID JWT payload as the tid claim.
A unique identifier for each identity within a store. For example in Entra ID, the unique user Object ID is available within an Entra ID JWT payload as the oid claim.

These two values form the unique key which is used to link a Verified Orchestration identity reference back to an identity within your organisation's identity stores.

Example mapping of an Entra ID User

The table below demonstrates how an Entra ID identity store user can be mapped to a Verified Orchestration identity reference. This reference includes both the Entra ID user attributes and under which claims the values are stored by an Entra ID produced JWT.

Entra ID User Attribute	JWT Payload Claim	Verified Orchestration Identity Field
Tenant ID	`tid`	`issuer`
User Object ID	`oid`	`identifier`
User Display name	`name`	`name`

What each identity reference looks like

A name is a convenient way to make identity references easily recognisable without querying your organisation's identity stores. Providing the name is optional. However, when a name is supplied, the Composer will use it for display when creating or viewing issuances, remote issuances, and presentations.

Identity input has the following properties:

Issuer: The unique identifier for the store to which the identity belongs.
Identifier: The unique identifier for the identity within the corresponding identity store.
Name: An optional human-readable name for quick identification of the identity.

tip

Custom labels can be configured for each identity store's issuer ID. This is a convenient way to make each identity store easier to distinguish between. When set, the Composer displays these human-readable labels instead of the issuer ID. See the instance configuration guide for more information.

How to create identity references

There are two ways to create and maintain identity references: The first is to save an identity reference directly, and the second is to create an issuance or remote issuance with the identity information included. The latter can be more convenient, as the identity is saved or updated and linked to the issuance in a single operation.

Creating an identity reference

To create an identity reference, use the saveIdentity mutation:

saveIdentity mutation: saves or updates an identity by issuer and identifier
mutation SaveIdentity($input: IdentityInput!) {
  saveIdentity(input: $input) {
    id
  }
}

Example code to save an identity based on a logged in user's JWT claims
function saveIdentity(user: JwtPayload) {
  const variables = {
    issuer: user.tid,
    identifier: user.oid,
    name: user.name,
  }

  return this.client.mutate({ mutation: saveIdentityMutation, variables: variables })
}

info

The saveIdentity mutation will create a new identity when an existing one cannot be matched by the issuer and identifier fields. In the case that the identity exists, the name will be updated if changed.

Creating an identity with issuance

When creating an issuance or remote issuance, you may optionally include the identity information instead supply the Verified Orchestration's identity ID. This can be more convenient, as the identity is saved or updated and linked to the issuance in a single operation.

createIssuance mutation
mutation CreateIssuanceRequest($request: IssuanceRequestInput!) {
  createIssuanceRequest(request: $request) {
    ... on IssuanceResponse {
      requestId
      url
      qrCode
      expiry
    }
    ... on RequestErrorResponse {
      error {
        code
        message
        innererror {
          code
          message
          target
        }
      }
    }
  }
}

Example issuance input with identity information included
{
  "request": {
    "contractId": "5C9D3AC6-0D6A-4ABB-8047-9E35EAD2B3EA",
    "identity": {
      "identifier": "d93907c3-8338-4acf-b8ed-0e3e5793a7c7",
      "issuer": "a4577872-4a36-4a93-9846-b29a1220ca89",
      "name": "Ebony Lawry"
    }
  }
}

Creating non-identity store linked identity references

There may be cases where you need to create identity references for users who are not part of your organisation's identity system or identity stores. In these cases, you can manually create identity references.

We recommend using an email address as a globally unique identifier, and manual as the issuer value:

Example manual identity input
{
  "issuer": "manual",
  "identifier": "citizen@outlook.com",
  "name": "Mary Citizen"
}

tip

The Composer has special handling of identity references featuring manual as the issuer, with these being shown and label as 'Manually Issued'.

Using identity references

Once identity references are saved:

They can be used as an API entry point to find related data.
The Composer supports searching for issuances, remote issuances and presentations by linked identities.
Admin users can find, list and filter identities via the quick search or Issuees page.

Querying identity data

Identities can be queried to return one or many by using either the Verified Orchestration identity ID or your organisation's own identity data (issuer and identifier unique key).

The following queries are available:

identity finds a single identity by ID
identities finds multiple identities by ID
identityByIdentifier finds one identity by issuer and identifier unique key
identitiesByIdentifiers finds one or more identities by issuer and identifier unique key
findIdentities finds identities by issuer and name partial match

You can also simply upsert and query identities in a single operation:

saveIdentity performs an efficient upsert operation to save or update an identity by issuer and identifier unique key, data can be returned in the same operation

Example identity operations

Upsert an identity, query active issuances, pending remote issuances
mutation UpsertIdentityWithIssuances($input: IdentityInput!) {
  saveIdentity(input: $input) {
    id
    issuer
    issuerLabel
    identifier
    name
    issuances(where: { status: active }) {
      id
      issuedAt
      status
      hasFaceCheckPhoto
      contract {
        id
        name
      }
    }
    asyncIssuanceRequests(where: { status: pending }) {
      id
      createdAt
      createdBy {
        id
        name
        isApp
      }
      expiresOn
      status
      contract {
        id
        name
      }
    }
  }
}

Query an identity by ID with presentations
query IdentityWithPresentations($identityId: ID!) {
  identity(id: $identityId) {
    id
    issuer
    issuerLabel
    identifier
    name
    presentations {
      presentedAt
      presentedCredentials {
        issuer
        type
        issuer
        faceCheck {
          matchConfidenceScore
        }
      }
      requestedBy {
        id
        name
        isApp
      }
    }
  }
}

Query an identity by issuer and identifier unique key
query IdentityWithIssuances($issuerId: IssuerIdentifierInput!) {
  identityByIdentifier(issuerId: $issuerId) {
    id
    issuer
    issuerLabel
    identifier
    name
    issuances(where: { status: active }) {
      id
      issuedAt
      status
      contract {
        id
        name
      }
    }
    asyncIssuanceRequests(where: { status: pending }) {
      id
      createdAt
      expiresOn
      status
      contract {
        id
        name
      }
    }
  }
}

Query a set of identities by issuer and identifier unique key
query IdentitiesWithIssuances($issuerIds: [IssuerIdentifierInput!]!) {
  identitiesByIdentifiers(filters: $issuerIds) {
    id
    issuer
    issuerLabel
    identifier
    name
    issuances(where: { status: active }) {
      id
      issuedAt
      status
      contract {
        id
        name
      }
    }
    asyncIssuanceRequests(where: { status: pending }) {
      id
      createdAt
      expiresOn
      status
      contract {
        id
        name
      }
    }
  }
}

Verified Orchestration identity reference​

How does it work?​

Example mapping of an Entra ID User​

What each identity reference looks like​

How to create identity references​

Creating an identity reference​

Creating an identity with issuance​

Creating non-identity store linked identity references​

Using identity references​

Querying identity data​

Example identity operations​