Using OpenID Connect

What is OpenID Connect? 🔗︎ click to copy

Before delving into the Mydex Identity Services OpenID Connect technical perspective, we would recommend that you first read the following resources, unless you are already familiar with OAuth2.0 and OpenID Connect:

There is also a video that we would recommend watching by Nat Sakimura, the Chairman on the OpenID Foundation:



“OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It enables Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.”

Terminology note: Mydex refers to what the OpenID Connect specification calls ‘End-Users’, as Mydex ‘Members’. The two terms are interchangeable for the purposes of this document and for understanding OpenID Connect in the context of Mydex. We use the term ‘member’. You may refer to these individuals in other ways in your application such as customer, citizen, user etc.

What can be done with OpenID Connect? 🔗︎ click to copy

Using OpenID Connect, a Subscribing Organisation can let members:

OpenID Connect is currently offered to relying parties to enable you to outsource the username and password management. Relying parties join the Mydex Trust Framework and identity federation. Each Mydex member has a unique MydexID.

Implementing OpenID Connect in your application 🔗︎ click to copy

Implementing OpenID Connect is relatively straightforward. There are many open source and commercial solutions that provide OpenID Connect support for what they call Relying Parties (RPs), sometimes called Service Providers (SPs) if familiar with the SAML 2.0 protocol.

In simple terms it means your application or service relies on the Mydex Identity as a Service for registration and authentication of those individual's accessing your apps and services. As an OpenID provider we are called an OP in the standards documentation.

Most of the libraries can be found on the OpenID site.

At a high level, the way OpenID Connect works in the context of Mydex Identity Services is:

  1. The RP (Client application) sends a request to the Mydex OpenID Provider (OP).
  2. The OP authenticates the member and obtains authorisation.
  3. The OP responds with an ID Token and usually an Access Token.
  4. The RP can send a request with the Access Token to the UserInfo Endpoint.
  5. The UserInfo Endpoint returns Claims about the member.

To help demonstrate the capabibility, Mydex has also created a sample, example application written in Python which demonstrates authentication (or registration) via OpenIDConnect. Click here to view it in the Developer API Examples git repository.


Registering MydexIDs via OIDC 🔗︎ click to copy

A member can register for a MydexID at any time via https://pds.mydex.org (live) or https://sbx.mydex.org (sandbox).

The registration process can also be performed via OpenID Connect by Subscriber applications that support the protocol. Registering via OpenID Connect will automatically log the new member in and return to your application to establish an authenticated experience.

Using OpenID Connect to register a member is advantageous to Subscribers because it means the Subscriber does not need to process the member's login credentials.

It is also possible to perform registration in a Subscriber application via the PDX API without using OpenID Connect, but we recommend Subscribers use the OIDC method wherever possible.

For specific information about the registration API services please see the registration documentation.


Authentication with MydexIDs 🔗︎ click to copy

If a member already has a MydexID, Subscribers can benefit from this by using OpenID Connect to let the member login with their MydexID credentials. This offloads the burden of maintaining username/password services in the Subscriber application entirely.

For specific information about how to authenticate a MydexID to your application, as well as how to support logging them out, please see the authentication documentation.


OpenID Connect Environment Details 🔗︎ click to copy

Production Environments 🔗︎ click to copy

Mydex provides Subscribing organisations with two environments to work with OpenID Connect as follows:

Discovery 🔗︎ click to copy

OpenID Connect specification defines a mechanism for an OpenID Connect Relying Party to obtain information needed to interact with the OP, including the various OAuth 2.0 endpoints that are consumed as part of the protocol.

You do not necessarily need to consume the ‘discovery’ services to use OpenID Connect with Mydex (and our examples later in this document will not use it).

However, if your client library expects to use discovery, or if you are seeking to confirm the auth, token and other endpoints, the URLs you need are here:

Setting up OpenID Connect with the Mydex Sandbox 🔗︎ click to copy

Mydex CIC has a Sandbox and Live environment. We recommend you get set up against our sandbox first to test your connection. It's good practice if you use a separate staging or testing environment with a unique URL of its own to connect to the Sandbox, before you proceed with a live service on a live URL.

Once you have got it working correctly at a technical level and your Subscribing organisation has completed verification, you can request that it is promoted to our live environment when you are ready, at which time you will be issued with another OAuth2.0 client for live environment use.

Please make sure that you have read the OpenID Connect “Basic Client Implementer's Guide 1.0” specification before proceeding. Mydex assumes you or your development team will learn how OpenID Connect itself works in order to use it with Mydex.

The key steps you need to take are as follows:

  1. Select OpenID Connect client library 🔗︎ click to copy

    • The OpenID Connect is an open standard, and you can interact with the OP via HTTP RESTful API calls. However, there is a lot more to the flow that involves cryptographic verification among other things. It is strongly recommended to consume existing OpenID Connect libraries that are suitable for an RP. Many libraries exist for different programming languages. Please see information on this website for examples.
    • Other options for libraries can be found on the OpenID Foundation website.

  2. Request an OIDC Client from Mydex 🔗︎ click to copy

    Mydex does not allow Dynamic Client Registration (which is an optional feature of the OpenID Connect specification) in order to obtain an OIDC client.

    You can request an OpenID Connect / OAuth2.0 Client via the Connection Manager, and Mydex will issue you with an OAuth2.0 Client ID and Client Secret for use with your application.

    Please fill out the form and provide all the required information we need to issue your OAuth2.0 client. This includes a variety of URLs for handling callbacks post-login, logout, terms of service/privacy URLs, grant and response types depending on the ‘flow’ you've chosen to implement per the OpenID Connect specification.

    Choosing the right options for an OIDC RP when making your request

    Mydex recommends using the following options:

    • the ‘Authorization Code’ grant type,
    • the ‘code’ response type,
    • the mydexid and openid scopes (these are in fact mandatory)
    This is the most common flow for traditional web applications that run on server infrastructure, and will work well if you copy the example PHP code provided below.

    Building a mobile app or a Single Page App (SPA)?

    If your app will be a mobile app or SPA, we recommend using Proof Key for Code Exchange (PKCE) and to not store a client secret or private key in your app. You can note that your app needs PKCE when requesting the OIDC client in our Connection Manager.

    For SPAs, you may also need our OIDC to set CORS headers containing your app's Origin URL, if your app makes cross-origin requests to the token endpoint. Again, you can note this in your Connection Manager request. Alternatively, get in touch with support after making your request, and we can help ensure your OIDC Client meets the requirements of your app and our security posture.

    Still need help?

    Mydex assumes you or your development team already know enough about the OpenID Connect standard to know what type of grant types, response codes etc your application requires. However, it's a complex area, and we're here to help! If you require assistance, you can reach out to us at developersupport@mydex.org and we can do our best to support getting your application working with our OP.

  3. Configure and test your OpenID Connect Client application 🔗︎ click to copy

    See the authentication documentation for examples and instructions on how to perform an OpenID Connect flow with your configured application.