package confidential

import "github.com/AzureAD/microsoft-authentication-library-for-go/apps/confidential"

Package confidential provides a client for authentication of "confidential" applications. A "confidential" application is defined as an app that run on servers. They are considered difficult to access and for that reason capable of keeping an application secret. Confidential clients can hold configuration-time secrets.

Example

This example demonstrates the general pattern for authenticating with MSAL Go:

  • create a client (only necessary at application start--it's best to reuse client instances)
  • call AcquireTokenSilent() to search for a cached access token
  • if the cache misses, acquire a new token

Code:play  

package main

import (
	"context"

	"github.com/AzureAD/microsoft-authentication-library-for-go/apps/confidential"
)

func main() {
	cred, err := confidential.NewCredFromSecret("client_secret")
	if err != nil {
		// TODO: handle error
	}
	client, err := confidential.New("https://login.microsoftonline.com/your_tenant", "client_id", cred)
	if err != nil {
		// TODO: handle error
	}

	scopes := []string{"scope"}
	result, err := client.AcquireTokenSilent(context.TODO(), scopes)
	if err != nil {
		// cache miss, authenticate with another AcquireToken* method
		result, err = client.AcquireTokenByCredential(context.TODO(), scopes)
		if err != nil {
			// TODO: handle error
		}
	}

	// TODO: use access token
	_ = result.AccessToken
}

Index

Examples

Constants 

const (
	TokenSourceIdentityProvider = base.TokenSourceIdentityProvider
	TokenSourceCache            = base.TokenSourceCache
)

Functions

func AutoDetectRegion 

func AutoDetectRegion() string

AutoDetectRegion instructs MSAL Go to auto detect region for Azure regional token service.

func CertFromPEM 

func CertFromPEM(pemData []byte, password string) ([]*x509.Certificate, crypto.PrivateKey, error)

CertFromPEM converts a PEM file (.pem or .key) for use with NewCredFromCert. The file must contain the public certificate and the private key. If a PEM block is encrypted and password is not an empty string, it attempts to decrypt the PEM blocks using the password. Multiple certs are due to certificate chaining for use cases like TLS that sign from root to leaf.

func WithAuthenticationScheme 

func WithAuthenticationScheme(authnScheme AuthenticationScheme) interface {
	AcquireSilentOption
	AcquireByCredentialOption
	options.CallOption
}

WithAuthenticationScheme is an extensibility mechanism designed to be used only by Azure Arc for proof of possession access tokens.

func WithChallenge 

func WithChallenge(challenge string) interface {
	AcquireByAuthCodeOption
	options.CallOption
}

WithChallenge allows you to provide a challenge for the .AcquireTokenByAuthCode() call.

func WithClaims 

func WithClaims(claims string) interface {
	AcquireByAuthCodeOption
	AcquireByCredentialOption
	AcquireOnBehalfOfOption
	AcquireByUsernamePasswordOption
	AcquireSilentOption
	AuthCodeURLOption
	options.CallOption
}

WithClaims sets additional claims to request for the token, such as those required by conditional access policies. Use this option when Azure AD returned a claims challenge for a prior request. The argument must be decoded. This option is valid for any token acquisition method.

func WithDomainHint 

func WithDomainHint(domain string) interface {
	AuthCodeURLOption
	options.CallOption
}

WithDomainHint adds the IdP domain as domain_hint query parameter in the auth url.

func WithLoginHint 

func WithLoginHint(username string) interface {
	AuthCodeURLOption
	options.CallOption
}

WithLoginHint pre-populates the login prompt with a username.

func WithSilentAccount 

func WithSilentAccount(account Account) interface {
	AcquireSilentOption
	options.CallOption
}

WithSilentAccount uses the passed account during an AcquireTokenSilent() call.

func WithTenantID 

func WithTenantID(tenantID string) interface {
	AcquireByAuthCodeOption
	AcquireByCredentialOption
	AcquireOnBehalfOfOption
	AcquireByUsernamePasswordOption
	AcquireSilentOption
	AuthCodeURLOption
	options.CallOption
}

WithTenantID specifies a tenant for a single authentication. It may be different than the tenant set in New. This option is valid for any token acquisition method.

Types

type Account 

type Account = shared.Account

type AcquireByAuthCodeOption 

type AcquireByAuthCodeOption interface {
	// contains filtered or unexported methods
}

AcquireByAuthCodeOption is implemented by options for AcquireTokenByAuthCode

type AcquireByCredentialOption 

type AcquireByCredentialOption interface {
	// contains filtered or unexported methods
}

AcquireByCredentialOption is implemented by options for AcquireTokenByCredential

type AcquireByUsernamePasswordOption 

type AcquireByUsernamePasswordOption interface {
	// contains filtered or unexported methods
}

AcquireByUsernamePasswordOption is implemented by options for AcquireTokenByUsernamePassword

type AcquireOnBehalfOfOption 

type AcquireOnBehalfOfOption interface {
	// contains filtered or unexported methods
}

AcquireOnBehalfOfOption is implemented by options for AcquireTokenOnBehalfOf

type AcquireSilentOption 

type AcquireSilentOption interface {
	// contains filtered or unexported methods
}

AcquireSilentOption is implemented by options for AcquireTokenSilent

type AssertionRequestOptions 

type AssertionRequestOptions = exported.AssertionRequestOptions

AssertionRequestOptions has required information for client assertion claims

type AuthCodeURLOption 

type AuthCodeURLOption interface {
	// contains filtered or unexported methods
}

AuthCodeURLOption is implemented by options for AuthCodeURL

type AuthResult 

type AuthResult = base.AuthResult

AuthResult contains the results of one token acquisition operation. For details see https://aka.ms/msal-net-authenticationresult

type AuthenticationScheme 

type AuthenticationScheme = authority.AuthenticationScheme

type Client 

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

Client is a representation of authentication client for confidential applications as defined in the package doc. A new Client should be created PER SERVICE USER. For more information, visit https://docs.microsoft.com/azure/active-directory/develop/msal-client-applications

func New 

func New(authority, clientID string, cred Credential, options ...Option) (Client, error)

New is the constructor for Client. authority is the URL of a token authority such as "https://login.microsoftonline.com/<your tenant>". If the Client will connect directly to AD FS, use "adfs" for the tenant. clientID is the application's client ID (also called its "application ID").

func (Client) Account 

func (cca Client) Account(ctx context.Context, accountID string) (Account, error)

Account gets the account in the token cache with the specified homeAccountID.

func (Client) AcquireTokenByAuthCode 

func (cca Client) AcquireTokenByAuthCode(ctx context.Context, code string, redirectURI string, scopes []string, opts ...AcquireByAuthCodeOption) (AuthResult, error)

AcquireTokenByAuthCode is a request to acquire a security token from the authority, using an authorization code. The specified redirect URI must be the same URI that was used when the authorization code was requested.

Options: WithChallenge, WithClaims, WithTenantID

func (Client) AcquireTokenByCredential 

func (cca Client) AcquireTokenByCredential(ctx context.Context, scopes []string, opts ...AcquireByCredentialOption) (AuthResult, error)

AcquireTokenByCredential acquires a security token from the authority, using the client credentials grant.

Options: WithClaims, WithTenantID

func (Client) AcquireTokenByUsernamePassword 

func (cca Client) AcquireTokenByUsernamePassword(ctx context.Context, scopes []string, username, password string, opts ...AcquireByUsernamePasswordOption) (AuthResult, error)

AcquireTokenByUsernamePassword acquires a security token from the authority, via Username/Password Authentication. NOTE: this flow is NOT recommended.

Options: WithClaims, WithTenantID

func (Client) AcquireTokenOnBehalfOf 

func (cca Client) AcquireTokenOnBehalfOf(ctx context.Context, userAssertion string, scopes []string, opts ...AcquireOnBehalfOfOption) (AuthResult, error)

AcquireTokenOnBehalfOf acquires a security token for an app using middle tier apps access token. Refer https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow.

Options: WithClaims, WithTenantID

func (Client) AcquireTokenSilent 

func (cca Client) AcquireTokenSilent(ctx context.Context, scopes []string, opts ...AcquireSilentOption) (AuthResult, error)

AcquireTokenSilent acquires a token from either the cache or using a refresh token.

Options: WithClaims, WithSilentAccount, WithTenantID

func (Client) AuthCodeURL 

func (cca Client) AuthCodeURL(ctx context.Context, clientID, redirectURI string, scopes []string, opts ...AuthCodeURLOption) (string, error)

AuthCodeURL creates a URL used to acquire an authorization code. Users need to call CreateAuthorizationCodeURLParameters and pass it in.

Options: WithClaims, WithDomainHint, WithLoginHint, WithTenantID

func (Client) RemoveAccount 

func (cca Client) RemoveAccount(ctx context.Context, account Account) error

RemoveAccount signs the account out and forgets account from token cache.

type Credential 

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

Credential represents the credential used in confidential client flows.

func NewCredFromAssertionCallback 

func NewCredFromAssertionCallback(callback func(context.Context, AssertionRequestOptions) (string, error)) Credential

NewCredFromAssertionCallback creates a Credential that invokes a callback to get assertions authenticating the application. The callback must be thread safe.

func NewCredFromCert 

func NewCredFromCert(certs []*x509.Certificate, key crypto.PrivateKey) (Credential, error)

NewCredFromCert creates a Credential from a certificate or chain of certificates and an RSA private key as returned by CertFromPEM.

Example (Pem)

Code:play  

package main

import (
	"fmt"
	"log"
	"os"

	"github.com/AzureAD/microsoft-authentication-library-for-go/apps/confidential"
)

func main() {
	b, err := os.ReadFile("key.pem")
	if err != nil {
		log.Fatal(err)
	}

	// This extracts our public certificates and private key from the PEM file. If it is
	// encrypted, the second argument must be password to decode.
	certs, priv, err := confidential.CertFromPEM(b, "")
	if err != nil {
		log.Fatal(err)
	}

	cred, err := confidential.NewCredFromCert(certs, priv)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(cred) // Simply here so cred is used, otherwise won't compile.
}

func NewCredFromSecret 

func NewCredFromSecret(secret string) (Credential, error)

NewCredFromSecret creates a Credential from a secret.

func NewCredFromTokenProvider 

func NewCredFromTokenProvider(provider func(context.Context, TokenProviderParameters) (TokenProviderResult, error)) Credential

NewCredFromTokenProvider creates a Credential from a function that provides access tokens. The function must be concurrency safe. This is intended only to allow the Azure SDK to cache MSI tokens. It isn't useful to applications in general because the token provider must implement all authentication logic.

type Option 

type Option func(o *clientOptions)

Option is an optional argument to New().

func WithAzureRegion 

func WithAzureRegion(val string) Option

WithAzureRegion sets the region(preferred) or Confidential.AutoDetectRegion() for auto detecting region. Region names as per https://azure.microsoft.com/en-ca/global-infrastructure/geographies/. See https://aka.ms/region-map for more details on region names. The region value should be short region name for the region where the service is deployed. For example "centralus" is short name for region Central US. Not all auth flows can use the regional token service. Service To Service (client credential flow) tokens can be obtained from the regional service. Requires configuration at the tenant level. Auto-detection works on a limited number of Azure artifacts (VMs, Azure functions). If auto-detection fails, the non-regional endpoint will be used. If an invalid region name is provided, the non-regional endpoint MIGHT be used or the token request MIGHT fail.

func WithCache 

func WithCache(accessor cache.ExportReplace) Option

WithCache provides an accessor that will read and write authentication data to an externally managed cache.

func WithClientCapabilities 

func WithClientCapabilities(capabilities []string) Option

WithClientCapabilities allows configuring one or more client capabilities such as "CP1"

func WithHTTPClient 

func WithHTTPClient(httpClient ops.HTTPClient) Option

WithHTTPClient allows for a custom HTTP client to be set.

func WithInstanceDiscovery 

func WithInstanceDiscovery(enabled bool) Option

WithInstanceDiscovery set to false to disable authority validation (to support private cloud scenarios)

func WithX5C 

func WithX5C() Option

WithX5C specifies if x5c claim(public key of the certificate) should be sent to STS to enable Subject Name Issuer Authentication.

type TokenProviderParameters 

type TokenProviderParameters = exported.TokenProviderParameters

TokenProviderParameters is the authentication parameters passed to token providers

type TokenProviderResult 

type TokenProviderResult = exported.TokenProviderResult

TokenProviderResult is the authentication result returned by custom token providers

type TokenSource 

type TokenSource = base.TokenSource

Source Files

confidential.go

Version
v1.4.2 (latest)
Published
Mar 26, 2025
Platform
linux/amd64
Imports
19 packages
Last checked
2 days ago –

Tools for package owners.