OAuth 2.0

OAuth 2.0 is fundamentally an authorization framework, not an authentication protocol. It grants a third-party application scoped access to a protected resource on behalf of a resource owner without exposing the owner's long-term credentials (username/password).

• Analogy: A valet key for a car. The valet can drive the car (limited access) but cannot open the trunk or glove box (restricted scope) and does not possess the owner's master key.
• Mechanism: The client obtains an access token—a string representing a specific grant—rather than handling raw credentials.
• Critical Distinction: While often used with authentication protocols like OpenID Connect (OIDC), OAuth 2.0 itself answers "What is this client allowed to do?" not "Who is the user?"

The OAuth 2.0 framework defines distinct authorization grant types to accommodate different client types and security postures. Each flow is optimized for a specific use case.

• Authorization Code Grant: The most secure server-side flow. The client exchanges an intermediary authorization code for an access token, keeping the token away from the user-agent (browser). Required for SMART on FHIR confidential clients.
• Client Credentials Grant: Used for machine-to-machine (M2M) communication where no user is involved. The client authenticates directly using its client_id and client_secret.
• Device Authorization Grant: Designed for input-constrained devices (e.g., smart TVs, IoT medical devices) that lack a browser. The user authorizes the device on a secondary screen via a user code.
• Refresh Token Grant: Allows a client to obtain a new access token without re-prompting the user, using a long-lived, revocable refresh token.

Access tokens are minted with a specific, limited scope that defines the exact permissions the client possesses. This enforces the principle of least privilege.

• Mechanism: The authorization server presents a list of scopes during the consent screen. The resource server validates the token's scope against the requested action.
• SMART on FHIR Scopes: SMART defines granular clinical scopes like patient/Observation.read or user/MedicationRequest.write.
• Example: A scheduling app might receive a token scoped for patient/Appointment.read and patient/Appointment.write, but it cannot read sensitive patient/Observation data (lab results).
• Token Introspection: Resource servers can call the introspection endpoint (RFC 7662) to verify if a token is active and what scopes it carries.

OAuth 2.0 primarily uses Bearer tokens—a type of access token where possession of the token is sufficient to gain access. This simplicity requires strict transport-level security.

• Usage: The client presents the token in the Authorization: Bearer <token> HTTP header.
• Security Constraint: Bearer tokens MUST only be transmitted over TLS (HTTPS) to prevent eavesdropping and man-in-the-middle attacks.
• Validation: Resource servers validate the token's signature (if a JWT) or call the introspection endpoint on every request.
• Mitigation: Short token lifetimes (e.g., 5 minutes) and refresh token rotation limit the blast radius of a leaked bearer token.

Before initiating any flow, the client application must be registered with the authorization server to establish a trusted identity.

• Registration: The developer provides application metadata (name, redirect URIs) and receives a client_id and, for confidential clients, a client_secret.
• Confidential vs. Public Clients:
  • Confidential Client: A server-side web app capable of securely storing a secret. Authenticates using client_secret_post or private_key_jwt.
  • Public Client: A native mobile or single-page app unable to protect a secret. Must use PKCE (Proof Key for Code Exchange) to prevent authorization code interception.
• SMART on FHIR Requirement: SMART mandates asymmetric client authentication using JSON Web Keys (JWK) for higher assurance, moving beyond shared secrets.

OAuth 2.0 provides mechanisms to terminate access before a token's natural expiration, which is critical for user logout and security incident response.

• Token Revocation Endpoint (RFC 7009): Allows a client to signal to the authorization server that a specific access or refresh token should be invalidated immediately.
• Use Cases:
  • User-initiated logout in a SMART on FHIR app.
  • Detecting a compromised refresh token.
  • Revoking consent for a specific application.
• Propagation: Revocation is not instantaneous across distributed systems; resource servers should rely on short-lived access tokens and frequent introspection to enforce revocation quickly.