By default, when a SMART Application requests a new authorization from the SMART Outbound Security module, the module will prompt the user for credentials in order to authenticate them, and will use an Inbound Security Module to verify the credentials directly.
Instead of prompting the user for credentials however, it is also possible to redirect the user to a third-party "Federated" OAUth2/OIDC provider. This allows SMART authentication against a standards compliant OIDC provider that is able to complete the OAuth2 Authorization Code flow, but is not able to support the SMART on FHIR extensions to the base OIDC specification.
In this tutorial, we'll be going over the basics of setting up Smile CDR in federated mode. We'll be using Keycloak as our third party identity provider (IDP), however these instructions are platform agnostic as all OIDC compliant servers should have similar, if not the same settings.
It's highly recommended that you read the Federated OAuth2/OIDC Login section before going through this tutorial to get an idea of what concepts we'll be covering.
A sample KeyCloak configuration is included to help get started quickly.
The first step for getting started is setting up Smile CDR in federated mode.
Most IDPs do not have SMART scopes by default. In order to use SMART scopes, we need to define which ones we want to use in the client definition.
We'll start with building our client definition in Smile CDR. We'll be using the sample Keycloak configuration to set up this client definition. Feel free to substitute values here for your setup.
openid patient/*.read profile
With that, a client definition has been created.
In order for the SMART Outbound Security Module to communicate with your external IDP, a Server Definition needs to be setup. At this point, it's best to have access to your IDP's
.well-known/openid-configuration, as it contains all relevant details for creating a server definition.
This section will use the configuration from a local copy of Keycloak, however, these URLs are standard across all OIDC compliant IDPs.
openid profile- these are default scopes that are needed to get user information.
With that, a server definition has been created. The Authorization Script page describes its usage and how you might go about adjusting the script.
This section will cover how to set up a client in Keycloak to connect with our server definition. Regardless of the IDP chosen, similar configurations should be found in any IDP as these are standard OIDC options that can be configured.
Note that even if you will be registering multiple client (SMART App) definitions in Smile CDR, you will only need to create one definition in the federated provider. The details in this client definition is what we enter in the server definition.
<your registration ID from your Smile CDR server definition>+
Access Token Signature Algorithm&
ID Token Signature Algorithmare set to any one of the accepted algorithms.
You will now have set up a client definition with the proper token signature algorithms.
At this point, you should now have a client definition, server definition, a configured IDP that the server definition is aware of, and your Outbound Security Module set to federated mode. We now need to initiate the Authorization Code flow.
To launch the federated flow, define the following:
code, as federated mode only supports code flow.
The following URL is an example of how you would initiate code flow (using setup details from the earlier sections):
From here, once the user logins into their IDP, they should be redirected to a page that shows the various scopes the client definition has outlined.
Once you've accepted the scopes, you'll be redirected to a page outlined in your redirect URL in the client definition. That URL will contain the
code needed for code exchange. Refer to the Authorization Code flow documentation for how to proceed with code flow.
The following token signature algorithms are accepted when setting up the IDP:
Using any other signature algorithm in your IDP's client setup will cause the token to be rejected by the Outbound Security Module.
*as a redirect URL tends to cause errors with most IDPs & Smile CDR. If you're simply testing, place an arbitrary URL as a redirect instead.