STEP 1

The user logs in

The user authenticates with the third-party system. This could be an EMR, HIS, web portal, etc., using whatever credentials that system supports. This flow assumes that the EHR is able to identify the user and make strong assertions about their identity. This fact is key to understanding the difference between this flow and the other SMART auth flows: for all other flows, the user/system is authenticating with Opala. For this flow, the third-party system is simply asserting the identity of the user/system that will be making requests.

STEP 2:

The EHR Generates an Authorization Token

Per the CODAP specification, the authorization token will be a signed JWT with claims resembling the following example. Note that the claims include information about who the user is, whose data are they requesting, and why are they requesting it.

{
    "iss": "http://third-party-ehr/issuer",
    "sub": "someuser",
    "aud": "https://fhir-server/issuer",
    "acr": "http://nist.gov/id-proofing/level/3",
    "jti": "uuid-representing-token",
    "iat": 1418698788,
    "exp": 1422568860,
    "requested_record": {
        "resourceType": "Patient",
        "name": {
            "text": "Pauline Smith"
        },
        "identifier": [
            {
                "system": "http://example.org/patients",
                "Identifier": "0123456789"
            }
        ],
        "gender": "female",
        "birthDate": "1970-05-18"
    },
    "reason_for_request": "treatment",
    "requested_scopes": "patient/*.read patient/*.write",
    "requesting_practitioner": {
        "resourceType": "Practitioner",
        "identifier": [
            {
                "system": "http://example.org/providers",
                "value": "983736235"
            }
        ],
        "name": {
            "text": "Juri van Gelder"
        },
        "practitionerRole": [
            {
                "role": {
                    "coding": [
                        {
                            "system": "http://snomed.info/sct",
                            "code": "36682004",
                            "display": "Physical therapist"
                        }
                    ]
                }
            }
        ]
    }
}

The "requested record", which is used by the requesting EHR to identify the patient whose record is being accessed, is a simple FHIR Patient resource. The level of identification required is not a requirement. For example, you may choose to require only an identifier, or a name and birth date, etc.

Similarly, the "requesting practitioner" is a FHIR Practitioner resource. The level of identification required is not a requirement.

STEP 3:

Generate Authentication Token

Per the CODAP specification, the authentication token will be a signed JWT containing claims resembling the example below. Note that where the authorization token contained claims about the user and what they wanted to accomplish, this token contains information about the system actually performing the request.

{
    "iss": "http://third-party-ehr/issuer",
    "sub": "{client_id}",
    "aud": "https://{baseurl}/issuer",
    "iat": 1422568860,
    "expires_in": 1438698788,
    "jki": "uuid-representing-token",
    "kid": "key_id"
}

STEP 4:

Third-Party System issues Token Request

This step consists of an HTTP POST from the third-party application to the CODAP Auth Server. The request will resemble the following:

POST /oauth/token

Content-Type: application/x-www-form-urlencoded



grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer

assertion={signed authorization JWT}
&
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer

client_assertion={signed authentication JWT}

In the above example, the {signed authorization JWT} and {signed authentication JWT} should be replaced with signed versions of the JWTs described above, using a key that belongs to the third-party application.

STEP 5:

Invoke Callback Scripts and generate Access Token

In this step, a custom callback script is executed that validates the information supplied by the authorization token and performs any necessary processing for the specific login workflow being implemented. This step is very flexible from implementation to implementation. For example, one implementation might decide that only minimal (or no) details about the patient are required, where another implementation might decide that a complete set of demographics are required to be supplied by the third-party application. This is completely implementation dependent and is specified in the callback script.

STEP 6:

Third-Party System issues Token Request

Once the validation step has completed, an Access Token is generated and returned to the user. This takes the form of a standard OAuth2 token response, such as the one below.

200 OK 
Content-Type: application/json 
{
  "access_token": "iaslfhsfauel3fgterioioeg0o.dfoifsiou.ururhi"
}

STEP 7:

Use Access Token

Once the third-party application has an Access Token, it may be used to perform any REST calls that are authorized. A simple FHIR read operation is shown as an example below.

GET /Patient/123 HTTP/1.1

Authorization: Bearer iaslfhsfauel3fgterioioeg0o.dfoifsiou.ururhi

Accept: application/fhir+json