Authorization Flows

Introduction

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

Interactive User Launch Flows

The following flows are intended for launching an application in an interactive way: for example, when 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 recommended 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 only appropriate for applications that are fully trusted, since the application has access to user credentials (unlike the other 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.

Launch 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 is able to handle the code exchange with the authorization server.
Mobile Applications where a secured "backend server" exists and 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 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. This 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 Opala highly recommends using it.
redirect_uri. This is the URI belonging to the client application where the user will be redirected when the flow completes.
prompt. (optional) This is a space-delimited, case-sensitive list of ASCII string values that specifies whether the Authorization Server prompts the end-user for re-authentication and consent. Current support is limited to the login value.

Note: 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 submission 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, then 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.
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.

Note: 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",
    "scope":"openid profile patient/*.read"
 }

If the client has requested and been approved with the offline_access or online_access scopes, a Refresh Token will also be provided in the response JSON document:

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

Security Option: Proof Key for Code Exchange (PKCE)

When using public clients with the Authorization Code flow, Opala highly recommends using the Proof Key for Code Exchange extension (also known as RFC7636/PKCE External Link 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 during the code exchange step (Step 4 above) that the client submit a verifier which 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.

When using the Smile CDR Outbound Security module, consider making the use of PKCE mandatory.

Launch 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. Opala recommends 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.

Launch Flow: Resource Owner Password Credentials

Because this flow allows the application to see the raw password that the user enters, this flow is dangerous to use with an app that isn't completely trusted. 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.

Non-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. In turn, Opala will issue a valid Access Token (and 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 External Link . 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 using a corresponding public key.

These tokens are:

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

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.

This flow consists of the following steps:

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://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. 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": "someclientid",
    "aud": "https://my-smile-server/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 and known to the SMART Outbound Security Module.

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 neccesary 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

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

System 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 in the SMART CDR documentation for information on how to use this grant type with the built-in Authorization server.

System Flow: Client Credentials with JWT Credential

This variant of the Client Credentials flow (see above) uses a cryptographically signed JWT as the credential that the client presents to the authorization server, instead of a client secret. This type of authentication is specified as the mechanism for SMART Backend Services External Link and is described in [RFC 7523](JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants) JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants.

In this flow, the client first creates a JWT resembling the following:

                            {
    "jti":"cc7a3074-5c59-4e3f-b493-bb5115049344",
    "sub":"my-client-id",
    "iss":"my-client-id",
    "aud":"http:\/\/example.com\/issuer\/oauth\/token",
    "kid":"some-key-id",
    "exp":1623019405,
     "iat":1623019345
}

Note the following claims in the JWT document:

The sub and iss claims contain the Client ID for the client that is authenticating (this value should be identical for both claims).
The aud claim contains the token endpoint for the Authorization Server.

The JWT is then digitally signed, and passed to the Authorization Server in a request similar to the following:

POST /oauth/token

                        Accept: application/json

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

                            

                            grant_type=client_credentials

                            &client_assertion_type=urn:ietf:params:oauth:grant-type:jwt-bearer

                            &client_assertion=[serialized JWT]

                            {
    "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 in the SMART CDR documentation for information on how to use this grant type with the built-in Authorization server.

System Flow: Refresh Token

The OpenID Connect flow allows for an Authorization Server to issue Access Tokens that are then consumed by Resource Servers in order to authenticate access to APIs. The design of the protocol means that this flow can generally work with minimal direct interaction needed between the Resource Server and the Authorization Server. Tokens leverage digital signatures, meaning that the Resource Server can verify that a token was issued by the Authorization Server without actually needing to communicate with it.

This is a useful property of the process as it means that the two different logical servers have less (or no) need to communicate directly with each other in order to validate individual client requests. This is good for scalability (indeed this is a common design principle in the popular Microservice Architecture application design).

However, this property does have one important drawback: it means that the Authorization Server is not able to notify the Resource Server if it wishes to revoke an access token. Because of this, the Authorization Server will often specify an access token with a short expiry time (often as short as 60 seconds or less) and will issue a second token called a Refresh Token while it is issuing an access token to the SMART Application.

This Refresh Token may be used by the SMART Application to request a new access token when the current one has expired (or perhaps beforehand). By issuing Access Tokens with a short expiry time and regularly requiring the SMART Application to request a new Access Token, the Authorization Server is able to ensure that the SMART Application only has a valid Access Token for an appropriate amount of time (i.e., the Authorization Server can effectively revoke tokens within a short amount of time).

Refresh tokens may also be used by the application to perform background tasks, such as periodic fetches of data on behalf of the user, even when the user is not actively using the client application.

Obtaining a Refresh Token

A client can request that a Refresh Token be issued by requesting the offline_access or online_access scopes (see Scopes later in this documentation set).

If one of these scopes is approved for the client session, the refresh token will be returned to the client during the Authorization Code flow (see above).

Using the Refresh Token

Once a client has a Refresh Token, the token can be exchanged for a new access token using the OAuth2 Refresh Flow.

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

                                Authorization: Basic [client_id:client_secret]

                                

                                grant_type=refresh_token

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

                                &client_id=growth_chart

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",
    "refresh_token":"c5bbdcab-2e02-4c80-bb2c-3022c66b2a7e",
    "expires_in":59,
    "scope":"patient/*.read online_access openid"
}

Refresh Flow without 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

Note: 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.

Top