Guide to Integrating OpenID Bridge

Learn how to integrate OpenID Bridge.

This guide describes how to integrate Procivis One OpenID Bridge with any OpenID Connect v1.0 provider.

OpenID Bridge integrations follow the same general pattern:

1. Configure your OIDC provider.

2. Choose your proof schema.

3. Create the provider in OpenID Bridge.

note

It is recommended to start with configuring the OIDC provider because it may provide unalterable values which are later required by OpenID Bridge, such as a redirect URI. Some OIDC provider configurations may allow for reversing the order of integration.

The general pattern is described here. An integration guide for Keycloak follows, with more provider-specific guides in the works.

Integrate OpenID Bridge

1. Configure your OIDC provider

1. Add a new identity provider using "OpenID Connect v1.0".

2. Set (or note) the Client ID and Client secret.

   • You will use these later when configuring OpenID Bridge.

3. Use the Discovery endpoint from OpenID Bridge to provide metadata to your OIDC provider.

   • https://{YOUR-BRIDGE-URL}/.well-known/openid-configuration

4. Set (or note) the OIDC redirect URI.

   • You will use this later when configuring OpenID Bridge.

5. Set the client redirect URI, so your OIDC provider knows where to send users on login.

2. Choose your proof schema

Each provider uses one proof schema as the basis for the information it requests from users attempting to log in. When a user initiates a login with OpenID Bridge, the system creates a proof request and generates a QR code to share with the end user.

When choosing (or creating a new) proof schema to use with OpenID Bridge, choose one that asks the user for the claims to be provided to OIDC. OpenID Bridge supports the following standard OIDC claims:

• subject
• family_name
• given_name
• birthdate
• email
• phone_number

When creating the provider in OpenID Bridge, any claim from the chosen proof schema can be mapped to any of the supported claims above.

3. Create the provider in OpenID Bridge

note

This section describes the creation of an OpenID provider using the OpenID Bridge endpoints. OpenID providers can also be created and managed using the Desk API. See the OpenID providers resource for more on using those endpoints.

If using the Desk API endpoints to create the provider in OpenID Bridge, the instructions in this guide mostly still apply, but:

• Use the Desk API's corresponding path: /api/openid-provider/v1.
• The organisationId field is not present in the Desk API endpoints since it uses your active organization.

Create a new provider in OpenID Bridge by calling POST /api/provider/v1. Use one API call to create the new provider, using request body parameters for configuration. The parameters used in the call are described below, divided by what they are used for.

Strictly required

Parameter	Description
proofSchemaId	UUID of the chosen proof schema.
didId	UUID of the DID to use for verification.
acceptedIssuerDidId	UUID of the DID to be used for issuer validation. Login credentials must be issued by this DID or login will fail.
redirectUris	The redirect URI from your OIDC provider must be passed here; additional URIs can be specified.
name	Assign an alias; must be unique within the organization.
organisationId	UUID of the organization.

Connect to OIDC

Parameter	Description
clientId	If integration is following the recommended order to configure the OIDC provider first, use the client ID provided by that configuration. If integration is starting first with Bridge, assign no value and the system will create a client ID.
clientSecret	If integration is following the recommended order to configure the OIDC provider first, use the client secret provided by that configuration. If integration is starting first with Bridge, assign no value and the system will create a client secret.

Specify grant types and scopes

API Parameter	Options	Default
scopes	[OPENID, PROFILE, EMAIL, ADDRESS, PHONE]	[OPENID, PROFILE]
grantTypes	[AUTHORIZATION_CODE, REFRESH_TOKEN, CLIENT_CREDENTIALS]	[AUTHORIZATION_CODE]

Map claims

The following table shows which parameter maps to which OIDC claim.

API parameter	OIDC standard claim
subjectMapping	subject
lastNameMapping	family_name
firstNameMapping	given_name
birthdateMapping	birthdate
emailMapping	email
phoneNumberMapping	phone_number

The mapping parameter expects the following format:

{credential schema id}--{path}

Notice the credential schema id is used, not the proof schema. This is because a proof schema can ask a wallet holder for multiple credentials. The path tells Bridge which claim to use. When no path is given, the DID of the wallet holder is mapped to the OIDC claim.

The following is an example mapping:

"subjectMapping": "ace0806f-63d5-4d14-9cbb-e16ee6e10f6e", // maps wallet holder's DID to subject
"phoneNumberMapping": "35590903-9dd6-41a3-ba80-45c4bbcebaa7--Phone no.",
"emailMapping": "321c258e-626e-4005-99ec-b924cb3b25bd--Email",

Additional parameters

Parameter	Description
postLogoutRedirectUris	Redirect URI for users logging out.
logo	Accepts base64-encoded files.
displayName	Optional alias for the provider.
privacyUrl	Specify a Privacy Policy URL.
termsUrl	Specify a Terms of Service URL.

Example API call

A retail store issues loyalty cards to customers to give them rewards and inform them of upcoming sales. To make it easier for customers to log in to the customer portal, the store wants to accept this customer loyalty card as a login.

The store uses the proof schema it already uses when customers scan in the shop. Since the customer information is already in the store's database, the surface area of the login request is small and the subject is mapped to the customer's email address. Here is the request body:

{
  "clientId": "<client-id>",
  "clientSecret": "<client-secret>",
  "didId": "b76cbe0d-f396-4fc3-9e21-930e79f12d43",
  "acceptedIssuerDidId": "8f7d3b2e-9a1c-4d5f-b6e8-c7f9d2a0x1y2",
  "redirectUris": ["https://ACMEshops.com/customer_welcome"],
  "proofSchemaId": "85c197b4-e7f5-43de-9e5c-06607c622cca",
  "organisationId": "154bc9a1-c20b-48b8-a82b-4f13f35e9899",
  "name": "Customer Portal Login",
  "grantTypes": ["AUTHORIZATION_CODE"],
  "scopes": ["OPENID"],
  "subjectMapping": "ace0806f-63d5-4d14-9cbb-e16ee6e10f6e--Email",
  "displayName": "Login with ACME",
  "postLogoutRedirectUris": ["https://ACMEshops.com/customer_goodbye"]
}

Integration considerations

For use cases with higher security needs, the store in the example above could issue the customer card with hardware-binding. In this case, login can only be completed by the device to which the original customer card was issued.

For use cases where there is no existing information in a database, the login can be used to gather necessary information about the new user. Use an existing credential such as a government issued ID, map the subject to the holder's DID, and request basic information such as name, email address and phone number.

Manage providers

Update a provider

Once created the following fields of a provider are fixed and cannot be changed:

• name
• proofSchemaId
• organisation
• clientId

All other fields can be updated via PATCH on the /api/openid-provider/v1/{providerID} endpoint.

Regenerate client secret

Client secrets can be updated for security.

If the new client secret is coming from the OIDC provider, update the provider with the new secret.

A new client secret can also be generated by OpenID Bridge. Call POST to the /api/openid-provider/v1/:providerId/regenerate-secret endpoint with the provider's UUID as a path parameter and a new client secret is returned.

tip

Whether generating a new secret in the OIDC provider or in OpenID Bridge, remember to update the secret in the other one.

History

The system records most events related to providers and login attempts. See the History guide for a full reference of what's recorded and how to search events.