OpenID Connect

OpenID Connect (OIDC) is an authentication protocol, based on the OAuth 2.0 specifications. While OAuth 2.0 is about resource access and sharing, OIDC is all about end-user authentication.

MIRACL Trust is a standards-compliant OpenID Connect provider. You can use any OIDC Relying Party Library to integrate with MIRACL Trust. For a list of certified OpenID Connect Libraries, see https://openid.net/developers/certified-openid-connect-implementations/.

This page provides general information about integrating with the OpenID Connect implementation provided by MIRACL Trust. For high-level information about OIDC, see https://openid.net/developers/how-connect-works/. For a full reference of all MIRACL Trust OIDC endpoints, see the OIDC API Reference.

# Quick Reference

See the full OIDC API reference.

# Configure Automatically Using Configuration Discovery

MIRACL Trust provides OpenID Connect (OIDC) configuration discovery (https://api.mpin.io/.well-known/openid-configuration). This is used for automatic configuration of your applications.

If you already have an OIDC implementation available in your application, you can easily configure it to use the MIRACL Trust service. Most clients are configured only with the issuer URL (https://api.mpin.io) and are automaticaly configured using configuration discovery.

# Configure the Authorization Endpoint

The end-user authorization endpoint in MIRACL Trust is https://api.mpin.io/authorize. An example for generated authorization URI is:

https://api.mpin.io/authorize?client_id=<YOUR_CLIENT_ID>&redirect_uri=<YOUR_REDIRECT_URI>&response_type=code&scope=openid+email

Here is a short description of the params in that URI:

• client_id - The Client ID generated on application creation in the MIRACL Trust Console. (The one mentioned in the Getting Started section)
• response_type - Determines what authorization processing flow is used.
• scope - The OIDC scopes that are used during authentication to authorize access to an end user’s details. (supported scopes).
• redirect_uri - The place where your application receives and processes the response from MIRACL.
• state - Used to maintain the state between request and callback.

For a full list of supported parameters and their descriptions, see the OIDC API Reference.

For more information, see the Authorization Endpoint section in the OIDC Specification.

# Fetch the JWKS

JSON Web Key Set (JWKS) contains the public keys that should be used to verify the ID and access JSON Web Tokens (JWT) issued by MIRACL Trust. You can fetch JWKS from https://api.mpin.io/oidc/certs.

Note that you should not hardcode the JWKS, as it is a subject of change. The OIDC client needs to fetch the JWKS dynamically in order to assure that the ID and access tokens are properly signed.

# Exchange ID and Access Tokens Using the Token Endpoint

To exchange ID and access tokens use the https://api.mpin.io/oidc/token endpoint. You have to authenticate requests with Client ID and Client Secret. The token endpoint supports basic and post authentication.

For more details, see OIDC API Reference.

# Receive Information About the Authenticated End User

To recieve information about the authenticated end user, use the https://api.mpin.io/oidc/userinfo endpoint. You must authenticate the request with an access token (returned from the token endpoint).

For more details, see OIDC API Reference.

# OIDC Authentication Flow

sequenceDiagram actor Alice participant Client as Client Web Site participant MIRACL as MIRACL Trust OIDC Issuer Alice->>Client: Request a protected resource activate Client Client-->>Alice: Redirect to the OIDC authorization endpoint Alice->>MIRACL: Open the OIDC authorization endpoint activate MIRACL MIRACL-->>Alice: Load the authentication client Alice->>MIRACL: Authenticate using M-PIN MIRACL-->>Alice: Redirect to the Redirect URL of the web site with an Access Code Alice->>Client: Open the Redirect URL Client->>MIRACL: Exchange Access Code for ID Token and Access Token MIRACL-->>Client: Return the ID Token and Access Token deactivate MIRACL Client-->>Alice: Return the protected resource deactivate Client

# OIDC Samples

For samples of integrations with MIRACL Trust using OpenID Connect for different technologies using popular open-source libraries, see https://github.com/miracl/oidc-samples/tree/master/samples.