confidential

Documentation

Overview

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.

Index

• func AutoDetectRegion() string
• func CertFromPEM(pemData []byte, password string) ([]*x509.Certificate, crypto.PrivateKey, error)
• type Account
• type AcquireTokenByAuthCodeOption
  • func WithChallenge(challenge string) AcquireTokenByAuthCodeOption
• type AcquireTokenByAuthCodeOptions
• type AcquireTokenSilentOption
  • func WithSilentAccount(account Account) AcquireTokenSilentOption
• type AcquireTokenSilentOptions
• type AuthResult
• type Client
  • func New(clientID string, cred Credential, options ...Option) (Client, error)
  • func (cca Client) Account(homeAccountID string) Account
  • func (cca Client) AcquireTokenByAuthCode(ctx context.Context, code string, redirectURI string, scopes []string, ...) (AuthResult, error)
  • func (cca Client) AcquireTokenByCredential(ctx context.Context, scopes []string) (AuthResult, error)
  • func (cca Client) AcquireTokenOnBehalfOf(ctx context.Context, userAssertion string, scopes []string) (AuthResult, error)
  • func (cca Client) AcquireTokenSilent(ctx context.Context, scopes []string, options ...AcquireTokenSilentOption) (AuthResult, error)
  • func (cca Client) AuthCodeURL(ctx context.Context, clientID, redirectURI string, scopes []string) (string, error)
  • func (cca Client) RemoveAccount(account Account) error
  • func (cca Client) UserID() string
• type Credential
  • func NewCredFromAssertion(assertion string) (Credential, error)
  • func NewCredFromCert(cert *x509.Certificate, key crypto.PrivateKey) Credential
  • func NewCredFromSecret(secret string) (Credential, error)
• type Option
  • func WithAccessor(accessor cache.ExportReplace) Option
  • func WithAuthority(authority string) Option
  • func WithAzureRegion(val string) Option
  • func WithHTTPClient(httpClient ops.HTTPClient) Option
  • func WithX5C() Option
• type Options

Examples

• NewCredFromCert (Pem)

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 have the public certificate and the private key encoded. The private key must be encoded in PKCS8 (not PKCS1). This is usually denoted by the section "PRIVATE KEY" (instead of PKCS1's "RSA PRIVATE KEY"). If a PEM block is encoded and password is not an empty string, it attempts to decrypt the PEM blocks using the password. This will return multiple x509 certificates, though this use case should have a single cert. Multiple certs are due to certificate chaining for use cases like TLS that sign from root to leaf.

Types

type Account

type Account = shared.Account

type AcquireTokenByAuthCodeOption

type AcquireTokenByAuthCodeOption func(a *AcquireTokenByAuthCodeOptions)

AcquireTokenByAuthCodeOption changes options inside AcquireTokenByAuthCodeOptions used in .AcquireTokenByAuthCode().

func WithChallenge

func WithChallenge(challenge string) AcquireTokenByAuthCodeOption

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

type AcquireTokenByAuthCodeOptions

type AcquireTokenByAuthCodeOptions struct {
	Challenge string
}

AcquireTokenByAuthCodeOptions contains the optional parameters used to acquire an access token using the authorization code flow.

type AcquireTokenSilentOption

type AcquireTokenSilentOption func(a *AcquireTokenSilentOptions)

AcquireTokenSilentOption changes options inside AcquireTokenSilentOptions used in .AcquireTokenSilent().

func WithSilentAccount

func WithSilentAccount(account Account) AcquireTokenSilentOption

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

type AcquireTokenSilentOptions

type AcquireTokenSilentOptions struct {
	// Account represents the account to use. To set, use the WithSilentAccount() option.
	Account Account
}

AcquireTokenSilentOptions are all the optional settings to an AcquireTokenSilent() call. These are set by using various AcquireTokenSilentOption functions.

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 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(clientID string, cred Credential, options ...Option) (Client, error)

New is the constructor for Client. userID is the unique identifier of the user this client will store credentials for (a Client is per user). clientID is the Azure clientID and cred is the type of credential to use.

func (Client) Account

func (cca Client) Account(homeAccountID string) Account

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, options ...AcquireTokenByAuthCodeOption) (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.

func (Client) AcquireTokenByCredential

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

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

func (Client) AcquireTokenOnBehalfOf

func (cca Client) AcquireTokenOnBehalfOf(ctx context.Context, userAssertion string, scopes []string) (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.

func (Client) AcquireTokenSilent

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

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

func (Client) AuthCodeURL

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

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

func (Client) RemoveAccount

func (cca Client) RemoveAccount(account Account) error

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

func (Client) UserID

func (cca Client) UserID() string

UserID is the unique user identifier this client if for.

type Credential

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

Credential represents the credential used in confidential client flows.

func NewCredFromAssertion

func NewCredFromAssertion(assertion string) (Credential, error)

NewCredFromAssertion creates a Credential from a signed assertion.

func NewCredFromCert

func NewCredFromCert(cert *x509.Certificate, key crypto.PrivateKey) Credential

NewCredFromCert creates a Credential from an x509.Certificate and a PKCS8 DER encoded private key. CertFromPEM() can be used to get these values from a PEM file storing a PKCS8 private key.

Example (Pem)

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

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

// PEM files can have multiple certs. This is usually for certificate chaining where roots
// sign to leafs. Useful for TLS, not for this use case.
if len(certs) > 1 {
	log.Fatal("too many certificates in PEM file")
}

cred := NewCredFromCert(certs[0], priv)
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.

type Option

type Option func(o *Options)

Option is an optional argument to New().

func WithAccessor

func WithAccessor(accessor cache.ExportReplace) Option

WithAccessor provides a cache accessor that will read and write to some externally managed cache that may or may not be shared with other applications.

func WithAuthority

func WithAuthority(authority string) Option

WithAuthority allows you to provide a custom authority for use in the client.

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 WithHTTPClient

func WithHTTPClient(httpClient ops.HTTPClient) Option

WithHTTPClient allows for a custom HTTP client to be set.

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 Options

type Options struct {
	// Accessor controls cache persistence.
	// By default there is no cache persistence. This can be set using the WithAccessor() option.
	Accessor cache.ExportReplace

	// The host of the Azure Active Directory authority.
	// The default is https://login.microsoftonline.com/common. This can be changed using the
	// WithAuthority() option.
	Authority string

	// The HTTP client used for making requests.
	// It defaults to a shared http.Client.
	HTTPClient ops.HTTPClient

	// SendX5C specifies if x5c claim(public key of the certificate) should be sent to STS.
	SendX5C bool

	// Instructs MSAL Go to use an Azure regional token service with sepcified AzureRegion.
	AzureRegion string
}

Options are optional settings for New(). These options are set using various functions returning Option calls.