API Authenticatoin

Overview
Authentication Overview
• Authentication vs Authorization
o Authentication: Identifies who the user or machine is.
o Authorization: Determines what the identified entity is allowed to do.
o Authorization typically depends on authentication.
Authentication Methods
• Basic Authentication
o Uses the HTTP Authorization header with the Basic scheme.
o Sends username and password (base64 encoded).
o Often used for machine identity.
o Exposes credentials to multiple systems.
o Common but insecure without TLS.
• API Keys
o Single token representing both identity and access.
o Used for application identification, throttling, and monetization.
o Limited to machine identity.
o Debate on whether it's a true authentication method.
• TLS Authentication (Mutual TLS)
o Both client and server authenticate using certificates.
o Proves possession of private key without sending it.
o Enables encrypted communication.
o More secure than Basic Auth and API keys.
o Not practical for user authentication.
o Higher CPU overhead, mostly used internally.
• Token-Based Authentication
o Third party issues tokens to the client.
o Tokens can expire, include audience, and carry identity information.
o Supports both user and machine identity.
o Tokens can be used for authorization as well.
o Tokens can contain detailed information (location, age, account).
o Valid tokens can still be unauthorized for certain actions.
OAuth and OpenID Connect
• OAuth
o Delegation protocol for API access.
o OAuth 1.0 (2010):
▪ Used message signing, didn't require HTTPS.
▪ Hard to implement, limited adoption.
o OAuth 2.0 (2012):
 ▪ Simplified client implementation.
▪ Requires HTTPS.
▪ Widely adopted, standard for API security.
o OAuth 2.1:
▪ Consolidation and cleanup of extensions.
▪ No breaking changes.
• OpenID Connect
o Built on top of OAuth.
o Adds identity layer for user authentication.
o Enables federation between domains.
o Out of scope for this course, but tightly related.
Key Points
• Machine and user authentication often need to be combined.
• OAuth is token-based and relies on TLS.
• Token architecture supports advanced authorization.
• Scopes (OAuth) and claims (OIDC) define token behavio

OAuth

Background
• In the early 2010s, large companies like Yahoo faced a challenge:
o They had valuable services and APIs.
o Third-party developers wanted to integrate with these services.
o However, companies didn’t want to share user credentials or sensitive identity data with third
parties.
• Example:
o If a third-party app wanted access to your Yahoo email history, the straightforward way before
OAuth would be for you to share your Yahoo username and password with the app.
o This was unacceptable for several reasons:
▪ Trust issues: The app could misuse your credentials.
▪ Privacy: Companies didn’t want to disclose customer identity details.
▪ Security: Credentials could be stored or transmitted insecurely.

The Problem OAuth Solves

• How can a third-party application access a user’s data on the user’s behalf without:
1. The user’s credentials being exposed to the third party.
2. Losing control over which data is shared and for how long.
• OAuth’s solution:
o Provide delegated access so that applications can access resources without direct credential
sharing.
 o Ensure the user is aware that access has been granted to the third-party app.

Core Concept: Delegation vs Authorization

• Delegation: Giving someone else permission to act on your behalf.
o Example: Your boss gives you a signed paper authorizing you to withdraw company funds from
the bank.
• Authorization: The process where the system (e.g., bank) decides whether you can perform the action.
o In the example, the bank still decides whether you can withdraw the funds, based on its own
rules.
• Key takeaway:
o OAuth is a delegation protocol, not strictly an authorization protocol.
o Having an OAuth token means you have delegated rights, but the final authorization still
depends on the API or resource server.

Actors in OAuth
There are four key actors in the OAuth process:
1. Resource Owner (RO)
o The entity that owns the data or resource.
o Usually the user.
o Example: You, the Yahoo account holder.
2. Resource Server (RS)
o The server hosting the protected resources.
o Usually an API.
o Example: Yahoo’s email API, holding your email data.
o Responds to requests only if valid access tokens are provided.
3. Client
o The application requesting access to the resource server on behalf of the resource owner.
o Could be a web app, mobile app, or another service.
o Example: A third-party calendar app that wants to access your Yahoo emails.
4. Authorization Server (AS)
o Issues access tokens to the client after authenticating the resource owner and obtaining
authorization.
o Example: Yahoo’s OAuth service.
o Often the same system as the resource server, but logically a separate role.

How Delegation Works in OAuth

1. The user (resource owner) uses the client (third-party app).
2. The client needs to access data from the resource server.
3. The authorization server verifies with the user that access should be granted.
4. If approved, the authorization server issues an access token to the client.
5. The client uses this token to request data from the resource server.
6. The resource server checks:
 o Is the token valid?
o Does it have the correct permissions (scopes)?
o Are there any other business rules preventing access?
7. The server either allows or denies access.

Important Clarifications
• Delegation is not the same as authorization
o Delegation: The client is allowed to act on your behalf (token issuance).
o Authorization: The resource server makes the final decision whether to allow access for a
specific request.
• Tokens ≠ guaranteed access
o A valid token can still be rejected if conditions aren’t met (e.g., expired scope, business rules,
policy constraints).

Key Summary Points

• OAuth was created to allow secure, controlled, third-party access to user resources without exposing
credentials.
• Four actors: Resource Owner, Resource Server, Client, Authorization Server.
• OAuth is delegation-focused, not purely an authorization protocol.
• The presence of a token means delegation has occurred, but authorization is still up to the API.
• The user must always be aware when delegation is granted.

OAuth 2.0 Pattern of Interaction

OAuth flows define how a client application obtains tokens to access APIs.
Each flow is suited for different application types and security needs. Choosing the correct flow depends on
whether you have an end user, the type of client, and the level of security required.

1. Authorization Code Flow

Description:
The most common and most secure OAuth flow, designed for applications where a user is involved (e.g., web
apps). It uses both front-channel (browser redirects) and back-channel (server-to-server) communication to
ensure security.
Key Steps:
1. Initiating the Authorization Request
o User visits the client application and triggers a login.
o The client redirects the browser to the authorization endpoint of the Authorization Server.
o Parameters sent:
▪ response_type=code → indicates Authorization Code Flow
▪ client_id → identifies the application
▪ scope → specifies requested permissions
 ▪ code_challenge & code_challenge_method → part of PKCE (Proof Key for Code
Exchange) for added security
▪ state → random value to maintain request integrity and prevent CSRF
Why: This step starts the user authentication process and establishes what the client is asking for.
2. User Authentication
o Authorization Server decides how to authenticate the user (OAuth spec leaves this open).
o Could involve:
▪ Username/password + MFA
▪ Passkeys
▪ Federated login via another IdP
o After successful authentication, the server decides whether to issue an authorization code.
Why: Confirms the user’s identity before granting access.
3. Redirect with Authorization Code
o Authorization Server redirects the browser back to the pre-registered redirect URI of the client.
o Query parameters sent:
▪ code → short-lived, single-use token
▪ state → matches initial request value for validation
Why: Passes control back to the client with a secure, temporary code.
4. Token Request (Back Channel)
o Client sends a POST request to the token endpoint.
o Parameters:
▪ grant_type=authorization_code
▪ client_id and client_secret (or other client authentication)
▪ code_verifier (for PKCE validation)
▪ code (from redirect)
o Server validates:
▪ Client authentication
▪ Code validity
▪ Code–client binding
Why: Exchanges the authorization code for tokens securely.
5. Token Response
o Authorization Server responds with:
▪ access_token → used to access APIs
▪ refresh_token → to obtain new access tokens without re-authentication
▪ scope → granted permissions
▪ token_type → typically Bearer
▪ expires_in → access token lifetime (commonly ~5 min)
Why: Provides credentials for API access.

2. Refresh Token Flow

Description:
Used to obtain new access tokens without forcing the user to re-authenticate, improving user experience and
reducing login frequency.
Key Steps:
1. Trigger Refresh
o Client detects that the access token is expired or near expiry.
2. Send Refresh Token Request
o POST to token endpoint with:
▪ grant_type=refresh_token
▪ client_id and client_secret (authentication)
▪ refresh_token
3. Server Validation
o Checks if the refresh token is valid and still active.
o May issue the same refresh token or a new one (rotating refresh tokens).
4. Token Response
o Returns:
▪ New access_token
▪ Possibly new refresh_token
▪ Updated scope (may differ if permissions have changed)
▪ expires_in
Why:
Avoids re-running the entire authorization process. Particularly useful for short-lived access tokens with long-
lived sessions.
Notes:
• Refresh token lifetime varies (hours to years).
• Often longer for mobile/desktop apps than web apps.
• No standard expiry in the OAuth spec; check implementation details.

3. Client Credentials Flow

Description:
Used when there is no user involved. Ideal for machine-to-machine communication, such as API-to-API calls or
background jobs.
Key Steps:
1. Token Request
o Client sends a POST request to the token endpoint with:
▪ grant_type=client_credentials
▪ client_id and client_secret
▪ scope → desired API permissions
2. Server Validation
o Confirms client identity and permission to request specified scopes.
3. Token Response
o Returns:
▪ access_token
 ▪ scope
▪ expires_in
▪ token_type (typically Bearer)
o No refresh token is issued; client simply requests a new access token when needed.
Why:
Simplifies authentication for trusted backend systems without interactive logins.

4. Flow Selection Guidelines

• If you have a user: Use Authorization Code Flow (with PKCE if possible).
• If you have no user: Use Client Credentials Flow.
• Always choose the flow that provides the highest security and meets your app’s architecture.
• OAuth “flows” = “grants” = “interaction patterns” (different names for the same concept).

Token Overview

Tokens are a fundamental concept in OAuth and OpenID Connect protocols used for authorization and
authentication. Understanding their formats, purposes, and types is essential for secure implementation and
correct usage.

1. Token Formats
Token format defines how the token data is encoded and how it can be validated.
By Reference Tokens (Opaque Tokens)
• Tokens are opaque strings with no readable or decryptable content for the client or resource server.
• The token itself is just a random identifier referencing a record on the Authorization Server.
• To validate or retrieve any info, the client or resource server must query the Authorization Server.
• They provide strong privacy as no information is exposed in the token itself.
• Common in scenarios where token introspection (validation by server lookup) is used.
By Value Tokens
• Tokens carry all relevant information embedded inside them.
• The recipient can validate the token independently, without contacting the Authorization Server.
• They are usually cryptographically signed and optionally encrypted.
• Examples:
o JWT (JSON Web Token): The most widely used by-value token format.
o SAML Assertions: XML-based tokens mostly used in enterprise SSO.
o CWT (CBOR Web Token): Compact binary format for constrained environments.

2. Token Purposes
Defines who the token is intended for and how it should be used.
Access Tokens
• Used by clients to access protected resources (resource servers/APIs).
 • The resource server validates the token and enforces access control.
• Typically short-lived to reduce risk if leaked.
Refresh Tokens
• Used only between the client and the Authorization Server.
• Allows the client to obtain new access tokens without re-authenticating the user.
• Should be securely stored and never sent to resource servers or exposed.
ID Tokens (OpenID Connect)
• Represent the authenticated user's identity information.
• Issued to the client application after authentication.
• Not meant to be sent to resource servers or other parties.
• Primarily used to verify the user identity and session.

3. Token Types (How Tokens Are Used)

Token type defines the usage semantics—specifically how possession of the token relates to authorization.
Bearer Tokens
• Most common type.
• Analogous to cash or a bearer bond: whoever holds the token can use it.
• No additional proof of identity is required.
• High risk if exposed: an attacker with the token can impersonate the user.
• Must be transmitted over secure channels (TLS/HTTPS).
• Must be kept secret, never logged or stored insecurely.
• Browser cookies behave similarly (not bound to a particular browser instance).
Proof of Possession (POP) Tokens / Holder-of-Key Tokens
• Requires the client to prove possession of a cryptographic key associated with the token.
• Analogous to a credit card with a PIN: possessing just the token is insufficient.
• Provides stronger security guarantees by binding token usage to the client’s key.
• Examples:
o DPoP (Demonstration of Proof of Possession): Adds a cryptographically signed header binding
token to a request.
o Mutual TLS (mTLS): Binds token usage to a client TLS certificate.
• POP tokens prevent misuse if tokens are leaked since an attacker would also need the key.

4. Using Access Tokens in Requests

• Bearer tokens are sent in the HTTP Authorization header as:
Authorization: Bearer <token>
• For DPoP tokens, two headers are sent:
Authorization: DPoP <token> and a separate DPoP header with the proof JWT.
• The client should treat tokens as opaque strings, not make assumptions about their internal structure
or format.
• Tokens can have any string format, length, and character set, including underscores, dashes, digits, etc.
• Clients should avoid parsing or depending on token format to ensure compatibility with server-side
changes.
5. JSON Web Tokens (JWT)
JWT is a widely used token format, not a protocol or token purpose. It encodes claims in a JSON structure and
ensures integrity via signatures.
Structure
• Three base64url-encoded parts separated by dots:
HEADER.PAYLOAD.SIGNATURE
• Header: Metadata about the token including:
o alg: The cryptographic algorithm used for signing (e.g., RS256).
o kid: Key ID referencing which key signed the token, useful for key rotation.
o x5t: X.509 certificate thumbprint (alternative to kid).
• Payload: Contains claims such as:
o iss: Issuer (authorization server URL).
o sub: Subject (user ID).
o aud: Audience (intended recipient, e.g., API).
o iat: Issued At timestamp.
o exp: Expiration timestamp.
o nbf: Not Before timestamp (token invalid before this time).
o jti: Unique JWT ID to prevent replay or duplicate tokens.
o scope: Permissions granted.
• Signature: Cryptographic signature over the header and payload to ensure token integrity.
Security Considerations
• Always whitelist accepted algorithms to avoid accepting insecure or unsigned tokens (alg=none attack).
• Use asymmetric signing (public/private keys) to avoid sharing signing keys across multiple parties.
• Signature verification proves authenticity but does not guarantee token validity:
o Must also check exp (expiration), aud (audience), iss (issuer), etc.
• JWTs can be encrypted (JWE) to protect token confidentiality but this is uncommon for access tokens
due to processing overhead and complexity.

6. Usage Best Practices and Considerations

• Tokens are not inherently secure just by their format; security depends on following protocol rules.
• Treat tokens like traffic laws: the security comes from how the tokens are used, not just the tokens
themselves.
• Clients should not decode or inspect access tokens; they should treat them as opaque.
• Token formats or claims may change without notice; clients relying on internal token structure risk
breaking applications.
• Avoid sending ID tokens or refresh tokens to resource servers or untrusted parties.
• Always transmit tokens over TLS (HTTPS) and avoid logging tokens.

Summary
• Tokens have three fundamental attributes: Format (opaque or by-value), Purpose (access, refresh, ID),
and Type (bearer, proof of possession).
 • Using JWTs is common but requires strict adherence to protocol to ensure security.
• The architecture of token-based authentication requires not just token usage but correct protocol
compliance to be secure.

Scope and Claims

Scopes
• Scopes define the scope of access granted by a token.
• They are keys only, not key-value pairs — essentially sets of strings like read, openid,
user_invoice_update.
• Scopes represent application-level permissions, i.e., what the client application can do or access.
• They are:
o Requested by the client during authorization.
o Pre-approved by the authorization server; clients cannot request arbitrary scopes.
o Sometimes consented to by the user via a consent screen (especially for third-party apps).
• Consent screens may allow users to selectively grant or deny certain scopes (e.g., allow reading
calendar but not updating it).
• First-party apps typically skip user consent because they operate within the same organization/trust
boundary.
• Scopes are used to control access at the application level, not the user data level.
Example Use Case of Scopes
• Client A (consumer app) requests scope: user_invoice_read
→ Gets access token with that scope
→ Can only read invoices but cannot modify.
• Client B (finance/back-office app) requests scopes: user_invoice_read and user_invoice_update
→ Gets access token with both scopes
→ Can read and update/create invoices.
• The resource server checks the scopes in the access token to allow or deny requests accordingly.
Important Note on Scopes
• Scopes do not specify user-level permissions.
For example, having user_invoice_read does not automatically mean the user can read all invoices; that’s
handled separately with claims.

Claims
• Claims are key-value pairs embedded inside the token payload.
• They are assertions made by the issuer (authorization server) about the user or client.
• Claims provide fine-grained information about the user, beyond just identification.
• Claims serve as a single source of truth for identity and user attributes, allowing APIs to avoid
additional database or external lookups.
Examples of Claims
• sub (subject): the user’s unique identifier
 • age: 42
• profession: "identity geek"
• subscription_level: "gold"
• Other claims could include workplace, roles, departments, etc.
How Claims Work in Practice
• Claims are included in the access token, allowing resource servers to perform fine-grained
authorization.
• For example, the API can check if the user’s subscription level allows access to certain features or data.
• Claims can also be dynamic based on the scopes requested.
Designing Claims
• Claims should be:
o Relevant to many APIs (not app-specific)
o Closely related to the user's identity or attributes
o Avoid contextual or volatile data (like time of day) inside claims
Hierarchy Between Scopes and Claims
• OpenID Connect defines scope-to-claim mappings.
• For example:
o Requesting email scope includes claims email and email_verified (Boolean).
o Requesting address scope includes structured claims like street address, locality, region, etc.
• Custom scopes and claims hierarchies can be designed for your APIs.
Example: Custom Scope-to-Claim Mapping
Scope Claims included
invoice_read subscriber_id, cost_center
invoice subscriber_id, cost_center, department
video_stream subscription_level, age

Combined Example
• Client requests scope user_invoice_read.
• The access token issued contains:
o Scope: user_invoice_read
o Claims:
▪ subscriber_id: "ABC123"
▪ cost_center: "gold"`
• When client calls GET /invoices/123, the API:
o Verifies token audience matches API.
o Checks token contains user_invoice_read scope to authorize the action.
o Checks if the invoice 123 belongs to subscriber "ABC123" from claims.
• This model enables coarse-grained authorization (via scopes) combined with fine-grained user-level
access control (via claims).

Summary
 • Scopes
o Define application-level, coarse-grained permissions (e.g., can the app read invoices at all?).
o Are keys only and predefined sets the client can request and the authorization server approves.
• Claims
o Define fine-grained, user-level details and permissions (e.g., which invoices can the user see?).
o Are key-value pairs issued by the authorization server inside the token.
o Enable APIs to make detailed authorization decisions without extra lookups.
• Together, scopes and claims provide a powerful, layered token-based authorization and identity
mechanism.

API Gateways

Introduction
After understanding tokens, their structure (scopes and claims), and how clients obtain them, the next crucial
part is what happens when the token reaches the API. This involves the API Gateway's role and how tokens
are validated, propagated, and enforced across distributed APIs.

API Gateway: The First Line of Defense

Purpose and Functions
• The API Gateway acts as a central entry point for all client requests to backend APIs.
• It provides layer 7 firewalling, meaning it inspects the full HTTP request content, including headers,
method, URI, and body, to decide if the request should be allowed or blocked.
• Protects internal APIs from direct external exposure, reducing attack surface.
• Offers centralized visibility, monitoring, throttling, and routing capabilities.
• Can enforce security policies such as authentication and coarse-grained authorization before
forwarding requests.

Token Validation at the Gateway

Token Types Recap
• By-value tokens (JWTs): Self-contained tokens embedding user data (claims) and scopes,
cryptographically signed.
• By-reference tokens (Opaque tokens): Tokens that serve as a key to look up authorization data stored
at the authorization server.
Why Use By-Reference Tokens Externally?
• Avoids leaking sensitive user info (PII) over the internet.
• Keeps token size small.
• The gateway must validate these tokens by introspecting with the authorization server (AS).
Introspection Process
• The gateway receives the access token from the client.
• If the token is opaque, the gateway calls the AS’s introspection endpoint with:
 o The token itself.
o Gateway’s client credentials (client ID and secret) to authenticate the call.
• The AS returns a JSON document describing:
o Whether the token is active or expired.
o The scopes and claims associated with it.

Phantom Token Flow: Enhancing Security and Traceability

• Problem: Forwarding the JSON response from introspection directly to the API is insecure because
anyone could forge such JSON.
• Solution: Use the phantom token flow.
• In this pattern, the gateway exchanges the opaque token for a by-value JWT token internally.
• This JWT token is then forwarded to the API.
• Benefits:
o Maintains a verifiable token signature.
o Keeps audit logs intact from client through gateway to API.
o Ensures zero trust by requiring token validation at every step.
o Provides a consistent token format to APIs, improving developer experience.

Methods for Token Introspection and Exchange

1. Introspection with application/jwt Accept Header
o Gateway calls introspection requesting JWT instead of JSON.
o AS returns a signed JWT token.
2. Introspection with JWT inside JSON Response
o AS returns the JWT token as a claim within the JSON payload.
3. Token Exchange Specification
o Gateway acts as OAuth client.
o Exchanges the received token for a new token (typically JWT).
o This approach allows requesting tokens with reduced scopes or different formats.
o Note: The behavior varies by AS implementation; always check documentation.

Token Propagation Between APIs

When one API needs to call another API, it must forward identity and authorization context:
Strategies
• Exchange
o API requests a new token with fewer scopes/claims for the next API.
o Provides least privilege principle, reducing attack surface.
o Dynamic, on-demand.
• Embed
o The initial token already contains nested tokens for downstream APIs.
o Efficient when multiple API calls happen frequently.
o Tokens are pre-provisioned, reducing runtime token exchanges.
• Share
 o Forward the same token to downstream APIs.
o Simple but increases risk since the token might have more privileges than needed.
o Best used when APIs share the same trust boundary and security domain.

Authorization Levels: Coarse-Grained vs Fine-Grained

Gateway: Coarse-Grained Authorization
• Gateway acts as a security gatekeeper.
• Performs quick validation:
o Checks token validity.
o Ensures token contains necessary scopes for the requested API domain.
• Example: For requests to the invoice API, checks if token has invoice_read or invoice_write scopes.
• Does not perform deep user-specific checks; focuses on allowing/blocking at the network edge.
Backend API: Fine-Grained Authorization
• APIs re-validate scopes and check claims for user-specific control.
• Claims include identity details such as subscriber ID, cost center, subscription level.
• APIs enforce policies like:
o Does the user own the invoice being accessed?
o Is the user’s subscription sufficient for requested action?
• May query external policy engines (e.g., OPA, Axiomatics) for complex authorization decisions.
• Fine-grained checks prevent unauthorized access even if coarse scope checks passed at gateway.

Designing Scopes and Claims

• Group APIs by domains or functionality:
o Invoicing APIs with scopes like invoice_read, invoice_write.
o Streaming APIs with scopes like video_stream, video_metadata.
• Use hierarchical naming for scopes, e.g., video_stream_high_quality.
• Scopes indicate which APIs or capabilities the token holder can access.
• Claims represent user-specific data used for detailed authorization decisions.

Summary of Key Concepts

• API gateways protect backend services, perform layer 7 filtering, and enforce coarse-grained
authorization using scopes.
• Phantom token flow keeps sensitive info inside the trusted network, forwarding JWTs internally for
consistent validation and auditing.
• Gateway uses introspection or token exchange with the authorization server to validate tokens.
• API-to-API calls use exchange, embed, or share token propagation methods depending on security
needs.
• Fine-grained authorization is performed at the API level using claims and scopes.
• Structured scope and claim design enables scalable, secure API authorization.
• This approach supports zero trust architecture, ensuring strong identity validation throughout the API
ecosystem.