Clarify BYOK token usage and limitations

[patniko]

No description provided.

[Copilot]

Pull request overview

Updates the BYOK (Bring Your Own Key) authentication documentation to better set expectations around bearer token usage and identity-provider limitations when using the SDK with custom providers.

Changes:

• Adds a note clarifying bearerToken is a static string and is not auto-refreshed by the SDK.
• Rewords identity limitations to emphasize “static credentials,” and expands on why Microsoft Entra ID isn’t supported as an automatic auth flow.

Comments suppressed due to low confidence (1)

docs/auth/byok.md:291

• The Entra ID explanation also says long-running workloads need to “create new sessions” with updated tokens, but resuming an existing session with an updated provider is supported. Suggest adjusting this to “create or resume/reconnect” to match SDK capabilities and reduce operational friction for users.

**Why not Entra ID?** While Entra ID does issue bearer tokens, these tokens are short-lived (typically 1 hour) and require automatic refresh via the Azure Identity SDK. The `bearerToken` option only accepts a static string—there is no callback mechanism for the SDK to request fresh tokens. For long-running workloads requiring Entra authentication, you would need to implement your own token refresh logic and create new sessions with updated tokens.

[Copilot]

The note says expired bearer tokens require creating a new session. However, all SDKs support resuming a session with a new provider config (e.g., ResumeSessionConfig.Provider), which can be used to supply an updated bearerToken without changing the session ID. Consider rewording to say you must reconnect (create or resume) with a fresh token, rather than implying only new sessions work.

This issue also appears on line 291 of the same file.

Suggested change

	> **Note:** The `bearerToken` option accepts a **static token string** only. The SDK does not refresh this token automatically. If your token expires, requests will fail and you'll need to create a new session with a fresh token.
	> **Note:** The `bearerToken` option accepts a **static token string** only. The SDK does not refresh this token automatically. If your token expires, requests will fail and you'll need to reconnect (create a new session or resume an existing one) with a fresh token.

[Copilot]

This section says Microsoft Entra ID is “NOT supported,” but the page also explains that Entra can issue bearer tokens and the SDK can accept a static bearerToken string. To avoid contradicting yourself, consider clarifying that Entra/managed identity/service principal token acquisition and automatic refresh are not supported by the SDK (but users may supply Entra-issued tokens if they manage refresh themselves).

See below for a potential fix:

BYOK authentication uses **static credentials only**. The SDK does not have built-in integrations with identity providers for token acquisition or automatic refresh:

- ❌ **Microsoft Entra ID (Azure AD)** - No built-in support for Entra managed identities or service principals (no automatic token acquisition/refresh)
- ❌ **Third-party identity providers** - No built-in OIDC, SAML, or other federated identity integrations
- ❌ **Managed identities** - No automatic token acquisition via Azure Managed Identity or similar mechanisms

You must use an API key or static bearer token that you manage yourself.

**Why not Entra ID?** While Entra ID does issue bearer tokens, these tokens are short-lived (typically 1 hour) and require automatic refresh via the Azure Identity SDK. The `bearerToken` option only accepts a static string—there is no callback mechanism for the SDK to request fresh tokens. Entra-issued bearer tokens can be used with BYOK as long as you acquire and refresh them yourself and create new sessions with updated tokens. For long-running workloads requiring Entra authentication, you must implement your own token acquisition/refresh logic outside the SDK.