Skip to main content

Authorization

Netsmart CareConnect follows the SMART on FHIR specifications to support the authorization of its FHIR APIs. SMART on FHIR defines patterns/standards for healthcare exchange using FHIR and OAuth/OpenID.

There are three basic access scenarios:

  • Patient Access (Authorization Code Flow)
  • Practitioner Access (Authorization Code Flow) and
  • Backend Access (Client Credentials Grant Type)

Patient and Practitioner Access​

Patient and Practitioner Access allows for FHIR clients to authenticate by using the authorization_code grant type.

Authorization Code Flow​

The authorization code flow is for all user authentication scenarios. Public Clients must use the authorization code flow with Proof Key for Code Exchange (PKCE) to authenticate, as a secret cannot be kept secure.

Authorization Request​

Authorization Request
curl -X GET https://fhir.netsmartcloud.com/auth/43477c76-ceb6-47ed-81c8-1b7c0ae10ca6/oauth2/v1/authorize? \
    'response_type=code&' \
    'client_id=987654321&' \
    'redirect_uri=https%3A%2F%2Fapp.example.com%2Fsmart%2Fredirect&' \
    'scope=launch%2Fpatient%20openid%20fhirUser%20offline_access%20patient%2FPatient.rs&' \
    'state=627bf2ef-8211-4677-aee0-1c3a1e1edc31&' \
    'aud=https%3A%2F%2Ffhir.netsmartcloud.com%2Fprovider%2Fpatient-access%2Fv2%2F43477c76-ceb6-47ed-81c8-1b7c0ae10ca6&' \
    'code_challenge=a4d5f78giw8r&' \
    'code_challenge_method=S256'
NameData TypeDescription
response_typeStringThis is set to code.
client_idStringThis is the client id assigned to your application at registration.
redirect_uriStringThis is the URL we are to redirect the user following login to provide your app the authorization code. This must be authorized in your application’s registration.
scopeStringThis is a space-delimited list of scope that are being requested by your application. At minimum the openid scope must be requested.

Include the appropriate SMART App Launch and Clinical scopes to access the FHIR endpoints. (E.g., launch and patient/Patient.read)
stateStringThis value is a random, one time use string provided by your application that will be returned unmodified in our response. This is used to help prevent cross-site forgery attacks.
audStringThis is the base URL of the FHIR endpoint you intend to utilize.
code_challengeStringThis is required when using the authorization code flow with PKCE. This is a single use string used to validate the subsequent token request.
code_challenge_methodStringThis is required when using the authorization code flow with PKCE. This value indicates the encryption method used to create your code challenge. I.e., S256 for SHA256 encryption.
Response Example​
Response
curl -X GET {redirect uri}? \
    'code={authorization code}&' \
    'state={state value from request}'
NameData TypeDescription
codeStringThis is an obscure code that your application will use to exchange for a token at the token endpoint.
stateStringThis value is the same value provided in the request.

Token Exchange​

We support authenticating your application to obtain the tokens using a Private Key JWT or a client secret for confidential applications. Public applications will not be issued a client secret.

To use the Private Key JWT method, you will need to include your JWK Set URI with the registration of your application.

Token Exchange with Private Key JWT
curl -X POST https://fhir.netsmartcloud.com/auth/43477c76-ceb6-47ed-81c8-1b7c0ae10ca6/oauth2/v1/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code=123456789 \
  -d redirect_uri=YOUR_REDIRECT_URI \
  -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
  -d client_assertion=YOUR_SIGNED_JWT \
  -d code_verifier=4534576

When using a client secret we recommend use of Basic Auth, however we do support their inclusion in the body as well.

Token Exchange with Client Secret
curl -X POST https://fhir.netsmartcloud.com/auth/43477c76-ceb6-47ed-81c8-1b7c0ae10ca6/oauth2/v1/token \
  -H "Authorization: Basic xxxxxxxxx (base64 encoding of {client_id}:{client_secret})" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code=123456789 \
  -d redirect_uri=YOUR_REDIRECT_URI \
  -d code_verifier=4534576
Response Example​
{
 "access_token": "xxxxxxxxxx",
 "token_type": "Bearer",
 "id_token": "yyyyyyyyy",
 "refresh_token": "zzzzzzzzzzz",
 "expires_in": 3600,
 "scope": "launch/patient openid fhirUser offline_access patient/Patient.rs",
 "tenant": "43477c76-ceb6-47ed-81c8-1b7c0ae10ca6",
 // The following claims may also be included depending upon the specific launch scenario
 "patient": "123",
 "encounter": "456",
 "need_patient_banner": false,
 "smart_style_url": "https://oauth.netsmartcloud.com/styles/smart_v1.json",
 "user": "user@example.com"
}

Backend (System) Access​

Backend Access allows for FHIR clients to authenticate without a user using the client_credentials grant type.

Client Credentials Grant Type​

We support authenticating your application using a Private Key JWT. To use this method you will need to include your JWK Set URI with the registration of your application.

Client Credentials Grant Type with Private Key JWT
curl -X POST https://fhir.netsmartcloud.com/auth/43477c76-ceb6-47ed-81c8-1b7c0ae10ca6/oauth2/v1/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=client_credentials \
  -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
  -d client_assertion=YOUR_SIGNED_JWT \
  -d scope=system/Patient.rs%20system/AllergyIntolerance.rs

This most commonly used method is to pass the client id and secret using Basic auth.

Client Credentials Grant Type with Client Secret
curl -X POST https://fhirtest.netsmartcloud.com/auth/43477c76-ceb6-47ed-81c8-1b7c0ae10ca6/oauth2/v1/token \
  -H "Authorization: Basic xxxxxxxxx (base64 encoding of {client_id}:{client_secret})" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=client_credentials \
  -d scope=system/Patient.rs%20system/AllergyIntolerance.rs

Response Example​

{
 "access_token": "xxxxxxxxxx",
 "token_type": "Bearer",
 "expires_in": 3600,
 "scope": "system/Patient.rs",
 "tenant": "43477c76-ceb6-47ed-81c8-1b7c0ae10ca6"
}