Authentication Examples

Relevant source files

• .github/workflows/test.yml
• CHANGELOG.md
• README.md
• poetry.lock
• pyproject.toml
• requirements.txt

Purpose and Scope

This page provides practical code examples for common authentication scenarios using the Authentication API client. It demonstrates how to implement various OAuth 2.0 flows, passwordless authentication, token management, and advanced authentication features supported by the Auth0 Python SDK.

For architectural details about the Authentication API structure, see Authentication API. For information about token acquisition flows and their technical implementation, see Token Acquisition (OAuth 2.0 Flows). For Management API usage examples, see Management API Examples. For asynchronous authentication patterns, see Async Usage Patterns.

---

GetToken Client Initialization

The GetToken client is the primary interface for authentication operations in the SDK. It supports both synchronous and asynchronous modes.

Basic Initialization Pattern:

from auth0.authentication import GetToken

token_client = GetToken(
    domain="your-tenant.auth0.com",
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET"
)

The client requires:

• domain: Your Auth0 tenant domain (without protocol)
• client_id: Application client ID from Auth0 dashboard
• client_secret: Application client secret (optional for public clients)

Sources: README.md47-61

---

OAuth 2.0 Flow Examples

Client Credentials Grant

The client credentials flow is used for machine-to-machine authentication where the application authenticates itself to access an API.

Usage Pattern:

The client_credentials() method obtains an access token using the application's credentials. The token can be used to access APIs that trust the Auth0 tenant.

Key Parameters:

• audience: The unique identifier of the target API (e.g., https://your-tenant.auth0.com/api/v2/)
• organization (optional): Organization ID for organization-specific tokens (added in v4.6.0)

Response Format:

Returns a dictionary containing:

• access_token: The JWT access token
• token_type: Always "Bearer"
• expires_in: Token lifetime in seconds

Sources: README.md56-61 CHANGELOG.md140

---

Authorization Code + PKCE Flow

The authorization code flow with Proof Key for Code Exchange (PKCE) is used for web and mobile applications where user interaction is required. PKCE adds security by generating a code verifier and challenge.

Implementation Steps:

1. Generate PKCE parameters: Create a code verifier and derive the code challenge
2. Build authorization URL: Use authorization_url() method to construct the URL with PKCE parameters
3. Redirect user: Send user to the authorization URL for authentication
4. Handle callback: Receive the authorization code from the redirect
5. Exchange code: Use authorization_code_exchange() to exchange the code for tokens

Key Parameters:

• redirect_uri: The callback URL registered in Auth0
• code_verifier: Random string for PKCE security
• code_challenge: SHA-256 hash of code_verifier, base64url encoded
• code_challenge_method: Always "S256" for SHA-256
• state: Random value for CSRF protection
• scope: Requested permissions (e.g., "openid profile email")

Sources: CHANGELOG.md542-548

---

Resource Owner Password Grant

The resource owner password grant allows users to authenticate directly with username and password credentials. This flow should only be used when redirect-based flows cannot be implemented.

Authentication Method:

The login() method exchanges user credentials for tokens. The method requires:

• username: User's email or username
• password: User's password
• realm: The connection name (e.g., "Username-Password-Authentication")
• scope: Requested OAuth scopes
• audience (optional): Target API identifier

Additional Options:

• forwarded_for: IP address for audit logging (added in v4.3.0)

Security Considerations:

This flow exposes user credentials to the application and should be avoided when possible. Use authorization code + PKCE for better security.

Sources: CHANGELOG.md177

---

Refresh Token Flow

Refresh tokens allow applications to obtain new access tokens without requiring user re-authentication.

Refresh Process:

The refresh_token() method exchanges a valid refresh token for a new access token and optionally a new refresh token.

Parameters:

• refresh_token: The refresh token obtained during initial authentication
• client_id: Application client ID
• client_secret (optional): Required for confidential clients
• scope (optional): Can request reduced scope from original grant

Token Rotation:

Some configurations enable refresh token rotation, where each refresh operation issues a new refresh token and invalidates the old one. Always update stored tokens after each refresh.

Sources: CHANGELOG.md530 README.md47-61

---

Passwordless Authentication

Passwordless authentication allows users to authenticate using email or SMS without traditional passwords.

Two-Step Process:

1. Initiate passwordless flow: Call passwordless_start() to send a verification code
2. Complete authentication: Call passwordless_login() with the received code

Start Method Parameters:

• connection_type: Either "email" or "sms"
• email or phone_number: User identifier
• send: "link" or "code" for delivery method
• client_secret: Application credentials

Login Method Parameters:

• username: Email or phone number
• otp: The one-time code received by user
• realm: "email" or "sms" matching the connection type
• scope: Requested permissions

Sources: CHANGELOG.md303 CHANGELOG.md389

---

CIBA (Client Initiated Backchannel Authentication)

CIBA enables authentication flows where the user authenticates on a different device from where the authentication was initiated. This is useful for scenarios like smart TV login or IoT device authentication.

CIBA Flow Implementation:

1. Initiate backchannel authentication: Call back_channel_login() with user identifier
2. Poll for completion: Repeatedly call token endpoint with auth_req_id
3. Handle responses: Process pending, slow_down, or success responses

Login Method Parameters:

• login_hint: User identifier (email, phone, or other)
• binding_message (optional): Short message shown to user for verification
• client_id: Application identifier
• scope: Requested permissions
• authorization_details (optional): RAR parameters for fine-grained authorization

Polling Behavior:

• pending: Authentication request is still being processed, continue polling
• slow_down: Polling too frequently, increase interval (HTTP 429)
• authorization_pending: User hasn't responded yet
• access_denied: User rejected the request
• expired_token: Request timed out

Enhanced Features (v4.12.0):

• Email-based CIBA support
• Rich Authorization Requests (RAR) integration
• Enhanced error headers for rate limiting

Sources: CHANGELOG.md54-58 CHANGELOG.md77 CHANGELOG.md83 CHANGELOG.md96

---

Token Management

Token Revocation

Token revocation invalidates refresh tokens or access tokens before their natural expiration.

Revocation Method:

The revoke_refresh_token() method invalidates a refresh token, preventing it from being used to obtain new access tokens.

Parameters:

• refresh_token: The token to revoke
• client_id: Application identifier
• client_secret: Application secret

Use Cases:

• User logout
• Security breach response
• Token cleanup after session end

Sources: CHANGELOG.md461

---

Token Verification

Token verification ensures the authenticity and validity of tokens received by your application.

Verification Components:

The SDK provides specialized classes for token verification:

• TokenVerifier: Main verification orchestrator
• AsymmetricSignatureVerifier: Handles RS256 signature verification using JWKS

Verification Process:

1. Signature verification: Validates the token signature using public keys from JWKS endpoint
2. Claims validation: Checks issuer, audience, expiration, and other standard claims
3. Custom validation: Optional additional checks for specific claims

Verifier Configuration:

• algorithm: Token signing algorithm (typically "RS256")
• issuer: Expected token issuer (e.g., https://your-tenant.auth0.com/)
• audience: Expected audience claim
• leeway: Allowed time skew in seconds for expiration checks

JWKS Caching:

The AsymmetricSignatureVerifier caches JWKS keys to reduce network requests. Cache behavior:

• cache_ttl: Cache lifetime in seconds (added in v4.2.0)
• Default caching prevents excessive JWKS endpoint calls
• Automatic refresh on cache expiration or key rotation

Async Support:

Async token verification (added in v3.24.0) enables non-blocking verification operations in async applications.

Return Value:

The verify() method returns the decoded token claims as a dictionary (feature added in v3.22.0).

Sources: CHANGELOG.md190 CHANGELOG.md235 CHANGELOG.md260

---

Advanced Authentication Features

Pushed Authorization Requests (PAR)

PAR enhances security by sending authorization parameters through a backchannel POST request instead of in the browser URL.

Benefits:

• Parameters sent via secure backchannel
• Prevents URL length limitations
• Protects sensitive request data
• Required for some security profiles

PAR Method Parameters:

• response_type: OAuth response type (typically "code")
• client_id: Application identifier
• redirect_uri: Callback URL
• code_challenge: PKCE code challenge
• code_challenge_method: "S256"
• scope: Requested permissions
• Additional OAuth parameters as needed

Response:

• request_uri: Opaque identifier for the stored request (prefixed with "urn:ietf:params:oauth:request_uri:")
• expires_in: URI lifetime in seconds (typically 60-90 seconds)

Implementation Note:

After obtaining the request_uri, construct the authorization URL using only the request_uri and client_id parameters. All other parameters are retrieved by the authorization server using the request URI.

Sources: CHANGELOG.md127 CHANGELOG.md89

---

JWT-Secured Authorization Requests (JAR)

JAR enables sending authorization request parameters as a signed JWT, providing request integrity and optional encryption.

JAR Parameters:

• request: A JWT containing all authorization parameters
• JWT must be signed by the client
• Can optionally be encrypted for confidentiality

Request JWT Claims:

• Standard OAuth parameters (response_type, scope, etc.)
• iss: Client ID (issuer of the request)
• aud: Authorization server URL
• iat: Issuance time
• exp: Expiration time

Sources: CHANGELOG.md95

---

Rich Authorization Requests (RAR)

RAR enables fine-grained authorization by allowing applications to request specific permissions with detailed context.

Authorization Details Structure:

RAR uses the authorization_details parameter containing an array of objects. Each object specifies:

• type: The authorization type identifier
• Additional type-specific fields defining the exact permission

Example Use Cases:

• Requesting access to specific bank accounts
• Specifying transaction limits
• Defining data access constraints
• Time-limited permissions

Integration with CIBA:

RAR is particularly useful with CIBA (added in v4.9.0), allowing the authentication device to display specific permission requests to the user.

Parameter Format:

authorization_details=[
    {
        "type": "account_information",
        "accounts": ["12345", "67890"],
        "actions": ["read"]
    }
]

Sources: CHANGELOG.md83 CHANGELOG.md95

---

Private Key JWT Authentication

Private Key JWT (private_key_jwt) is a client authentication method using asymmetric cryptography instead of client secrets.

Authentication Mechanism:

Instead of sending client_secret, the client sends a client_assertion parameter containing:

• A JWT signed with the client's private key
• client_assertion_type: Always "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"

JWT Assertion Claims:

• iss: Client ID (issuer)
• sub: Client ID (subject)
• aud: Token endpoint URL
• jti: Unique JWT identifier
• exp: Expiration time
• iat: Issuance time

Benefits:

• No shared secrets transmitted
• Better security for confidential clients
• Supports key rotation
• Required for some compliance standards

Setup Requirements:

The client's public key must be registered with Auth0 (via JWKS URL or direct registration) before using this authentication method.

Sources: CHANGELOG.md210

---

Organizations Support

Organizations allow partitioning users and applications into isolated tenants within a single Auth0 environment.

Organization Parameters:

When authenticating, specify the organization using:

• organization: Organization ID or name

Integration Points:

1. Client Credentials: Include organization parameter to scope tokens to specific organization (added in v4.6.0)
2. Authorization Code: Add organization to authorization URL
3. Password Grant: Specify organization in login request
4. Token Verification: Validate org_id claim in tokens

Organization ID Validation:

Access tokens for organization requests include an org_id claim. Applications should verify:

• The org_id claim exists
• The value matches the expected organization
• The claim is validated as part of token verification

Organization Name Validation:

Organization names must meet specific format requirements. The SDK includes validation (added in v4.4.0) to ensure names conform to Auth0's naming rules.

Password Change Support:

The change_password() method supports organization parameter (added in v4.6.0), allowing password reset flows within organization context.

Sources: CHANGELOG.md140-141 CHANGELOG.md167 CHANGELOG.md326 CHANGELOG.md327

---

Authentication Flow Comparison

Flow	Use Case	User Interaction	Security Level	Token Types
Client Credentials	Machine-to-machine	None	Medium	Access token only
Authorization Code + PKCE	Web/mobile apps	Required	High	Access + ID + Refresh
Resource Owner Password	Trusted applications	Direct credentials	Low	Access + ID + Refresh
Passwordless	Frictionless login	Email/SMS code	Medium	Access + ID
CIBA	Cross-device auth	Separate device	High	Access + ID + Refresh

---

Code Entity Reference

The Authentication API implementation uses these primary components:

Component	Purpose	Key Methods
GetToken	Main authentication client	client_credentials(), authorization_code_exchange(), refresh_token()
TokenVerifier	Token validation	verify()
AsymmetricSignatureVerifier	RS256 signature verification	Signature validation with JWKS
Passwordless API	Passwordless flows	passwordless_start(), passwordless_login()
Database API	Username/password auth	login(), change_password()

HTTP Dependencies:

• requests library for synchronous operations requirements.txt11
• aiohttp library for asynchronous operations requirements.txt8
• pyjwt for JWT handling requirements.txt10
• cryptography for cryptographic operations requirements.txt9

Sources: requirements.txt1-13 README.md47-61