Documentation
¶
Overview ¶
Package auth provides Azure authentication token acquisition and caching.
Package auth acquires Azure OAuth tokens for REST calls and maps request URLs to the scopes their services expect.
Scope detection ¶
DetectScope answers "which audience does this URL need a token for". It returns an empty scope, and no error, for a host it does not recognize, which callers treat as "send this request unauthenticated".
The static host to scope mapping is delegated to azdext.ScopeDetector, extended with custom rules for the services the SDK does not cover and one deliberate override: azdext maps a container registry to the Resource Manager scope, used to exchange for an ACR refresh token, while this package issues the registry data plane scope so a direct /v2/ call works.
Two services stay local because a static map cannot express them. Azure Data Explorer issues a token for the cluster itself, so the scope is derived from the host. A Service Bus and an Event Hubs namespace share the servicebus.windows.net suffix and are told apart by the request path; azdext resolves that suffix to Event Hubs unconditionally, which would hand a queue operation a token for the wrong audience.
IsAzureHost answers a different and broader question: "should we try to authenticate at all". A host can be recognizably Azure without this package knowing its scope.
Token acquisition ¶
AzureTokenProvider caches tokens per scope, applies a request timeout, and classifies failures into AuthPermissionError, AuthCredentialUnavailableError, or AuthError so callers can tell "you lack permission" from "you are not logged in".
NewAzureTokenProvider builds a resilient credential chain that tries the azd CLI, the Azure CLI, environment variables, workload identity, and managed identity in that order. Unlike azidentity.DefaultAzureCredential it continues past a hard failure instead of stopping at the first one, which is what makes it work on Azure Arc where the managed identity probe fails outright.
NewAzureTokenProviderForHost prefers azdext.TokenProvider when an azd host client is available. That is what makes acquisition tenant correct: the SDK provider reads the tenant from the deployment context, while the credential chain has no way to know it. It is not a replacement for this package though, since it has no cache, uses only the azd CLI credential, and returns raw azidentity errors. Wrapping it keeps the cache and the classification.
NewAzureTokenProviderWithCredential wraps any azcore.TokenCredential the same way, which is also the seam tests use.
Index ¶
- func DetectScope(urlString string) (string, error)
- func GetAzureToken(ctx context.Context, scope string) (string, error)
- func IsAzureHost(urlString string) bool
- type AuthCredentialUnavailableError
- type AuthError
- type AuthPermissionError
- type AzureTokenProvider
- type MockTokenProvider
- type TokenProvider
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DetectScope ¶
DetectScope analyzes a URL and returns the appropriate Azure OAuth scope. Returns empty string when the hostname does not match a known Azure service.
Most of the mapping comes from azdext.ScopeDetector, extended with extraScopeRules. Two services cannot be expressed as a static host to scope pair and are resolved here instead:
Azure Data Explorer issues a token for the cluster itself, so the scope is derived from the host rather than looked up.
A Service Bus and an Event Hubs namespace share the servicebus.windows.net suffix and are told apart by the request path. azdext resolves the suffix to Event Hubs unconditionally, which would hand a Service Bus queue call a token for the wrong audience.
func GetAzureToken ¶
GetAzureToken acquires a bearer token for the supplied scope using the shared provider instance (cached credential and token reuse).
func IsAzureHost ¶
IsAzureHost checks if a hostname appears to be an Azure service.
This is deliberately broader than DetectScope: it answers "should we try to authenticate at all", while DetectScope answers "with which audience". A host can be recognizably Azure without azd-core knowing its scope.
Types ¶
type AuthCredentialUnavailableError ¶ added in v0.6.0
type AuthCredentialUnavailableError struct {
}
AuthCredentialUnavailableError indicates no valid credential is configured.
func (*AuthCredentialUnavailableError) Error ¶ added in v0.6.0
func (e *AuthCredentialUnavailableError) Error() string
func (*AuthCredentialUnavailableError) Unwrap ¶ added in v0.6.0
func (e *AuthCredentialUnavailableError) Unwrap() error
type AuthPermissionError ¶ added in v0.6.0
AuthPermissionError indicates insufficient permissions for a scope.
func (*AuthPermissionError) Error ¶ added in v0.6.0
func (e *AuthPermissionError) Error() string
func (*AuthPermissionError) Unwrap ¶ added in v0.6.0
func (e *AuthPermissionError) Unwrap() error
type AzureTokenProvider ¶
type AzureTokenProvider struct {
// contains filtered or unexported fields
}
AzureTokenProvider implements TokenProvider using azd-core's credential chain (DefaultAzureCredential-equivalent) with in-memory token reuse.
func NewAzureTokenProvider ¶
func NewAzureTokenProvider() (*AzureTokenProvider, error)
NewAzureTokenProvider creates a provider backed by a resilient credential chain that tries all Azure credential types regardless of individual error types. The provider caches tokens per scope until close to expiration.
func NewAzureTokenProviderForHost ¶ added in v0.6.0
func NewAzureTokenProviderForHost( ctx context.Context, client *azdext.AzdClient, opts *azdext.TokenProviderOptions, ) (*AzureTokenProvider, error)
NewAzureTokenProviderForHost selects a credential based on whether the extension is running under an azd host.
With a client, tokens come from azdext.TokenProvider, which resolves the tenant from the deployment context. Without one, they come from the resilient credential chain, which tries the azd CLI, the Azure CLI, environment variables, workload identity, and managed identity in that order.
Either way the returned provider caches per scope and classifies failures.
func NewAzureTokenProviderWithCredential ¶ added in v0.6.0
func NewAzureTokenProviderWithCredential(cred azcore.TokenCredential) (*AzureTokenProvider, error)
NewAzureTokenProviderWithCredential creates a provider backed by an explicit credential, keeping the per-scope caching, the request timeout, and the error classification that NewAzureTokenProvider provides.
Pass an azdext.TokenProvider here when the extension is running under an azd host. Doing so is what makes token acquisition tenant correct: the SDK provider reads the tenant out of the deployment context, while the credential chain built by NewAzureTokenProvider has no way to know it and will acquire against whichever tenant the local login happens to point at.
Note that azdext.TokenProvider is not a replacement for this type. It has no token cache, so every call shells out to azd, and it returns the raw azidentity error rather than an AuthPermissionError or an AuthCredentialUnavailableError. Wrapping it here keeps both.
type MockTokenProvider ¶
MockTokenProvider is a mock implementation for testing
Source Files