Using OpenID Connect
Before delving into the Mydex Identity Services OpenID Connect technical perspective, we would recommend that unless you are already familiar with OpenID Connect, to first read:
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.”
Implementing OpenID Connect is relatively straightforward. There are many open source and commercial solutions that provide OpenID Connect support for service providers (relying parties). Most of the libraries can be found on the OpenID site: http://openid.net/developers/libraries/
At a high-level, the way OpenID Connect works in the context of Mydex Identity Services is:
- The RP (Client) sends a request to the Mydex OpenID Provider (OP).
- The OP authenticates the End-User and obtains authorization.
- The OP responds with an ID Token and usually an Access Token.
- The RP can send a request with the Access Token to the UserInfo Endpoint.
- The UserInfo Endpoint returns Claims about the End-User.
Mydex Identity Services provides authentication services in the context of Single Sign-On (SSO), and supporting services that include change password and password reset. Registration via OpenID Connect is currently not supported, but is on the development roadmap.
Mydex CIC provide additional Identity Assurance Services for some clients but this is distinct from Single Sign-On and is an additional chargeable service.
The service provider (sometimes called a relying party) is responsible for access control to their services. This means giving authorisation for an registered and authenticated MydexID to access each application. The precise level of access and functionality they can make use of is an internal decision by each organisation. There are a number of ways this can be implemented and each organisation’s context will be different depending on the applications being connected to the Single Sign-On environment and the corporate approach to directory services e.g. use of an LDAP compliant directory.
Mydex provides organisations with two environments to work with as follows:
- The Sandbox environment - This is a replica of our live environments for identity and personal data services and enables any organisations to experiment, develop and test their connections easily and quickly.
- https://sbx.mydex.org is the personal data services environment from which profile information and other data is sourced.
- https://sbx-idp.mydexid.org is where the Mydex implementation of OpenID Connect identity provider is located. There is no actual UI for this site, but it is where the config files for your OpenID Connect setup will point to.
- The live environment - This the live operational environment subject to the terms of connection and is part of the Mydex Trust Framework. Connection to this environment requires verification of your organisation, its connections and environments that are to be connected.
- https://api.mydex.org - this is the API services that is used to send and receive profile information from and to the individual personal data store. It can be used for a wider range of data services as well.
- https://idp.mydexid.org is where the OpenID Connect identity provider is located. There is no actual UI for this site, but is where the config files for your OpenID Connect setup will point to.
Basic Configuration Overview
JSON Web Tokens (JWT)
OAuth 2.0, the substrate for OpenID Connect, outsources the necessary encryption to the Web’s built-in TLS (also called HTTPS or SSL) infrastructure, which is universally implemented on both client and server platforms. OpenID Connect uses standard JSON Web Token (JWT) data structures when signatures are required. (ref: http://openid.net/connect/faq/)
Mydex provides the jwks_uri in its discovery metadata: “URL of the OP's JSON Web Key Set [JWK] document. This contains the signing key(s) the RP uses to validate signatures from the OP. The JWK Set MAY also contain the Server's encryption key(s), which are used by RPs to encrypt requests to the Server. When both signing and encryption keys are made available, a use (Key Use) parameter value is REQUIRED for all keys in the referenced JWK Set to indicate each key's intended usage. Although some algorithms allow the same key to be used for both signatures and encryption, doing so is NOT RECOMMENDED, as it is less secure. The JWK x5c parameter MAY be used to provide X.509 representations of keys provided. When used, the bare key values MUST still be present and MUST match those in the certificate.“
More on encrypted requests:
Mydex Identity Services are delivered as a web service. You can control the journey your customers or citizens take through registration and authentication and embed these into your website or application.
“This specification defines a mechanism for an OpenID Connect Relying Party to discover the End-User's OpenID Provider and obtain information needed to interact with it, including its OAuth 2.0 endpoint locations.”
This is how the RP will ‘discover’ the Mydex IDP.
The Mydex OpenID Connect configuration file (/.well-known/openid-configuration) file that is used for discovery is located at:
- SBX: http://
- LIVE: http://
Components of the full length OpenID (with example):
The Code Flow consists of the following steps:
- Client prepares an Authentication Request containing the desired request parameters.
- Client sends the request to the Mydex Authorization Server.
- Authorization Server authenticates the End-User.
- Authorization Server obtains End-User Consent/Authorization.
- Authorization Server sends the End-User back to the Client with code.
- Client sends the code to the Token Endpoint to receive an Access Token and ID Token in the response.
- Client validates the tokens and retrieves the End-User's Subject Identifier.
Setting up with the Mydex Sandbox
Mydex has a Sandbox and Live environment. We recommend you get set up against our sandbox first to test your connection. Once you have got it working correctly at a technical level and your organisation has completed verification we will move you across to our live environment when you are ready.
Please make sure that you have read the OpenID Connect “Basic Client Implementer's Guide 1.02” before proceeding: http://openid.net/specs/openid-connect-basic-1_0.html
The key steps you need to take are as follows:
- Select OpenID Connect Service Provider
- Mydex uses the phpOIDC library which can be downloaded from: https://bitbucket.org/PEOFIAMP/phpoidc.
- This is an open source implementation of OpenID Connect in PHP by Nomura Research Institute, Ltd.
- Other options for libraries can be found at: http://openid.net/developers/libraries/
- Send an email to developersupport@mydex
- Please include the following information in your email as it is essential to creating your certificate:
- State or Province Name/County
- Organisation Name
- Common Name (your server FQDN) This is this domain name that your server is located on (ie. pds.mydex.org)
- Email address
- SBX: https://
- LIVE: https://
- response_type - REQUIRED. This value MUST be code. This requests that both an Access Token and an ID Token be returned from the Token Endpoint in exchange for the code value returned from the Authorization Endpoint.
- clinet_id - REQUIRED. OAuth 2.0 Client Identifier valid at the Authorization Server.
- scope - REQUIRED. OpenID Connect requests MUST contain the openid scope value.
- redirect_uri - REQUIRED. Redirection URI to which the response will be sent. This URI MUST exactly match one of the Redirection URI values for the Client pre-registered at the OpenID Provider, with the matching performed as described in Section 6.2.1 of [RFC3986] (Simple String Comparison). The Redirection URI SHOULD use the https scheme; however, it MAY use the http scheme, provided that the Client Type is confidential, as defined in Section 2.1 of OAuth 2.0, and provided the OP allows the use ofhttp Redirection URIs in this case. The Redirection URI MAY use an alternate scheme, such as one that is intended to identify a callback into a native application.
- state - RECOMMENDED. Opaque value used to maintain state between the request and the callback. Typically, Cross-Site Request Forgery (CSRF, XSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie. For a full list go here:
- Here is an example of a complete OpenID Connect authentication URI:
<mydexid>.sbx.mydexid.org/index.php/auth? state=8e9217b40e18a29c7843dc1e60aed4a8& redirect_uri=http%3A%2F%2Fidp.local.mixcic.eu%3A8080%2Fpt%2Foidc%2FphpRp%2Findex.php%2Fcallback& response_type=code& client_id=G7Dz6eDDAXBzE4XqVyUsDw& nonce=d9a514a59c6691b1c30d1b80252a51e0& scope=openid
- You should now be able to register users and authenticate against Mydex Identity Services.
- Report any problems to developersupport@mydex.
Once an individual has successfully registered and logged into to their first service, they will subsequently be able to seamlessly login to all subsequent services within your domain.
Connecting Organisation use cases and guide content
The principle benefit to our members is being able use their MydexID as an OpenID Connect on the internet in the same way as they can use it as a Mozilla Persona.
Where organisations use Mydex as an Identity Provider, the choice of protocol by the organisation (SAML/OpenID/Persona) is in reality invisible to the individual, and of no real concern to them.
When Mydex members use the OpenID Connect protocol as a means to log in to a website or application, a record of this will be logged in that members PDS in their identity log, as it currently does for SAML and Mozilla Persona.
Use case 1 - General support for OpenID on an organization's site
Adding openid support to your website generically:
This would require to ask the individual for the full length OpenID, such as:
Followed by their password. Supplying these credentials would authenticate the user. Where Mydex is acting as the Identity Provider to the organisation we have made it possible to provide only the MydexID itself, all the other components of the OpenID path are dynamically generated (full length OpenID path), which essentially renders OpenID Connect hidden as the protocol for optimal user experience.
Use Case 2 Using Mydex as your IDP for registration and authentication using the OpenID connect protocol
Registration is currently not supported using OpenIDConnect, only SAML. Organisation can implement a two protocol strategy which enables registration using SAML and subsequent authentication using OpenID if required. E.g. johnpsmith instead of https://johnpsmith.mydexid.org/ or firstname.lastname@example.org
This would work by asking the user for their MydexID and password at the point of login/authentication. As the other components of the OpenID path are dynamically set (full length OpenID path), which essentially renders OpenID Connect hidden as the protocol for optimal user experience.