Azure Active Directory / Microsoft Entra

Azure Active Directory can be used independently as an authorization server, however some caveats exist regarding the usage of SMART on FHIR here.

Note

Firely only provides support for deployment and configuration of Firely Auth. The usage of any other authorization server falls outside of the scope of support and may be subject of consultancy instead.

Azure Active Directory (v2.0) does not allow to define a scope with / (forward slash) in it, which is not compatible with the structure of a SMART on FHIR scope. Therefore when you use AAD to provide SMART on FHIR scopes to Firely Server, you need to take the following steps

  1. In a SMART scope, use another character (for instance -) instead of /. For example:

  • user/*.read becomes user-*.read

  • user/*.write becomes user-*.write

  • patient/Observation.r becomes patient-Observation.r

If the used character (for instance -) is already in your SMART scope, then you can use \ (backward slash) to escape it.

  • patient/Observation.r?_id=Id-With-Dashes becomes patient-Observation.r?_id=Id\-With\-Dashes

If a \ (backward slash) is already in your SMART scope, then you can escape it with another \.

  • patient/Observation.r?_id=Id\With\BackwardSlash becomes patient-Observation.r?_id=Id\\With\\BackwardSlash

  1. Configure Firely Server which character is used in Step 1, then Firely Server will generate a proper SMART on FHIR scope and handle the request further. This can be configured via setting AccessTokenScopeReplace.

For the first step above, instead of requesting different scopes in the user application, you can deploy SMART on FHIR AAD Proxy to Azure, which helps you to replace / to - in a SMART scope when you request your access token. The other option would be to follow Quickstart: Deploy Azure API for FHIR using Azure portal, check “SMART on FHIR proxy” box in the “Additional settings” and use the proxy by following Quickstart: Deploy Azure API for FHIR using Azure portal.

Warning

When you use the SMART on FHIR AAD Proxy, be careful with SMART on FHIR v2 scopes. - is an allowed character within the access scope (see examples below). In those cases, the proxy simply replaces / with - and does not escape the original -, then Firely Server cannot figure out which - is original, which will result in a failed request.

  • patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory

  • Observation.rs?code:in=http://valueset.example.org/ValueSet/diabetes-codes

Firely Server provides a plugin to interpret SMART on FHIR scopes by default, however it needs to be enabled and configured. For its configuration see Enforcing access control. For the configuration of additional access policies, to restrict access based on the authenticated user see Permissions (AccessPolicy).