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.
Setting up this module requires several key configuration items.
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.
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.
In order to generate OpenID Connect Access Tokens, this module requires a JSON Web Key Set (JWKS). This keyset is used to sign the tokens that are generated so that Resource Servers may verify and ultimately trust that they are legitimate.
Note that anyone who is in possession of the key used here is able to generate access tokens. For this reason it is very important that the key be safely stored.
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:
2048 (this is the default, which should be sufficient for most purposes)SigningRS256 should be sufficient)my-openid-token-signature)Once a key is generated, copy its value from the "Keypair set" textbox and set it for use:
classes directory. In this case, the openid.signing.jwks_file (Signing JWKS (File)) property should be set to classpath://[filename].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]"
}
]
}
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.
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.
OIDC clients managed by appSphere will offer the plain-language version of the developer attestation on the approval page.
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.
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.
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.
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(...).
If needed, a callback script may be invoked during the authorization process.
| Function | Context for Use | When Called | Location |
|---|---|---|---|
onAuthenticateSuccess(..) Documentation |
Federated OAuth2/OIDC Mode Only | Called immediately after a token has been issued by the federated provider but before a local (to Smile CDR) user and session has been created. | Federation Auth Script option in the OIDC Server Definition. |
onAuthenticateSuccessClientCredentials(..) Documentation |
Client Credentials with JWT Credential Only | Called immediately after an OIDC client has been authenticated using a JWT credential. | Post-Authorize Script setting on SMART Outbound Security module. |
authenticate(..) Documentation |
CODAP Mode Only | Called immediately after a token has been received from the CODAP token issuer. | CODAP Authorization Script setting on SMART Outbound Security module. |
onSmartLoginPreContextSelection(..) Documentation |
Any Interactive Flow | Called immediately after the user has authenticated in order to determine whether a session context needs to be selected by the user, and to supply the options that will be presented to the user. | Post-Authorize Script setting on SMART Outbound Security module. |
onSmartScopeAuthorityNarrowing(..) Documentation |
Any | Called after the session's authorities have been narrowed based on the approved scopes. This function can be used to restore any removed authorities, or add new ones based on approved scopes or permissions. If Enforce Approved Scopes to Restrict Permissions is not enabled, this function can be used to manually apply scope-based authority narrowing logic in place of the built-in logic. | Post-Authorize Script setting on SMART Outbound Security module. |
onTokenGenerating(..) Documentation |
Any | Called after authentication has succeeded and before an access token (and corresponsing ID token) is issued. | Post-Authorize Script setting on SMART Outbound Security module. |
onPostAuthorize(..) Documentation |
Any | Called after a token has been issued and stored but before it is returned to the client. | Post-Authorize Script setting on SMART Outbound Security module. |
getUserName(..) Documentation |
Federated OAuth2/OIDC Mode Only | Called immediately after a token has been issued by the federated provider but before a local (to Smile CDR) user and session has been created. | Federation Auth Script option in the OIDC Server Definition. |
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.
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.