Overview #
User provisioning is automatic and happens when the patient’s first session starts. To start a session, construct a magic link in the following format:
{base_url}/{route}#id_token={id_token}
E.g., https://embed.emed.com/partners/consultations/new#id_token=eyJ...
Then, load the magic link inside an iframe.
Our system expects an ID token that is signed and encrypted in a Nested JWT format and follows the OpenID Connect Core 1.0 standard. A user is provisioned if one does not exist for the given identifier (sub). Provisioning might take a few seconds and so launching the first session may be slightly slower.
Passing the ID token in the URI fragment ensures it is available for the eMed web app at runtime without it being sent as part of the HTTP request. The app then passes the ID token to the eMed identity provider for single sign-on.
Once user lookup and provisioning are complete, the requested functionality (e.g. appointment booking) will be rendered within the iframe.
Please note: While OpenID Connect includes standard flows for silent reauthentication, these are not supported here, as modern web browsers do not allow third-party iframe content to access cookies.
ID token #
The ID token contains the following claims in standard format:
| Claim name | Value | Example | Mandatory |
|---|---|---|---|
| sub | Patient’s external identifier unique within partner system | df6b1233-9a15-4173-81f2-b11545d99c83 | Y |
| aud | OAuth Client ID created by partner for eMed, or the static value listed under Environments | https://embed-uk.preprod.babylontech.co.uk | Y |
| iat | Time at which ID token was issued | 1516239022 | Y |
| exp | Expiry – must be iat + 30 seconds | 1516239052 | Y |
| iss | Issuer – partner’s identifier | https://abc-health.com/idp | Y |
| nonce | A unique per request random UUID – used to prevent replay attacks | 08a3d8c6-e45b-45b5-bbdc-2f108e1b3d4d | Y |
| org | Organisation ID. This will be provided to you by eMed during onboarding | abc-health | Y |
| given_name | Given name | John | Y |
| family_name | Family name | Smith | Y |
| Email address | john.smith@example.com | Y | |
| birthdate | Date of birth | 1990-01-01 | |
| phone_number | Phone number in international E.164 format | +44 7500 700 000 | |
| address | JSON object containing street address, locality, region, and postal code. See detailed requirements below. | {"street_address":"Flat 12\n184 Drummond St","locality":"London", “region”: “Greater London”, "postal_code":"NW1 3HP"} |
The platform stores and updates these values at the start of each session. If a value is absent, the old value is kept and not updated.
Signing the ID Token #
The ID token must be signed by the partner (with the partner’s public key enrolled), and then that token should be encrypted using JWE with the eMed public key specified under Environments, using AES GCM (256-bit key) and the RSA-OAEP algorithm. The encryption is done in order to protect the personally identifiable information (PII) contained in the JWT. See https://datatracker.ietf.org/doc/html/rfc7519#section-11.2
Address field #
The address field represents the patient’s address and should be provided when the patient starts their first session. The supported subfields are a subset of the official OpenID specifications. Specifically, a valid address must contain the mandatory street_address field (e.g. "Flat 12\n184 Drummond St") which may contain line breaks. Additionally, the address may contain the following optional fields: locality (e.g. "London"), region (e.g. "Greater London"), and postal_code (e.g. "NW1 3HP"). Note that there is no field for country since only UK addresses are supported. If a valid address is provided at the time of initial signup, then the address will be included in the newly provisioned user profile. If no address is provided, the user profile will be provisioned without an address. If an address is provided but fails validation (e.g. if the provided value is not a JSON object or if the mandatory street_address field is missing) then the user provisioning aborts with an error.