SMART Server Definitions

OpenID Connect Server Definitions are used by the SMART Inbound Security module as the definition for an OIDC provider whose tokens may be trusted by the module.

They are also used by the SMART Outbound Security when running in Federated OAuth2 mode as the definition for an OIDC provider to federate with.

Creating a Server Definition

An OpenID Connect Server definition must be created in order to accept external access tokens. This definition describes the external Authorization Server and tells the SMART Inbound Security module that it is okay to trust the Authorization Server and the tokens it generates in order to authorize access to functions in Smile CDR.

To create an OpenID Connect Server definition:

• Using the Web Admin Console, select Module Config OpenID Connect Servers.
• Using the JSON Admin API, use the OpenID Connect Servers Endpoint.

Issuer

The most important property when defining the server definition is the Issuer. This is a URL which points to the base URL of the OpenID Connect Authorization Server you wish to trust. Note that the value here must point to a valid OpenID Connect server, and this server must be network accessible by the SMART Inbound Security module. The issuer URL must also match the iss (issuer) claim that is received as a part of any Access Tokens created by the Authorization Server.

Note that trailing slashes in the Issuer URL are ignored in order to avoid incompatibilities. If the Authorization Server iss claim includes a trailing slash, this will not cause any issues.

Key

If present, the validation key is specified in JWK/JWKS format. Any tokens accepted for this server will be verified against the given key, and authentication will fail if the token can not be verified.

The JWK/JWKS can be supplied from one of the following sources (checked in priority order; the first configured source is used):

1. JWK text — If Key(Text) is set on the server definition, the inline JWK/JWKS text is used directly.
2. JWK file — If Key(File) is set, the JWK/JWKS is read from the specified file path.
3. Direct JWKS URL — If JWKSet URL under the section Federated OAuth2/OIDC Login is set, the key set is fetched from that URL.
4. Well-known discovery (fallback) — If none of the above are configured, the module reads the jwks_url from the issuer's OpenID Connect discovery and retrieves the key set from that URI.

If no key is available from any of these sources, token validation fails.

Client Authentication Mode

If Smile CDR needs to authenticate itself with the OIDC server, the client authentication mode may be specified. The following mode options are available:

• (Not Specified) – If no explicit mode is specified, CLIENT_SECRET_BASIC will be used if a client secret is provided, and no authentication will be provided otherwise.
• NONE – No authentication will be presented to the server.
• CLIENT_SECRET_BASIC – An HTTP Basic Authorization header will be presented to the server, containing the client ID and client secret.
• CLIENT_SECRET_FORM – HTTP POST form parameters will be presented to the server, containing the client ID and client secret.
• PRIVATE_KEY_JWT – A JWT containing the client ID will be signed using a private key held by Smile CDR and presented to the server.