25.5.1SMART on FHIR Outbound Security Module

The SMART Outbound Security module is a complete SMART on FHIR compliant Authorization Server. It is able to accept authorization requests from SMART Applications, grant access tokens on behalf of users, and manage these Applications.

25.5.2Setting Up This Module

Setting up this module requires several key configuration items.

25.5.2.1Username/Password Authentication

This module uses an Inbound Security module such as the Local Inbound Security Module or the LDAP Inbound Security Module in order to actually validate user credentials. This module is specified as a dependency in the SMART on FHIR Outbound Security module configuration.

25.5.2.2JSON Web KeySet (JWKS) for Signing Tokens

While it is still possible to save a JWKS to the security module directly, it is advisable to use Keystores for all future Smile CDR key management.

This documentation is kept for posterity.

There are a number of tools that can be used to generate JWKS files. One popular option is the MKJWK tool maintained by the MIT Kerberos and Internet Trust. The steps below show how to create a JWKS file using the online version of their tool; however, for increased security you may wish to download a copy and use it locally:

• Navigate to https://mkjwk.org/
• Select the RSA tab with a key size of 2048 (this is the default, which should be sufficient for most purposes)
• Select a Key Use of Signing
• Select an algorithm (the default of RS256 should be sufficient)
• Enter a meaningful key ID (e.g. my-openid-token-signature)
• Click "Generate New Key"

Once a key is generated, copy its value from the "Keypair set" textbox and set it for use:

• It may be stored in a file in the Smile CDR classes directory. In this case, the openid.signing.jwks_file (Signing JWKS (File)) property should be set to classpath://[filename].
• The raw JWKS JSON document may be placed directly in the openid.signing.jwks_text (Signing JWKS (Text)) property.

Note that a JWKS file will have contents similar to the following:

{
  "keys": [
    {
      "kty": "RSA",
      "d": "cSYq2di [trimmed]",
      "e": "AQAB",
      "use": "sig",
      "kid": "test",
      "alg": "RS512",
      "n": "mVuJygm [trimmed]"
    }
  ]
}

25.5.2.3Issuer URL

The security_out_smart.issuer.url (Issuer URL) property should be set to the outward facing URL at which this module will be accessible.

For example, if Smile CDR is deployed on a server named "myserver" and this module is configured to use port 9200 then this property might be set to https://myserver:9200.

25.5.3Terms of Service

When the terms-of-service feature is active, the login flow will include a separate page to present Terms of Service for the user to accept after login, but before scopes are authorized. The Terms of Service feature is activated by configuring the version string. Once accepted, the user will not be asked again on subsequent logins for that SMART client application until the version string is changed. The system records these user agreement actions per-client with a timestamp. They are also recorded in the audit log. A user's active Terms of Service agreements are revoked along with the access token on the Revocation Page.

The default terms of service page only includes sample text and is not appropriate for production use. Production usage should configure a custom skin to present the desired text. When the TOS text changes, the configured version string should be changed as well to prompt users to re-agree.

25.5.4Plain-language Developer Attestation

OIDC clients managed by appSphere will offer the plain-language version of the developer attestation on the approval page.

25.5.5Client Credentials Grant

When using the Client Credentials Grant, the client will be authenticated and authorized without any user being involved.

This grant type may be used to authorize FHIR operations and other Smile CDR functions as well.

Note that when using this grant type, clients will automatically be granted any scopes listed in the Scopes sectiopn of the client definition. These scopes will be combined with the permissions granted directly to the client in order to determine which operations the client should be permitted to perform.

For example, if the client is given the ROLE_FHIR_CLIENT_SUPERUSER permission and the patient/*.read scope, the client will be permitted to perform read operations but not write operations.

25.5.5.1SMART Backend Services

The SMART Backend Services Authorization Guide describes a mechanism for using a cryptographically signed JWT as the credential for an authenticating client, instead of a client secret. See System Flow: Client Credentials with JWT Credential for a description of how this flow works.

For this flow to work, an OIDC Client Definition must be created in Smile CDR, with the Public JWKS Keystore (i.e. a copy of the keystore that does not contain private keys) included in the appropriate field.

25.5.6Cross-Organization Data Access Profile Grant

The SMART Cross-Organization Data Access Profile (CODAP) is a security specification that allows third-party systems such as EHRs and remote systems to authenticate a user implicitly, meaning that their identity and permission is asserted and trusted by the local authorization server.

This flow would typically be used when a local Smile CDR instance is providing access to clinical data, and you wish to allow users using systems at other organizations to make direct data access (i.e. FHIR API) requests without the need for these users to have an account already created in the local Smile CDR instance.

See CODAP Authorization Flow for a description of how this flow works.

25.5.6.1Authorization Script

When performing a CODAP authorization flow, an Authorization script must be supplied to the module configuration. This authorization script is responsible for examining the supplied Authentication and Authorization tokens, and for determining the appropriate user permissions that should be granted. This permission process is critical to the implementation of the CODAP process: The CODAP specification supplies a mechanism for accepting tokens and the format that these tokens should take, but it does not spell out how an implementor might use these tokens to decide what the user should be allowed to do. This is always going to be implementation specific, which is why a script is used.

The authorization script for CODAP uses the function authenticate(...).

25.5.7SMART Callback Scripts

If needed, a callback script may be invoked during the authorization process.

25.5.8User Self Registration

If configured to do so, users can be permitted to self-register. In this flow, a user fills out a web form, and an account is created for them.

This flow requires an Inbound Security module with support for supplying the User Self Registration Provider module dependency. Currently, only the Local Inbound Security module supports this. See Self Registration for information on how to enable this feature on the Local Inbound Security module.

25.5.8.1Enabling Self Registration

To enable user self registration:

• Enable and configure self registration on the Inbound Security module that is supplying authentication services to the SMART Outbound Security module. This step determines the permissions that are granted to newly created users.

• Set a User Self Registration Provider module dependency from the SMART Outbound Security module to the Inbound Security module providing registration services.

• You may also wish to skin the registration pages to customize the UI that will be seen by users.