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 applications that can "keep a secret", meaning that they have an architecture where a backend server is able to keep a secret password that the user will never have access to.
  • Implicit flow is used for interactive applications where there is no ability to keep an application specific credential that the user does not have access to. This is appropriate for single-page web apps (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 should be used by applications that are able to "keep a secret". This typically means applications that have a backend server, and this backend server is fully secured. Note that SMART documentation refers to this as a "confidential client".

The secret referred to here is a password that is specific to the application itself (not the user). Examples of apps that should use the Authorization Code flow 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.

Examples of applications that should not use the Authorization Code flow include:

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

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

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 code it originally provided. 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: http://myserver:9200/oauth/token?client_id=my-client-id&client_secret=MY_CLIENT_SECRET&grant_type=authorization_code&code=cdcd883gr3g8dggakH&redirect_uri=https://myapp.example.com/cb&scope=openid&state=af0ifjsldkj

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

7.11.2Launch Flow: Implicit Grant

 

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