Documentation ¶
Overview ¶
Example (PersistentUserAuthentication) ¶
This example shows how to cache authentication data persistently so a user doesn't need to authenticate interactively every time the application runs. The example uses InteractiveBrowserCredential, however DeviceCodeCredential has the same API. The key steps are:
- Call github.com/Azure/azure-sdk-for-go/sdk/azidentity/cache.New to construct a persistent cache
- Set the Cache field in the credential's options
- Call Authenticate to acquire an AuthenticationRecord and store that for future use. An AuthenticationRecord enables credentials to access data in the persistent cache. The record contains no authentication secrets.
- Add the AuthenticationRecord to the credential's options
//go:build go1.18 // +build go1.18 // Copyright (c) Microsoft Corporation. All rights reserved. // Licensed under the MIT License. package main import ( "context" "encoding/json" "os" "github.com/Azure/azure-sdk-for-go/sdk/azidentity" "github.com/Azure/azure-sdk-for-go/sdk/azidentity/cache" ) // this example shows file storage but any form of byte storage would work func retrieveRecord() (azidentity.AuthenticationRecord, error) { record := azidentity.AuthenticationRecord{} b, err := os.ReadFile(authRecordPath) if err == nil { err = json.Unmarshal(b, &record) } return record, err } func storeRecord(record azidentity.AuthenticationRecord) error { b, err := json.Marshal(record) if err == nil { err = os.WriteFile(authRecordPath, b, 0600) } return err } // This example shows how to cache authentication data persistently so a user doesn't need to authenticate // interactively every time the application runs. The example uses [InteractiveBrowserCredential], however // [DeviceCodeCredential] has the same API. The key steps are: // // 1. Call [github.com/Azure/azure-sdk-for-go/sdk/azidentity/cache.New] to construct a persistent cache // 2. Set the Cache field in the credential's options // 3. Call Authenticate to acquire an [AuthenticationRecord] and store that for future use. An [AuthenticationRecord] // enables credentials to access data in the persistent cache. The record contains no authentication secrets. // 4. Add the [AuthenticationRecord] to the credential's options func main() { record, err := retrieveRecord() if err != nil { // TODO: handle error } c, err := cache.New(nil) if err != nil { // TODO: handle error. An error here means persistent // caching is impossible in the runtime environment. } cred, err := azidentity.NewInteractiveBrowserCredential(&azidentity.InteractiveBrowserCredentialOptions{ // If record is zero, the credential will start with no user logged in AuthenticationRecord: record, // Credentials cache in memory by default. Setting Cache with a // nonzero value from cache.New() enables persistent caching. Cache: c, }) if err != nil { // TODO: handle error } if record == (azidentity.AuthenticationRecord{}) { // No stored record; call Authenticate to acquire one. // This will prompt the user to authenticate interactively. record, err = cred.Authenticate(context.TODO(), nil) if err != nil { // TODO: handle error } err = storeRecord(record) if err != nil { // TODO: handle error } } }
Output:
Index ¶
- Constants
- func NewCredentialUnavailableError(message string) error
- func ParseCertificates(certData []byte, password []byte) ([]*x509.Certificate, crypto.PrivateKey, error)
- type AuthenticationFailedError
- type AuthenticationRecord
- type AuthenticationRequiredError
- type AzureCLICredential
- type AzureCLICredentialOptions
- type AzureDeveloperCLICredential
- type AzureDeveloperCLICredentialOptions
- type AzurePipelinesCredential
- type AzurePipelinesCredentialOptions
- type Cache
- type ChainedTokenCredential
- type ChainedTokenCredentialOptions
- type ClientAssertionCredential
- type ClientAssertionCredentialOptions
- type ClientCertificateCredential
- type ClientCertificateCredentialOptions
- type ClientID
- type ClientSecretCredential
- type ClientSecretCredentialOptions
- type DefaultAzureCredential
- type DefaultAzureCredentialOptions
- type DeviceCodeCredential
- type DeviceCodeCredentialOptions
- type DeviceCodeMessage
- type EnvironmentCredential
- type EnvironmentCredentialOptions
- type InteractiveBrowserCredential
- type InteractiveBrowserCredentialOptions
- type ManagedIDKind
- type ManagedIdentityCredential
- type ManagedIdentityCredentialOptions
- type OnBehalfOfCredential
- func NewOnBehalfOfCredentialWithCertificate(tenantID, clientID, userAssertion string, certs []*x509.Certificate, ...) (*OnBehalfOfCredential, error)
- func NewOnBehalfOfCredentialWithClientAssertions(tenantID, clientID, userAssertion string, ...) (*OnBehalfOfCredential, error)
- func NewOnBehalfOfCredentialWithSecret(tenantID, clientID, userAssertion, clientSecret string, ...) (*OnBehalfOfCredential, error)
- type OnBehalfOfCredentialOptions
- type ResourceID
- type UsernamePasswordCredential
- type UsernamePasswordCredentialOptions
- type WorkloadIdentityCredential
- type WorkloadIdentityCredentialOptions
Examples ¶
Constants ¶
const EventAuthentication log.Event = "Authentication"
EventAuthentication entries contain information about authentication. This includes information like the names of environment variables used when obtaining credentials and the type of credential used.
Variables ¶
This section is empty.
Functions ¶
func NewCredentialUnavailableError ¶ added in v1.3.0
NewCredentialUnavailableError constructs an error indicating a credential can't attempt authentication because it lacks required data or state. When ChainedTokenCredential receives this error it will try its next credential, if any.
func ParseCertificates ¶ added in v0.12.0
func ParseCertificates(certData []byte, password []byte) ([]*x509.Certificate, crypto.PrivateKey, error)
ParseCertificates loads certificates and a private key, in PEM or PKCS#12 format, for use with NewClientCertificateCredential. Pass nil for password if the private key isn't encrypted. This function has limitations, for example it can't decrypt keys in PEM format or PKCS#12 certificates that use SHA256 for message authentication. If you encounter such limitations, consider using another module to load the certificate and private key.
Types ¶
type AuthenticationFailedError ¶
type AuthenticationFailedError struct { // RawResponse is the HTTP response motivating the error, if available. RawResponse *http.Response // contains filtered or unexported fields }
AuthenticationFailedError indicates an authentication request has failed.
func (*AuthenticationFailedError) Error ¶
func (e *AuthenticationFailedError) Error() string
Error implements the error interface. Note that the message contents are not contractual and can change over time.
func (*AuthenticationFailedError) NonRetriable ¶ added in v0.2.0
func (*AuthenticationFailedError) NonRetriable()
NonRetriable indicates the request which provoked this error shouldn't be retried.
type AuthenticationRecord ¶ added in v1.8.0
type AuthenticationRecord struct { // Authority is the URL of the authority that issued the token. Authority string `json:"authority"` // ClientID is the ID of the application that authenticated the user. ClientID string `json:"clientId"` // HomeAccountID uniquely identifies the account. HomeAccountID string `json:"homeAccountId"` // TenantID identifies the tenant in which the user authenticated. TenantID string `json:"tenantId"` // Username is the user's preferred username. Username string `json:"username"` // Version of the AuthenticationRecord. Version string `json:"version"` }
AuthenticationRecord is non-secret account information about an authenticated user that user credentials such as DeviceCodeCredential and InteractiveBrowserCredential can use to access previously cached authentication data. Call these credentials' Authenticate method to get an AuthenticationRecord for a user.
func (*AuthenticationRecord) UnmarshalJSON ¶ added in v1.8.0
func (a *AuthenticationRecord) UnmarshalJSON(b []byte) error
UnmarshalJSON implements json.Unmarshaler for AuthenticationRecord
type AuthenticationRequiredError ¶ added in v1.8.0
type AuthenticationRequiredError struct { // TokenRequestOptions for the required token. Pass this to the credential's Authenticate method. TokenRequestOptions policy.TokenRequestOptions // contains filtered or unexported fields }
AuthenticationRequiredError indicates a credential's Authenticate method must be called to acquire a token because the credential requires user interaction and is configured not to request it automatically.
Example ¶
Credentials that require user interaction such as InteractiveBrowserCredential and DeviceCodeCredential can optionally return this error instead of automatically prompting for user interaction. This allows applications to decide when to request user interaction. This example shows how to handle the error and authenticate a user interactively. It shows InteractiveBrowserCredential but the same pattern applies to DeviceCodeCredential.
cred, err := azidentity.NewInteractiveBrowserCredential( &azidentity.InteractiveBrowserCredentialOptions{ // This option is useful only for applications that need to control when to prompt users to // authenticate. If the timing of user interaction isn't important, don't set this option. DisableAutomaticAuthentication: true, }, ) if err != nil { // TODO: handle error } // this could be any client that authenticates with an azidentity credential client, err := newServiceClient(cred) if err != nil { // TODO: handle error } err = client.Method() if err != nil { var are *azidentity.AuthenticationRequiredError if errors.As(err, &are) { // The client requested a token and the credential requires user interaction. Whenever it's convenient // for the application, call Authenticate to prompt the user. Pass the error's TokenRequestOptions to // request a token with the parameters the client specified. _, err = cred.Authenticate(context.TODO(), &are.TokenRequestOptions) if err != nil { // TODO: handle error } // TODO: retry the client method; it should succeed because the credential now has the required token } }
Output:
func (*AuthenticationRequiredError) Error ¶ added in v1.8.0
func (e *AuthenticationRequiredError) Error() string
Error implements the error interface. Note that the message contents are not contractual and can change over time.
func (*AuthenticationRequiredError) NonRetriable ¶ added in v1.8.0
func (*AuthenticationRequiredError) NonRetriable()
NonRetriable is a marker method indicating this error should not be retried. It has no implementation.
type AzureCLICredential ¶
type AzureCLICredential struct {
// contains filtered or unexported fields
}
AzureCLICredential authenticates as the identity logged in to the Azure CLI.
func NewAzureCLICredential ¶
func NewAzureCLICredential(options *AzureCLICredentialOptions) (*AzureCLICredential, error)
NewAzureCLICredential constructs an AzureCLICredential. Pass nil to accept default options.
func (*AzureCLICredential) GetToken ¶
func (c *AzureCLICredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (azcore.AccessToken, error)
GetToken requests a token from the Azure CLI. This credential doesn't cache tokens, so every call invokes the CLI. This method is called automatically by Azure SDK clients.
type AzureCLICredentialOptions ¶
type AzureCLICredentialOptions struct { // AdditionallyAllowedTenants specifies tenants for which the credential may acquire tokens, in addition // to TenantID. Add the wildcard value "*" to allow the credential to acquire tokens for any tenant the // logged in account can access. AdditionallyAllowedTenants []string // Subscription is the name or ID of a subscription. Set this to acquire tokens for an account other // than the Azure CLI's current account. Subscription string // TenantID identifies the tenant the credential should authenticate in. // Defaults to the CLI's default tenant, which is typically the home tenant of the logged in user. TenantID string // contains filtered or unexported fields }
AzureCLICredentialOptions contains optional parameters for AzureCLICredential.
type AzureDeveloperCLICredential ¶ added in v1.5.0
type AzureDeveloperCLICredential struct {
// contains filtered or unexported fields
}
AzureDeveloperCLICredential authenticates as the identity logged in to the Azure Developer CLI.
func NewAzureDeveloperCLICredential ¶ added in v1.5.0
func NewAzureDeveloperCLICredential(options *AzureDeveloperCLICredentialOptions) (*AzureDeveloperCLICredential, error)
NewAzureDeveloperCLICredential constructs an AzureDeveloperCLICredential. Pass nil to accept default options.
func (*AzureDeveloperCLICredential) GetToken ¶ added in v1.5.0
func (c *AzureDeveloperCLICredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (azcore.AccessToken, error)
GetToken requests a token from the Azure Developer CLI. This credential doesn't cache tokens, so every call invokes azd. This method is called automatically by Azure SDK clients.
type AzureDeveloperCLICredentialOptions ¶ added in v1.5.0
type AzureDeveloperCLICredentialOptions struct { // AdditionallyAllowedTenants specifies tenants for which the credential may acquire tokens, in addition // to TenantID. Add the wildcard value "*" to allow the credential to acquire tokens for any tenant the // logged in account can access. AdditionallyAllowedTenants []string // TenantID identifies the tenant the credential should authenticate in. Defaults to the azd environment, // which is the tenant of the selected Azure subscription. TenantID string // contains filtered or unexported fields }
AzureDeveloperCLICredentialOptions contains optional parameters for AzureDeveloperCLICredential.
type AzurePipelinesCredential ¶ added in v1.7.0
type AzurePipelinesCredential struct {
// contains filtered or unexported fields
}
AzurePipelinesCredential authenticates with workload identity federation in an Azure Pipeline. See Azure Pipelines documentation for more information.
func NewAzurePipelinesCredential ¶ added in v1.7.0
func NewAzurePipelinesCredential(tenantID, clientID, serviceConnectionID, systemAccessToken string, options *AzurePipelinesCredentialOptions) (*AzurePipelinesCredential, error)
NewAzurePipelinesCredential is the constructor for AzurePipelinesCredential.
- tenantID: tenant ID of the service principal federated with the service connection
- clientID: client ID of that service principal
- serviceConnectionID: ID of the service connection to authenticate
- systemAccessToken: security token for the running build. See Azure Pipelines documentation for an example showing how to get this value.
func (*AzurePipelinesCredential) GetToken ¶ added in v1.7.0
func (a *AzurePipelinesCredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (azcore.AccessToken, error)
GetToken requests an access token from Microsoft Entra ID. Azure SDK clients call this method automatically.
type AzurePipelinesCredentialOptions ¶ added in v1.7.0
type AzurePipelinesCredentialOptions struct { azcore.ClientOptions // AdditionallyAllowedTenants specifies additional tenants for which the credential may acquire tokens. // Add the wildcard value "*" to allow the credential to acquire tokens for any tenant in which the // application is registered. AdditionallyAllowedTenants []string // Cache is a persistent cache the credential will use to store the tokens it acquires, making // them available to other processes and credential instances. The default, zero value means the // credential will store tokens in memory and not share them. Cache Cache // DisableInstanceDiscovery should be set true only by applications authenticating in disconnected clouds, or // private clouds such as Azure Stack. It determines whether the credential requests Microsoft Entra instance metadata // from https://login.microsoft.com before authenticating. Setting this to true will skip this request, making // the application responsible for ensuring the configured authority is valid and trustworthy. DisableInstanceDiscovery bool }
AzurePipelinesCredentialOptions contains optional parameters for AzurePipelinesCredential.
type Cache ¶ added in v1.8.0
Cache represents a persistent cache that makes authentication data available across processes. Construct one with github.com/Azure/azure-sdk-for-go/sdk/azidentity/cache.New. This package's persistent user authentication example shows how to use a persistent cache to reuse logins across application runs.
type ChainedTokenCredential ¶
type ChainedTokenCredential struct {
// contains filtered or unexported fields
}
ChainedTokenCredential links together multiple credentials and tries them sequentially when authenticating. By default, it tries all the credentials until one authenticates, after which it always uses that credential.
func NewChainedTokenCredential ¶
func NewChainedTokenCredential(sources []azcore.TokenCredential, options *ChainedTokenCredentialOptions) (*ChainedTokenCredential, error)
NewChainedTokenCredential creates a ChainedTokenCredential. Pass nil for options to accept defaults.
Example (ManagedIdentityTimeout) ¶
This example demonstrates a small wrapper that sets a deadline for authentication and signals ChainedTokenCredential to try another credential when managed identity authentication times out, as it would for example in a local development environment.
//go:build go1.18 // +build go1.18 // Copyright (c) Microsoft Corporation. All rights reserved. // Licensed under the MIT License. package main import ( "context" "errors" "time" "github.com/Azure/azure-sdk-for-go/sdk/azcore" "github.com/Azure/azure-sdk-for-go/sdk/azcore/policy" "github.com/Azure/azure-sdk-for-go/sdk/azidentity" ) // timeoutWrapper signals ChainedTokenCredential to try another credential when managed identity times out type timeoutWrapper struct { cred *azidentity.ManagedIdentityCredential timeout time.Duration } // GetToken implements the azcore.TokenCredential interface func (w *timeoutWrapper) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (azcore.AccessToken, error) { var tk azcore.AccessToken var err error if w.timeout > 0 { c, cancel := context.WithTimeout(ctx, w.timeout) defer cancel() tk, err = w.cred.GetToken(c, opts) if ce := c.Err(); errors.Is(ce, context.DeadlineExceeded) { // The Context reached its deadline, probably because no managed identity is available. // A credential unavailable error signals the chain to try its next credential, if any. err = azidentity.NewCredentialUnavailableError("managed identity timed out") } else { // some managed identity implementation is available, so don't apply the timeout to future calls w.timeout = 0 } } else { tk, err = w.cred.GetToken(ctx, opts) } return tk, err } // This example demonstrates a small wrapper that sets a deadline for authentication and signals // [ChainedTokenCredential] to try another credential when managed identity authentication times // out, as it would for example in a local development environment. func main() { mic, err := azidentity.NewManagedIdentityCredential(nil) if err != nil { // TODO: handle error } azCLI, err := azidentity.NewAzureCLICredential(nil) if err != nil { // TODO: handle error } creds := []azcore.TokenCredential{ &timeoutWrapper{mic, time.Second}, azCLI, } chain, err := azidentity.NewChainedTokenCredential(creds, nil) if err != nil { // TODO: handle error } // TODO: construct a client with the credential chain _ = chain }
Output:
func (*ChainedTokenCredential) GetToken ¶
func (c *ChainedTokenCredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (azcore.AccessToken, error)
GetToken calls GetToken on the chained credentials in turn, stopping when one returns a token. This method is called automatically by Azure SDK clients.
type ChainedTokenCredentialOptions ¶ added in v0.12.0
type ChainedTokenCredentialOptions struct { // RetrySources configures how the credential uses its sources. When true, the credential always attempts to // authenticate through each source in turn, stopping when one succeeds. When false, the credential authenticates // only through this first successful source--it never again tries the sources which failed. RetrySources bool }
ChainedTokenCredentialOptions contains optional parameters for ChainedTokenCredential.
type ClientAssertionCredential ¶ added in v1.2.0
type ClientAssertionCredential struct {
// contains filtered or unexported fields
}
ClientAssertionCredential authenticates an application with assertions provided by a callback function. This credential is for advanced scenarios. ClientCertificateCredential has a more convenient API for the most common assertion scenario, authenticating a service principal with a certificate. See Microsoft Entra ID documentation for details of the assertion format.
func NewClientAssertionCredential ¶ added in v1.2.0
func NewClientAssertionCredential(tenantID, clientID string, getAssertion func(context.Context) (string, error), options *ClientAssertionCredentialOptions) (*ClientAssertionCredential, error)
NewClientAssertionCredential constructs a ClientAssertionCredential. The getAssertion function must be thread safe. Pass nil for options to accept defaults.
func (*ClientAssertionCredential) GetToken ¶ added in v1.2.0
func (c *ClientAssertionCredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (azcore.AccessToken, error)
GetToken requests an access token from Microsoft Entra ID. This method is called automatically by Azure SDK clients.
type ClientAssertionCredentialOptions ¶ added in v1.2.0
type ClientAssertionCredentialOptions struct { azcore.ClientOptions // AdditionallyAllowedTenants specifies additional tenants for which the credential may acquire tokens. // Add the wildcard value "*" to allow the credential to acquire tokens for any tenant in which the // application is registered. AdditionallyAllowedTenants []string // Cache is a persistent cache the credential will use to store the tokens it acquires, making // them available to other processes and credential instances. The default, zero value means the // credential will store tokens in memory and not share them. Cache Cache // DisableInstanceDiscovery should be set true only by applications authenticating in disconnected clouds, or // private clouds such as Azure Stack. It determines whether the credential requests Microsoft Entra instance metadata // from https://login.microsoft.com before authenticating. Setting this to true will skip this request, making // the application responsible for ensuring the configured authority is valid and trustworthy. DisableInstanceDiscovery bool }
ClientAssertionCredentialOptions contains optional parameters for ClientAssertionCredential.
type ClientCertificateCredential ¶
type ClientCertificateCredential struct {
// contains filtered or unexported fields
}
ClientCertificateCredential authenticates a service principal with a certificate.
func NewClientCertificateCredential ¶
func NewClientCertificateCredential(tenantID string, clientID string, certs []*x509.Certificate, key crypto.PrivateKey, options *ClientCertificateCredentialOptions) (*ClientCertificateCredential, error)
NewClientCertificateCredential constructs a ClientCertificateCredential. Pass nil for options to accept defaults. See ParseCertificates for help loading a certificate.
Example ¶
data, err := os.ReadFile(certPath) handleError(err) // NewClientCertificateCredential requires at least one *x509.Certificate, and a crypto.PrivateKey. // ParseCertificates returns these given certificate data in PEM or PKCS12 format. It handles common // scenarios but has limitations, for example it doesn't load PEM encrypted private keys or PKCS12 certs // that use SHA256 for message authentication. If it isn't able to parse your certificate, consider // using another module to load the certificate and private key. certs, key, err := azidentity.ParseCertificates(data, nil) handleError(err) cred, err = azidentity.NewClientCertificateCredential(tenantID, clientID, certs, key, nil) handleError(err)
Output:
func (*ClientCertificateCredential) GetToken ¶
func (c *ClientCertificateCredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (azcore.AccessToken, error)
GetToken requests an access token from Microsoft Entra ID. This method is called automatically by Azure SDK clients.
type ClientCertificateCredentialOptions ¶ added in v0.4.0
type ClientCertificateCredentialOptions struct { azcore.ClientOptions // AdditionallyAllowedTenants specifies additional tenants for which the credential may acquire tokens. // Add the wildcard value "*" to allow the credential to acquire tokens for any tenant in which the // application is registered. AdditionallyAllowedTenants []string // Cache is a persistent cache the credential will use to store the tokens it acquires, making // them available to other processes and credential instances. The default, zero value means the // credential will store tokens in memory and not share them. Cache Cache // DisableInstanceDiscovery should be set true only by applications authenticating in disconnected clouds, or // private clouds such as Azure Stack. It determines whether the credential requests Microsoft Entra instance metadata // from https://login.microsoft.com before authenticating. Setting this to true will skip this request, making // the application responsible for ensuring the configured authority is valid and trustworthy. DisableInstanceDiscovery bool // SendCertificateChain controls whether the credential sends the public certificate chain in the x5c // header of each token request's JWT. This is required for Subject Name/Issuer (SNI) authentication. // Defaults to False. SendCertificateChain bool }
ClientCertificateCredentialOptions contains optional parameters for ClientCertificateCredential.
type ClientID ¶ added in v0.9.2
type ClientID string
ClientID is the client ID of a user-assigned managed identity.
type ClientSecretCredential ¶
type ClientSecretCredential struct {
// contains filtered or unexported fields
}
ClientSecretCredential authenticates an application with a client secret.
func NewClientSecretCredential ¶
func NewClientSecretCredential(tenantID string, clientID string, clientSecret string, options *ClientSecretCredentialOptions) (*ClientSecretCredential, error)
NewClientSecretCredential constructs a ClientSecretCredential. Pass nil for options to accept defaults.
func (*ClientSecretCredential) GetToken ¶
func (c *ClientSecretCredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (azcore.AccessToken, error)
GetToken requests an access token from Microsoft Entra ID. This method is called automatically by Azure SDK clients.
type ClientSecretCredentialOptions ¶ added in v0.4.0
type ClientSecretCredentialOptions struct { azcore.ClientOptions // AdditionallyAllowedTenants specifies additional tenants for which the credential may acquire tokens. // Add the wildcard value "*" to allow the credential to acquire tokens for any tenant in which the // application is registered. AdditionallyAllowedTenants []string // DisableInstanceDiscovery should be set true only by applications authenticating in disconnected clouds, or // private clouds such as Azure Stack. It determines whether the credential requests Microsoft Entra instance metadata // from https://login.microsoft.com before authenticating. Setting this to true will skip this request, making // the application responsible for ensuring the configured authority is valid and trustworthy. DisableInstanceDiscovery bool // Cache is a persistent cache the credential will use to store the tokens it acquires, making // them available to other processes and credential instances. The default, zero value means the // credential will store tokens in memory and not share them. Cache Cache }
ClientSecretCredentialOptions contains optional parameters for ClientSecretCredential.
type DefaultAzureCredential ¶ added in v0.12.0
type DefaultAzureCredential struct {
// contains filtered or unexported fields
}
DefaultAzureCredential simplifies authentication while developing applications that deploy to Azure by combining credentials used in Azure hosting environments and credentials used in local development. In production, it's better to use a specific credential type so authentication is more predictable and easier to debug.
DefaultAzureCredential attempts to authenticate with each of these credential types, in the following order, stopping when one provides a token:
- EnvironmentCredential
- WorkloadIdentityCredential, if environment variable configuration is set by the Azure workload identity webhook. Use WorkloadIdentityCredential directly when not using the webhook or needing more control over its configuration.
- ManagedIdentityCredential
- AzureCLICredential
- AzureDeveloperCLICredential
Consult the documentation for these credential types for more information on how they authenticate. Once a credential has successfully authenticated, DefaultAzureCredential will use that credential for every subsequent authentication.
func NewDefaultAzureCredential ¶
func NewDefaultAzureCredential(options *DefaultAzureCredentialOptions) (*DefaultAzureCredential, error)
NewDefaultAzureCredential creates a DefaultAzureCredential. Pass nil for options to accept defaults.
func (*DefaultAzureCredential) GetToken ¶ added in v0.12.0
func (c *DefaultAzureCredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (azcore.AccessToken, error)
GetToken requests an access token from Microsoft Entra ID. This method is called automatically by Azure SDK clients.
type DefaultAzureCredentialOptions ¶
type DefaultAzureCredentialOptions struct { // ClientOptions has additional options for credentials that use an Azure SDK HTTP pipeline. These options don't apply // to credential types that authenticate via external tools such as the Azure CLI. azcore.ClientOptions // AdditionallyAllowedTenants specifies additional tenants for which the credential may acquire tokens. Add // the wildcard value "*" to allow the credential to acquire tokens for any tenant. This value can also be // set as a semicolon delimited list of tenants in the environment variable AZURE_ADDITIONALLY_ALLOWED_TENANTS. AdditionallyAllowedTenants []string // DisableInstanceDiscovery should be set true only by applications authenticating in disconnected clouds, or // private clouds such as Azure Stack. It determines whether the credential requests Microsoft Entra instance metadata // from https://login.microsoft.com before authenticating. Setting this to true will skip this request, making // the application responsible for ensuring the configured authority is valid and trustworthy. DisableInstanceDiscovery bool // TenantID sets the default tenant for authentication via the Azure CLI and workload identity. TenantID string }
DefaultAzureCredentialOptions contains optional parameters for DefaultAzureCredential. These options may not apply to all credentials in the chain.
type DeviceCodeCredential ¶
type DeviceCodeCredential struct {
// contains filtered or unexported fields
}
DeviceCodeCredential acquires tokens for a user via the device code flow, which has the user browse to a Microsoft Entra URL, enter a code, and authenticate. It's useful for authenticating a user in an environment without a web browser, such as an SSH session. If a web browser is available, InteractiveBrowserCredential is more convenient because it automatically opens a browser to the login page.
func NewDeviceCodeCredential ¶
func NewDeviceCodeCredential(options *DeviceCodeCredentialOptions) (*DeviceCodeCredential, error)
NewDeviceCodeCredential creates a DeviceCodeCredential. Pass nil to accept default options.
func (*DeviceCodeCredential) Authenticate ¶ added in v1.8.0
func (c *DeviceCodeCredential) Authenticate(ctx context.Context, opts *policy.TokenRequestOptions) (AuthenticationRecord, error)
Authenticate prompts a user to log in via the device code flow. Subsequent GetToken calls will automatically use the returned AuthenticationRecord.
func (*DeviceCodeCredential) GetToken ¶
func (c *DeviceCodeCredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (azcore.AccessToken, error)
GetToken requests an access token from Microsoft Entra ID. It will begin the device code flow and poll until the user completes authentication. This method is called automatically by Azure SDK clients.
type DeviceCodeCredentialOptions ¶ added in v0.2.2
type DeviceCodeCredentialOptions struct { azcore.ClientOptions // AdditionallyAllowedTenants specifies additional tenants for which the credential may acquire // tokens. Add the wildcard value "*" to allow the credential to acquire tokens for any tenant. AdditionallyAllowedTenants []string // AuthenticationRecord returned by a call to a credential's Authenticate method. Set this option // to enable the credential to use data from a previous authentication. AuthenticationRecord AuthenticationRecord // Cache is a persistent cache the credential will use to store the tokens it acquires, making // them available to other processes and credential instances. The default, zero value means the // credential will store tokens in memory and not share them. Cache Cache // ClientID is the ID of the application to which users will authenticate. When not set, users // will authenticate to an Azure development application, which isn't recommended for production // scenarios. In production, developers should instead register their applications and assign // appropriate roles. See https://aka.ms/identity/AppRegistrationAndRoleAssignment for more // information. ClientID string // DisableAutomaticAuthentication prevents the credential from automatically prompting the user to authenticate. // When this option is true, GetToken will return AuthenticationRequiredError when user interaction is necessary // to acquire a token. DisableAutomaticAuthentication bool // DisableInstanceDiscovery should be set true only by applications authenticating in disconnected clouds, or // private clouds such as Azure Stack. It determines whether the credential requests Microsoft Entra instance metadata // from https://login.microsoft.com before authenticating. Setting this to true will skip this request, making // the application responsible for ensuring the configured authority is valid and trustworthy. DisableInstanceDiscovery bool // TenantID is the Microsoft Entra tenant the credential authenticates in. Defaults to the // "organizations" tenant, which can authenticate work and school accounts. Required for single-tenant // applications. TenantID string // UserPrompt controls how the credential presents authentication instructions. The credential calls // this function with authentication details when it receives a device code. By default, the credential // prints these details to stdout. UserPrompt func(context.Context, DeviceCodeMessage) error }
DeviceCodeCredentialOptions contains optional parameters for DeviceCodeCredential.
type DeviceCodeMessage ¶ added in v0.3.0
type DeviceCodeMessage struct { // UserCode is the user code returned by the service. UserCode string `json:"user_code"` // VerificationURL is the URL at which the user must authenticate. VerificationURL string `json:"verification_uri"` // Message is user instruction from Microsoft Entra ID. Message string `json:"message"` }
DeviceCodeMessage contains the information a user needs to complete authentication.
type EnvironmentCredential ¶ added in v0.2.1
type EnvironmentCredential struct {
// contains filtered or unexported fields
}
EnvironmentCredential authenticates a service principal with a secret or certificate, or a user with a password, depending on environment variable configuration. It reads configuration from these variables, in the following order:
Service principal with client secret ¶
AZURE_TENANT_ID: ID of the service principal's tenant. Also called its "directory" ID.
AZURE_CLIENT_ID: the service principal's client ID
AZURE_CLIENT_SECRET: one of the service principal's client secrets
Service principal with certificate ¶
AZURE_TENANT_ID: ID of the service principal's tenant. Also called its "directory" ID.
AZURE_CLIENT_ID: the service principal's client ID
AZURE_CLIENT_CERTIFICATE_PATH: path to a PEM or PKCS12 certificate file including the private key.
AZURE_CLIENT_CERTIFICATE_PASSWORD: (optional) password for the certificate file.
Note that this credential uses ParseCertificates to load the certificate and key from the file. If this function isn't able to parse your certificate, use ClientCertificateCredential instead.
User with username and password ¶
AZURE_TENANT_ID: (optional) tenant to authenticate in. Defaults to "organizations".
AZURE_CLIENT_ID: client ID of the application the user will authenticate to
AZURE_USERNAME: a username (usually an email address)
AZURE_PASSWORD: the user's password
Configuration for multitenant applications ¶
To enable multitenant authentication, set AZURE_ADDITIONALLY_ALLOWED_TENANTS with a semicolon delimited list of tenants the credential may request tokens from in addition to the tenant specified by AZURE_TENANT_ID. Set AZURE_ADDITIONALLY_ALLOWED_TENANTS to "*" to enable the credential to request a token from any tenant.
func NewEnvironmentCredential ¶
func NewEnvironmentCredential(options *EnvironmentCredentialOptions) (*EnvironmentCredential, error)
NewEnvironmentCredential creates an EnvironmentCredential. Pass nil to accept default options.
func (*EnvironmentCredential) GetToken ¶ added in v0.2.1
func (c *EnvironmentCredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (azcore.AccessToken, error)
GetToken requests an access token from Microsoft Entra ID. This method is called automatically by Azure SDK clients.
type EnvironmentCredentialOptions ¶ added in v0.4.0
type EnvironmentCredentialOptions struct { azcore.ClientOptions // DisableInstanceDiscovery should be set true only by applications authenticating in disconnected clouds, or // private clouds such as Azure Stack. It determines whether the credential requests Microsoft Entra instance metadata // from https://login.microsoft.com before authenticating. Setting this to true will skip this request, making // the application responsible for ensuring the configured authority is valid and trustworthy. DisableInstanceDiscovery bool // contains filtered or unexported fields }
EnvironmentCredentialOptions contains optional parameters for EnvironmentCredential
type InteractiveBrowserCredential ¶ added in v0.2.1
type InteractiveBrowserCredential struct {
// contains filtered or unexported fields
}
InteractiveBrowserCredential opens a browser to interactively authenticate a user.
func NewInteractiveBrowserCredential ¶ added in v0.2.1
func NewInteractiveBrowserCredential(options *InteractiveBrowserCredentialOptions) (*InteractiveBrowserCredential, error)
NewInteractiveBrowserCredential constructs a new InteractiveBrowserCredential. Pass nil to accept default options.
func (*InteractiveBrowserCredential) Authenticate ¶ added in v1.8.0
func (c *InteractiveBrowserCredential) Authenticate(ctx context.Context, opts *policy.TokenRequestOptions) (AuthenticationRecord, error)
Authenticate opens the default browser so a user can log in. Subsequent GetToken calls will automatically use the returned AuthenticationRecord.
func (*InteractiveBrowserCredential) GetToken ¶ added in v0.2.1
func (c *InteractiveBrowserCredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (azcore.AccessToken, error)
GetToken requests an access token from Microsoft Entra ID. This method is called automatically by Azure SDK clients.
type InteractiveBrowserCredentialOptions ¶ added in v0.2.1
type InteractiveBrowserCredentialOptions struct { azcore.ClientOptions // AdditionallyAllowedTenants specifies additional tenants for which the credential may acquire // tokens. Add the wildcard value "*" to allow the credential to acquire tokens for any tenant. AdditionallyAllowedTenants []string // AuthenticationRecord returned by a call to a credential's Authenticate method. Set this option // to enable the credential to use data from a previous authentication. AuthenticationRecord AuthenticationRecord // Cache is a persistent cache the credential will use to store the tokens it acquires, making // them available to other processes and credential instances. The default, zero value means the // credential will store tokens in memory and not share them. Cache Cache // ClientID is the ID of the application to which users will authenticate. When not set, users // will authenticate to an Azure development application, which isn't recommended for production // scenarios. In production, developers should instead register their applications and assign // appropriate roles. See https://aka.ms/identity/AppRegistrationAndRoleAssignment for more // information. ClientID string // DisableAutomaticAuthentication prevents the credential from automatically prompting the user to authenticate. // When this option is true, GetToken will return AuthenticationRequiredError when user interaction is necessary // to acquire a token. DisableAutomaticAuthentication bool // DisableInstanceDiscovery should be set true only by applications authenticating in disconnected clouds, or // private clouds such as Azure Stack. It determines whether the credential requests Microsoft Entra instance metadata // from https://login.microsoft.com before authenticating. Setting this to true will skip this request, making // the application responsible for ensuring the configured authority is valid and trustworthy. DisableInstanceDiscovery bool // LoginHint pre-populates the account prompt with a username. Users may choose to authenticate a different account. LoginHint string // RedirectURL is the URL Microsoft Entra ID will redirect to with the access token. This is required // only when setting ClientID, and must match a redirect URI in the application's registration. // Applications which have registered "http://localhost" as a redirect URI need not set this option. RedirectURL string // TenantID is the Microsoft Entra tenant the credential authenticates in. Defaults to the // "organizations" tenant, which can authenticate work and school accounts. TenantID string }
InteractiveBrowserCredentialOptions contains optional parameters for InteractiveBrowserCredential.
type ManagedIDKind ¶ added in v0.12.0
ManagedIDKind identifies the ID of a managed identity as either a client or resource ID
type ManagedIdentityCredential ¶
type ManagedIdentityCredential struct {
// contains filtered or unexported fields
}
ManagedIdentityCredential authenticates an Azure managed identity in any hosting environment supporting managed identities. This credential authenticates a system-assigned identity by default. Use ManagedIdentityCredentialOptions.ID to specify a user-assigned identity. See Microsoft Entra ID documentation for more information about managed identities: https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/overview
func NewManagedIdentityCredential ¶
func NewManagedIdentityCredential(options *ManagedIdentityCredentialOptions) (*ManagedIdentityCredential, error)
NewManagedIdentityCredential creates a ManagedIdentityCredential. Pass nil to accept default options.
Example (UserAssigned) ¶
// select a user assigned identity with its client ID... clientID := azidentity.ClientID("abcd1234-...") opts := azidentity.ManagedIdentityCredentialOptions{ID: clientID} cred, err = azidentity.NewManagedIdentityCredential(&opts) handleError(err) // ...or its resource ID resourceID := azidentity.ResourceID("/subscriptions/...") opts = azidentity.ManagedIdentityCredentialOptions{ID: resourceID} cred, err = azidentity.NewManagedIdentityCredential(&opts) handleError(err)
Output:
func (*ManagedIdentityCredential) GetToken ¶
func (c *ManagedIdentityCredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (azcore.AccessToken, error)
GetToken requests an access token from the hosting environment. This method is called automatically by Azure SDK clients.
type ManagedIdentityCredentialOptions ¶
type ManagedIdentityCredentialOptions struct { azcore.ClientOptions // ID is the ID of a managed identity the credential should authenticate. Set this field to use a specific identity // instead of the hosting environment's default. The value may be the identity's client ID or resource ID, but note that // some platforms don't accept resource IDs. ID ManagedIDKind // contains filtered or unexported fields }
ManagedIdentityCredentialOptions contains optional parameters for ManagedIdentityCredential.
type OnBehalfOfCredential ¶ added in v1.3.0
type OnBehalfOfCredential struct {
// contains filtered or unexported fields
}
OnBehalfOfCredential authenticates a service principal via the on-behalf-of flow. This is typically used by middle-tier services that authorize requests to other services with a delegated user identity. Because this is not an interactive authentication flow, an application using it must have admin consent for any delegated permissions before requesting tokens for them. See Microsoft Entra ID documentation for more details.
func NewOnBehalfOfCredentialWithCertificate ¶ added in v1.3.0
func NewOnBehalfOfCredentialWithCertificate(tenantID, clientID, userAssertion string, certs []*x509.Certificate, key crypto.PrivateKey, options *OnBehalfOfCredentialOptions) (*OnBehalfOfCredential, error)
NewOnBehalfOfCredentialWithCertificate constructs an OnBehalfOfCredential that authenticates with a certificate. See ParseCertificates for help loading a certificate.
Example ¶
data, err := os.ReadFile(certPath) if err != nil { // TODO: handle error } // NewOnBehalfOfCredentialFromCertificate requires at least one *x509.Certificate, and a crypto.PrivateKey. // ParseCertificates returns these given certificate data in PEM or PKCS12 format. It handles common // scenarios but has limitations, for example it doesn't load PEM encrypted private keys or PKCS12 certs // that use SHA256 for message authentication. If it isn't able to parse your certificate, consider // using another module to load the certificate and private key. certs, key, err := azidentity.ParseCertificates(data, nil) if err != nil { // TODO: handle error } // userAssertion is the user's access token for the application. Typically it comes from a client request. userAssertion := "TODO" cred, err = azidentity.NewOnBehalfOfCredentialWithCertificate(tenantID, clientID, userAssertion, certs, key, nil) if err != nil { // TODO: handle error }
Output:
func NewOnBehalfOfCredentialWithClientAssertions ¶ added in v1.6.0
func NewOnBehalfOfCredentialWithClientAssertions(tenantID, clientID, userAssertion string, getAssertion func(context.Context) (string, error), options *OnBehalfOfCredentialOptions) (*OnBehalfOfCredential, error)
NewOnBehalfOfCredentialWithClientAssertions constructs an OnBehalfOfCredential that authenticates with client assertions. userAssertion is the user's access token for the application. The getAssertion function should return client assertions that authenticate the application to Microsoft Entra ID, such as federated credentials.
func NewOnBehalfOfCredentialWithSecret ¶ added in v1.3.0
func NewOnBehalfOfCredentialWithSecret(tenantID, clientID, userAssertion, clientSecret string, options *OnBehalfOfCredentialOptions) (*OnBehalfOfCredential, error)
NewOnBehalfOfCredentialWithSecret constructs an OnBehalfOfCredential that authenticates with a client secret.
func (*OnBehalfOfCredential) GetToken ¶ added in v1.3.0
func (o *OnBehalfOfCredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (azcore.AccessToken, error)
GetToken requests an access token from Microsoft Entra ID. This method is called automatically by Azure SDK clients.
type OnBehalfOfCredentialOptions ¶ added in v1.3.0
type OnBehalfOfCredentialOptions struct { azcore.ClientOptions // AdditionallyAllowedTenants specifies additional tenants for which the credential may acquire tokens. // Add the wildcard value "*" to allow the credential to acquire tokens for any tenant in which the // application is registered. AdditionallyAllowedTenants []string // DisableInstanceDiscovery should be set true only by applications authenticating in disconnected clouds, or // private clouds such as Azure Stack. It determines whether the credential requests Microsoft Entra instance metadata // from https://login.microsoft.com before authenticating. Setting this to true will skip this request, making // the application responsible for ensuring the configured authority is valid and trustworthy. DisableInstanceDiscovery bool // SendCertificateChain applies only when the credential is configured to authenticate with a certificate. // This setting controls whether the credential sends the public certificate chain in the x5c header of each // token request's JWT. This is required for, and only used in, Subject Name/Issuer (SNI) authentication. SendCertificateChain bool }
OnBehalfOfCredentialOptions contains optional parameters for OnBehalfOfCredential
type ResourceID ¶ added in v0.9.2
type ResourceID string
ResourceID is the resource ID of a user-assigned managed identity.
func (ResourceID) String ¶ added in v0.12.0
func (r ResourceID) String() string
String returns the string value of the ID.
type UsernamePasswordCredential ¶
type UsernamePasswordCredential struct {
// contains filtered or unexported fields
}
UsernamePasswordCredential authenticates a user with a password. Microsoft doesn't recommend this kind of authentication, because it's less secure than other authentication flows. This credential is not interactive, so it isn't compatible with any form of multi-factor authentication, and the application must already have user or admin consent. This credential can only authenticate work and school accounts; it can't authenticate Microsoft accounts.
func NewUsernamePasswordCredential ¶
func NewUsernamePasswordCredential(tenantID string, clientID string, username string, password string, options *UsernamePasswordCredentialOptions) (*UsernamePasswordCredential, error)
NewUsernamePasswordCredential creates a UsernamePasswordCredential. clientID is the ID of the application the user will authenticate to. Pass nil for options to accept defaults.
func (*UsernamePasswordCredential) Authenticate ¶ added in v1.8.0
func (c *UsernamePasswordCredential) Authenticate(ctx context.Context, opts *policy.TokenRequestOptions) (AuthenticationRecord, error)
Authenticate the user. Subsequent calls to GetToken will automatically use the returned AuthenticationRecord.
func (*UsernamePasswordCredential) GetToken ¶
func (c *UsernamePasswordCredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (azcore.AccessToken, error)
GetToken requests an access token from Microsoft Entra ID. This method is called automatically by Azure SDK clients.
type UsernamePasswordCredentialOptions ¶ added in v0.4.0
type UsernamePasswordCredentialOptions struct { azcore.ClientOptions // AdditionallyAllowedTenants specifies additional tenants for which the credential may acquire tokens. // Add the wildcard value "*" to allow the credential to acquire tokens for any tenant in which the // application is registered. AdditionallyAllowedTenants []string // AuthenticationRecord returned by a call to a credential's Authenticate method. Set this option // to enable the credential to use data from a previous authentication. AuthenticationRecord AuthenticationRecord // Cache is a persistent cache the credential will use to store the tokens it acquires, making // them available to other processes and credential instances. The default, zero value means the // credential will store tokens in memory and not share them. Cache Cache // DisableInstanceDiscovery should be set true only by applications authenticating in disconnected clouds, or // private clouds such as Azure Stack. It determines whether the credential requests Microsoft Entra instance metadata // from https://login.microsoft.com before authenticating. Setting this to true will skip this request, making // the application responsible for ensuring the configured authority is valid and trustworthy. DisableInstanceDiscovery bool }
UsernamePasswordCredentialOptions contains optional parameters for UsernamePasswordCredential.
type WorkloadIdentityCredential ¶ added in v1.3.0
type WorkloadIdentityCredential struct {
// contains filtered or unexported fields
}
WorkloadIdentityCredential supports Azure workload identity on Kubernetes. See Azure Kubernetes Service documentation for more information.
func NewWorkloadIdentityCredential ¶ added in v1.3.0
func NewWorkloadIdentityCredential(options *WorkloadIdentityCredentialOptions) (*WorkloadIdentityCredential, error)
NewWorkloadIdentityCredential constructs a WorkloadIdentityCredential. Service principal configuration is read from environment variables as set by the Azure workload identity webhook. Set options to override those values.
func (*WorkloadIdentityCredential) GetToken ¶ added in v1.3.0
func (w *WorkloadIdentityCredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (azcore.AccessToken, error)
GetToken requests an access token from Microsoft Entra ID. Azure SDK clients call this method automatically.
type WorkloadIdentityCredentialOptions ¶ added in v1.3.0
type WorkloadIdentityCredentialOptions struct { azcore.ClientOptions // AdditionallyAllowedTenants specifies additional tenants for which the credential may acquire tokens. // Add the wildcard value "*" to allow the credential to acquire tokens for any tenant in which the // application is registered. AdditionallyAllowedTenants []string // Cache is a persistent cache the credential will use to store the tokens it acquires, making // them available to other processes and credential instances. The default, zero value means the // credential will store tokens in memory and not share them. Cache Cache // ClientID of the service principal. Defaults to the value of the environment variable AZURE_CLIENT_ID. ClientID string // DisableInstanceDiscovery should be set true only by applications authenticating in disconnected clouds, or // private clouds such as Azure Stack. It determines whether the credential requests Microsoft Entra instance metadata // from https://login.microsoft.com before authenticating. Setting this to true will skip this request, making // the application responsible for ensuring the configured authority is valid and trustworthy. DisableInstanceDiscovery bool // TenantID of the service principal. Defaults to the value of the environment variable AZURE_TENANT_ID. TenantID string // TokenFilePath is the path of a file containing a Kubernetes service account token. Defaults to the value of the // environment variable AZURE_FEDERATED_TOKEN_FILE. TokenFilePath string }
WorkloadIdentityCredentialOptions contains optional parameters for WorkloadIdentityCredential.
Source Files ¶
- authentication_record.go
- azidentity.go
- azure_cli_credential.go
- azure_developer_cli_credential.go
- azure_pipelines_credential.go
- chained_token_credential.go
- client_assertion_credential.go
- client_certificate_credential.go
- client_secret_credential.go
- confidential_client.go
- default_azure_credential.go
- developer_credential_util.go
- device_code_credential.go
- environment_credential.go
- errors.go
- interactive_browser_credential.go
- logging.go
- managed_identity_client.go
- managed_identity_credential.go
- on_behalf_of_credential.go
- public_client.go
- username_password_credential.go
- version.go
- workload_identity.go