Federated OAuth2/OIDC Tutorial

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.

Setting up Smile CDR - SMART Outbound Security Module

The first step for getting started is setting up Smile CDR in federated mode.

• Navigate to your Config Module Config SMART Outbound Security Module.
• In the module, navigate to & enable the option Federated OAuth2/OIDC Login.
• Navigate to the top of the module, save & restart.

Setting up Smile CDR - OIDC Client Definition

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.

• Navigate to Config OpenID Connect Clients
• Click on Create Clients to the top left corner of the page
• Enter the following:
  • Client ID: cdr-test
  • Client Name: cdr-test
  • Authorized Grant Types: Authorization Code (enabled)
  • Client Secret: secrettest
  • Authorized Redirect URLs: http://localhost:3000
  • Scopes: openid patient/*.read profile
  • (Optional) Remember User Approved Scopes (enabled)
• Navigate to the top of the page and click on Create

With that, a client definition has been created.

Setting up Smile CDR - OIDC Server Definition

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.

1. Navigate to Config OpenID Connect Servers.
2. Click on Add Servers to the top left corner of the page.
3. Give a name to this server definition - in this case we'll call it cdr-tester.
4. Enter the issuer URL from your openid-configuration: http://localhost:8080/auth/realms/master.
5. Enter the client ID & client secret from your IDP's client definition.

If your IDP does not have at the minimum a client ID setup in its client definition, the server will not be able to establish a connection.

6. The Registration ID is a random GUID that's created automatically by Smile. If your setup depends on a specific ID, you may enter it here

Keep a note of the Registration ID, we'll need this when setting up the redirect URI in the external IDP.

7. Enter the Authorization URL: http://localhost:8080/auth/realms/master/protocol/openid-connect/auth.
8. Enter the Token Endpoint URL: http://localhost:8080/auth/realms/master/protocol/openid-connect/token.
9. Enter the Userinfo Endpoint URL: http://localhost:8080/auth/realms/master/protocol/openid-connect/userinfo.
10. Enter the JWKSet URL: http://localhost:8080/auth/realms/master/protocol/openid-connect/certs.
11. You can leave the request scopes as openid profile - these are default scopes that are needed to get user information.
12. Copy the Authorization Script from the Federated OAuth2/OIDC Login page. This is required, as it helps with setting up details of a user's session.
13. Navigate to the top of the page and click on Create.

With that, a server definition has been created. The Authorization Script page describes its usage and how you might go about adjusting the script.

Setting up the IDP

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.

In Keycloak:

1. Navigate to the Clients option. Click on Create.
2. Enter the following:
   • Client ID: cdr-tester
   • Client Protocol: openid-connect
   • Access Type: confidential
   • Valid Redirect URIs: http://localhost:9200/login/oauth2/code/ + <your registration ID from your Smile CDR server definition> + /*
3. Navigate to the Fine Grain OpenID Connect Configuration at the bottom of the page. Ensure that the Access Token Signature Algorithm & ID Token Signature Algorithm are set to any one of the accepted algorithms.
4. Click on Save.
5. The option for Credentials should now appear on the tab menu at the top of the page. Click on Credentials.
6. Ensure that Client Authenticator is set to Client Id and Secret.
7. Generate a new secret. Depending on how you set up a server definition in Smile CDR, you may need to enter the new client secret in the Client Secret section of your server definition.

You will now have set up a client definition with the proper token signature algorithms.

If you're using Keycloak, the steps above might be different between versions of Keycloak & Redhat SSO. The options are still the same across more recent versions.

Starting the Federated Flow

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:

1. Define the client ID in the launch URL.
2. Define the client secret in the launch URL.
3. Define the response type in the launch URL - this will always be set to code, as federated mode only supports code flow.
4. Define the redirect URL in the launch URL.
5. Define the scopes in the launch URL - note that this should be URL encoded (optional, but recommended).
6. Define the state in the launch URL (optional, but recommended in production).
7. Define the nonce in the launch URL (optional, but recommended in production).

The following URL is an example of how you would initiate code flow (using setup details from the earlier sections):

http://localhost:9200/oauth/authorize?response_type=code&client_id=cdr-test&client_secret=secrettest&redirect_uri=http://localhost:3000&scope=openid%20patient%2F*.read%20profile

Copy

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.

Token Signature Algorithms

The following token signature algorithms are accepted when setting up the IDP:

• RS256
• RS512
• ES256
• ES512

Using any other signature algorithm in your IDP's client setup will cause the token to be rejected by the Outbound Security Module.

Considerations

• Federated mode only supports code flow.
• When using this flow, an access token is generated by the Federated OIDC Provider, but this token is only used by Smile CDR to perform introspection. To the Federated OIDC Provider, your Smile CDR installation is the client requesting access. This means that even if many SMART Applications are registered in Smile CDR and then used, a single client definition will be used by the Federated OIDC Provider.
• All SMART Applications are authorizing against the Smile CDR SMART Outbound Security module. These applications are unaware of the Federated OIDC Provider.
• Access tokens and refresh tokens used to access your FHIR APIs are managed by Smile CDR and not by the Federated OIDC Provider.
• LDAP & the Inbound Security Module have no effect on the Federated flow, as this flow will only work with OIDC capable IDPs.
• Despite settings being similar between the Sever Definition and some options the Inbound & Outbound security modules, there is no other way to set up Federated OA2 aside from the steps outlined in this page.
• If your deployment requires one IDP to connect to Smile CDR, then you'll only need one server definition to set up a connection to it. If there are multiple IDPs that need to work in your solution, then you'll need to define a server definition for each IDP.
• Using * 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.

HL7 v2.x Ingestion Tutorial

Federated OAuth2/OIDC Tutorial

Tutorials

Introduction Integration Testing Tutorial Custom Operations Tutorial HL7 v2.x Ingestion Tutorial Federated OAuth2/OIDC Tutorial MDM Tutorial MDM UI Tutorial MDM First Golden Resource Tutorial MDM Advanced Rule Authoring Tutorial MDM Web UI Admin Setup Tutorial CDA Import Tutorial CDA Export Tutorial CDA Export - Custom Narrative Generation Tutorial CDA Import JSON example CDA Export Template JSON example Consent Tutorial CMS-0057-F IG Setup Tutorial

MDM Tutorial