This example shows how to cache service principal authentication data persistently to make it accessible to multiple processes. The example uses ClientCertificateCredential, however the pattern is the same for all service principal credential types having a Cache field in their options. The key steps are:
Credentials that authenticate users such as InteractiveBrowserCredential have a different pattern; see the persistent user authentication example.
package main
import (
"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
"github.com/Azure/azure-sdk-for-go/sdk/azidentity/cache"
)
func main() {
c, err := cache.New(nil)
if err != nil {
// TODO: handle error. An error here means persistent
// caching is impossible in the runtime environment.
}
certs, key, err := azidentity.ParseCertificates([]byte("cert data"), nil)
if err != nil {
// TODO: handle error
}
opts := &azidentity.ClientCertificateCredentialOptions{
// Credentials cache in memory by default. Setting Cache with a
// nonzero value from cache.New() enables persistent caching.
Cache: c,
}
cred, err := azidentity.NewClientCertificateCredential("tenant ID", "client ID", certs, key, opts)
if err != nil {
// TODO: handle error
}
// TODO: pass the credential to an Azure SDK client constructor
_ = cred
}
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:
This examples applies to credentials that authenticate users. For credentials authenticating service principal, see the persistent service principal authentication example.
//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
//
// This examples applies to credentials that authenticate users. For credentials authenticating service principal, see
// the [persistent service principal authentication example].
//
// [persistent service principal authentication example]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#example-package-PersistentServicePrincipalAuthentication
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
}
}
}
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.
This section is empty.
func NewCredentialUnavailableError(message string) error
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.
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.
type AuthenticationFailedError struct {
RawResponse *http.Response
}
AuthenticationFailedError indicates an authentication request has failed.
Error implements the error interface. Note that the message contents are not contractual and can change over time.
NonRetriable indicates the request which provoked this error shouldn't be retried.
type AuthenticationRecord struct {
Authority string `json:"authority"`
ClientID string `json:"clientId"`
HomeAccountID string `json:"homeAccountId"`
TenantID string `json:"tenantId"`
Username string `json:"username"`
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.
UnmarshalJSON implements json.Unmarshaler for AuthenticationRecord
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.
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
}
}
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()
NonRetriable is a marker method indicating this error should not be retried. It has no implementation.
type AzureCLICredential struct {
}
AzureCLICredential authenticates as the identity logged in to the Azure CLI.
NewAzureCLICredential constructs an AzureCLICredential. Pass nil to accept default options.
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 struct {
AdditionallyAllowedTenants []string
Subscription string
TenantID string
}
AzureCLICredentialOptions contains optional parameters for AzureCLICredential.
type AzureDeveloperCLICredential struct {
}
AzureDeveloperCLICredential authenticates as the identity logged in to the Azure Developer CLI.
NewAzureDeveloperCLICredential constructs an AzureDeveloperCLICredential. Pass nil to accept default options.
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 struct {
AdditionallyAllowedTenants []string
TenantID string
}
AzureDeveloperCLICredentialOptions contains optional parameters for AzureDeveloperCLICredential.
type AzurePipelinesCredential struct {
}
AzurePipelinesCredential authenticates with workload identity federation in an Azure Pipeline. See Azure Pipelines documentation for more information.
NewAzurePipelinesCredential is the constructor for AzurePipelinesCredential.
GetToken requests an access token from Microsoft Entra ID. Azure SDK clients call this method automatically.
AzurePipelinesCredentialOptions contains optional parameters for AzurePipelinesCredential.
type ChainedTokenCredential struct {
}
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. For more information, see ChainedTokenCredential overview.
NewChainedTokenCredential creates a ChainedTokenCredential. Pass nil for options to accept defaults.
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
}
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 struct {
RetrySources bool
}
ChainedTokenCredentialOptions contains optional parameters for ChainedTokenCredential.
type ClientAssertionCredential struct {
}
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.
NewClientAssertionCredential constructs a ClientAssertionCredential. The getAssertion function must be thread safe. Pass nil for options to accept defaults.
GetToken requests an access token from Microsoft Entra ID. This method is called automatically by Azure SDK clients.
ClientAssertionCredentialOptions contains optional parameters for ClientAssertionCredential.
type ClientCertificateCredential struct {
}
ClientCertificateCredential authenticates a service principal with a certificate.
NewClientCertificateCredential constructs a ClientCertificateCredential. Pass nil for options to accept defaults. See ParseCertificates for help loading a certificate.
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)
GetToken requests an access token from Microsoft Entra ID. This method is called automatically by Azure SDK clients.
ClientCertificateCredentialOptions contains optional parameters for ClientCertificateCredential.
ClientID is the client ID of a user-assigned managed identity. NewManagedIdentityCredential returns an error when a ClientID is specified on the following platforms:
String returns the string value of the ID.
type ClientSecretCredential struct {
}
ClientSecretCredential authenticates an application with a client secret.
NewClientSecretCredential constructs a ClientSecretCredential. Pass nil for options to accept defaults.
GetToken requests an access token from Microsoft Entra ID. This method is called automatically by Azure SDK clients.
ClientSecretCredentialOptions contains optional parameters for ClientSecretCredential.
type DefaultAzureCredential struct {
}
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. For more information, see DefaultAzureCredential overview.
DefaultAzureCredential attempts to authenticate with each of these credential types, in the following order, stopping when one provides a token:
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.
Selecting credentials ¶Set environment variable AZURE_TOKEN_CREDENTIALS to select a subset of the credential chain described above. DefaultAzureCredential will try only the specified credential(s), but its other behavior remains the same. Valid values for AZURE_TOKEN_CREDENTIALS are the name of any single type in the above chain, for example "EnvironmentCredential" or "AzureCLICredential", and these special values:
NewDefaultAzureCredential creates a DefaultAzureCredential. Pass nil for options to accept defaults.
GetToken requests an access token from Microsoft Entra ID. This method is called automatically by Azure SDK clients.
DefaultAzureCredentialOptions contains optional parameters for DefaultAzureCredential. These options may not apply to all credentials in the chain.
type DeviceCodeCredential struct {
}
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.
NewDeviceCodeCredential creates a DeviceCodeCredential. Pass nil to accept default options.
Authenticate prompts a user to log in via the device code flow. Subsequent GetToken calls will automatically use the returned AuthenticationRecord.
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.
DeviceCodeCredentialOptions contains optional parameters for DeviceCodeCredential.
type DeviceCodeMessage struct {
UserCode string `json:"user_code"`
VerificationURL string `json:"verification_uri"`
Message string `json:"message"`
}
DeviceCodeMessage contains the information a user needs to complete authentication.
type EnvironmentCredential struct {
}
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.
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.
NewEnvironmentCredential creates an EnvironmentCredential. Pass nil to accept default options.
GetToken requests an access token from Microsoft Entra ID. This method is called automatically by Azure SDK clients.
EnvironmentCredentialOptions contains optional parameters for EnvironmentCredential
type InteractiveBrowserCredential struct {
}
InteractiveBrowserCredential opens a browser to interactively authenticate a user.
NewInteractiveBrowserCredential constructs a new InteractiveBrowserCredential. Pass nil to accept default options.
Authenticate opens the default browser so a user can log in. Subsequent GetToken calls will automatically use the returned AuthenticationRecord.
GetToken requests an access token from Microsoft Entra ID. This method is called automatically by Azure SDK clients.
InteractiveBrowserCredentialOptions contains optional parameters for InteractiveBrowserCredential.
ManagedIDKind identifies the ID of a managed identity as either a client or resource ID
type ManagedIdentityCredential struct {
}
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.
NewManagedIdentityCredential creates a ManagedIdentityCredential. Pass nil to accept default options.
This example shows how to specify a user-assigned identity. Note that some hosting environments don't support user-assigned identities, and some that do support them accept only a subset of their identifiers. See the documentation for ClientID, ResourceID, and ObjectID for details.
// select a user-assigned identity with its client ID...
clientID := azidentity.ClientID("abcd1234-...")
opts := azidentity.ManagedIdentityCredentialOptions{ID: clientID}
cred, err = azidentity.NewManagedIdentityCredential(&opts)
if err != nil {
// TODO
}
// ...or its resource ID...
resourceID := azidentity.ResourceID("/subscriptions/...")
opts = azidentity.ManagedIdentityCredentialOptions{ID: resourceID}
cred, err = azidentity.NewManagedIdentityCredential(&opts)
if err != nil {
// TODO
}
// ...or its object ID
objectID := azidentity.ObjectID("4321dcba-...")
opts = azidentity.ManagedIdentityCredentialOptions{ID: objectID}
cred, err = azidentity.NewManagedIdentityCredential(&opts)
if err != nil {
// TODO
}
GetToken requests an access token from the hosting environment. This method is called automatically by Azure SDK clients.
ManagedIdentityCredentialOptions contains optional parameters for ManagedIdentityCredential.
ObjectID is the object ID of a user-assigned managed identity. NewManagedIdentityCredential returns an error when an ObjectID is specified on the following platforms:
String returns the string value of the ID.
type OnBehalfOfCredential struct {
}
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.
NewOnBehalfOfCredentialWithCertificate constructs an OnBehalfOfCredential that authenticates with a certificate. See ParseCertificates for help loading a certificate.
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
}
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.
NewOnBehalfOfCredentialWithSecret constructs an OnBehalfOfCredential that authenticates with a client secret.
GetToken requests an access token from Microsoft Entra ID. This method is called automatically by Azure SDK clients.
OnBehalfOfCredentialOptions contains optional parameters for OnBehalfOfCredential
ResourceID is the resource ID of a user-assigned managed identity. NewManagedIdentityCredential returns an error when a ResourceID is specified on the following platforms:
String returns the string value of the ID.
type UsernamePasswordCredential struct {
}
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 multifactor 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.
Deprecated: this credential is deprecated because it can't support multifactor authentication. See Entra ID documentation for migration guidance.
NewUsernamePasswordCredential creates a UsernamePasswordCredential. clientID is the ID of the application the user will authenticate to. Pass nil for options to accept defaults.
Authenticate the user. Subsequent calls to GetToken will automatically use the returned AuthenticationRecord.
GetToken requests an access token from Microsoft Entra ID. This method is called automatically by Azure SDK clients.
UsernamePasswordCredentialOptions contains optional parameters for UsernamePasswordCredential.
Deprecated: UsernamePasswordCredential is deprecated because it can't support multifactor authentication. See Entra ID documentation for migration guidance.
type WorkloadIdentityCredential struct {
}
WorkloadIdentityCredential supports Azure workload identity on Kubernetes. See Azure Kubernetes Service documentation for more information.
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.
GetToken requests an access token from Microsoft Entra ID. Azure SDK clients call this method automatically.
WorkloadIdentityCredentialOptions contains optional parameters for WorkloadIdentityCredential.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4