feat: add Multiple Custom Domain Support

[kishore7snehil]

📋 Changes

This PR implements Multiple Custom Domain (MCD) support for auth0-api-python, enabling APIs to accept tokens from multiple Auth0 custom domains with static lists, dynamic resolvers, and hybrid mode for zero-downtime domain migrations.

✨ Features

• Multiple Custom Domain Verification: Accept tokens from multiple Auth0 domains via a domains parameter (static list or callable resolver) on ApiClientOptions
• Double Issuer Validation: Pre-signature and post-signature issuer checks to prevent issuer confusion attacks
• Hybrid Mode: Use domain and domains together for migration scenarios — domain drives client-initiated flows (token exchange, connection tokens), domains drives token verification
• Dynamic Resolver: Runtime domain resolution via DomainsResolver callable with request context (DomainsResolverContext)
• Per-Issuer Caching: OIDC discovery metadata and JWKS cached per issuer domain with configurable TTL, max entries, and LRU eviction
• Pluggable Cache Backends: New CacheAdapter ABC allows custom backends (Redis, Memcached, etc.) with a default InMemoryCache implementation

🔧 API Changes

• Extended ApiClientOptions with MCD parameters: domains, cache_ttl_seconds, cache_max_entries, cache_adapter
• Added request_url and request_headers parameters to verify_access_token() and verify_request() for resolver context
• New types: DomainsResolverContext (TypedDict), DomainsResolver (type alias)
• New error classes: ConfigurationError (invalid SDK config, status 500), DomainsResolverError (resolver failure, status 500)
• New cache classes: CacheAdapter (ABC), InMemoryCache (default LRU cache with TTL)

📖 Documentation

• Updated README.md with MCD feature callout and new section 7 (Multi-Custom Domain Support)
• Created docs/MultipleCustomDomain.md — configuration modes, resolver patterns, error handling, migration guide
• Created docs/Caching.md — default behavior, custom adapters (Redis example), tuning recommendations

🧪 Testing

• This change adds test coverage
• This change has been tested on the latest version of the platform/language

Manual Integration Testing

Requires an Auth0 tenant with multiple custom domains configured and a machine-to-machine application with client credentials grant enabled.

import asyncio
import httpx
from auth0_api_python import ApiClient, ApiClientOptions

DOMAIN = "<AUTH0_DOMAIN>"               # e.g. "dev-tenant.us.auth0.com"
CUSTOM_DOMAIN_1 = "<CUSTOM_DOMAIN_1>"   # e.g. "auth.example.com"
CUSTOM_DOMAIN_2 = "<CUSTOM_DOMAIN_2>"   # e.g. "auth.acme.org"
ALL_DOMAINS = [DOMAIN, CUSTOM_DOMAIN_1, CUSTOM_DOMAIN_2]

CLIENT_ID = "<CLIENT_ID>"
CLIENT_SECRET = "<CLIENT_SECRET>"
AUDIENCE = "<API_AUDIENCE>"


# Helper: get an access token from a specific domain via client_credentials grant.
# POST to https://{domain}/oauth/token with grant_type, client_id, client_secret, audience.
# Returns the access_token string from the response.

async def get_token(domain: str) -> str:
    ...


async def test_bearer_mcd():
    api_client = ApiClient(ApiClientOptions(
        domains=ALL_DOMAINS,
        audience=AUDIENCE,
    ))

    for domain in ALL_DOMAINS:
        token = await get_token(domain)
        claims = await api_client.verify_request(
            headers={"Authorization": f"Bearer {token}"}
        )
        print(f"[PASS] {domain} -> iss={claims['iss']}, sub={claims['sub']}")

asyncio.run(test_bearer_mcd())

Expected: All three domains succeed. Each token's iss matches its issuing domain.

Contributor Checklist

• I agree to adhere to the Auth0 General Contribution Guidelines.
• I agree to uphold the Auth0 Code of Conduct.

General fix: Avoid reusing the same attribute for both a list of domains and a resolver function. Maintain separate attributes for the static list and for the callable resolver so that the callable one is never a list and vice versa.

Concrete approach for this file:

1. In __init__, introduce two instance attributes:
   • self._allowed_domains – always a list of normalized domain strings (or None if not set).
   • self._domains_resolver – always either a callable (sync or async) or None.
2. When options.domains is a list, normalize and store it in self._allowed_domains, leaving self._domains_resolver = None.
3. When options.domains is callable, store it in self._domains_resolver and set self._allowed_domains = None.
4. In the later logic (around lines 145–181), change:
   • The elif callable(self._allowed_domains): branch to instead test and call self._domains_resolver.
   • The invocation self._allowed_domains(context) to self._domains_resolver(context).
5. Ensure that any earlier uses of self._allowed_domains (as shown) are compatible—where it’s treated as a list, it will only ever be a list; where it’s treated as callable, use the new self._domains_resolver.

This retains existing functionality (still supports both static domain lists and dynamic resolvers) while making the types consistent and eliminating the potential non‑callable call that CodeQL flags.

---