Setup an OpenID Connect Provider

Introduction

As outlined in the Platform Overview, the MATTR Platform allows a user to bootstrap into their existing infrastructure using Platform Extensions.

The first of these Platform Extensions comes in the form of OIDC Bridge. This Extension allows a user to leverage their existing identity management infrastructure in order to obtain Verifiable Credentials. If you are unfamiliar with OpenID Connect (OIDC), there are many excellent guides available online.

In order to issue your first custom Verifiable Credential, you will first need to configure a standard OpenID Connect Provider (OP).

OpenID Connect Providers

The following capabilites specified by OIDC Core are required to work with the issuance flow.

  • Must support Authorisation Code flow
  • Must support the state parameter

For the purpose of this tutorial, we will utilize a cloud-based identity management solution, Auth0.

Pre-Requisites

First sign up with Auth0 Or, use your own compatible OIDC Provider.

Once you have your free tenant set up, follow these steps to configure your instance.

Configure Auth0

For this exercise, skip the Auth0 onboarding tutorials and go straight to your Dashboard.

Create a New Application. Name it something meaningful.

We will be connecting to a 'Regular web applications'.

Create application

Skip the 'Quick Start'.

Navigate to the 'Settings' tab.

Update the 'Allowed Callback URLs' to include your MATTR Tenant URL + 'v1/oauth/federated/callback'.

https://tenant.platform.mattr.global/v1/oauth/federated/callback

Make note of:

  • Domain
  • Client ID
  • Client Secret

Setup a Connection and Add Users

This is where Auth0 is used to store and hold user information, including PII. Before you add details about users, make sure you understand Auth0's policies around storing this information.

In Connections

  • Leave Database, Username-Password-Authentication Enabled
  • Disable the Social login

In Users & Roles

Create User:

  • Provide an email address, that is different to the Admin account used to sign up with Auth0
  • Add a password
  • Leave Connection as 'Username-Password-Authentication'

In Details for the new user

This is where we can add in additional information about a user to appear in the ID Token ultimately will appear in the issued Verifiable Credential.

  • Scroll down to user_metadata
  • Add claims about the user that you want to see represented in the ID token.

For example:

{
"educationalCredentialAwarded": "Certificate Name"
}

In Rules

Create a new rule

  • Start with an Empty Rule
  • Give it a meaning full name
  • For each attribute in the user_metadata add a mapping to an idToken claim.

    Note Auth0 enforces a namespace for custom claims, use the full domain of your MATTR Identity Agent

Example code

function (user, context, callback) {
const namespace = 'https://tenant.platform.mattr.global/';
context.idToken[namespace + 'educationalCredentialAwarded'] = user.user_metadata.educationalCredentialAwarded;
callback(null, user, context);
}

New Rule

Try it out

Before we connect to the MATTR Identity Agent, let's test the Auth0 configuration.

In a new browser window, navigate to the /authorize endpoint:

https://dev-rol4woao.au.auth0.com/authorize
?scope=openid%20profile
&response_type=code
&client_id=vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN
&state=xqw2Lcafhx0NIoX0
&prompt=login
&redirect_uri=https://tenant.platform.mattr.global/v1/oauth/federated/callback

Authenticate in Auth0 with a user you have setup

Auth0 login

The redirect to the MATTR Identity Agent will fail, however you can still retrieve the code from the query parameter: Example

https://tenant.platform.mattr.global/v1/oauth/federated/callback?code=oLxCRk2oPgfR8QU3&state=xqw2Lcafhx0NIoX0

Construct a request to the /token endpoint of your Auth0 tenant:

POST https://dev-rol4woao.au.auth0.com/oauth/token

Request

code=oLxCRk2oPgfR8QU3
client_id=vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN
grant_type=authorization_code
redirect_uri=https://tenant.platform.mattr.global/v1/oauth/federated/callback
client_secret=QNwfa4Yi4Im9zy1u_15n7SzWKt-9G5cdH0r1bONRpUPfN-UIRaaXv_90z8V6-OjH

Response

{
"access_token": "-vtm3ahlh9k_V2uDjnZ5r2MPbKRaHpA1",
"id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlJUVXdOVEpCTXpJNFJUTTNNVGt4TURnNU5EVTJRamRETlRVNVJrWTNNamMyTTBWRU1FVkJPUSJ9.eyJodHRwczovL215dGVuYW50Lm1hdHRyLmdsb2JhbC90cmFpbmluZ0NlcnQiOiJQYXNzZWQgQSsiLCJuaWNrbmFtZSI6Im1lIiwibmFtZSI6Im1lQGVtYWlsLmNvbSIsInBpY3R1cmUiOiJodHRwczovL3MuZ3JhdmF0YXIuY29tL2F2YXRhci84ZjlkYzA0ZTZhYmRjYzlmZWE1M2U4MTk0NWM3Mjk0Yj9zPTQ4MCZyPXBnJmQ9aHR0cHMlM0ElMkYlMkZjZG4uYXV0aDAuY29tJTJGYXZhdGFycyUyRm1lLnBuZyIsInVwZGF0ZWRfYXQiOiIyMDIwLTA0LTMwVDA3OjUxOjA4Ljk0MloiLCJpc3MiOiJodHRwczovL2Rldi1yb2w0d29hby5hdS5hdXRoMC5jb20vIiwic3ViIjoiYXV0aDB8NWU2NmVjZjZlNWNjZjUwY2QwMDNmZjIwIiwiYXVkIjoidkowU0NLY2hyNFhqQzB4SE5FOERrSDZQbWxnMmxrQ04iLCJpYXQiOjE1ODgyMzQwNzEsImV4cCI6MTU4ODI3MDA3MX0.KLrMUoqz5mrvNQQ3K09eFijVg3qkmT17R_zOUvVhtfC8LvUWaBYpszQ7j3x3zCZ1TsS4ATS68kcxLfSbq7A71atYVzwjKvGwGce9IjH7cRKyIO8Z1RAcSCw7ncXBOzT_O20sH3BV_ZgPHEJA2PreKQERKjcKSCHJeRaPyqVbh2v2lSHYCm6e8HdB8v_Zq0looLvxS5afQ8PMn3k36COo13F4zvLuUn9is--B-SRUqUjSX6-KOvULa1HXbQVnO6RUNiijQSbN-ZLA_6TRQC8BKoT3-8v1cLSb49sZOXGSBHkkNHGBhMXeJuw4iD8IjYQWpcXlVRQHuCQwFgSHxdez9w",
"scope": "openid profile",
"expires_in": 86400,
"token_type": "Bearer"
}

Copy & paste the id_token value into a tool like https://jwt.io to inspect the Payload of the ID token, there you will see your fully namespaced custom claim:

{
"https://tenant.platform.mattr.global/educationalCredentialAwarded": "Certificate Name",
"nickname": "me",
"name": "me@email.com",
"updated_at": "2020-04-30T07:51:08.942Z",
"iss": "https://dev-rol4woao.au.auth0.com/",
"sub": "auth0|5e66ecf6e5ccf50cd003ff20",
"aud": "vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN",
"iat": 1588234071,
"exp": 1588270071
}

Setup the MATTR Tenant

Make a call to POST /v1/oauth/federated/providers With using attributes from your Auth0 App configuration:

  • A meaningful name for your Auth0 App
  • Domain
  • Client ID
  • Client Secret

Request

{
"name": "your-auth0-appname",
"url": "https://your-auth0-tenant",
"clientId": "auth0_client_id",
"clientSecret": "auth0_client_secret"
}

Response

{
"id": "162b47b0-8357-11ea-8242-39dee06023c4",
"name": "your-auth0-appname",
"url": "https://your-auth0-tenant",
"clientId": "auth0_client_id",
"clientSecret": "auth0_client_secret"
}

You now have a MATTR Identity Agent configured for Verifiable Credential Issuance using an OpenID Connect Provider.