Authorization Server OpenID Connect Support

Introduction

OpenID Connect describes itself as “a simple identity layer on top of the OAuth 2.0 protocol”. The specification provides a set of message structures, a messaging protocol, and a security framework to allow a system that has authenticated a user to securely convey said identity to another service provider (relying party). Cerner’s authorization server implements support for OpenID Connect in conjunction with the SMART on FHIR® profile of OAuth 2. Client applications may use this as a source of “single sign-on” for users when protecting resources outside of the EMR (example: user-generated data that is stored by the client application).

In addition to SSO, SMART on FHIR® also leverages OpenID Connect to convey the location of the authenticated user’s FHIR® endpoint, as described by the HL7® FHIR® standard.

Requesting OpenID Connect

Per OpenID Connect and SMART on FHIR®, a client application requests the scope of “openid” to receive an identity token within the access token response.

Identifying the User

Upon retrieving an access token, an identity token will be presented in the access token response. These are parsed as JSON web tokens per the OpenID Connect specification. Within identity tokens, two values are of importance in identifying the user:

The subject value of the identity assertion corresponds to the user identifier asserted by the authentication system being used, locally unique within context of the “issuer”. This value may be a user’s username, or could be an opaque identifier (such as a UUID), depending on the tenant’s identity strategy. Both the issuer and subject value combined constitute a globally-unique identifier for the authenticated user.

User identifiers remain permanent, except in the following conditions:

Neither OpenID Connect nor SMART on FHIR® prescribe mechanisms for addressing the above scenarios. As such, application developers should consider proprietary mechansims for handling such scenarios if critical user information is managed outside of the EHR.

Validating OpenID Connect Identity Tokens

The client application receiving the identity token must validate that the audience (aud) claim matches its own client identifier, per section 3.1.3.7 of OpenID Connect Core.

For applications interoperating only with Cerner’s authorization server, no explicit signature validation is required when retrieving the access token directly from the token endpoint (as advertised via the FHIR® conformance document).

For applications that interoperate with multiple implementations, or are distributed in nature, identity tokens should be verified (including signature) per section 3.1.3.7 of OpenID Connect Core. Signing keys may be retrieved via the following steps:

The following is an example of an access token response containing an OpenID Connect identity token:

{
    "access_token": "eyJraWQiOiIyMDIwLTA4LTE1VDE3OjM2OjE0Ljg1Ni5lYyIsInR5cCI6IkpXVCIsImFsZyI6IkVTMjU2In0.eyJzdWIiOiJwb3J0YWwiLCJ1cm46Y29tOmNlcm5lcjphdXRob3JpemF0aW9uOmNsYWltcyI6eyJ2ZXIiOiIxLjAiLCJ0bnQiOiJlYzI0NThmMi0xZTI0LTQxYzgtYjcxYi0wZTcwMWFmNzU4M2QiLCJhenMiOiJvcGVuaWQgcHJvZmlsZSB1c2VyXC9QYXRpZW50LnJlYWQifSwiYXpwIjoiZmhpci1sb2NhbCIsImlzcyI6Imh0dHBzOlwvXC9hdXRob3JpemF0aW9uLmNlcm5lci5jb21cLyIsImV4cCI6MTU5NzYyNjgxOCwiaWF0IjoxNTk3NjI2MjE4LCJqdGkiOiIzNGRkZWZiMC0wMzU5LTQwOTctYWJiZS00ZTk2YWFlY2NhNjUiLCJ1cm46Y2VybmVyOmF1dGhvcml6YXRpb246Y2xhaW1zOnZlcnNpb246MSI6eyJ2ZXIiOiIxLjAiLCJwcm9maWxlcyI6eyJzbWFydC12MSI6eyJhenMiOiJvcGVuaWQgcHJvZmlsZSB1c2VyXC9QYXRpZW50LnJlYWQifX0sImNsaWVudCI6eyJuYW1lIjoiRkhJUiBMb2NhbCBUZXN0IENsaWVudCIsImlkIjoiZmhpci1sb2NhbCJ9LCJ1c2VyIjp7InByaW5jaXBhbCI6InBvcnRhbCIsInBlcnNvbmEiOiJwcm92aWRlciIsImlkc3AiOiJlYzI0NThmMi0xZTI0LTQxYzgtYjcxYi0wZTcwMWFmNzU4M2QiLCJzZXNzaW9uSWQiOiIxYjBhZDY3Mi1mZjRmLTRiYzItYTNhNi05ZmUzOWI2N2JiZWIiLCJwcmluY2lwYWxUeXBlIjoidXNlcm5hbWUiLCJwcmluY2lwYWxVcmkiOiJodHRwczpcL1wvbWlsbGVubmlhLmNlcm5lci5jb21cL2luc3RhbmNlXC9lYzI0NThmMi0xZTI0LTQxYzgtYjcxYi0wZTcwMWFmNzU4M2RcL3ByaW5jaXBhbFwvMDAwMC4wMDAwLjAwQzIuNkRCNSIsImlkc3BVcmkiOiJodHRwczpcL1wvbWlsbGVubmlhLmNlcm5lci5jb21cL2FjY291bnRzXC9jMTk0MS5jZXJuX2FiY24uY2VybmVyYXNwLmNvbVwvZWMyNDU4ZjItMWUyNC00MWM4LWI3MWItMGU3MDFhZjc1ODNkXC9sb2dpbiJ9LCJ0ZW5hbnQiOiJlYzI0NThmMi0xZTI0LTQxYzgtYjcxYi0wZTcwMWFmNzU4M2QifX0.-ZfKiTNE2mv28HnussbTu4T3Pq9r_UPo1wYCHu46L6KO9objSEfUJKV4SA8JYoMtBwlH85DoR26Btl5fZ5zK4g",
    "scope": "openid fhirUser user/Patient.read",
    "id_token": "eyJraWQiOiIyMDIwLTA4LTE1VDE3OjM2OjE0Ljg1OS5yc2EiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJwb3J0YWwiLCJhdWQiOiJmaGlyLWxvY2FsIiwicHJvZmlsZSI6Imh0dHBzOlwvXC9maGlyLWVoci1jb2RlLmNlcm5lci5jb21cL2RzdHUyXC9lYzI0NThmMi0xZTI0LTQxYzgtYjcxYi0wZTcwMWFmNzU4M2RcL1ByYWN0aXRpb25lclwvMTI3NDIwNjkiLCJpc3MiOiJodHRwczpcL1wvYXV0aG9yaXphdGlvbi5jZXJuZXIuY29tXC90ZW5hbnRzXC9lYzI0NThmMi0xZTI0LTQxYzgtYjcxYi0wZTcwMWFmNzU4M2RcL29pZGNcL2lkc3BzXC9lYzI0NThmMi0xZTI0LTQxYzgtYjcxYi0wZTcwMWFmNzU4M2RcLyIsIm5hbWUiOiJQb3J0YWwsIFBvcnRhbCIsImV4cCI6MTU5NzYyNjgxOCwiaWF0IjoxNTk3NjI2MjE4LCJmaGlyVXNlciI6Imh0dHBzOlwvXC9maGlyLWVoci1jb2RlLmNlcm5lci5jb21cL2RzdHUyXC9lYzI0NThmMi0xZTI0LTQxYzgtYjcxYi0wZTcwMWFmNzU4M2RcL1ByYWN0aXRpb25lclwvMTI3NDIwNjkifQ.N-5R_9mZ2zmJGTiiwkPhnhOCbjpod9ghjQFuSK4imUNwYI-9po3eyjPB1IcZKkFCEZ0flZRZ8vmEUgj5EyMPA8xdiXPo5C3PQDMbKMw1wm_5nS95XGKNBNBgaQ7Nff69nRF4i4y9IhMO9ndxA7VtNCqP3NnxpeOXLCov-yl7zGlZLKJZ3DTQpBGhWOrWuH16Usk1UuXFp7-6Ih4e6DKkooJyUedEY0_fJ6i36_4xrFZ9D6wlP6F5F3hWbkTbrFEN239jnie8f-tr-mGr0r-KaxQqpG1pa_6UofopK7ngT_Guh46Ib0bUrgTlYDJ5EUDETIjvAwR3kA_2pPgJHfwjaw",
    "token_type": "Bearer",
    "expires_in": 570
}

The claims of the identity token in the above example are as follows:

{
  "sub": "portal",
  "aud": "94bbd90d-482a-4a10-b7df-b40edb278da2",
  "fhirUser": "https://fhir-ehr-code.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Practitioner/12742069",
  "iss": "https://authorization.cerner.com/tenants/ec2458f2-1e24-41c8-b71b-0e701af7583d/oidc/idsps/ec2458f2-1e24-41c8-b71b-0e701af7583d/",
  "name": "Portal, Portal",
  "exp": 1597626818,
  "iat": 1597626218,
  "fhirUser": "https://fhir-ehr-code.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Practitioner/12742069"
}

In this example, the user identifier is “portal”, the issuer is https://authorization.cerner.com/tenants/ec2458f2-1e24-41c8-b71b-0e701af7583d/oidc/idsps/ec2458f2-1e24-41c8-b71b-0e701af7583d/ and the recipient client id is 94bbd90d-482a-4a10-b7df-b40edb278da2.

The following is an example URL for the location of an OpenID Connect configuration document, derived from the issuer in the above id_token:

https://authorization.cerner.com/tenants/ec2458f2-1e24-41c8-b71b-0e701af7583d/oidc/idsps/ec2458f2-1e24-41c8-b71b-0e701af7583d/.well-known/openid-configuration

The following is example content of the configuration document:

{
    "response_types_supported": ["code"],
    "request_parameter_supported": false,
    "require_request_uri_registration": false,
    "request_uri_parameter_supported": true,
    "claims_parameter_supported": false,
    "jwks_uri": "https://authorization.cerner.com/jwk",
    "subject_types_supported": ["public"],
    "id_token_signing_alg_values_supported": ["RS256"],
    "issuer": "https://authorization.cerner.com/tenants/ec2458f2-1e24-41c8-b71b-0e701af7583d/oidc/idsps/ec2458f2-1e24-41c8-b71b-0e701af7583d/",
    "authorization_endpoint": "https://authorization.cerner.com/tenants/ec2458f2-1e24-41c8-b71b-0e701af7583d/oidc/idsps/ec2458f2-1e24-41c8-b71b-0e701af7583d/",
    "token_endpoint": "https://authorization.cerner.com/tenants/ec2458f2-1e24-41c8-b71b-0e701af7583d/oidc/idsps/ec2458f2-1e24-41c8-b71b-0e701af7583d/"
}

In this example, the jwks_uri is: https://authorization.cerner.com/jwk

Session Management

SMART® on FHIR® currently does not prescribe mechanisms for managing session state between applications, or providing a sign-out experience for users.