On this page:

7.11Authorization Flows

 

There are a number of different flows that can be used for different purposes. Many of these flows share some similarities, but have nuances and tradeoffs making them useful in different scenarios.

The following list outlines different flows for different purposes. These flows are described in greater detail in the sections below.

Interactive User Launch Flows

The following flows are intended for launching an application in an interactive way (e.g. the user is logging into the SMART server via an app that is requesting access to clinical data).

  • Authorization Code flow is used for end user interactive applications (i.e. applications where there is a user directly authenticating), as opposed to applications that are purely business-to-business
  • Implicit flow is a previously recommended flow for interactive applications (SPAs), mobile applications, etc.
  • Resource Owner Password Credentials flow is used when the application should have its own username and password UI and should only pass the credentials directly to the authorization server. This is appropriate only for applications that are fully trusted, since the application has access to user credentials (unlike the flows above).

Non-Interactive User Flows

  • Cross-Organization Data Access Profile allows an entirely separate trusted application stack (such as a system with its own identity provider / user database) to request an access token on behalf of a user to assert the identity of that user without requiring them to log in.

System Flows

  • Client Credentials flow allows a client (i.e. a system) to authorize directly without having a user (i.e. a person) named or present as a part of the authentication.
  • Refresh flow allows a server to request a new access token using a refresh token.

7.11.1Launch Flow: Authorization Code

 

This flow is the most common authorization flow, and is generally the right one to use if you have a real user (i.e. not a system) who needs to authenticate/authorize themself for access to an application.

This flow can be used by applications that are able to "keep a secret" (confidental client), as well as applications that are not (public clients). The secret referred to here is a password that is specific to the application itself (not the user).

Confidential Clients

Examples of confidential clients include:

  • Web Applications where a secured "backend server" exists, and this backend server is able to handle the code exchange with the authorization server.
  • Mobile Applications where a secured "backend server" exists, and this backend server is able to handle the code exchange with the authorization server.

Confidential clients use a client secret to authenticate with the Authorization Server.

Public Clients

Examples of public clients include:

  • Native Mobile Apps where the app is installed on a user's device and the app does not have a separate secure backend server (aside from the FHIR server). Storing a client secret is inappropriate because the secret would need to be stored in the on the device, and a malicious user could theoretically decompile the application and retrieve it.
  • Single Page WebApps where the entire application consists of HTML+JS code. Using a client secret is inappropriate because the User has access to the source code of these applications.

Public clients are recommended to use Proof Key for Code Exchange (PKCE) as described below. PKCE is an additional layer of security intended to compensate for the lack of a client secret.

Flow

The Authorization Code flow works as follows:

Step 1: The SMART Application redirects the user to the Authorization Server (or in the case of a native application, opens a web browser) at a URL similar to the following: http://myserver:9200/oauth/authorize?response_type=code&scope=openid+profile+patient/*.read&client_id=my-client-id&state=af0ifjsldkj&redirect_uri=https://myapp.example.com/cb

Note the parameters in the URL:

  • response_type – This must be set to code for the authorization code flow.
  • scope – Indicates the specific scopes that are being requested.
  • client_id – This is a unique identifier for the given client. In the Smile CDR SMART Outbound Security module, this ID corresponds to a Client Definition.
  • state – (optional) This is a random, opaque string generated by the client. This is verified later in order to prevent replay attacks. It may be omitted, but it is highly recommended to use it.
  • redirect_uri – This is the URI (belonging to the Client application) where the user will be redirected when the flow completes.
  • If the authorization flow is using PKCE, the url will also contain the code_challenge and code_challenge_method parameters:

Step 2: The Authorization Server presents the user with a login screen, and if necessary asks the user to approve the selected scopes.

Step 3: The Authorization Server redirects the user back to the Callback URL, adding several parameters to the URL. For example: https://myapp.example.com/cb?state=af0ifjsldkj&code=cdcd883gr3g8dggakH

The client should verify that the state code matches the state token it originally provided. This is done in order to prevent replay attacks.

The code parameter is a temporary token (an "Authorization Code") provided by the Authorization Server that the SMART Application can now use to exchange for an Access Token.

Step 4: The SMART Application invokes a REST method on the Authorization Server to exchange the Authorization Code for an Access Token. This is done using a request such as the following:

POST http://myserver:9200/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic [client ID and secret]

client_id=my-client-id&grant_type=authorization_code&code=cdcd883gr3g8dggakH&redirect_uri=https://myapp.example.com/cb&scope=openid

Note the headers in the submisson above:

  • Content-Type – This must be set to application/x-www-form-urlencoded
  • Authorization – (optional) If the client is a confidential client (i.e. it has a client secret configured), this header will have the string Basic followed by a space, followed by the Base64 encoding of the string [client ID]:[client secret].

Note the parameters in the submission above:

  • client_id – This is the same Client ID used above.
  • client_secret – This is the same Client ID used above.
  • grant_type – This is set to authorization_code.
  • code – This is the code received from the Authorization Server in the step above.
  • redirect_uri – This must match the URI above.
  • scope – This must match the scopes above.
  • If the flow is using PKCE, the code_verifier parameter should also be included.

The Authorization Server will respond with a response similar to the following, which includes the Access Token:

{
   "access_token":"eyJraWQiOiJ1.eyJhenAiOiJteS1jbGllb.Bv42OB0p",
   "id_token":"eyJra33ed8dofh.doh3ohfeisgdOiJteS1jbGllb.u44hdhB0p",
   "token_type":"bearer",
   "expires_in":59,
   "scope":"openid profile patient/*.read"
}

Proof Key for Code Exchange (PKCE)

When using public clients with the Authorization Code flow, it is highly recommended to use the Proof Key for Code Exchange extension (also known as RFC7636/PKCE and pronounced "Pixy") in order to mitigate potential interception attacks. PKCE allows the client to add an additional token to the initial authorization request (step 1 above) and then requires the client to submit a verifier during the code exchange step (step 4 above) that can be used as additional proof that no "man in the middle" has intercepted the authorization code and is trying to maliciously redeem it.

In order to use PKCE, the client should first generate a random string to use as a challenge. For example: d93i4uggdiuf8p4or0Au (Do not use the same string shown in this example! You must generate a new random string each time PKCE is used)

The client should then generate a SHA-256 hash of this string, and Base64 encode the result. For the example above, this results in: 6VLmPKYqeh3cI/YKXLbeOLfF0SiR3/38pQC6ozldmXs=

The following additions to the steps described above are then performed.

Step 1: When the SMART Application redirects the user to the Authorization Server, two new parameters are added as shown in the following example. http://myserver:9200/oauth/authorize?response_type=code&scope=openid+profile+patient/*.read&client_id=my-client-id&state=af0ifjsldkj&redirect_uri=https://myapp.example.com/cb&code_challenge=6VLmPKYqeh3cI/YKXLbeOLfF0SiR3/38pQC6ozldmXs=&code_challenge_method=S256

Note the two extra parameters in the URL:

  • code_challenge – This is the Base64 encoded SHA256 hash of the challenge string.
  • code_challenge_method – This parameter should have a value of S256 to indicate the hashing method. Note that a value of PLAIN is also allowed, but is not recommended for use as it is less secure.

Step 4: When performing the code exchange, one new parameter is added as shown in the following example.

POST http://myserver:9200/oauth/token
Content-Type: application/x-www-form-urlencoded

client_id=my-client-id&grant_type=authorization_code&code=cdcd883gr3g8dggakH&redirect_uri=https://myapp.example.com/cb&scope=openid&code_verifier=d93i4uggdiuf8p4or0Au

Note the additional parameter:

  • code_verifier – This is the original (unhashed) challenge string.

7.11.2Launch Flow: Implicit Grant

 
The Implicit Grant flow is fully supported in Smile CDR, but it is generally not recommended for use by many security experts. We recommend using the Authorization Code flow without a Client Secret for applications that are unable to keep a secret.

This flow is used for applications that are unable to "keep a secret". It should only be used in these cases.

Step 1: The SMART Application redirects the user to the Authorization Server (or in the case of a native application, opens a web browser) at a URL similar to the following: http://myserver:9200/oauth/authorize?response_type=id_token%20token&scope=openid+profile+patient/*.read&client_id=my-client-id&state=af0ifjsldkj&redirect_uri=https://myapp.example.com/cb

Step 2: The Authorization Server presents the user with a login screen, and if necessary asks the user to approve the selected scopes.

Step 3: The Authorization Server redirects the user back to the Callback URL, adding several parameters to the URL. For example: https://myapp.example.com/cb?state=af0ifjsldkj&access_token=cdcd883gr3g8d.ggakHeuedhd&token_type=bearer&expires_in=60

In this response the access_token parameter contains the Access Token that has been granted.

7.11.3Launch Flow: Resource Owner Password Credentials

 
This flow is dangerous to use with an app that isn't completely trusted. This is because this flow allows the Application to see the raw password that the user enters. It should generally only be used for applications that were developed by the owner of the Resource Server.

This flow relies on credentials being collected directly in the source application and then transferred to the Authorization Server for validation.

To perform the Resource Owner Password Credentials flow, the Application collects the user's username and password directly in the Application UI. It then uses an HTTP POST to the token endpoint in order to request an access token.

The following example shows a SMART Application making a request to the Authorization Server to grant a new Access Token using the Resource Owner Password Credentials flow (for readability each parameter is shown on a new line but in a real request these would be joined together in one long line):

POST /oauth/token
Accept: application/json
Content-Type: application/x-www-form-urlencoded

grant_type=password
&client_id=growth-chart
&client_secret=someclientsecret
&username=someuser
&password=someuserspassword
&scope=openid+profile+patient.%2A%2Fread

This client request must contain the client secret if the client definition has one.

The Authorization Server will respond with a response similar to the following, which includes the Access Token:

{
   "access_token":"eyJraWQiOiJ1.eyJhenAiOiJteS1jbGllb.Bv42OB0p",
   "id_token":"eyJra33ed8dofh.doh3ohfeisgdOiJteS1jbGllb.u44hdhB0p",
   "token_type":"bearer",
   "expires_in":59,
   "scope":"openid profile patient/*.read"
}

Client Secrets for Resource Owner Password Credentials

If the Client definition contains a client secret, this secret must be provided during the grant process. This should only be done if the communication between the Client application and the Authorization Server is being performed using a trusted and secured backend server.

If the Client definition does not contain a client secret, this flow will be permitted without the client secret as a request parameter. Use this mode with caution as it has security implications which must be considered!

7.11.4Non-Interactive User Flow: Cross-Organization Data Access Profile

 

The SMART Cross-Organization Data Access Profile (CODAP) is useful in scenarios where data is being requested from a trusted third-party application that maintains its own identity provider and does not wish to federate at the directory level.

This flow is fundamentally different from the interactive flows in that it allows the third-party application to securely assert the identity of the requesting system and user to Smile CDR. Smile CDR will in turn issue a valid Access Token (and will create entries in its own user database in order to track audit events) but will not attempt to verify the identity of the calling user at all.

Authorization and Authentication Token

The Cross-Organization Data Access Profile uses two separate tokens which are generated and signed by the third-party application. The technology for this signature involves JSON Web Tokens. For this exchange to be secure, the tokens are signed using a private key that only the third-party application has access to, and are verified by Smile CDR using a corresponding public key.

These tokens are:

  • The Authentication Token contains an assertion about the system (application) that is making the request on behalf of a user
  • The Authorization Token contains an assertion about the user (person) making the request

Note that although the specification treats these as separate tokens in order to facilitate flows where these tokens are generated in separate steps, it is also possible to generate a single token containing all relevant assertions. This can reduce the burden on implementors.

CODAP Data Flow

The following diagram illustrates the Cross-Organization Data Access Profile.

CODAP Flow

This flow consists of the following steps:

  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 Smile CDR. For this flow, the Third-Party System is simply asserting the identity of the user/system that will be making requests.

  1. 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 is the user, whose data are they requesting, and why are they requesting it.

{
  "iss": "http://third-party-ehr/issuer",
  "sub": "someuser",
  "aud": "https://my-smile-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 of Smile CDR. 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 of Smile CDR.

  1. 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": "someclientid",
  "aud": "https://my-smile-server/issuer",
  "iat": 1422568860,
  "expires_in": 1438698788,
  "jki": "uuid-representing-token",
  "kid": "key_id"
}

  1. 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 and known to the SMART Outbound Security Module.

  1. 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 neccesary processing for the specific login workflow being implemented. This step is very flexible from implementation to implementation. For example, one implementation of Smile CDR 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.

  1. Return Access Token to Third-Party Application

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"}

  1. 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

See the CODAP Grant section of the SMART Outbound Security module documentation for information on how to use this grant type with the built-in Authorization server in Smile CDR.

7.11.5System Flow: Client Credentials

 

The Client Credentials flow can be used to authenticate a client directly, without the involvement of any user account.

This is useful in situations where a system needs to be authorized for actions without needing to involve or authorize a user. For example, this grant type could be used for authenticating a system for system-to-system data flow.

The following example shows a SMART Application making a request to the Authorization Server to grant a new Access Token using the Client Credentials Grant (for readability each parameter is shown on a new line but in a real request these would be joined together in one long line):

POST /oauth/token
Accept: application/json
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=growth-chart
&client_secret=someclientsecret

The server will then respond with a response similar to the following, which includes a new Access Token (note that the Authorization Server may or may not reuse the same Refresh Token at its own discretion).

{
   "access_token":"eyJraWQiOiJ1bml0dG.eyJhenAiOiJteS1j.THbNnfuX7Ly4g",
   "token_type":"bearer",
   "expires_in":59,
   "scope":"patient/*.read"
}

See the Client Credentials Grant section of the SMART Outbound Security module documentation for information on how to use this grant type with the built-in Authorization server in Smile CDR.

7.11.6System Flow: Refresh

 

The Refresh Flow is used by a backend server to request a new Access Token using a Refresh Token that was granted by the Authorization Server.

The following example shows a SMART Application making a request to the Authorization Server to grant a new Access Token using a Refresh Token (for readability each parameter is shown on a new line but in a real request these would be joined together in one long line):

POST /oauth/token
Accept: application/json
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=37d53025-964c-4ab4-afcb-54ea5d892ebb
&client_id=growth-chart
&client_secret=someclientsecret

The server will then respond with a response similar to the following, which includes a new Access Token and a Refresh Token that may be used to request the next Access Token (note that the Authorization Server may or may not reuse the same Refresh Token at its own discretion).

{
   "access_token":"eyJraWQiOiJ1bml0dG.eyJhenAiOiJteS1j.THbNnfuX7Ly4g",
   "token_type":"bearer",
   Constants.GRANT_TYPE_REFRESH_TOKEN:"c5bbdcab-2e02-4c80-bb2c-3022c66b2a7e",
   "expires_in":59,
   "scope":"patient/*.read online_access openid"
}

Refresh Flow without Client Secret

Note that if the client definition is not marked as Client Secret Required to Authenticate, it will be possible for the client to request a new access token without requiring the use of the client secret.

In this case, the client must present a valid Access Token instead. The following example shows such a request. Note that the Client ID is not presented.

POST /oauth/token
Accept: application/json
Authorization: Bearer zddefffpof4wopwjfsf.sfsef9ef9oesjKLKLhldhdg
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=37d53025-964c-4ab4-afcb-54ea5d892ebb