Editing OAuth

'''OAuth''' in the [[AT Protocol]] provides a standardized way for applications to access user data without requiring users to share their passwords. This implementation follows a specific profile of the [https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12 OAuth 2.1] framework, adapted to the decentralized nature of the AT Protocol.

Unlike traditional OAuth implementations that operate within a single centralized service, AT Protocol's OAuth is designed to work across a network of independent [[Personal Data Server (PDS)|Personal Data Servers (PDSes)]]. This requires special considerations for server discovery, client registration, and security.

The AT Protocol uses OAuth primarily for:

* Allowing applications to access user data with specific permissions
* Verifying user identity across the network
* Maintaining secure connections between applications and servers

== User Experience ==
From a user perspective, the OAuth flow typically involves:

# Entering their AT Protocol handle inside an application
# Being redirected to their PDS's login page
# Approving the application's requested permissions
# Being redirected back to the application

Users can manage authorized applications through their PDS interface, including revoking access when needed.

== Key Components ==

=== Client Registration ===
In the AT Protocol, client applications identify themselves using a '''<code>client_id</code>''' that is a fully-qualified HTTPS URL pointing to a public metadata document. This eliminates the need for a central registration authority:<syntaxhighlight lang="http">
https://app.example.com/client-metadata.json
</syntaxhighlight>This metadata document contains essential information about the client, including redirect URIs, requested scopes, application type (web or native), and public keys (for confidential clients).

=== Client Types ===
The protocol supports two types of clients:

* '''Confidential Clients''': Applications with a server component which can securely store secrets. These clients:
** Authenticate using cryptographic keys
** Can receive longer-lived tokens
** Are typically web services or applications with backend components
* '''Public Clients''': Applications that run entirely on user devices. These clients:
** Cannot securely store secrets
** Receive shorter-lived tokens
** Are typically mobile apps or browser-based applications

=== Server Discovery ===
When a user wants to authenticate with their AT Protocol account, the application must:

# Resolve the user's [[handle]] or [[Decentralized Identifier (DID)]] to find their PDS
# Discover whether the PDS handles authentication directly or delegates to an "entryway" service
# Fetch the OAuth server metadata from the appropriate endpoint

This discovery process is meant to ensure that applications can authenticate users regardless of which PDS hosts their account.

=== Authorization Scopes ===
Scopes define what permissions an application is requesting. The AT Protocol defines several standard scopes:

* <code>'''atproto'''</code>: Required for all AT Protocol OAuth sessions
* '''<code>transition:generic</code>''': Broad permissions, similar to [[App Passwords]]
* '''<code>transition:chat.bsky</code>''': Access to direct messaging features

Applications should request only the scopes they need to function.

=== Token Management ===
The AT Protocol uses two types of tokens:

* '''Access Tokens''': Short-lived tokens (typically 5-30 minutes) used to make API requests
* '''Refresh Tokens''': Longer-lived tokens used to obtain new access tokens withing requiring user re-authentication

All tokens are bound to the specific client application (<code>client_id</code>), a unique cryptographic key for the session (DPoP), and the user's account identity

== Authentication Flow ==
A typical authentication flow works as follows:

# The application resolves the user's identity to find their PDS
# The application creates a cryptographic key pair for the session
# The application sends an authorization request to the PDS
# The user is redirected to their PDS to approve the request
# The PDS returns an authorization code to the application
# The application exchanges the code for access and refresh tokens
# The application uses the access token for API requests

== Security Considerations ==
The AT Protocol implements the OAuth Authorization Code flow with several mandatory security enhancements:

* '''Proof Key for Code Exchange (PKCE)''': Prevents authorization code interception attacks
* '''Bidirectional Identity Verification''': Ensures the authorization server is legitimate for the claimed account
* '''Pushed Authorization Requests (PAR)''': Improves security by sending authorization parameters directly to the server
* '''Demonstrating Proof of Possession (DPoP)''': Binds tokens to specific client instances
* '''Server-issues nonces''': Prevents token replay attacks
* '''Short Token Lifetimes''': Limits the impact of compromised tokens.
* '''Mandatory HTTPS''': Ensures all communication is encrypted.