adal

package module
v0.9.24 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 30, 2024 License: Apache-2.0 Imports: 28 Imported by: 1,545

README

NOTE: This module will go out of support by March 31, 2023. For authenticating with Azure AD, use module azidentity instead. For help migrating from adal to azidentiy please consult the migration guide. General information about the retirement of this and other legacy modules can be found here.

Azure Active Directory authentication for Go

This is a standalone package for authenticating with Azure Active Directory from other Go libraries and applications, in particular the Azure SDK for Go.

Note: Despite the package's name it is not related to other "ADAL" libraries maintained in the github.com/AzureAD org. Issues should be opened in this repo's or the SDK's issue trackers.

Install

go get -u github.com/Azure/go-autorest/autorest/adal

Usage

An Active Directory application is required in order to use this library. An application can be registered in the Azure Portal by following these guidelines or using the Azure CLI.

Register an Azure AD Application with secret

  1. Register a new application with a secret credential

    az ad app create \
   --display-name example-app \
   --homepage https://example-app/home \
   --identifier-uris https://example-app/app \
   --password secret

  2. Create a service principal using the Application ID from previous step

    az ad sp create --id "Application ID"
    • Replace Application ID with appId from step 1.
Register an Azure AD Application with certificate

  1. Create a private key

    openssl genrsa -out "example-app.key" 2048

  2. Create the certificate

    openssl req -new -key "example-app.key" -subj "/CN=example-app" -out "example-app.csr"
openssl x509 -req -in "example-app.csr" -signkey "example-app.key" -out "example-app.crt" -days 10000

  3. Create the PKCS12 version of the certificate containing also the private key

    openssl pkcs12 -export -out "example-app.pfx" -inkey "example-app.key" -in "example-app.crt" -passout pass:

  4. Register a new application with the certificate content form example-app.crt

    certificateContents="$(tail -n+2 "example-app.crt" | head -n-1)"

az ad app create \
   --display-name example-app \
   --homepage https://example-app/home \
   --identifier-uris https://example-app/app \
   --key-usage Verify --end-date 2018-01-01 \
   --key-value "${certificateContents}"

  5. Create a service principal using the Application ID from previous step

    az ad sp create --id "APPLICATION_ID"
    • Replace APPLICATION_ID with appId from step 4.
Grant the necessary permissions

Azure relies on a Role-Based Access Control (RBAC) model to manage the access to resources at a fine-grained level. There is a set of pre-defined roles which can be assigned to a service principal of an Azure AD application depending of your needs.

az role assignment create --assigner "SERVICE_PRINCIPAL_ID" --role "ROLE_NAME"
  • Replace the SERVICE_PRINCIPAL_ID with the appId from previous step.
  • Replace the ROLE_NAME with a role name of your choice.

It is also possible to define custom role definitions.

az role definition create --role-definition role-definition.json
  • Check custom roles for more details regarding the content of role-definition.json file.
Acquire Access Token

The common configuration used by all flows:

const activeDirectoryEndpoint = "https://login.microsoftonline.com/"
tenantID := "TENANT_ID"
oauthConfig, err := adal.NewOAuthConfig(activeDirectoryEndpoint, tenantID)

applicationID := "APPLICATION_ID"

callback := func(token adal.Token) error {
    // This is called after the token is acquired
}

// The resource for which the token is acquired
resource := "https://management.core.windows.net/"
  • Replace the TENANT_ID with your tenant ID.
  • Replace the APPLICATION_ID with the value from previous section.
Client Credentials
applicationSecret := "APPLICATION_SECRET"

spt, err := adal.NewServicePrincipalToken(
	*oauthConfig,
	appliationID,
	applicationSecret,
	resource,
	callbacks...)
if err != nil {
	return nil, err
}

// Acquire a new access token
err  = spt.Refresh()
if (err == nil) {
    token := spt.Token
}
  • Replace the APPLICATION_SECRET with the password value from previous section.
Client Certificate
certificatePath := "./example-app.pfx"

certData, err := os.ReadFile(certificatePath)
if err != nil {
	return nil, fmt.Errorf("failed to read the certificate file (%s): %v", certificatePath, err)
}

// Get the certificate and private key from pfx file
certificate, rsaPrivateKey, err := decodePkcs12(certData, "")
if err != nil {
	return nil, fmt.Errorf("failed to decode pkcs12 certificate while creating spt: %v", err)
}

spt, err := adal.NewServicePrincipalTokenFromCertificate(
	*oauthConfig,
	applicationID,
	certificate,
	rsaPrivateKey,
	resource,
	callbacks...)

// Acquire a new access token
err  = spt.Refresh()
if (err == nil) {
    token := spt.Token
}
  • Update the certificate path to point to the example-app.pfx file which was created in previous section.
Device Code
oauthClient := &http.Client{}

// Acquire the device code
deviceCode, err := adal.InitiateDeviceAuth(
	oauthClient,
	*oauthConfig,
	applicationID,
	resource)
if err != nil {
	return nil, fmt.Errorf("Failed to start device auth flow: %s", err)
}

// Display the authentication message
fmt.Println(*deviceCode.Message)

// Wait here until the user is authenticated
token, err := adal.WaitForUserCompletion(oauthClient, deviceCode)
if err != nil {
	return nil, fmt.Errorf("Failed to finish device auth flow: %s", err)
}

spt, err := adal.NewServicePrincipalTokenFromManualToken(
	*oauthConfig,
	applicationID,
	resource,
	*token,
	callbacks...)

if (err == nil) {
    token := spt.Token
}
Username password authenticate
spt, err := adal.NewServicePrincipalTokenFromUsernamePassword(
	*oauthConfig,
	applicationID,
	username,
	password,
	resource,
	callbacks...)

if (err == nil) {
    token := spt.Token
}
Authorization code authenticate
spt, err := adal.NewServicePrincipalTokenFromAuthorizationCode(
	*oauthConfig,
	applicationID,
	clientSecret,
        authorizationCode,
        redirectURI,
	resource,
	callbacks...)

err  = spt.Refresh()
if (err == nil) {
    token := spt.Token
}
Command Line Tool

A command line tool is available in cmd/adal.go that can acquire a token for a given resource. It supports all flows mentioned above.

adal -h

Usage of ./adal:
  -applicationId string
        application id
  -certificatePath string
        path to pk12/PFC application certificate
  -mode string
        authentication mode (device, secret, cert, refresh) (default "device")
  -resource string
        resource for which the token is requested
  -secret string
        application secret
  -tenantId string
        tenant id
  -tokenCachePath string
        location of oath token cache (default "/home/cgc/.adal/accessToken.json")

Example acquire a token for https://management.core.windows.net/ using device code flow:

adal -mode device \
    -applicationId "APPLICATION_ID" \
    -tenantId "TENANT_ID" \
    -resource https://management.core.windows.net/

Documentation

Index

Constants

View Source 
const (

	// OAuthGrantTypeDeviceCode is the "grant_type" identifier used in device flow
	OAuthGrantTypeDeviceCode = "device_code"

	// OAuthGrantTypeClientCredentials is the "grant_type" identifier used in credential flows
	OAuthGrantTypeClientCredentials = "client_credentials"

	// OAuthGrantTypeUserPass is the "grant_type" identifier used in username and password auth flows
	OAuthGrantTypeUserPass = "password"

	// OAuthGrantTypeRefreshToken is the "grant_type" identifier used in refresh token flows
	OAuthGrantTypeRefreshToken = "refresh_token"

	// OAuthGrantTypeAuthorizationCode is the "grant_type" identifier used in authorization code flows
	OAuthGrantTypeAuthorizationCode = "authorization_code"
)

Variables

View Source 
var (
	// ErrDeviceGeneric represents an unknown error from the token endpoint when using device flow
	ErrDeviceGeneric = fmt.Errorf("%s Error while retrieving OAuth token: Unknown Error", logPrefix)

	// ErrDeviceAccessDenied represents an access denied error from the token endpoint when using device flow
	ErrDeviceAccessDenied = fmt.Errorf("%s Error while retrieving OAuth token: Access Denied", logPrefix)

	// ErrDeviceAuthorizationPending represents the server waiting on the user to complete the device flow
	ErrDeviceAuthorizationPending = fmt.Errorf("%s Error while retrieving OAuth token: Authorization Pending", logPrefix)

	// ErrDeviceCodeExpired represents the server timing out and expiring the code during device flow
	ErrDeviceCodeExpired = fmt.Errorf("%s Error while retrieving OAuth token: Code Expired", logPrefix)

	// ErrDeviceSlowDown represents the service telling us we're polling too often during device flow
	ErrDeviceSlowDown = fmt.Errorf("%s Error while retrieving OAuth token: Slow Down", logPrefix)

	// ErrDeviceCodeEmpty represents an empty device code from the device endpoint while using device flow
	ErrDeviceCodeEmpty = fmt.Errorf("%s Error while retrieving device code: Device Code Empty", logPrefix)

	// ErrOAuthTokenEmpty represents an empty OAuth token from the token endpoint when using device flow
	ErrOAuthTokenEmpty = fmt.Errorf("%s Error while retrieving OAuth token: Token Empty", logPrefix)
)
View Source 
var (
	// ErrMissingCertificate is returned when no local certificate is found in the provided PFX data.
	ErrMissingCertificate = errors.New("adal: certificate missing")

	// ErrMissingPrivateKey is returned when no private key is found in the provided PFX data.
	ErrMissingPrivateKey = errors.New("adal: private key missing")
)

Functions

func AddToUserAgent 

func AddToUserAgent(extension string) error

AddToUserAgent adds an extension to the current user agent

func DecodePfxCertificateData added in v0.9.2 

func DecodePfxCertificateData(pfxData []byte, password string) (*x509.Certificate, *rsa.PrivateKey, error)

DecodePfxCertificateData extracts the x509 certificate and RSA private key from the provided PFX data. The PFX data must contain a private key along with a certificate whose public key matches that of the private key or an error is returned. If the private key is not password protected pass the empty string for password.

func GetMSIAppServiceEndpoint added in v0.7.0 

func GetMSIAppServiceEndpoint() (string, error)

GetMSIAppServiceEndpoint get the MSI endpoint for App Service and Functions. It will return an error when not running in an app service/functions environment. Deprecated: NewServicePrincipalTokenFromMSI() and variants will automatically detect the endpoint.

func GetMSIEndpoint added in v0.7.0 

func GetMSIEndpoint() (string, error)

GetMSIEndpoint get the appropriate MSI endpoint depending on the runtime environment Deprecated: NewServicePrincipalTokenFromMSI() and variants will automatically detect the endpoint.

func GetMSIVMEndpoint 

func GetMSIVMEndpoint() (string, error)

GetMSIVMEndpoint gets the MSI endpoint on Virtual Machines. NOTE: this always returns the IMDS endpoint, it does not work for app services or cloud shell. Deprecated: NewServicePrincipalTokenFromMSI() and variants will automatically detect the endpoint.

func MSIAvailable added in v0.9.2 

func MSIAvailable(ctx context.Context, s Sender) bool

MSIAvailable returns true if the MSI endpoint is available for authentication.

func SaveToken 

func SaveToken(path string, mode os.FileMode, token Token) error

SaveToken persists an oauth token at the given location on disk. It moves the new file into place so it can safely be used to replace an existing file that maybe accessed by multiple processes.

func UserAgent 

func UserAgent() string

UserAgent returns a string containing the Go version, system architecture and OS, and the adal version.

Types

type DeviceCode 

type DeviceCode struct {
	DeviceCode      *string `json:"device_code,omitempty"`
	UserCode        *string `json:"user_code,omitempty"`
	VerificationURL *string `json:"verification_url,omitempty"`
	ExpiresIn       *int64  `json:"expires_in,string,omitempty"`
	Interval        *int64  `json:"interval,string,omitempty"`

	Message     *string `json:"message"` // Azure specific
	Resource    string  // store the following, stored when initiating, used when exchanging
	OAuthConfig OAuthConfig
	ClientID    string
}

DeviceCode is the object returned by the device auth endpoint It contains information to instruct the user to complete the auth flow

func InitiateDeviceAuth 

func InitiateDeviceAuth(sender Sender, oauthConfig OAuthConfig, clientID, resource string) (*DeviceCode, error)

InitiateDeviceAuth initiates a device auth flow. It returns a DeviceCode that can be used with CheckForUserCompletion or WaitForUserCompletion. Deprecated: use InitiateDeviceAuthWithContext() instead.

func InitiateDeviceAuthWithContext added in v0.8.0 

func InitiateDeviceAuthWithContext(ctx context.Context, sender Sender, oauthConfig OAuthConfig, clientID, resource string) (*DeviceCode, error)

InitiateDeviceAuthWithContext initiates a device auth flow. It returns a DeviceCode that can be used with CheckForUserCompletion or WaitForUserCompletion.

type JWTCallback added in v0.9.23 

type JWTCallback func() (string, error)

JWTCallback is the type representing callback that will be called to get the federated OIDC JWT

type ManagedIdentityOptions added in v0.9.11 

type ManagedIdentityOptions struct {
	// ClientID is the user-assigned identity to use during authentication.
	// It is mutually exclusive with IdentityResourceID.
	ClientID string

	// IdentityResourceID is the resource ID of the user-assigned identity to use during authentication.
	// It is mutually exclusive with ClientID.
	IdentityResourceID string
}

ManagedIdentityOptions contains optional values for configuring managed identity authentication.

type MultiTenantOAuthConfig added in v0.2.0 

type MultiTenantOAuthConfig interface {
	PrimaryTenant() *OAuthConfig
	AuxiliaryTenants() []*OAuthConfig
}

MultiTenantOAuthConfig provides endpoints for primary and aulixiary tenant IDs.

func NewMultiTenantOAuthConfig added in v0.2.0 

func NewMultiTenantOAuthConfig(activeDirectoryEndpoint, primaryTenantID string, auxiliaryTenantIDs []string, options OAuthOptions) (MultiTenantOAuthConfig, error)

NewMultiTenantOAuthConfig creates an object that support multitenant OAuth configuration. See https://docs.microsoft.com/en-us/azure/azure-resource-manager/authenticate-multi-tenant for more information.

type MultiTenantServicePrincipalToken added in v0.2.0 

type MultiTenantServicePrincipalToken struct {
	PrimaryToken    *ServicePrincipalToken
	AuxiliaryTokens []*ServicePrincipalToken
}

MultiTenantServicePrincipalToken contains tokens for multi-tenant authorization.

func NewMultiTenantServicePrincipalToken added in v0.2.0 

func NewMultiTenantServicePrincipalToken(multiTenantCfg MultiTenantOAuthConfig, clientID string, secret string, resource string) (*MultiTenantServicePrincipalToken, error)

NewMultiTenantServicePrincipalToken creates a new MultiTenantServicePrincipalToken with the specified credentials and resource.

func NewMultiTenantServicePrincipalTokenFromCertificate added in v0.9.8 

func NewMultiTenantServicePrincipalTokenFromCertificate(multiTenantCfg MultiTenantOAuthConfig, clientID string, certificate *x509.Certificate, privateKey *rsa.PrivateKey, resource string) (*MultiTenantServicePrincipalToken, error)

NewMultiTenantServicePrincipalTokenFromCertificate creates a new MultiTenantServicePrincipalToken with the specified certificate credentials and resource.

func (*MultiTenantServicePrincipalToken) AuxiliaryOAuthTokens added in v0.2.0 

func (mt *MultiTenantServicePrincipalToken) AuxiliaryOAuthTokens() []string

AuxiliaryOAuthTokens returns one to three auxiliary authorization tokens.

func (*MultiTenantServicePrincipalToken) EnsureFreshWithContext added in v0.2.0 

func (mt *MultiTenantServicePrincipalToken) EnsureFreshWithContext(ctx context.Context) error

EnsureFreshWithContext will refresh the token if it will expire within the refresh window (as set by RefreshWithin) and autoRefresh flag is on. This method is safe for concurrent use.

func (*MultiTenantServicePrincipalToken) PrimaryOAuthToken added in v0.2.0 

func (mt *MultiTenantServicePrincipalToken) PrimaryOAuthToken() string

PrimaryOAuthToken returns the primary authorization token.

func (*MultiTenantServicePrincipalToken) RefreshExchangeWithContext added in v0.5.0 

func (mt *MultiTenantServicePrincipalToken) RefreshExchangeWithContext(ctx context.Context, resource string) error

RefreshExchangeWithContext refreshes the token, but for a different resource.

func (*MultiTenantServicePrincipalToken) RefreshWithContext added in v0.5.0 

func (mt *MultiTenantServicePrincipalToken) RefreshWithContext(ctx context.Context) error

RefreshWithContext obtains a fresh token for the Service Principal.

type MultitenantOAuthTokenProvider added in v0.2.0 

type MultitenantOAuthTokenProvider interface {
	PrimaryOAuthToken() string
	AuxiliaryOAuthTokens() []string
}

MultitenantOAuthTokenProvider provides tokens used for multi-tenant authorization.

type OAuthConfig 

type OAuthConfig struct {
	AuthorityEndpoint  url.URL `json:"authorityEndpoint"`
	AuthorizeEndpoint  url.URL `json:"authorizeEndpoint"`
	TokenEndpoint      url.URL `json:"tokenEndpoint"`
	DeviceCodeEndpoint url.URL `json:"deviceCodeEndpoint"`
}

OAuthConfig represents the endpoints needed in OAuth operations

func NewOAuthConfig 

func NewOAuthConfig(activeDirectoryEndpoint, tenantID string) (*OAuthConfig, error)

NewOAuthConfig returns an OAuthConfig with tenant specific urls

func NewOAuthConfigWithAPIVersion 

func NewOAuthConfigWithAPIVersion(activeDirectoryEndpoint, tenantID string, apiVersion *string) (*OAuthConfig, error)

NewOAuthConfigWithAPIVersion returns an OAuthConfig with tenant specific urls. If apiVersion is not nil the "api-version" query parameter will be appended to the endpoint URLs with the specified value.

func (OAuthConfig) IsZero 

func (oac OAuthConfig) IsZero() bool

IsZero returns true if the OAuthConfig object is zero-initialized.

type OAuthOptions added in v0.2.0 

type OAuthOptions struct {
	APIVersion string
}

OAuthOptions contains optional OAuthConfig creation arguments.

type OAuthTokenProvider 

type OAuthTokenProvider interface {
	OAuthToken() string
}

OAuthTokenProvider is an interface which should be implemented by an access token retriever

type Refresher 

type Refresher interface {
	Refresh() error
	RefreshExchange(resource string) error
	EnsureFresh() error
}

Refresher is an interface for token refresh functionality

type RefresherWithContext 

type RefresherWithContext interface {
	RefreshWithContext(ctx context.Context) error
	RefreshExchangeWithContext(ctx context.Context, resource string) error
	EnsureFreshWithContext(ctx context.Context) error
}

RefresherWithContext is an interface for token refresh functionality

type SendDecorator 

type SendDecorator func(Sender) Sender

SendDecorator takes and possibly decorates, by wrapping, a Sender. Decorators may affect the http.Request and pass it along or, first, pass the http.Request along then react to the http.Response result.

type Sender 

type Sender interface {
	Do(*http.Request) (*http.Response, error)
}

Sender is the interface that wraps the Do method to send HTTP requests.

The standard http.Client conforms to this interface.

func CreateSender 

func CreateSender(decorators ...SendDecorator) Sender

CreateSender creates, decorates, and returns, as a Sender, the default http.Client.

func DecorateSender 

func DecorateSender(s Sender, decorators ...SendDecorator) Sender

DecorateSender accepts a Sender and a, possibly empty, set of SendDecorators, which is applies to the Sender. Decorators are applied in the order received, but their affect upon the request depends on whether they are a pre-decorator (change the http.Request and then pass it along) or a post-decorator (pass the http.Request along and react to the results in http.Response).

type SenderFunc 

type SenderFunc func(*http.Request) (*http.Response, error)

SenderFunc is a method that implements the Sender interface.

func (SenderFunc) Do 

func (sf SenderFunc) Do(r *http.Request) (*http.Response, error)

Do implements the Sender interface on SenderFunc.

type ServicePrincipalAuthorizationCodeSecret 

type ServicePrincipalAuthorizationCodeSecret struct {
	ClientSecret      string `json:"value"`
	AuthorizationCode string `json:"authCode"`
	RedirectURI       string `json:"redirect"`
}

ServicePrincipalAuthorizationCodeSecret implements ServicePrincipalSecret for authorization code auth.

func (ServicePrincipalAuthorizationCodeSecret) MarshalJSON 

func (secret ServicePrincipalAuthorizationCodeSecret) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (*ServicePrincipalAuthorizationCodeSecret) SetAuthenticationValues 

func (secret *ServicePrincipalAuthorizationCodeSecret) SetAuthenticationValues(spt *ServicePrincipalToken, v *url.Values) error

SetAuthenticationValues is a method of the interface ServicePrincipalSecret.

type ServicePrincipalCertificateSecret 

type ServicePrincipalCertificateSecret struct {
	Certificate *x509.Certificate
	PrivateKey  *rsa.PrivateKey
}

ServicePrincipalCertificateSecret implements ServicePrincipalSecret for generic RSA cert auth with signed JWTs.

func (ServicePrincipalCertificateSecret) MarshalJSON 

func (secret ServicePrincipalCertificateSecret) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (*ServicePrincipalCertificateSecret) SetAuthenticationValues 

func (secret *ServicePrincipalCertificateSecret) SetAuthenticationValues(spt *ServicePrincipalToken, v *url.Values) error

SetAuthenticationValues is a method of the interface ServicePrincipalSecret. It will populate the form submitted during oAuth Token Acquisition using a JWT signed with a certificate.

func (*ServicePrincipalCertificateSecret) SignJwt 

func (secret *ServicePrincipalCertificateSecret) SignJwt(spt *ServicePrincipalToken) (string, error)

SignJwt returns the JWT signed with the certificate's private key.

type ServicePrincipalFederatedSecret added in v0.9.19 

type ServicePrincipalFederatedSecret struct {
	// contains filtered or unexported fields
}

ServicePrincipalFederatedSecret implements ServicePrincipalSecret for Federated JWTs.

func (ServicePrincipalFederatedSecret) MarshalJSON added in v0.9.19 

func (secret ServicePrincipalFederatedSecret) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (*ServicePrincipalFederatedSecret) SetAuthenticationValues added in v0.9.19 

func (secret *ServicePrincipalFederatedSecret) SetAuthenticationValues(_ *ServicePrincipalToken, v *url.Values) error

SetAuthenticationValues is a method of the interface ServicePrincipalSecret. It will populate the form submitted during OAuth Token Acquisition using a JWT signed by an OIDC issuer.

type ServicePrincipalMSISecret 

type ServicePrincipalMSISecret struct {
	// contains filtered or unexported fields
}

ServicePrincipalMSISecret implements ServicePrincipalSecret for machines running the MSI Extension.

func (ServicePrincipalMSISecret) MarshalJSON 

func (msiSecret ServicePrincipalMSISecret) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (*ServicePrincipalMSISecret) SetAuthenticationValues 

func (msiSecret *ServicePrincipalMSISecret) SetAuthenticationValues(spt *ServicePrincipalToken, v *url.Values) error

SetAuthenticationValues is a method of the interface ServicePrincipalSecret.

type ServicePrincipalNoSecret 

type ServicePrincipalNoSecret struct {
}

ServicePrincipalNoSecret represents a secret type that contains no secret meaning it is not valid for fetching a fresh token. This is used by Manual

func (ServicePrincipalNoSecret) MarshalJSON 

func (noSecret ServicePrincipalNoSecret) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (*ServicePrincipalNoSecret) SetAuthenticationValues 

func (noSecret *ServicePrincipalNoSecret) SetAuthenticationValues(spt *ServicePrincipalToken, v *url.Values) error

SetAuthenticationValues is a method of the interface ServicePrincipalSecret It only returns an error for the ServicePrincipalNoSecret type

type ServicePrincipalSecret 

type ServicePrincipalSecret interface {
	SetAuthenticationValues(spt *ServicePrincipalToken, values *url.Values) error
}

ServicePrincipalSecret is an interface that allows various secret mechanism to fill the form that is submitted when acquiring an oAuth token.

type ServicePrincipalToken 

type ServicePrincipalToken struct {

	// MaxMSIRefreshAttempts is the maximum number of attempts to refresh an MSI token.
	// Settings this to a value less than 1 will use the default value.
	MaxMSIRefreshAttempts int
	// contains filtered or unexported fields
}

ServicePrincipalToken encapsulates a Token created for a Service Principal.

func NewServicePrincipalToken 

func NewServicePrincipalToken(oauthConfig OAuthConfig, clientID string, secret string, resource string, callbacks ...TokenRefreshCallback) (*ServicePrincipalToken, error)

NewServicePrincipalToken creates a ServicePrincipalToken from the supplied Service Principal credentials scoped to the named resource.

func NewServicePrincipalTokenFromAuthorizationCode 

func NewServicePrincipalTokenFromAuthorizationCode(oauthConfig OAuthConfig, clientID string, clientSecret string, authorizationCode string, redirectURI string, resource string, callbacks ...TokenRefreshCallback) (*ServicePrincipalToken, error)

NewServicePrincipalTokenFromAuthorizationCode creates a ServicePrincipalToken from the

func NewServicePrincipalTokenFromCertificate 

func NewServicePrincipalTokenFromCertificate(oauthConfig OAuthConfig, clientID string, certificate *x509.Certificate, privateKey *rsa.PrivateKey, resource string, callbacks ...TokenRefreshCallback) (*ServicePrincipalToken, error)

NewServicePrincipalTokenFromCertificate creates a ServicePrincipalToken from the supplied pkcs12 bytes.

func NewServicePrincipalTokenFromFederatedToken deprecated added in v0.9.19 

func NewServicePrincipalTokenFromFederatedToken(oauthConfig OAuthConfig, clientID string, jwt string, resource string, callbacks ...TokenRefreshCallback) (*ServicePrincipalToken, error)

NewServicePrincipalTokenFromFederatedToken creates a ServicePrincipalToken from the supplied federated OIDC JWT.

Deprecated: Use NewServicePrincipalTokenFromFederatedTokenWithCallback to refresh jwt dynamically.

func NewServicePrincipalTokenFromFederatedTokenCallback added in v0.9.23 

func NewServicePrincipalTokenFromFederatedTokenCallback(oauthConfig OAuthConfig, clientID string, jwtCallback JWTCallback, resource string, callbacks ...TokenRefreshCallback) (*ServicePrincipalToken, error)

NewServicePrincipalTokenFromFederatedTokenCallback creates a ServicePrincipalToken from the supplied federated OIDC JWTCallback.

func NewServicePrincipalTokenFromMSI 

func NewServicePrincipalTokenFromMSI(msiEndpoint, resource string, callbacks ...TokenRefreshCallback) (*ServicePrincipalToken, error)

NewServicePrincipalTokenFromMSI creates a ServicePrincipalToken via the MSI VM Extension. It will use the system assigned identity when creating the token. msiEndpoint - empty string, or pass a non-empty string to override the default value. Deprecated: use NewServicePrincipalTokenFromManagedIdentity() instead.

func NewServicePrincipalTokenFromMSIWithIdentityResourceID added in v0.9.1 

func NewServicePrincipalTokenFromMSIWithIdentityResourceID(msiEndpoint, resource string, identityResourceID string, callbacks ...TokenRefreshCallback) (*ServicePrincipalToken, error)

NewServicePrincipalTokenFromMSIWithIdentityResourceID creates a ServicePrincipalToken via the MSI VM Extension. It will use the azure resource id of user assigned identity when creating the token. msiEndpoint - empty string, or pass a non-empty string to override the default value. Deprecated: use NewServicePrincipalTokenFromManagedIdentity() instead.

func NewServicePrincipalTokenFromMSIWithUserAssignedID 

func NewServicePrincipalTokenFromMSIWithUserAssignedID(msiEndpoint, resource string, userAssignedID string, callbacks ...TokenRefreshCallback) (*ServicePrincipalToken, error)

NewServicePrincipalTokenFromMSIWithUserAssignedID creates a ServicePrincipalToken via the MSI VM Extension. It will use the clientID of specified user assigned identity when creating the token. msiEndpoint - empty string, or pass a non-empty string to override the default value. Deprecated: use NewServicePrincipalTokenFromManagedIdentity() instead.

func NewServicePrincipalTokenFromManagedIdentity added in v0.9.11 

func NewServicePrincipalTokenFromManagedIdentity(resource string, options *ManagedIdentityOptions, callbacks ...TokenRefreshCallback) (*ServicePrincipalToken, error)

NewServicePrincipalTokenFromManagedIdentity creates a ServicePrincipalToken using a managed identity. It supports the following managed identity environments. - App Service Environment (API version 2017-09-01 only) - Cloud shell - IMDS with a system or user assigned identity

func NewServicePrincipalTokenFromManualToken 

func NewServicePrincipalTokenFromManualToken(oauthConfig OAuthConfig, clientID string, resource string, token Token, callbacks ...TokenRefreshCallback) (*ServicePrincipalToken, error)

NewServicePrincipalTokenFromManualToken creates a ServicePrincipalToken using the supplied token

func NewServicePrincipalTokenFromManualTokenSecret 

func NewServicePrincipalTokenFromManualTokenSecret(oauthConfig OAuthConfig, clientID string, resource string, token Token, secret ServicePrincipalSecret, callbacks ...TokenRefreshCallback) (*ServicePrincipalToken, error)

NewServicePrincipalTokenFromManualTokenSecret creates a ServicePrincipalToken using the supplied token and secret

func NewServicePrincipalTokenFromUsernamePassword 

func NewServicePrincipalTokenFromUsernamePassword(oauthConfig OAuthConfig, clientID string, username string, password string, resource string, callbacks ...TokenRefreshCallback) (*ServicePrincipalToken, error)

NewServicePrincipalTokenFromUsernamePassword creates a ServicePrincipalToken from the username and password.

func NewServicePrincipalTokenWithSecret 

func NewServicePrincipalTokenWithSecret(oauthConfig OAuthConfig, id string, resource string, secret ServicePrincipalSecret, callbacks ...TokenRefreshCallback) (*ServicePrincipalToken, error)

NewServicePrincipalTokenWithSecret create a ServicePrincipalToken using the supplied ServicePrincipalSecret implementation.

func (*ServicePrincipalToken) EnsureFresh 

func (spt *ServicePrincipalToken) EnsureFresh() error

EnsureFresh will refresh the token if it will expire within the refresh window (as set by RefreshWithin) and autoRefresh flag is on. This method is safe for concurrent use.

func (*ServicePrincipalToken) EnsureFreshWithContext 

func (spt *ServicePrincipalToken) EnsureFreshWithContext(ctx context.Context) error

EnsureFreshWithContext will refresh the token if it will expire within the refresh window (as set by RefreshWithin) and autoRefresh flag is on. This method is safe for concurrent use.

func (*ServicePrincipalToken) InvokeRefreshCallbacks 

func (spt *ServicePrincipalToken) InvokeRefreshCallbacks(token Token) error

InvokeRefreshCallbacks calls any TokenRefreshCallbacks that were added to the SPT during initialization

func (ServicePrincipalToken) MarshalJSON 

func (spt ServicePrincipalToken) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (ServicePrincipalToken) MarshalTokenJSON 

func (spt ServicePrincipalToken) MarshalTokenJSON() ([]byte, error)

MarshalTokenJSON returns the marshalled inner token.

func (*ServicePrincipalToken) OAuthToken 

func (spt *ServicePrincipalToken) OAuthToken() string

OAuthToken implements the OAuthTokenProvider interface. It returns the current access token.

func (*ServicePrincipalToken) Refresh 

func (spt *ServicePrincipalToken) Refresh() error

Refresh obtains a fresh token for the Service Principal. This method is safe for concurrent use.

func (*ServicePrincipalToken) RefreshExchange 

func (spt *ServicePrincipalToken) RefreshExchange(resource string) error

RefreshExchange refreshes the token, but for a different resource. This method is safe for concurrent use.

func (*ServicePrincipalToken) RefreshExchangeWithContext 

func (spt *ServicePrincipalToken) RefreshExchangeWithContext(ctx context.Context, resource string) error

RefreshExchangeWithContext refreshes the token, but for a different resource. This method is safe for concurrent use.

func (*ServicePrincipalToken) RefreshWithContext 

func (spt *ServicePrincipalToken) RefreshWithContext(ctx context.Context) error

RefreshWithContext obtains a fresh token for the Service Principal. This method is safe for concurrent use.

func (*ServicePrincipalToken) SetAutoRefresh 

func (spt *ServicePrincipalToken) SetAutoRefresh(autoRefresh bool)

SetAutoRefresh enables or disables automatic refreshing of stale tokens.

func (*ServicePrincipalToken) SetCustomRefreshFunc added in v0.8.1 

func (spt *ServicePrincipalToken) SetCustomRefreshFunc(customRefreshFunc TokenRefresh)

SetCustomRefreshFunc sets a custom refresh function used to refresh the token.

func (*ServicePrincipalToken) SetRefreshCallbacks 

func (spt *ServicePrincipalToken) SetRefreshCallbacks(callbacks []TokenRefreshCallback)

SetRefreshCallbacks replaces any existing refresh callbacks with the specified callbacks.

func (*ServicePrincipalToken) SetRefreshWithin 

func (spt *ServicePrincipalToken) SetRefreshWithin(d time.Duration)

SetRefreshWithin sets the interval within which if the token will expire, EnsureFresh will refresh the token.

func (*ServicePrincipalToken) SetSender 

func (spt *ServicePrincipalToken) SetSender(s Sender)

SetSender sets the http.Client used when obtaining the Service Principal token. An undecorated http.Client is used by default.

func (*ServicePrincipalToken) Token 

func (spt *ServicePrincipalToken) Token() Token

Token returns a copy of the current token.

func (*ServicePrincipalToken) UnmarshalJSON 

func (spt *ServicePrincipalToken) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface.

type ServicePrincipalTokenSecret 

type ServicePrincipalTokenSecret struct {
	ClientSecret string `json:"value"`
}

ServicePrincipalTokenSecret implements ServicePrincipalSecret for client_secret type authorization.

func (ServicePrincipalTokenSecret) MarshalJSON 

func (tokenSecret ServicePrincipalTokenSecret) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (*ServicePrincipalTokenSecret) SetAuthenticationValues 

func (tokenSecret *ServicePrincipalTokenSecret) SetAuthenticationValues(spt *ServicePrincipalToken, v *url.Values) error

SetAuthenticationValues is a method of the interface ServicePrincipalSecret. It will populate the form submitted during oAuth Token Acquisition using the client_secret.

type ServicePrincipalUsernamePasswordSecret 

type ServicePrincipalUsernamePasswordSecret struct {
	Username string `json:"username"`
	Password string `json:"password"`
}

ServicePrincipalUsernamePasswordSecret implements ServicePrincipalSecret for username and password auth.

func (ServicePrincipalUsernamePasswordSecret) MarshalJSON 

func (secret ServicePrincipalUsernamePasswordSecret) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (*ServicePrincipalUsernamePasswordSecret) SetAuthenticationValues 

func (secret *ServicePrincipalUsernamePasswordSecret) SetAuthenticationValues(spt *ServicePrincipalToken, v *url.Values) error

SetAuthenticationValues is a method of the interface ServicePrincipalSecret.

type Token 

type Token struct {
	AccessToken  string `json:"access_token"`
	RefreshToken string `json:"refresh_token"`

	ExpiresIn json.Number `json:"expires_in"`
	ExpiresOn json.Number `json:"expires_on"`
	NotBefore json.Number `json:"not_before"`

	Resource string `json:"resource"`
	Type     string `json:"token_type"`
}

Token encapsulates the access token used to authorize Azure requests. https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-oauth2-client-creds-grant-flow#service-to-service-access-token-response

func CheckForUserCompletion 

func CheckForUserCompletion(sender Sender, code *DeviceCode) (*Token, error)

CheckForUserCompletion takes a DeviceCode and checks with the Azure AD OAuth endpoint to see if the device flow has: been completed, timed out, or otherwise failed Deprecated: use CheckForUserCompletionWithContext() instead.

func CheckForUserCompletionWithContext added in v0.8.0 

func CheckForUserCompletionWithContext(ctx context.Context, sender Sender, code *DeviceCode) (*Token, error)

CheckForUserCompletionWithContext takes a DeviceCode and checks with the Azure AD OAuth endpoint to see if the device flow has: been completed, timed out, or otherwise failed

func LoadToken 

func LoadToken(path string) (*Token, error)

LoadToken restores a Token object from a file located at 'path'.

func WaitForUserCompletion 

func WaitForUserCompletion(sender Sender, code *DeviceCode) (*Token, error)

WaitForUserCompletion calls CheckForUserCompletion repeatedly until a token is granted or an error state occurs. This prevents the user from looping and checking against 'ErrDeviceAuthorizationPending'. Deprecated: use WaitForUserCompletionWithContext() instead.

func WaitForUserCompletionWithContext added in v0.8.0 

func WaitForUserCompletionWithContext(ctx context.Context, sender Sender, code *DeviceCode) (*Token, error)

WaitForUserCompletionWithContext calls CheckForUserCompletion repeatedly until a token is granted or an error state occurs. This prevents the user from looping and checking against 'ErrDeviceAuthorizationPending'.

func (Token) Expires 

func (t Token) Expires() time.Time

Expires returns the time.Time when the Token expires.

func (Token) IsExpired 

func (t Token) IsExpired() bool

IsExpired returns true if the Token is expired, false otherwise.

func (Token) IsZero 

func (t Token) IsZero() bool

IsZero returns true if the token object is zero-initialized.

func (*Token) OAuthToken 

func (t *Token) OAuthToken() string

OAuthToken return the current access token

func (Token) WillExpireIn 

func (t Token) WillExpireIn(d time.Duration) bool

WillExpireIn returns true if the Token will expire after the passed time.Duration interval from now, false otherwise.

type TokenError 

type TokenError struct {
	Error            *string `json:"error,omitempty"`
	ErrorCodes       []int   `json:"error_codes,omitempty"`
	ErrorDescription *string `json:"error_description,omitempty"`
	Timestamp        *string `json:"timestamp,omitempty"`
	TraceID          *string `json:"trace_id,omitempty"`
}

TokenError is the object returned by the token exchange endpoint when something is amiss

type TokenRefresh added in v0.8.1 

type TokenRefresh func(ctx context.Context, resource string) (*Token, error)

TokenRefresh is a type representing a custom callback to refresh a token

type TokenRefreshCallback 

type TokenRefreshCallback func(Token) error

TokenRefreshCallback is the type representing callbacks that will be called after a successful token refresh

type TokenRefreshError 

type TokenRefreshError interface {
	error
	Response() *http.Response
}

TokenRefreshError is an interface used by errors returned during token refresh.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.