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.

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: https://openid.net/developers/libraries/

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.
( https://openid.net/specs/openid-connect-basic-1_0.html )

🔗︎ click to copy OpenIDconnect Authorisation code flow web sequence diagram

OpenIDConnect offers a feature to request User Info or claims. Currently we are only returning their MydexID.

A future phase of work will enable our members to select what user info they wish to make available to relying parties. All personal data is stored in the members personal data store. Mapping of available data from the personal data store will be offered to relying parties to include in their requests in the future.

OpenID Connect, like SAML 2.0, 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.

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 is currently independent of either OpenID Connect or SAML. For specific information about using the registration API services please go here.

Your application in OpenID Connect - this is referred to as a Relying Party or RP - is responsible for access control to their services. In other words we can provide authentication but you must decide and manage what an authenticated member (client, customer, citizen, member of staff) can do within your application.

There are a number of ways access control and feature access permissions can be implemented and each organisation’s context will be different depending on the applications using the Mydex Identity as a Service Single Sign-On environment. Examples are use of a corporate approach to directory services e.g. use of an LDAP compliant directory or application specific access control.

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 its OAuth 2.0 endpoint locations.

https://openid.net/specs/openid-connect-discovery-1_0.html

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, the URLs you need are here:

Authorization Code Flow 🔗︎ click to copy

The Authorization Code Flow is the most common OpenID Connect/OAuth2.0 flow, and is probably the flow your web application should be using. It consists of the following steps:

  1. Client application or Relying Party (RP) prepares an Authentication Request containing the desired request parameters, including the OAuth2.0 Client ID and Secret, the requested scope/claims, and the URL of the Mydex OP.
  2. RP initiates the request in its login route, which causes the member’s browser to redirect to the OP.
  3. OP validates the RP’s request, and redirects the member to the Login & Consent application.
  4. The member submits their login credentials and the Login & Consent app validates these against the IDP API.
  5. If the credentials are correct, the Login & Consent app requests Consent from the member.
  6. If the member consents, the OP stores information about what claims were consented to in the UserInfo endpoint for this member, and then redirects the member back to the RP with a code.
  7. RP uses the code to request an Access Token and/or ID Token from the OP’s Token Endpoint.
  8. RP validates the tokens and retrieves any relevant claim information from the UserInfo endpoint, such as their mydexid. With this information, they can treat the member as logged in to the RP app.

Getting Started 🔗︎ click to copy

Setting up OpenID Connect with the Mydex Sandbox

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/URL of your 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” before proceeding. Mydex assumes you or your development team will learn how OpenID Connect itself works in order to use it with Mydex.
https://openid.net/specs/openid-connect-basic-1_0.html

The key steps you need to take are as follows:

  1. Select OpenID Connect client library

    • 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 at https://www.ory.sh/hydra/docs/guides/using-oauth2/ for examples.
    • If your Client application (RP) is written in PHP, we recommend using the JumboJett OpenIDConnect PHP library which can be found at https://github.com/jumbojett/OpenID-Connect-PHP .
    • Other options for libraries can be found at: http://openid.net/developers/libraries/

  2. Request an OIDC Client from Mydex

    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 at https://connection-manager.mydex.org , in the same way that you can request or submit SAML service provider information to our SAML IDP, 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 your OpenID Connect Client application

    Once you have your OAuth2.0 client ID and secret, you can use these in your application's login route with the OP URL to initiate the login flow.

    When the RP wishes to Authenticate the member, or determine whether the End-User is already Authenticated, the Client prepares an Authentication Request to be sent to the Authorization Endpoint.

    If using the JumboJett PHP library, this would look like this: 

                        
// Initiate the OIDC client library with your OAuth2.0 client credentials
$oidc = new OpenIDConnectClient(‘https://sbx-op.mydexid.org’, ‘ClientIDHere’, ‘ClientSecretHere’);

// Register the post-login callback URL
$oidc->setRedirectURL(‘https://your-client-application.example.com/home’);

// Register what scopes you need. 
// ‘openid’ will always be added even if you don't specify it.
$oidc->addScope(‘mydexid’);

// Initiate the login process at the OP
$oidc->authenticate();

    Note: the redirect URL or ‘callback’ URL, in this example with the /home route, must be the URL you provided when requesting your OAuth2.0 Client from Mydex via the Connection Manager. If you provide a URL that was not attached to your OAuth2.0 Client when we created it, the flow will throw an error, because this URL cannot be arbitrary for security reasons. If you need to change the URL, please contact us and we can update the OAuth2.0 Client settings at our end.

    That's it! Upon the call to $oidc->authenticate();, our OP takes care of the rest of the redirects to the Login and Consent pages in the member's browser.

    In the above example, we assume that your application has a /home route, which the member will be redirected back to after completing the Login and Consent process, with a code in the query parameters.

    In your /home route's controller, you can now exchange that code for an ID Token. You could store that in the member's session so that you can use it later, for things like initiating a logout request at the OP:
    $_SESSION['id_token'] = $oidc->getIdToken();

    Now that you have a token, you can request the ‘claims’ from the OP's UserInfo endpoint:
    $claims = $oidc->requestUserInfo();

    Mydex currently requires the ‘mydexid’ scope in addition to the ‘openidid’ scope. You can then fetch the ‘mydexid’ as a claim via the UserInfo endpoint above. You can then use the member's MydexID to store in your Client app's session however you want, so that your application understands the member has successfully authenticated and is now ‘logged in’ from the perspective of your app.

    Note: In future, Mydex may add other representations of the member's PDS datasets that your connection may have been granted access to, as a claim, but these claims will not represent the data itself, just a form of consent statement. The data must always be requested by your application via the PDS API with a Connection Key per the standard Mydex PDS model explained elsewhere on this website.

  4. Test logging in with your Sandbox MydexID

    If you initiated the authentication request like the above example, and you are using a client library that implements the OpenID Connect specification correctly, your application should now be able to let Mydex members access your service using their MydexID.

    Report any issues to developersupport@mydex.org.

  5. Handling logout

    Mydex's OpenID Connect service supports front-channel and back-channel logout mechanisms, per the OpenID Connect specification. Of the two, back-channel is the recommended option.

    If you provided either front-channel or back-channel URLs when requesting your OAuth2.0 client via the Connection Manager, Mydex's OP will make a request to those relevant URLs if the member initiates a logout request from your Client app, or even from another participating RP that uses Mydex's OpenID Connect service.

    This is so the member can achieve ‘single logout’ from any app without having to log out from each app individually - considered a security feature of the OpenID Connect specification.

    However, if you don't provide any front- or back-channel URLs when requesting your OAuth2.0 Client, your application won't participate in the single logout process.

    In either case, your application's main logout route (the navigation item that the member clicks on to Logout of your app) should still initiate a logout request to Mydex's OpenID Connect service, with a previously-obtained ID Token. If using PHP and the Jumbojett library, it would look something like this: 

                        
// You are responsible for ending your own Client app's session 
// for the member. OpenID Connect knows nothing about your RP's
// own session management system.
session_destroy();

// Now you must initiate the logout flow at the OP, even if the 
// member didn't choose to create a session at the OP (‘Remember me’)
$oidc->signOut($_SESSION['id_token'], 'https://your-client-application.example.com/goodbye');

    Note: like the redirect callback on login, this /goodbye URL is an example but it must be the same URL you provided Mydex as a post-logout callback URL when you requested your OAuth2.0 Client via the Connection Manager. It cannot be an arbitrary URL that isn't already associated with your OAuth2.0 Client at our end.

    The above request will initiate the logout request. If the member did not choose to ‘remember’ their session at the OP, they will simply be redirected straight back to your post-logout callback URL, and they should no longer appear logged in to your service.

    If the member did choose to be remembered, they will be asked to confirm the logout, and front/back-channel logout flows will be initiated by the Mydex OP to all participating RPs (even if your own app is not participating in front/back-channel logout).

    If you are participating in front- or back-channel logout, you should also have another route that answers on those URLs, which does some sort of session destruction in your Client app, but which unlike the above main logout route, does not initiate signout with the OP.

    Front- and back-channel routes are not intended to be visited by the member explicitly - in other words they operate almost like API routes even if the member had not consciously opened your webapp in their browser.

    This ensures that even if the member initiated Single LogOut from an RP other than yours, your app correctly and transparently ends the member's session on your website automatically.

    Note: if you opted to support front-channel logout, your application must be able to be loaded as a HTTP GET request in an iframe by the OP. Ensure that your Content Security Policy and/or X-Frame-Options headers allow the Mydex OP URL so that the member's browser is able to load your app in an iframe in their browser.

    If you opted to support back-channel logout, remember that the OP makes a direct HTTP POST request to your back-channel URL as a server-to-server request (not via the member's browser). This means that your back-channel logout URL must be reachable over the public internet from the Mydex OP (it can't be behind Network Address Translation or other firewall restrictions that prevent direct access).

Taking it Live 🔗︎ click to copy

Once you know your application is working correctly with OpenID Connect, you can request an OAuth2.0 Client against the ‘live’ environment, via the Mydex Connection Manager. If you wish, this request can be with the same URLs as the site you used with the Sandbox, but it will still need to be a separate request.

Mydex will issue you another Client ID/Secret keypair for use with the live environment.

The process should work the same as above for the live environment, but just with https://op.mydexid.org rather than the https://sbx-op.mydexid.org URL.

Registering MydexIDs via OIDC 🔗︎ click to copy

Mydex also supports using the OIDC auth flow to present a registration screen for members to register for a MydexID and PDS. This is a convenient way to onboard new members without having to write your own registration form or needing to apply for a Dedicated Connection to our PDS platform as a subscriber.

To find out more, visit our Registration Services documentation.