For you to enable SSO into the HealthKey platform, we’d need your platform to be able to generate access tokens, following the OAuth protocol. That means your platform needs to be able to act as an authorisation server, and provide HealthKey with the identity of the user, once the user consents to that.

Prerequisites

You know the basics of how OAuth works. We’ve kept things fairly simple, so you don’t need to be an OAuth 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

Once your platform has the ability to act as an 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 endpoint, 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"
}

By doing so, the only information we’ll need from you is the value for {{your_hostname}}, as well as a client_id, and a client_secret.