OAuth 2.0 and OpenID Connect

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 services comply with the OAuth 2.0 and OpenID Connect (OIDC) standards.

Postman Collections

For full request/response examples, use the Postman collections:

• FanScore Authentication (External) — Registration, Login, Logout, Password, Profile, Email verification, Preferences

How It Works

The system unifies access across disparate services — such as retail shops, ticketing systems, and dynamic content — through a single user login. The architecture comprises two components:

• Identity Provider: Manages user login credentials
• SSO Server: Manages authorisation via JWT (JSON Web Token) access tokens

Once the Identity Provider validates credentials and validates with the Authorisation Server, access tokens become available for API calls. These tokens persist in request headers throughout the active session across multiple platforms and service providers, granting access to permitted routes and resources.

Example Authorisation Request

When a user requests a protected service (e.g. retail on a sports team website), the login request flows to the Identity Provider, which then requests authorisation from the SSO server via:

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

Key Parameters:

The SSO Server issues an authorisation code for token exchange without passing credentials through the chain.

ID Tokens and the openid Scope

Cortex returns an ID token only when the token request includes the OpenID Connect scope:

scope=openid profile email address phone

If a refresh token was issued with openid in its scope, the refresh-token response includes a new id_token. If the refresh token does not include openid, the refresh-token response does not include an id_token.

When configuring requests in Postman or an OAuth client, add openid to the Scope field whenever the integration needs an ID token.

Common API Calls

1. Fetch Authentication/Authorisation Configuration

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

Example:

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

Response:

{
  "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"}]
}

2. Fetch Public Keys

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

Returns the JSON Web Key Set (JWKS) containing public keys for verifying token signatures for a given client ID.

Important Notes

• Fields requiring population are enclosed in {curly-brackets}; remove brackets when populating
• The Identity Provider and SSO Server typically function as a unified Cortex service, though separation is possible
• Custom login pages and authentication management require coordination with Cortex
• Refresh-token responses include id_token only when the refresh token scope includes openid
• Further resources available at OpenIdConnect.net