Client Management
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.
A client secret is 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.
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.
Clients may be marked as Client Secret Required to Authenticate, meaning that the client is required to authenticate itself when interacting with the authentication server.
If this property is not enabled, but a client secret is present:
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.