For you to enable SSO into the HealthKey platform, we'd need your platform to be able to generate access tokens, following the OAuth 2.0 protocol, with an OpenID Connect (OIDC) identity layer on top. That means your platform needs to be able to act as an OAuth 2.0 / OIDC authorisation server, and provide HealthKey with the identity of the user — via an ID token and/or a userinfo endpoint — once the user consents to that.

If running a full OAuth authorisation server isn't something you want to take on, we also support a simpler, JWT (or encrypted-token) based integration — see the JWT-based SSO section further down.

Prerequisites

You know the basics of how OAuth 2.0 and OpenID Connect (OIDC) work. We've kept things fairly simple, so you don't need to be an OAuth/OIDC expert to be able to integrate with us. As we grow as an organisation, we will look at adding more capabilities on our end. For now, if you'd like us to do more than what we currently do, please get in touch with us and we can have a chat.

The big picture

The flow of the process is as follows:

1. User clicks on "HealthKey" on your website, which will prompt you to redirect the users to our platform
2. Once we receive that request, we will make a call to your platform, with a list of scopes, requesting an access code; when we do this, you'll have to ask the user for their consent
3. After we receive the code, we'll make another request to your platform, to get an access token
4. Once we receive a token, we'll make a call to your platform to validate the token, and make sure it's a valid token
5. If the token is valid, we will authenticate the user on our end. If they don't have an account, we will create one for them, using the information received from calling an endpoint on your end, to read the user's information.

Enabling SSO into HealthKey (OAuth 2.0 / OIDC)

Once your platform has the ability to act as an OAuth 2.0 / OIDC authorisation server and generate valid access tokens, we can look at integrating our two platforms together.

In order to keep the coupling between the platforms at a minimum, we'd appreciate it if your API could expose an OpenID Connect discovery endpoint ( {{your_hostname}}/.well-known/openid-configuration/ ), which we call to read the other endpoints. At a minimum, we would need that endpoint to return a JSON containing the following attributes:

{
  "issuer": "{{your_hostname}}",
  "authorization_endpoint": "{{your_hostname}}/oauth2/v1/authorize",
  "token_endpoint": "{{your_hostname}}/oauth2/v1/token",
  "userinfo_endpoint": "{{your_hostname}}/oauth2/v1/userinfo",
  "response_types_supported": [
    "code",
    "id_token",
    "code id_token",
    "code token",
    "id_token token",
    "code id_token token"
  ],
  "scopes_supported": [
    "openid",
    "email",
    "profile"
  ],
  "code_challenge_methods_supported": [
    "S256"
  ],
  "introspection_endpoint": "{{your_hostname}}/oauth2/v1/introspect"
}