ceph-csi/vendor/github.com/Azure/azure-sdk-for-go/sdk/azidentity
Praveen M 47b202554e rebase: Azure key vault module dependency update
This commit adds the Azure SDK for Azure key vault KMS
integration to the Ceph CSI driver.

Signed-off-by: Praveen M <m.praveen@ibm.com>
2024-03-13 14:46:41 +00:00
..
internal rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
assets.json rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
authentication_record.go rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
azidentity.go rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
azure_cli_credential.go rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
azure_developer_cli_credential.go rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
chained_token_credential.go rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
CHANGELOG.md rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
ci.yml rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
client_assertion_credential.go rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
client_certificate_credential.go rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
client_secret_credential.go rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
confidential_client.go rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
default_azure_credential.go rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
developer_credential_util.go rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
device_code_credential.go rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
environment_credential.go rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
errors.go rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
go.work rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
go.work.sum rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
interactive_browser_credential.go rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
LICENSE.txt rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
logging.go rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
managed_identity_client.go rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
managed_identity_credential.go rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
MIGRATION.md rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
on_behalf_of_credential.go rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
public_client.go rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
README.md rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
test-resources-pre.ps1 rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
test-resources.bicep rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
TOKEN_CACHING.MD rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
TROUBLESHOOTING.md rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
username_password_credential.go rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
version.go rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00
workload_identity.go rebase: Azure key vault module dependency update 2024-03-13 14:46:41 +00:00

Azure Identity Client Module for Go

The Azure Identity module provides Microsoft Entra ID (formerly Azure Active Directory) token authentication support across the Azure SDK. It includes a set of TokenCredential implementations, which can be used with Azure SDK clients supporting token authentication.

PkgGoDev | Microsoft Entra ID documentation | Source code

Getting started

Install the module

This project uses Go modules for versioning and dependency management.

Install the Azure Identity module:

go get -u github.com/Azure/azure-sdk-for-go/sdk/azidentity

Prerequisites

Authenticating during local development

When debugging and executing code locally, developers typically use their own accounts to authenticate calls to Azure services. The azidentity module supports authenticating through developer tools to simplify local development.

Authenticating via the Azure CLI

DefaultAzureCredential and AzureCLICredential can authenticate as the user signed in to the Azure CLI. To sign in to the Azure CLI, run az login. On a system with a default web browser, the Azure CLI will launch the browser to authenticate a user.

When no default browser is available, az login will use the device code authentication flow. This can also be selected manually by running az login --use-device-code.

Authenticate via the Azure Developer CLI

Developers coding outside of an IDE can also use the Azure Developer CLI to authenticate. Applications using the DefaultAzureCredential or the AzureDeveloperCLICredential can use the account logged in to the Azure Developer CLI to authenticate calls in their application when running locally.

To authenticate with the Azure Developer CLI, run azd auth login. On a system with a default web browser, azd will launch the browser to authenticate. On systems without a default web browser, run azd auth login --use-device-code to use the device code authentication flow.

Key concepts

Credentials

A credential is a type which contains or can obtain the data needed for a service client to authenticate requests. Service clients across the Azure SDK accept a credential instance when they are constructed, and use that credential to authenticate requests.

The azidentity module focuses on OAuth authentication with Microsoft Entra ID. It offers a variety of credential types capable of acquiring a Microsoft Entra access token. See Credential Types for a list of this module's credential types.

DefaultAzureCredential

DefaultAzureCredential is appropriate for most apps that will be deployed to Azure. It combines common production credentials with development credentials. It attempts to authenticate via the following mechanisms in this order, stopping when one succeeds:

DefaultAzureCredential authentication flow

  1. Environment - DefaultAzureCredential will read account information specified via environment variables and use it to authenticate.
  2. Workload Identity - If the app is deployed on Kubernetes with environment variables set by the workload identity webhook, DefaultAzureCredential will authenticate the configured identity.
  3. Managed Identity - If the app is deployed to an Azure host with managed identity enabled, DefaultAzureCredential will authenticate with it.
  4. Azure CLI - If a user or service principal has authenticated via the Azure CLI az login command, DefaultAzureCredential will authenticate that identity.
  5. Azure Developer CLI - If the developer has authenticated via the Azure Developer CLI azd auth login command, the DefaultAzureCredential will authenticate with that account.

Note: DefaultAzureCredential is intended to simplify getting started with the SDK by handling common scenarios with reasonable default behaviors. Developers who want more control or whose scenario isn't served by the default settings should use other credential types.

Managed Identity

DefaultAzureCredential and ManagedIdentityCredential support managed identity authentication in any hosting environment which supports managed identities, such as (this list is not exhaustive):

Examples

Authenticate with DefaultAzureCredential

This example demonstrates authenticating a client from the armresources module with DefaultAzureCredential.

cred, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
  // handle error
}

client := armresources.NewResourceGroupsClient("subscription ID", cred, nil)

Specify a user-assigned managed identity for DefaultAzureCredential

To configure DefaultAzureCredential to authenticate a user-assigned managed identity, set the environment variable AZURE_CLIENT_ID to the identity's client ID.

Define a custom authentication flow with ChainedTokenCredential

DefaultAzureCredential is generally the quickest way to get started developing apps for Azure. For more advanced scenarios, ChainedTokenCredential links multiple credential instances to be tried sequentially when authenticating. It will try each chained credential in turn until one provides a token or fails to authenticate due to an error.

The following example demonstrates creating a credential, which will attempt to authenticate using managed identity. It will fall back to authenticating via the Azure CLI when a managed identity is unavailable.

managed, err := azidentity.NewManagedIdentityCredential(nil)
if err != nil {
  // handle error
}
azCLI, err := azidentity.NewAzureCLICredential(nil)
if err != nil {
  // handle error
}
chain, err := azidentity.NewChainedTokenCredential([]azcore.TokenCredential{managed, azCLI}, nil)
if err != nil {
  // handle error
}

client := armresources.NewResourceGroupsClient("subscription ID", chain, nil)

Credential Types

Authenticating Azure Hosted Applications

Credential Usage
DefaultAzureCredential Simplified authentication experience for getting started developing Azure apps
ChainedTokenCredential Define custom authentication flows, composing multiple credentials
EnvironmentCredential Authenticate a service principal or user configured by environment variables
ManagedIdentityCredential Authenticate the managed identity of an Azure resource
WorkloadIdentityCredential Authenticate a workload identity on Kubernetes

Authenticating Service Principals

Credential Usage
ClientAssertionCredential Authenticate a service principal with a signed client assertion
ClientCertificateCredential Authenticate a service principal with a certificate
ClientSecretCredential Authenticate a service principal with a secret

Authenticating Users

Credential Usage
InteractiveBrowserCredential Interactively authenticate a user with the default web browser
DeviceCodeCredential Interactively authenticate a user on a device with limited UI
UsernamePasswordCredential Authenticate a user with a username and password

Authenticating via Development Tools

Credential Usage
AzureCLICredential Authenticate as the user signed in to the Azure CLI
AzureDeveloperCLICredential Authenticates as the user signed in to the Azure Developer CLI

Environment Variables

DefaultAzureCredential and EnvironmentCredential can be configured with environment variables. Each type of authentication requires values for specific variables:

Service principal with secret

variable name value
AZURE_CLIENT_ID ID of a Microsoft Entra application
AZURE_TENANT_ID ID of the application's Microsoft Entra tenant
AZURE_CLIENT_SECRET one of the application's client secrets

Service principal with certificate

variable name value
AZURE_CLIENT_ID ID of a Microsoft Entra application
AZURE_TENANT_ID ID of the application's Microsoft Entra tenant
AZURE_CLIENT_CERTIFICATE_PATH path to a certificate file including private key
AZURE_CLIENT_CERTIFICATE_PASSWORD password of the certificate file, if any

Username and password

variable name value
AZURE_CLIENT_ID ID of a Microsoft Entra application
AZURE_USERNAME a username (usually an email address)
AZURE_PASSWORD that user's password

Configuration is attempted in the above order. For example, if values for a client secret and certificate are both present, the client secret will be used.

Token caching

Token caching is an azidentity feature that allows apps to:

  • Cache tokens in memory (default) or on disk (opt-in).
  • Improve resilience and performance.
  • Reduce the number of requests made to Microsoft Entra ID to obtain access tokens.

For more details, see the token caching documentation.

Troubleshooting

Error Handling

Credentials return an error when they fail to authenticate or lack data they require to authenticate. For guidance on resolving errors from specific credential types, see the troubleshooting guide.

For more details on handling specific Microsoft Entra errors, see the Microsoft Entra error code documentation.

Logging

This module uses the classification-based logging implementation in azcore. To enable console logging for all SDK modules, set AZURE_SDK_GO_LOGGING to all. Use the azcore/log package to control log event output or to enable logs for azidentity only. For example:

import azlog "github.com/Azure/azure-sdk-for-go/sdk/azcore/log"

// print log output to stdout
azlog.SetListener(func(event azlog.Event, s string) {
    fmt.Println(s)
})

// include only azidentity credential logs
azlog.SetEvents(azidentity.EventAuthentication)

Credentials log basic information only, such as GetToken success or failure and errors. These log entries don't contain authentication secrets but may contain sensitive information.

Next steps

Client and management modules listed on the Azure SDK releases page support authenticating with azidentity credential types. You can learn more about using these libraries in their documentation, which is linked from the release page.

Provide Feedback

If you encounter bugs or have suggestions, please open an issue.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Impressions