Using OpenID Connect

Business Perspective

Managing usernames and passwords is a risk, takes time and costs money, it is also not a great experience for an organisations customers, employees and partners to have to have dedicated credentials for every place they visit or every system they use inside and outside the organisation.

Mydex Identity services provides identity as a service which allows organisations get out the username and password issuance and management process and focus on access control and customer / user experience.

We support multiple open standards protocols. The benefits are simple:

  • low cost - tiny charge per individual per year with some low initial set up costs per system or services.
  • low risk - ISO27001 certified company operating a 24x7 highly scalable identity services platform.
  • Extensible - When you use our service you join the Mydex Trust Framework which provides uniform terms of service for all relying parties and you can take part in the wider federation of trusted organisations and services when you want to.
  • Secure service - we use PKI end to end for our service following the open standards specifications.
  • Total control of user experience - We work through our API’s so you control your customer / employee or partner journey for registration and authentication.
  • Benefits for your users - They get a MydexID and a Personal Data Store with a set of tools that let them manage their life online easily. The MydexID can be used anywhere open standards are support such as OpenID, Mozilla Persona.
  • Single Sign On with ease - Given our open API and multi protocol support you can easily integrate into your existing systems and provide single sign on across all of them. You only need to focus on your access control policies not the username and password.

These guidances pages are about using OpenIDConnect 1.0 as your protocol as a service provider / relying party when outsourcing identity management to Mydex CIC. If you want to understand more broadly the different use cases for the Mydex Identity and personal data services platform please view our guide on this located here https://dev.mydex.org/getting-started/use-cases.html.

Technical Perspective

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:

  1. The RP (Client) sends a request to the Mydex OpenID Provider (OP).
  2. The OP authenticates the End-User and obtains authorization.
  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 End-User.

(http://openid.net/specs/openid-connect-basic-1_0.html)

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.

Production Environments

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.“
http://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata

More on JWTs:
http://self-issued.info/docs/draft-ietf-oauth-json-web-token.html

More on encrypted requests:
http://openid.net/specs/openid-connect-core-1_0.html#EncryptedRequestObject

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.

Discovery

“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.
http://openid.net/specs/openid-connect-discovery-1_0.html

The Mydex OpenID Connect configuration file (/.well-known/openid-configuration) file that is used for discovery is located at:

  • SBX: http://<mydexid>.sbx.mydexid.org/.well-known/openid-configuration
  • LIVE: http://<mydexid>.mydexid.org/.well-known/openid-configuration

Components of the full length OpenID (with example):

Url MydexID Separator OpenID Extension
https:// johnpsmith . mydexid.org

Code Flow

The Code Flow consists of the following steps:

  1. Client prepares an Authentication Request containing the desired request parameters.
  2. Client sends the request to the Mydex Authorization Server.
  3. Authorization Server authenticates the End-User.
  4. Authorization Server obtains End-User Consent/Authorization.
  5. Authorization Server sends the End-User back to the Client with code.
  6. Client sends the code to the Token Endpoint to receive an Access Token and ID Token in the response.
  7. Client validates the tokens and retrieves the End-User's Subject Identifier.

(http://openid.net/specs/openid-connect-basic-1_0.html)

Getting Started

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:

  1. Select OpenID Connect Service Provider
  2. Request keys from Mydex - We manufacture the keys for you, one private and one public.
    • Send an email to developersupport@mydex.org
      1. Please include the following information in your email as it is essential to creating your certificate:
        1. Country
        2. State or Province Name/County
        3. City
        4. Organisation Name
        5. Common Name (your server FQDN) This is this domain name that your server is located on (ie. pds.mydex.org)
        6. Email address
  3. Configure your OpenID Connect Client
  4. Set up OpenID Connect Endpoint discovery - this is located at
    • SBX: https://<mydexid>.sbx.mydexid.org/.well-known/openid-configuration
    • LIVE: https://<mydexid>.mydexid.org/.well-known/openid-configuration
  5. Send an authentication request - When the RP wishes to Authenticate the End-User or determine whether the End-User is already Authenticated, the Client prepares an Authentication Request to be sent to the Authorization Endpoint. Using the following basic parameters:
    • 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:
      http://openid.net/specs/openid-connect-basic-1_0.html#RequestParameters
    • Here is an example of a complete OpenID Connect authentication URI:
    • http://<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
    • Further reading:
      http://openid.net/specs/openid-connect-basic-1_0.html#AuthenticationRequest
      https://developers.google.com/accounts/docs/OAuth2Login
  6. Test
    • You should now be able to register users and authenticate against Mydex Identity Services.
    • Report any problems to developersupport@mydex.org.

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 organizations site

Adding openid support to your website generically:

http://openid.net/add-openid/

This would require to ask the individual for the full length OpenID, such as:

https://johnpsmith.mydexid.org/

Followed by their password. Supplying these credentials would authenticate the user.

Use Case 2 Using Mydex as your IDP for registration and authentication using the OpenID connect protocol

Registration

Registration is currently not supported by Mydex Identity Services. It is however on the Mydex development roadmap, and will be announced here once we have more details.

Authentication

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.