Guides
Start typing to search…

OAuth 2.0 and OpenID Connect

Summary

NOTE
This article explains how accounts and communications between different services and service providers across the wide area are protected by Cortex using OAuth 2.0 and OpenID Connect. The article also details the structure of API calls that use these features.

Table of contents

Introduction

Cortex provides authentication and authorisation services that facilitate seamless access for users to a range of services from multiple service providers through one secure single sign-on (SSO) by the user.

These authentication and authorisation services are compliant with OAuth 2.0 and OpenID Connect (OIDC) standards and specifications.

How it works

A website and app may have, for example, a shop, with services provided by one third party, a ticketing service provided by another and pages populated with dynamic content provided by Cortex. In order to unify access to all these facilities, and personalise them to the user, Cortex’s authentication and authorisation services provide seamless, secure access to all the services from a single login by the user.

The overall capability is split into two: The Identity Provider manages the user and their login, and the SSO Server manages authorisation using JWTs (JSON Web Tokens - also known as ‘access tokens’). As described in the process flow diagram below, once the user credentials have been authenticated by the Identity Provider and a validation process has taken place between the Identity Provider and the Authorisation Server, the access tokens for the logged-in user can be used by the Service Provider in the headers of the API calls requiring authorisation from that point onwards until the session ends, the token expires, or an event takes place that nullifies the token (such as the user logging out). Each subsequent request during the active session - even across multiple platforms and service providers - will include the access tokens, authorising the user to access routes, services and resources that are permitted with that token.

The process flow for single sign-on using JWT access tokens for access, ID and refresh is as follows:

Stepping through the above process flow, let us assume the end-user is a football fan, actively navigating around their favourite team’s website. The service they request on the website is a retail shop provided to the football team website by a third-party service provider, and it requires the user to log in. The user’s login request is passed through to the Identity Provider, which validates the user, then makes a request of the SSO server for authorisation. The API call looks something like this:

NOTE
https://login.footballclubwebsite.co.uk/authorize?client_id={Cortex-Client-ID}&redirect_uri={URL_for_redirect_on_success}&response_type=code&scope=openid+profile+email+address+phone&state=88548820-7201-4d9c-98e2-6bea2275b879

In which:

  • clientID is the client ID assigned during the onboarding process.
  • url_redirect is the URL to which the user should be directed following successful authorisation. This is required because the user may be, for example, part-way through a ticket or merchandise process when they choose to log in.
  • scope is the user profile data to which the Service Provider wants access.
  • state is a random value used to maintain state between the request and the callback. The same value passed in by the Service Provider will be returned in the response.

The SSO Server provides an authorisation code to the Identity Provider which is passed on to the Service Provider. This code is used to verify that the participants in the chain are all whom they claim to be without needing to pass user credentials around.

The Service Provider can now message the SSO Server and exchange the code for a set of JWTs.

All being well, the user will now be logged on to the website, but with a set of JWT access tokens which, from then on, are passed in the headers of the API calls and authorise the user to access the range of services and resources permitted by those tokens.

A client-side developer does not need to know much of the technical detail of the workings of the SSO capability and the detail will vary on a client-by-client basis. Suffice to say that the service provision from Cortex follows the OpenID Connect standards and specification.

Should you wish to learn more, the specification and a set of test harnesses are available at OpenIdConnect.net that can help you understand your authentication and authorisation needs and functionality.

Below are a set of API call examples that can aid the developer.

IMPORTANT NOTE: The identity provider and the SSO server are generally provided by Cortex as a single, unified service. However, the two are shown as independent entities in this document because it is possible to separate out the Identity Provider from the SSO Server. If you wish to create your own login page and/or manage your own authentication, do please talk to us to establish and configure the relevant setup data to work with our SSO Authorisation Server.

Common API calls in authentication and authorisation

Below are the common API calls you are most likely to need in working with Cortex authentication and authorisation services.

NOTE
In every case, the fields that require populating are in {curly-brackets}. Remove these brackets when populating these fields.

  1. To fetch the authentication/authorisation details of your own account:

GET {SSOServer-url}/.well-known/openid-configuration?client_id={clientID}

In which:

  • SSOServer-url is the URL for the node you have been given for the SSO Server.
  • clientID is the client ID assigned to you during onboarding.

For example, the call:

https://oauth-stage.fanscore.com/.well-known/openid-configuration?client_id=DEMO

Returns the following OpenID Connect configuration information in JSON format:

{
  "issuer": "{websiteUrl}",
  "authorization_endpoint": "{websiteUrl}/oauth/authorize",
  "token_endpoint": "{url}/oauth/token",
  "jwks_uri": "{url}/oauth/keys?client_id=DEMO",
  "response_types_supported": [
    "code"
  ],
  "scopes_supported": [
    "openid",
    "profile",
    "email",
    "address",
    "phone"
  ],
  "grant_types_supported": [
    "password",
    "refresh_token",
    "register",
    "register_minor",
    "anonymous",
    "authorization_code"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "subject_types_supported": [
    "public"
  ],
  "userinfo_endpoint": "{url}/oauth/userinfo",
  "claims_supported": [
   {"List_of_Claims"}
  ]
}

  1. Fetch the public keys:

Returns the JSON Web Key Set (JWKS) that contains the public keys that can be used to verify the signatures of tokens for a given client ID.

GET {URL}/oauth/keys?client_id={clientID}

In which:

  • URL is the endpoint for the authorisation API, given to you by Cortex. This is the same as the SSOServer-url in the example above.
  • clientID is your client ID, assigned to you during onboarding.

If you would like more details on how to work with Cortex on authentication and authorisation, please contact your administrator or account manager.

Updated about 1 month ago