docs: expand Azure Managed Identity BYOK guidance#1995
Conversation
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c19bbd67-bd50-4f54-93e1-8c6961012916
There was a problem hiding this comment.
Pull request overview
Expands Azure Managed Identity BYOK guidance across all SDK languages and documents on-demand bearer token providers.
Changes:
- Adds static-token and callback examples for six SDKs.
- Documents bearer token provider behavior in the BYOK reference.
Show a summary per file
| File | Description |
|---|---|
docs/setup/azure-managed-identity.md |
Expands setup guidance and multi-language examples. |
docs/auth/byok.md |
Adds bearer token provider documentation. |
Review details
- Files reviewed: 2/2 changed files
- Comments generated: 20
- Review effort level: Medium
Co-authored-by: scottaddie <10702007+scottaddie@users.noreply.github.com>
Co-authored-by: scottaddie <10702007+scottaddie@users.noreply.github.com>
Co-authored-by: scottaddie <10702007+scottaddie@users.noreply.github.com>
sunbrye
left a comment
sunbrye
left a comment
There was a problem hiding this comment.
Mainly reviewed the structure of the content and it looks good to me ✅
| # Azure Managed Identity with BYOK | ||
|
|
||
| The Copilot SDK's [BYOK mode](../auth/byok.md) accepts static API keys, but Azure deployments often use **Managed Identity** (Microsoft Entra ID) instead of long-lived keys. Since the SDK doesn't natively support Microsoft Entra authentication, you can use a short-lived bearer token via the `bearer_token` provider config field. | ||
| The GitHub Copilot SDK's [BYOK mode](../auth/byok.md) supports static API keys, but Azure deployments often use **Managed Identity** (Microsoft Entra ID) instead of long-lived keys. Since the SDK doesn't natively support Microsoft Entra authentication, supply either a bearer token you already acquired or a bearer token provider that can fetch fresh tokens on demand. |
There was a problem hiding this comment.
Saying "SDK doesn't native support Entra" might sound like the product is deficient, but the layering we've chosen is deliberate - we've designed this to compose with Azure Identity SDK for maximum flexibility.
| 1. Pass the token as the `bearer_token` in the BYOK provider config | ||
| 1. Refresh the token before it expires (tokens are typically valid for ~1 hour) | ||
| * [Provide an access token that your application refreshes.](#provide-an-access-token-you-manage) | ||
| * [Specify a token provider callback so the runtime can acquire tokens on demand.](#specify-a-token-provider-for-automatic-token-acquisition) |
There was a problem hiding this comment.
Can we give some advice for how developers should choose between these two options?
My guess is they should always use the token provider callback since manual token refreshing is complex. But is there some edge-case reason why people would want to do their own token refresh?
| ### Basic usage | ||
| ### Provide an access token you manage | ||
|
|
||
| Get a token using your language's Azure Identity SDK credential and pass it as the bearer token in your provider configuration. Track the token's expiration or refresh metadata so you know when to acquire a fresh token. Because a static bearer token is captured when the session is created, create a new session when you need to use the refreshed token. See the language-specific guidance in each code sample's comments below. |
There was a problem hiding this comment.
Because a static bearer token is captured when the session is created, create a new session when you need to use the refreshed token.
This doesn't seem like a viable approach. Doesn't that mean you lose your sessions when tokens expire?
Do you think we should swap the doc around and describe the "automatic token acquisition" method as the only real method? Then we could also comment that if somehow you know you don't need to refresh tokens (e.g., because your sessions are always just one-shot operations not ongoing conversations) then you can pass a static token, but we don't have to document how to do any of the token refresh stuff because that's orthogonal to Copilot SDK.
Summary
Directly addresses Patrick's comment: https://github.com/github/copilot-sdk-internal/issues/45#issuecomment-4971913761