SMART Client Definitions
In order for a SMART Application to authenticate a user and receive an Access Token using the SMART on FHIR Outbound Security module, a client definition must be created for the application.
Client definitions may be configured using the Web Admin Console or the JSON Admin API. In the Web Admin Console, clients definitions may be found under Module Config OpenID Connect Clients
A Client definition should be created for each SMART Application.
The first time a user authorizes a given client, the user will be prompted to approve any scopes that the client has requested (assuming they are permitted in the client definition. If a client is configured with Remember User Approved Scopes, the user's approval will be persisted and the user will not be prompted to re-approve these scopes in future authentication flows (unless new scopes are also requested).
Users may revoke clients using the Revocation Page.
On the OpenID Connect Clients page, beside each client there is a button to export the configuration for that OpenID Connect Client configuration. This can be useful when copying OpenID Connect client configuration from one environment to another. The configuration content is exported in json format. Any secrets present in the client are redacted.
When importing from a json document, first the system looks up the OpenID Connect Client by the clientId in the uploaded json document. If an existing OpenID Connect Client is found matching the clientId, it is updated with the contents of the uploaded json document. Client Secrets are never overridden in this way. If there are secrets already present in the matching OpenID Connect Client and there are also unredacted Client Secrets present in the uploaded json, the import will fail. If you intend to replace the Client Secrets with new secrets from the uploaded file, you must first manually delete all old secrets from the existing OpenID Connect Client.
If no OpenID Connect Client is found with the same clientId, then a new OpenID Connect Client is created. If a "pid" element is present in the imported data, it ignored.
A client secret can be used to authenticate the Client. It is a similar concept to the user's password in that it is a secret credential used to authenticate, but it is different in that it authenticates a system and not a person.
Client secrets should only be used in situations where the client system is able to securely store the secret. For example, a Single Page Webapp (SPA) or Mobile Application should never use a client secret, since it is possible for malicious users to decompile and examine the source of the application in order to learn the secret.
The default client secret encoding is BCRYPT_12_ROUND, and it is configurable. The full list of options is available here.
Authenticating the client is considered more secure than not authenticating the client (and in the case of the Client Credentials Flow it is required) as long as the client is a Confidential Client.
An alternative to using a client secret to authenticate the client is to use Client JWT Authentication. The JWT method is considered even more secure than using a client secret, and should always be used if possible.
The client definition allows multiple secrets to be defined for a single client. This is done in order to facilitate secret rotation, where a new secret is used periodically. By setting the secret's Activation Date (the earliest date that a given secret will be accepted on) and the Expiration Date (the latest date that a given secret will be accepted on) it is possible to define a window of time where the old secret and the new secret are both usable.
This strategy is useful in cases where client updates need to be propagated and a grace period is required.
An alternative to using Client Secrets for client authentication is to use a signed JWT. This mechanism is described in the Backend Services Authorization specification for authenticating system-to-system backend data transfers. It is also described in Client Credentials Flow with JWT Credential as a mechanism for using this type of client authentication during interactive user authentication flows.
To use Client JWT Authentication, a JWKS containing a public key that will be used to verify the signature of the JWT must be provided in the Smile CDR OIDC Client Definition. JWTs are then signed using a corresponding private key which is held only by the client.
The public JWKS can be included in the OIDC Client Definition in two ways:
Clients may be marked as Client Required to Authenticate, meaning that the client is required to authenticate itself when interacting with the authentication server.
If this property is not enabled:
Clients can be authenticated using either a Client Secret or Client JWT Authentication.
Clients can change their own secret using a HTTP POST to the change-secret endpoint. Clients can change their secret with a grace period, allowing them to briefly have an overlap with the previous secret(s) and the new secret.
The following example shows a SMART Application making a request to the Authorization Server to change their client secret (for readability each parameter is shown on a new line but in a real request these would be joined together in one long line):
POST /oauth/change-secret
Accept: application/json
Content-Type: application/x-www-form-urlencoded
client_id=my-client-id
&client_secret=my-client-secret
&client_secret_new=my-client-secret-new
&grace_period_mins=10
In the above example, all parameters are required except for grace_period_mins. When a client changes their secret without grace period, expiration will be set to now.