Authentication

Your Verified Orchestration instance includes an OpenID Connect (OIDC) authentication provider, allowing applications to use credential presentation for authentication.

This feature supports:

• Administrative control over authentication clients:
  • What types of credentials can be presented
  • Use of partner credentials for authentication
  • Use of face check for biometric authentication
• Dynamic control over authentication within applications:
  • What partner credentials can be presented
  • What credential types can be presented
  • Whether face check is required for biometric authentication
  • Arbitrary constraints on claims, e.g. limiting authentication to a specific identity
• Configuration of resources to protect access to backend services e.g. APIs:
  • Define resources with scopes
  • Configuration of client access to resources

Administration of clients and resources

To administer authentication, you must be granted access to user role VerifiableCredential.OidcAdmin.

The Composer authentication page displays the:

1. OpenID Connect provider details:
   • Authority URL
   • Discovery URL
2. List of authentication clients
3. List of resources

Create an authentication client

Each application that requires authentication needs an authentication client.

1. Navigate to the Composer authentication page.
2. Click the Add button above the client list.
3. Type a Name for the client. This name is shown to users when they sign-in and sign-out.
4. Type one or more Redirect URIs the client is allowed to use.
5. Type one or more Log out URIs the client is allowed to use.

Demo 🎥

Add authentication to an application

Exactly how you add authentication to an application depends on the application's technology stack and which authentication library you choose to use.

The Verified Orchestration OIDC provider currently only supports the Authorization Code Grant with Proof Key for Code Exchange (PKCE) flow for web clients.

The authentication client view page contains code samples for both front-end authentication using react-oidc-context and server-side authentication using openid-client.

You can copy the sample code and paste it into your application. Any library supporting the PKCE flow should work with Verified Orchestration authentication. Choose the most appropriate library for your stack and reference the code samples for example configuration.

Demo 🎥

This demo shows how to add authentication to a React application using the react-oidc-context library.

Server-side authentication

Server side authentication implementations vary wildly depending on the technology stack. The server-side authentication code sample can be pasted straight into an Express.js application, for a basic working example of server-side PKCE.

Control authentication within an application

The Verified Orchestration OIDC provider allows you to control authentication behaviour within an application by providing additional parameters.

The following parameter configuration forces the user to present a credential of type passport from a partner issuer, requires a biometric face check and constrains the presentation to a single passport number:

const signInWithPassport = useCallback(
  () =>
    signinRedirect({
      redirect_uri: window.location.origin + window.location.pathname,
      extraQueryParams: {
        vc_type: 'passport',
        vc_issuer: 'did:web:example.country.gov',
        vc_unique_claim_for_sub: 'passportNumber',
        vc_facecheck: true,
        vc_constraint_name: 'passportNumber',
        vc_constraint_operator: 'values',
        vc_constraint_value: '123456789',
      },
    }),
  [signinRedirect],

Authentication control parameters

Parameter	Description
vc_type	The type of credential to be presented. Note: If a single type is configured with the client, it need not be specified.
vc_facecheck	Whether face check is required for biometric authentication. Note: If forced via client configuration, it need not be specified.
vc_issuer	The partner issuer DID (authenticating using partner credentials). Note: vc_unique_claim_for_sub must also be supplied or values configured with the client.
vc_unique_claim_for_sub	The claim from which a unique identifier can be derived when authenticating using partner credentials. Note: Only required for partner credentials when values are not configured with the client or one specific claim needs to be used.
vc_constraint_name	The claim key to match when applying a constraint value as specified by vc_constraint_operator and vc_constraint_value.
vc_constraint_operator	The constraint operator which specifies how the constraint is applied, either one of: contains: The constraint evaluates to true if the claim value contains the specified value. startsWith: The constraint evaluates to true if the claim value starts with the specified value. values: Set of values that should match the claim value. If you specify multiple values, like red,green,blue it's a match if the claim value in the credential has any of the values in the collection.
vc_constraint_value	A single constraint value, e.g. 123. When using values operator, several values can be specified using a comma to separate, e.g. 123,456,789 to specify a match on either 123, 456, or 789, but not 999. The value oidc:login_hint will dynamically resolve at runtime and be substituted in place of the original value.

Demo 🎥

This demo shows use of various authentication control parameters.

Protect resources

Resources can be defined with scopes to control access from clients. This provides the ability to protect access to backend services, e.g. APIs.

Add a resource

1. Navigate to the Composer authentication page.
2. Click the Add button above the resource list.
3. Type a Name for the resource.
4. Type the Redirect indicator URI.
5. Type one or more Scopes to use for resource authorization.

Configure client resource access

1. Navigate to the Composer authentication page.
2. Click the Details button for the client you want to configure.
3. Click the Add resource button.
4. Select the Resource you want to add.
5. Select the Scopes that this client can request.
6. Click Add.

Request resource access

1. When authenticating, specify the resource parameter with the Resource indicator URI.
2. Specify one or more resource scopes in the scope parameter.
3. The client will receive an access token with the requested scopes and the audience claim aud set to the resource indicator. This access token can be used to access the resource (e.g. API).

const settings: OidcClientSettings = {
  client_id: '2f93583c-dd81-40b5-8c86-37d5c090f6e1',
  authority: 'https://demo.api.verifiedorchestration.com/oidc',
  redirect_uri: 'http://localhost:5173/',
  post_logout_redirect_uri: 'http://localhost:5173/',
  resource: 'https://example.com/api',
  scope: 'openid profile offline_access vc_info vc_presented_attributes vc_vo_presentation vc_vo_identity api:read api:write',
}

Demo 🎥

This demo shows how to set up resources, configure access for a client and obtain an access token for the resource.

Scopes and claims

Claims are organised by scopes, which are used to request specific information about the credential presentation.

Claims and scopes are both predefined (static) and configurable (dynamic):

• Predefined claims and scopes are based on standard credential presentation data (see definition below).
• Configurable claims and scopes are based on:
  • Resource definitions and scopes
  • Mapped claims and scopes

The complete list of available scopes and claims is shown in the OpenID discovery document at /oidc/.well-known/openid-configuration.

The Verified Orchestration OIDC provider supports standard OIDC scopes: openid, profile and offline_access*.

Additionally, credential info is available via the following scopes:

Scope	Description
vc_info	Standard verifiable credential info
vc_presented_attributes	Claim values from the credential presentation
vc_vo_presentation	Verified Orchestration presentation details
vc_vo_identity	Verified Orchestration identity details

note

* The offline_access scope is automatically included, granted, and does not require consent.

Claims

The Verified Orchestration OIDC provider supports both predefined (static) and mapped (configurable) claims:

1. Predefined claims
2. Mapped claims

Predefined claims

The following table describes the predefined claims and the scope required to access them:

Claim	Scope	Description
sub	openid	The subject identifier, derived from the Verified Orchestration issuance ID. Or, for partner credential presentations: - the value of the vc_unique_claim_for_sub parameter - the first matching Unique claim for subject identifier configured on the client
name	profile	The Verified Orchestration identity name (n/a for partner presentations).
vc_issuer	vc_info	The issuer DID of the verifiable credential.
vc_type	vc_info	Array: the type(s) of the verifiable credential.
vc_revocation_status	vc_info	The revocation status of the verifiable credential, either VALID or REVOKED.
vc_presented_attributes	vc_presented_attributes	All claims from the verifiable credential presentation as a single object.
vc_vo_presentation_id	vc_vo_presentation	The Verified Orchestration presentation ID.
vc_vo_issuance_id	vc_vo_presentation	The Verified Orchestration issuance ID.
vc_vo_credential_supports_facecheck	vc_vo_presentation	The presented credential has a photo claim and the VO instance supports face check.
vc_vo_facecheck_match_confidence_score	vc_vo_presentation	The confidence score of the face check match, when available.
vc_vo_identity_id	vc_vo_identity	The Verified Orchestration identity ID. Useful for referencing the identity reference in the Verified Orchestration platform.
vc_vo_identity_issuer	vc_vo_identity	The identity issuer value. Useful for referencing the source identity store.
vc_vo_identity_identifier	vc_vo_identity	The identity identifier value. Useful for referencing the identity in the source identity store.

Mapped claims

If you need verifiable credential presentation claim values returned as individual top-level OIDC claims, instead of nested within the single claim vc_presented_attributes value, you can define and apply OIDC claim mapping:

1. Navigate to the Composer claim mappings page.
2. Create one or more claim mappings, specifying the scope, claim name and the source claim from the verifiable credential.
3. Optionally specify credential types that the mapping applies to, or leave it empty to apply to all credential types.
4. Navigate to the Composer authentication clients page.
5. Edit your authentication client and select the claim mappings you want to apply to the client.

Once you have defined the claim mappings and applied them to clients, the scopes and claims will be shown in the OpenID discovery document at /oidc/.well-known/openid-configuration.

Demo 🎥

This demo shows how to create and use a set of claim mappings.

Customize and brand your authentication client

You have the option to customize the appearance of your authentication client to align with your application’s branding by configuring a background color or adding a background image for a more personalized user experience.

Customization options

• Background Color: Set a color to match your application's theme using a color picker or hexadecimal code.
• Background Image: Upload a background image to add a personal touch or a brand-specific aesthetic.

How to customize

1. Navigate to the Composer authentication page.
2. Select the client you want to customize and click the Details button.
3. Click the Edit button.
4. Choose a Background Color and upload a Background Image.
5. Save the changes.

Customization guidelines

To ensure a seamless and professional appearance when customizing your authentication client, follow these guidelines for configuring background images and colors.

Property	Guideline
Resolution	1920×1080 (16:9)
File Format	JPEG or PNG
File Size	≤ 500 KB
Aspect Ratio	Maintain a 16:9 aspect ratio for best fit.
Content Position	Keep critical content centered to avoid cropping.
Fallback Color	Ensure the background color matches your brand palette to maintain a consistent visual identity.

Recommendations

• Background Image: Use high-resolution images with a 16:9 aspect ratio to ensure the image displays properly across different screen sizes.
• Safe Margins: Keep important content, such as logos or text, away from the edges to prevent it from being cropped on various devices.
• Fallback Color: Choose a fallback background color that complements your background image.