Skip to content

Commit 230c9d2

Browse files
chlowellchlowell
authored
Revise azidentity doc comments (Azure#17746)
1 parent 1d23ee6 commit 230c9d2

12 files changed

+71
-141
lines changed

‎sdk/azidentity/azure_cli_credential.go

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -27,11 +27,11 @@ type azureCLITokenProvider func(ctx context.Context, resource string, tenantID s
2727

2828
// AzureCLICredentialOptions contains optional parameters for AzureCLICredential.
2929
type AzureCLICredentialOptions struct {
30-
tokenProvider azureCLITokenProvider
31-
3230
// TenantID identifies the tenant the credential should authenticate in.
3331
// Defaults to the CLI's default tenant, which is typically the home tenant of the logged in user.
3432
TenantID string
33+
34+
tokenProvider azureCLITokenProvider
3535
}
3636

3737
// init returns an instance of AzureCLICredentialOptions initialized with default values.
@@ -47,8 +47,7 @@ type AzureCLICredential struct {
4747
tenantID string
4848
}
4949

50-
// NewAzureCLICredential constructs an AzureCLICredential.
51-
// options: Optional configuration. Pass nil to accept default settings.
50+
// NewAzureCLICredential constructs an AzureCLICredential. Pass nil to accept default options.
5251
func NewAzureCLICredential(options *AzureCLICredentialOptions) (*AzureCLICredential, error) {
5352
cp := AzureCLICredentialOptions{}
5453
if options != nil {
@@ -63,8 +62,6 @@ func NewAzureCLICredential(options *AzureCLICredentialOptions) (*AzureCLICredent
6362

6463
// GetToken requests a token from the Azure CLI. This credential doesn't cache tokens, so every call invokes the CLI.
6564
// This method is called automatically by Azure SDK clients.
66-
// ctx: Context controlling the request lifetime.
67-
// opts: Options for the token request, in particular the desired scope of the access token.
6865
func (c *AzureCLICredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (*azcore.AccessToken, error) {
6966
if len(opts.Scopes) != 1 {
7067
return nil, errors.New(credNameAzureCLI + ": GetToken() requires exactly one scope")

‎sdk/azidentity/chained_token_credential.go

Lines changed: 8 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -17,16 +17,14 @@ import (
1717

1818
// ChainedTokenCredentialOptions contains optional parameters for ChainedTokenCredential.
1919
type ChainedTokenCredentialOptions struct {
20-
// RetrySources configures how the credential uses its sources.
21-
// When true, the credential will always request a token from each source in turn,
22-
// stopping when one provides a token. When false, the credential requests a token
23-
// only from the source that previously retrieved a token--it never again tries the sources which failed.
20+
// RetrySources configures how the credential uses its sources. When true, the credential always attempts to
21+
// authenticate through each source in turn, stopping when one succeeds. When false, the credential authenticates
22+
// only through this first successful source--it never again tries the sources which failed.
2423
RetrySources bool
2524
}
2625

27-
// ChainedTokenCredential is a chain of credentials that enables fallback behavior when a credential can't authenticate.
28-
// By default, this credential will assume that the first successful credential should be the only credential used on future requests.
29-
// If the `RetrySources` option is set to true, it will always try to get a token using all of the originally provided credentials.
26+
// ChainedTokenCredential links together multiple credentials and tries them sequentially when authenticating. By default,
27+
// it tries all the credentials until one authenticates, after which it always uses that credential.
3028
type ChainedTokenCredential struct {
3129
cond *sync.Cond
3230
iterating bool
@@ -36,9 +34,7 @@ type ChainedTokenCredential struct {
3634
successfulCredential azcore.TokenCredential
3735
}
3836

39-
// NewChainedTokenCredential creates a ChainedTokenCredential.
40-
// sources: Credential instances to comprise the chain. GetToken() will invoke them in the given order.
41-
// options: Optional configuration. Pass nil to accept default settings.
37+
// NewChainedTokenCredential creates a ChainedTokenCredential. Pass nil for options to accept defaults.
4238
func NewChainedTokenCredential(sources []azcore.TokenCredential, options *ChainedTokenCredentialOptions) (*ChainedTokenCredential, error) {
4339
if len(sources) == 0 {
4440
return nil, errors.New("sources must contain at least one TokenCredential")
@@ -61,9 +57,8 @@ func NewChainedTokenCredential(sources []azcore.TokenCredential, options *Chaine
6157
}, nil
6258
}
6359

64-
// GetToken calls GetToken on the chained credentials in turn, stopping when one returns a token. This method is called automatically by Azure SDK clients.
65-
// ctx: Context controlling the request lifetime.
66-
// opts: Options for the token request, in particular the desired scope of the access token.
60+
// GetToken calls GetToken on the chained credentials in turn, stopping when one returns a token.
61+
// This method is called automatically by Azure SDK clients.
6762
func (c *ChainedTokenCredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (*azcore.AccessToken, error) {
6863
if !c.retrySources {
6964
// ensure only one goroutine at a time iterates the sources and perhaps sets c.successfulCredential

‎sdk/azidentity/client_certificate_credential.go

Lines changed: 4 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -38,12 +38,7 @@ type ClientCertificateCredential struct {
3838
client confidentialClient
3939
}
4040

41-
// NewClientCertificateCredential constructs a ClientCertificateCredential.
42-
// tenantID: The application's Azure Active Directory tenant or directory ID.
43-
// clientID: The application's client ID.
44-
// certs: one or more certificates, for example as returned by ParseCertificates()
45-
// key: the signing certificate's private key, for example as returned by ParseCertificates()
46-
// options: Optional configuration. Pass nil to accept default settings.
41+
// NewClientCertificateCredential constructs a ClientCertificateCredential. Pass nil for options to accept defaults.
4742
func NewClientCertificateCredential(tenantID string, clientID string, certs []*x509.Certificate, key crypto.PrivateKey, options *ClientCertificateCredentialOptions) (*ClientCertificateCredential, error) {
4843
if len(certs) == 0 {
4944
return nil, errors.New("at least one certificate is required")
@@ -84,9 +79,7 @@ func NewClientCertificateCredential(tenantID string, clientID string, certs []*x
8479
return &ClientCertificateCredential{client: c}, nil
8580
}
8681

87-
// GetToken obtains a token from Azure Active Directory. This method is called automatically by Azure SDK clients.
88-
// ctx: Context controlling the request lifetime.
89-
// opts: Options for the token request, in particular the desired scope of the access token.
82+
// GetToken requests an access token from Azure Active Directory. This method is called automatically by Azure SDK clients.
9083
func (c *ClientCertificateCredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (*azcore.AccessToken, error) {
9184
if len(opts.Scopes) == 0 {
9285
return nil, errors.New(credNameCert + ": GetToken() requires at least one scope")
@@ -105,9 +98,8 @@ func (c *ClientCertificateCredential) GetToken(ctx context.Context, opts policy.
10598
return &azcore.AccessToken{Token: ar.AccessToken, ExpiresOn: ar.ExpiresOn.UTC()}, err
10699
}
107100

108-
// ParseCertificates loads certificates and a private key for use with NewClientCertificateCredential.
109-
// certData: certificate data encoded in PEM or PKCS12 format, including the certificate's private key.
110-
// password: the password required to decrypt the private key. Pass nil if the key is not encrypted. This function can't decrypt keys in PEM format.
101+
// ParseCertificates loads certificates and a private key, in PEM or PKCS12 format, for use with NewClientCertificateCredential.
102+
// Pass nil for password if the private key isn't encrypted. This function can't decrypt keys in PEM format.
111103
func ParseCertificates(certData []byte, password []byte) ([]*x509.Certificate, crypto.PrivateKey, error) {
112104
var blocks []*pem.Block
113105
var err error

‎sdk/azidentity/client_secret_credential.go

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -25,11 +25,7 @@ type ClientSecretCredential struct {
2525
client confidentialClient
2626
}
2727

28-
// NewClientSecretCredential constructs a ClientSecretCredential.
29-
// tenantID: The application's Azure Active Directory tenant or directory ID.
30-
// clientID: The application's client ID.
31-
// clientSecret: One of the application's client secrets.
32-
// options: Optional configuration. Pass nil to accept default settings.
28+
// NewClientSecretCredential constructs a ClientSecretCredential. Pass nil for options to accept defaults.
3329
func NewClientSecretCredential(tenantID string, clientID string, clientSecret string, options *ClientSecretCredentialOptions) (*ClientSecretCredential, error) {
3430
if !validTenantID(tenantID) {
3531
return nil, errors.New(tenantIDValidationErr)
@@ -55,9 +51,7 @@ func NewClientSecretCredential(tenantID string, clientID string, clientSecret st
5551
return &ClientSecretCredential{client: c}, nil
5652
}
5753

58-
// GetToken obtains a token from Azure Active Directory. This method is called automatically by Azure SDK clients.
59-
// ctx: Context used to control the request lifetime.
60-
// opts: Options for the token request, in particular the desired scope of the access token.
54+
// GetToken requests an access token from Azure Active Directory. This method is called automatically by Azure SDK clients.
6155
func (c *ClientSecretCredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (*azcore.AccessToken, error) {
6256
if len(opts.Scopes) == 0 {
6357
return nil, errors.New(credNameSecret + ": GetToken() requires at least one scope")

‎sdk/azidentity/default_azure_credential.go

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -28,15 +28,17 @@ type DefaultAzureCredentialOptions struct {
2828
// DefaultAzureCredential is a default credential chain for applications that will deploy to Azure.
2929
// It combines credentials suitable for deployment with credentials suitable for local development.
3030
// It attempts to authenticate with each of these credential types, in the following order, stopping when one provides a token:
31-
// - EnvironmentCredential
32-
// - ManagedIdentityCredential
33-
// - AzureCLICredential
31+
// EnvironmentCredential
32+
// ManagedIdentityCredential
33+
// AzureCLICredential
3434
// Consult the documentation for these credential types for more information on how they authenticate.
35+
// Once a credential has successfully authenticated, DefaultAzureCredential will use that credential for
36+
// every subsequent authentication.
3537
type DefaultAzureCredential struct {
3638
chain *ChainedTokenCredential
3739
}
3840

39-
// NewDefaultAzureCredential creates a DefaultAzureCredential.
41+
// NewDefaultAzureCredential creates a DefaultAzureCredential. Pass nil for options to accept defaults.
4042
func NewDefaultAzureCredential(options *DefaultAzureCredentialOptions) (*DefaultAzureCredential, error) {
4143
var creds []azcore.TokenCredential
4244
var errorMessages []string
@@ -87,9 +89,7 @@ func NewDefaultAzureCredential(options *DefaultAzureCredentialOptions) (*Default
8789
return &DefaultAzureCredential{chain: chain}, nil
8890
}
8991

90-
// GetToken obtains a token from Azure Active Directory. This method is called automatically by Azure SDK clients.
91-
// ctx: Context used to control the request lifetime.
92-
// opts: Options for the token request, in particular the desired scope of the access token.
92+
// GetToken requests an access token from Azure Active Directory. This method is called automatically by Azure SDK clients.
9393
func (c *DefaultAzureCredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (token *azcore.AccessToken, err error) {
9494
return c.chain.GetToken(ctx, opts)
9595
}

‎sdk/azidentity/device_code_credential.go

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -69,8 +69,7 @@ type DeviceCodeCredential struct {
6969
account public.Account
7070
}
7171

72-
// NewDeviceCodeCredential creates a DeviceCodeCredential.
73-
// options: Optional configuration. Pass nil to accept default settings.
72+
// NewDeviceCodeCredential creates a DeviceCodeCredential. Pass nil to accept default options.
7473
func NewDeviceCodeCredential(options *DeviceCodeCredentialOptions) (*DeviceCodeCredential, error) {
7574
cp := DeviceCodeCredentialOptions{}
7675
if options != nil {
@@ -94,10 +93,8 @@ func NewDeviceCodeCredential(options *DeviceCodeCredentialOptions) (*DeviceCodeC
9493
return &DeviceCodeCredential{userPrompt: cp.UserPrompt, client: c}, nil
9594
}
9695

97-
// GetToken obtains a token from Azure Active Directory. It will begin the device code flow and poll until the user completes authentication.
96+
// GetToken requests an access token from Azure Active Directory. It will begin the device code flow and poll until the user completes authentication.
9897
// This method is called automatically by Azure SDK clients.
99-
// ctx: Context used to control the request lifetime.
100-
// opts: Options for the token request, in particular the desired scope of the access token.
10198
func (c *DeviceCodeCredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (*azcore.AccessToken, error) {
10299
if len(opts.Scopes) == 0 {
103100
return nil, errors.New(credNameDeviceCode + ": GetToken() requires at least one scope")

‎sdk/azidentity/doc.go

Lines changed: 0 additions & 35 deletions
This file was deleted.

‎sdk/azidentity/environment_credential.go

Lines changed: 25 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -25,29 +25,36 @@ type EnvironmentCredentialOptions struct {
2525
// EnvironmentCredential authenticates a service principal with a secret or certificate, or a user with a password, depending
2626
// on environment variable configuration. It reads configuration from these variables, in the following order:
2727
//
28-
// Service principal:
29-
// - AZURE_TENANT_ID: ID of the service principal's tenant. Also called its "directory" ID.
30-
// - AZURE_CLIENT_ID: the service principal's client ID
31-
// - AZURE_CLIENT_SECRET: one of the service principal's client secrets
28+
// Service principal with client secret
3229
//
33-
// Service principal with certificate:
34-
// - AZURE_TENANT_ID: ID of the service principal's tenant. Also called its "directory" ID.
35-
// - AZURE_CLIENT_ID: the service principal's client ID
36-
// - AZURE_CLIENT_CERTIFICATE_PATH: path to a PEM or PKCS12 certificate file including the private key. The
37-
// certificate must not be password-protected.
30+
// AZURE_TENANT_ID: ID of the service principal's tenant. Also called its "directory" ID.
3831
//
39-
// User with username and password:
40-
// - AZURE_CLIENT_ID: the application's client ID
41-
// - AZURE_USERNAME: a username (usually an email address)
42-
// - AZURE_PASSWORD: that user's password
43-
// - AZURE_TENANT_ID: (optional) tenant to authenticate in. If not set, defaults to the "organizations" tenant, which
44-
// can authenticate only Azure Active Directory work or school accounts.
32+
// AZURE_CLIENT_ID: the service principal's client ID
33+
//
34+
// AZURE_CLIENT_SECRET: one of the service principal's client secrets
35+
//
36+
// Service principal with certificate
37+
//
38+
// AZURE_TENANT_ID: ID of the service principal's tenant. Also called its "directory" ID.
39+
//
40+
// AZURE_CLIENT_ID: the service principal's client ID
41+
//
42+
// AZURE_CLIENT_CERTIFICATE_PATH: path to a PEM or PKCS12 certificate file including the unencrypted private key.
43+
//
44+
// User with username and password
45+
//
46+
// AZURE_TENANT_ID: (optional) tenant to authenticate in. Defaults to "organizations".
47+
//
48+
// AZURE_CLIENT_ID: client ID of the application the user will authenticate to
49+
//
50+
// AZURE_USERNAME: a username (usually an email address)
51+
//
52+
// AZURE_PASSWORD: the user's password
4553
type EnvironmentCredential struct {
4654
cred azcore.TokenCredential
4755
}
4856

49-
// NewEnvironmentCredential creates an EnvironmentCredential.
50-
// options: Optional configuration. Pass nil to accept default settings.
57+
// NewEnvironmentCredential creates an EnvironmentCredential. Pass nil to accept default options.
5158
func NewEnvironmentCredential(options *EnvironmentCredentialOptions) (*EnvironmentCredential, error) {
5259
if options == nil {
5360
options = &EnvironmentCredentialOptions{}
@@ -104,9 +111,7 @@ func NewEnvironmentCredential(options *EnvironmentCredentialOptions) (*Environme
104111
return nil, errors.New("incomplete environment variable configuration. Only AZURE_TENANT_ID and AZURE_CLIENT_ID are set")
105112
}
106113

107-
// GetToken obtains a token from Azure Active Directory. This method is called automatically by Azure SDK clients.
108-
// ctx: Context used to control the request lifetime.
109-
// opts: Options for the token request, in particular the desired scope of the access token.
114+
// GetToken requests an access token from Azure Active Directory. This method is called automatically by Azure SDK clients.
110115
func (c *EnvironmentCredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (*azcore.AccessToken, error) {
111116
return c.cred.GetToken(ctx, opts)
112117
}

‎sdk/azidentity/errors.go

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -31,11 +31,11 @@ func getResponseFromError(err error) *http.Response {
3131

3232
// AuthenticationFailedError indicates an authentication request has failed.
3333
type AuthenticationFailedError struct {
34-
credType string
35-
message string
36-
3734
// RawResponse is the HTTP response motivating the error, if available.
3835
RawResponse *http.Response
36+
37+
credType string
38+
message string
3939
}
4040

4141
func newAuthenticationFailedError(credType string, message string, resp *http.Response) AuthenticationFailedError {
@@ -47,8 +47,7 @@ func newAuthenticationFailedErrorFromMSALError(credType string, err error) Authe
4747
return newAuthenticationFailedError(credType, err.Error(), res)
4848
}
4949

50-
// Error implements the error interface for type ResponseError.
51-
// Note that the message contents are not contractual and can change over time.
50+
// Error implements the error interface. Note that the message contents are not contractual and can change over time.
5251
func (e AuthenticationFailedError) Error() string {
5352
if e.RawResponse == nil {
5453
return e.credType + ": " + e.message
@@ -76,7 +75,7 @@ func (e AuthenticationFailedError) Error() string {
7675
return msg.String()
7776
}
7877

79-
// NonRetriable indicates that this error should not be retried.
78+
// NonRetriable indicates the request which provoked this error shouldn't be retried.
8079
func (AuthenticationFailedError) NonRetriable() {
8180
// marker method
8281
}

‎sdk/azidentity/interactive_browser_credential.go

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -46,8 +46,7 @@ type InteractiveBrowserCredential struct {
4646
account public.Account
4747
}
4848

49-
// NewInteractiveBrowserCredential constructs a new InteractiveBrowserCredential.
50-
// options: Optional configuration. Pass nil to accept default settings.
49+
// NewInteractiveBrowserCredential constructs a new InteractiveBrowserCredential. Pass nil to accept default options.
5150
func NewInteractiveBrowserCredential(options *InteractiveBrowserCredentialOptions) (*InteractiveBrowserCredential, error) {
5251
cp := InteractiveBrowserCredentialOptions{}
5352
if options != nil {
@@ -71,9 +70,7 @@ func NewInteractiveBrowserCredential(options *InteractiveBrowserCredentialOption
7170
return &InteractiveBrowserCredential{options: cp, client: c}, nil
7271
}
7372

74-
// GetToken obtains a token from Azure Active Directory. This method is called automatically by Azure SDK clients.
75-
// ctx: Context used to control the request lifetime.
76-
// opts: Options for the token request, in particular the desired scope of the access token.
73+
// GetToken requests an access token from Azure Active Directory. This method is called automatically by Azure SDK clients.
7774
func (c *InteractiveBrowserCredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (*azcore.AccessToken, error) {
7875
if len(opts.Scopes) == 0 {
7976
return nil, errors.New(credNameBrowser + ": GetToken() requires at least one scope")

0 commit comments

Comments
 (0)