Authentication
In line with the SMART framework, authentication is typically an integral part of the OAuth 2.0 authorization process. For verifying end-user identity, an external identity provider is expected, typically using OpenID Connect (OIDC). While OIDC is the recommended approach, the exact mechanisms of identity verification are considered implementation-specific and fall outside the scope of this specification.
Supported Authentication Flows
Client Applications may authenticate with the Platform using one of the following OAuth2-compatible flows. The choice of flow depends on the client application type (public vs. confidential) and the desired security posture.
-
Authorization Code Grant with Proof Key for Code Exchange (PKCE): Recommended for public clients (e.g., browser or mobile apps) as it does not require a client secret and mitigates interception risks.
-
Authorization Code Grant with
client_secret: Suitable for confidential clients, such as backend web applications capable of securely storing secrets. -
Client Credentials Grant: Used when no end-user is involved (e.g., background system-to-system communication).
-
JWT Bearer Token Grant: Preferred for confidential clients using asymmetric keys (e.g., JSON Web Keys) to authenticate via signed JWTs in accordance with JSON Web Signature (JWS).
Platform implementation must clearly advertise which flows are supported in its .well-known/smart-configuration metadata document. This allows clients to dynamically determine how to authenticate and obtain tokens.
Client Authentication Methods
SMART distinguishes two main authentication methods for confidential clients:
-
Asymmetric Authentication: The preferred method in SMART framework. This approach avoids transmitting shared secrets. It leverages either the Client Credentials Grant or the JWT Bearer Token Grant, using public/private key pairs (e.g., JSON Web Keys) for authentication.
-
Symmetric Authentication: This approach is simpler but less secure and uses a pre-shared
client_secretto authenticate. Typically used with the Authorization Code Grant flow.
Deprecated Flows
The following OAuth 2.0 flows are discouraged and MUST NOT be used within SMART on openEHR due to security concerns:
-
Implicit Grant: Exposes tokens in the URL and lacks proper confidentiality guarantees.
-
Resource Owner Password Credentials Grant: Involves direct transmission of user credentials and does not support modern identity federation.
Flow Recommendations
The following recommendations apply based on client type and use case:
-
Public clients should use the Authorization Code Grant with Proof Key for Code Exchange (PKCE) exclusively. This flow offers strong security without requiring client secrets.
-
Confidential clients may use the Authorization Code Grant with Proof Key for Code Exchange (PKCE), or the Authorization Code Grant with
client_secret, depending on security infrastructure. -
Backend services must use a confidential client and are recommended to use the JWT Bearer Token Grant (preferred) or the Client Credentials Grant, depending on the level of trust and identity requirements.
These flows ensure secure and appropriate access to the Platform based on the capabilities and deployment context of the application.
The table below illustrates recommended flows for common application scenarios:
| Application Example | Client Type | User Interaction Type | Recommended Flow |
|---|---|---|---|
Single Page Web Application for a Patient Portal |
Public |
Patient-facing |
Authorization Code Grant with PKCE |
Mobile Application for Tracking Heart Rate |
Public |
Patient-facing |
Authorization Code Grant with PKCE |
Web Application with Backend for Cardiology Management |
Confidential |
Practitioner-facing |
Authorization Code Grant with PKCE or Authorization Code Grant with |
Realtime Alert System for Hospital |
Confidential |
Backend service |
JWT Bearer Token Grant with JWS or Client Credentials Grant |