Security Model > Authentication and Authorization Tokens

Authentication and Authorization Tokens

As described in the CODAP specification, a JSON Web Token (JWT) bearer token is used to request an access token from the IAR FHIR Authorization Server. The Client Application is responsible for the creation and signing two separate JWT tokens (authentication and authorization).

JWT Authorization Token

This section describes the content of the JWT Authorization token which is used to make assertions about the user (person) making the request. In the initial pilot phase, the user must be pre-registered in IAR in order to launch the IAR Visual App.

After the content is populated, the authorization JWT must be digitally signed by the Client application as specified in the CODAP specification, using the private key counterpart to the public key registered with IAR.

Claim Optionality Description Sample Data
iss REQUIRED Client Application's issuer URI

This value will be assigned by IAR during the Client Application Registration process.
http://client-app/issuer
sub REQUIRED Client Application’s user id on whose behalf this request is being made. Matches requesting_practitioner.id

Corresponds to the IAR User ID
iar-user-id
acr REQUIRED Level of assurance of the requesting user’s identity
(e.g. NIST level 0-4, as defined in NIST SP 800-63-2)
http://nist.gov/id-proofing/level/3
aud REQUIRED IAR FHIR Authorization Server Token URL (URL to which the authentication JWT will be posted) https://iar-authorization-server/oauth/token
requested_record REQUIRED FHIR patient resource being requested

Patient context is based on Health Card Number and must be populated under patient.identifier section
Refer to requested_record sample below
requested_scopes REQUIRED Patient data being requested patient/*.read profile offline_access cdr_all_user_authorities
requested_practitioner REQUIRED FHIR practitioner resource Refer to requested_practitioner sample below
reason_for_request REQUIRED Purpose for which access is being requested treatment
exp REQUIRED Expiration time integer after which this authorization JWT MUST be considered invalid; expressed in seconds since the "Epoch" (1970-01-01T00:00:00Z UTC). This time MUST be no more than five minutes in the future 1542743248
kid OPTIONAL Key id of the encryption key used to digitally sign this token
jti REQUIRED A nonce string value that uniquely identifies this authorization JWT. MUST have at least 128 bits of entropy and MUST NOT be reused in another token ea3b7768-996d-4e92-a1d3-b52a9eaf9722
iat REQUIRED The UTC time the JWT was created 1542743243

Sample Authorization JWT

The following is a sample authorization JWT:

{
  "iss": "http://client-application/issuer",
  "sub": "client-application-user-id",
  "aud": "https://iar-authorization-server:9001/oauth/token",
  "acr": "http://nist.gov/id-proofing/level/3",
  "requested_record": {
    "birthDate": "1952-01-25",
    "gender": "male",
    "identifier": [
      {
        "system": "https://fhir.infoway-inforoute.ca/NamingSystem/ca-on-patient-hcn",
        "value": "8060101956"
      }
    ],
    "resourceType": "Patient"
  },
  "requested_scopes": "patient/*.read profile offline_access cdr_all_user_authorities",
  "requesting_practitioner": {
    "id": "128641521",
    "identifier": [
      {
        "system": "iar-orgid",
        "value": "345"
      },
      {
        "system": "org-userid",
        "value": "hsp-userid"
      },
      {
        "system": "iar-userid",
        "value": "jgelder"
      }
    ],
    "name": [
      {
        "text": "John Gelder"
      }
    ],
    "resourceType": "Practitioner",
    "telecom": [
      {
        "system": "email",
        "value": "john.gelder@cmha.ca"
      }
    ]
  },
  "kid": "client-name-token-signature",
  "exp": "1542743248",
  "iat": "1542743243",
  "reason_for_request": "treatment",
  "jti": "ea3b7768-996d-4e92-a1d3-b52a9eaf9722"
}

JWT Authentication Token

This section describes the content of the JWT Autentication token which is used to authenticate the Client Application (system) which is making the request on behalf of a user.

After the content is populated, the authentication JWT must be digitally signed by the Client Application as specified in RFC7515 (JSON Web Signature).

Claim Optionality Description Sample Data
iss REQUIRED Client Application's issuer URI
This value will be assigned by IAR during the Client Application Registration process.
http://client-app/issuer
sub REQUIRED The OAuth client_id by which IAR Authorization Server knows the Client Application

This value will be provided during the Client App registration process
HSP_CLIENT_APP_ID
aud REQUIRED IAR FHIR Authorization Server Token URL (URL to which the authentication JWT will be posted)

This value will be provided during the Client App registration process
https://iar-authorization-server/oath/token
exp REQUIRED Expiration time integer after which this authorization JWT MUST be considered invalid; expressed in seconds since the "Epoch" (1970-01-01T00:00:00Z UTC). This time MUST be no more than five minutes in the future 1542743248
kid OPTIONAL Key id of the encryption key used to digitally sign this token.
jti REQUIRED A nonce string value that uniquely identifies this authorization JWT. MUST have at least 128 bits of entropy and MUST NOT be reused in another token 64c8f437-4e0f-492a-a8f8-0cc48376b76b
iat REQUIRED The UTC time the JWT was created and signed by Client Application 1542920080

 

Complete Authentication JWT

The following is a sample authentication JWT:

{
  "iss": "http://client-application/issuer",
  "sub": "someclientid",
  "aud": "https://iar-authorization-server/oauth/token",
  "exp": "1542743510",
  "jti": "5cb82272-8fca-4d52-a810-6679c66dba51"
  "kid": "client-name-token-signature",    
  "iat": "1542743505",  
}

Signing the JWT tokens

CODAP specifies that both the authorization and authentication tokens will be signed using RFC7515, JSON Web Signature. There are a number libraries (different technologies such as .NET, Java, Python, Javascript, Node.js, Perl) for token signing and verification. Refer to jwt.io to find the appropriate library.