OIDC Client Setup

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 user authentication.

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

This page contains information about the OpenID Connect endpoints that MIRACL Trust exposes. For higher-level information about OIDC, see https://openid.net/connect/. For information how to use these endpoints, see https://connect2id.com/learn/openid-connect.

Quick Reference

Setting Value
Configuration Discovery https://api.mpin.io/.well-known/openid-configuration
Issuer https://api.mpin.io
Authorization Endpoint https://api.mpin.io/authorize
JWKS URI https://api.mpin.io/oidc/certs
Token Endpoint https://api.mpin.io/oidc/token
Userinfo Endpoint https://api.mpin.io/oidc/userinfo

Configuration Discovery

MIRACL Trust exposes OpenID Connect (OIDC) configuration discovery (https://api.mpin.io/.well-known/openid-configuration). This can be used to automatically configure 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.

Authorization Endpoint

The user authorization endpoint for MIRACL Trust is https://api.mpin.io/authorize. A valid example of a generated authorization URI is:

https://api.mpin.io/authorize?client_id=wplkh5ertuboa&redirect_uri=https%3A%2F%2Fexample.com%2Flogin&response_type=code&scope=openid+email+profile

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

  • client_id (required) - OAuth 2.0 Client Identifier valid at the Authorization Server. It is generated when you create an app in the portal. (The one mentioned in the Get started section)
  • response_type (required) - Determines what authorization processing flow will be used.
  • scope (required) - The OIDC scopes that are used during authentication to authorize access to a user’s details (supported scopes).
  • redirect_uri (required) - The place where your application will receive and process the response from MIRACL.
  • state - It is basically being used to mitigate CSRF attacks, by cryptographically binding the value of this parameter with a browser cookie, so it’s usage is recommended.

For more information, you can visit the Authorization Endpoing section in the OIDC Specification.

Aside from the OIDC related params described above, you can also pass:

  • lang - The language that you want the client to be translated in. Currently supported are de, ja, ro, fr.

JWKS

JSON Web Key Set (JWKS) is a set of keys containing the public keys that should be used to verify the ID and access JSON Web Tokens (JWT) issued by MIRACL Trust. You can fetch the 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.

Token Endpoint

The token endpoint https://api.mpin.io/oidc/token is used to exchange the authorization code for ID and access tokens. Requests to this endpoint need to be authenticated with the Client ID and Client Secret, which you received when creating an application in the management portal (Get Started). The token endpoint supports basic and post authentication.

Userinfo Endpoint

The userinfo endpoint https://api.mpin.io/oidc/userinfo returns information about the authenticated user. You must authenticate the request with an access token (returned from the token endpoint) by using basic HTTP authentication.

Supported OIDC Scopes

  • openid
  • profile
  • email
  • dvs
  • mpin_id
  • hash_mpin_id

Supported OIDC Claims

  • sub
  • iss
  • email
  • email_verified
  • mpin_id
  • hash_mpin_id
  • dvs_keys

OIDC Authentication Flow

sequenceDiagram User -> Relying Party: Start Authentication Relying Party -> MIRACL Trust: Authentication request MIRACL Trust -> User: Authenticate user User -> Relying Party: Redirect with access code Relying Party -> MIRACL Trust: Exchange code for ID and access tokens User -> Relying Party: Authorize user