Documentation
¶
Overview ¶
Package public provides a client for authentication of "public" applications. A "public" application is defined as an app that runs on client devices (android, ios, windows, linux, ...). These devices are "untrusted" and access resources via web APIs that must authenticate.
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
package main
import (
"context"
"github.com/AzureAD/microsoft-authentication-library-for-go/apps/public"
)
func main() {
client, err := public.New("client_id", public.WithAuthority("https://login.microsoftonline.com/your_tenant"))
if err != nil {
// TODO: handle error
}
var result public.AuthResult
scopes := []string{"scope"}
// If your application previously authenticated a user, call AcquireTokenSilent with that user's account
// to use cached authentication data. This example shows choosing an account from the cache, however this
// isn't always necessary because the AuthResult returned by authentication methods includes user account
// information.
accounts, err := client.Accounts(context.TODO())
if err != nil {
// TODO: handle error
}
if len(accounts) > 0 {
// There may be more accounts; here we assume the first one is wanted.
// AcquireTokenSilent returns a non-nil error when it can't provide a token.
result, err = client.AcquireTokenSilent(context.TODO(), scopes, public.WithSilentAccount(accounts[0]))
}
if err != nil || len(accounts) == 0 {
// cache miss, authenticate a user with another AcquireToken* method
result, err = client.AcquireTokenInteractive(context.TODO(), scopes)
if err != nil {
// TODO: handle error
}
}
// TODO: save the authenticated user's account, use the access token
_ = result.Account
_ = result.AccessToken
}
Output:
Index ¶
- func WithAuthenticationScheme(authnScheme AuthenticationScheme) interface{ ... }
- func WithChallenge(challenge string) interface{ ... }
- func WithClaims(claims string) interface{ ... }
- func WithDomainHint(domain string) interface{ ... }
- func WithLoginHint(username string) interface{ ... }
- func WithOpenURL(openURL func(url string) error) interface{ ... }
- func WithRedirectURI(redirectURI string) interface{ ... }
- func WithSilentAccount(account Account) interface{ ... }
- func WithTenantID(tenantID string) interface{ ... }
- type Account
- type AcquireByAuthCodeOption
- type AcquireByDeviceCodeOption
- type AcquireByUsernamePasswordOption
- type AcquireInteractiveOption
- type AcquireSilentOption
- type AuthCodeURLOption
- type AuthResult
- type AuthenticationScheme
- type Client
- func (pca Client) Accounts(ctx context.Context) ([]Account, error)
- func (pca Client) AcquireTokenByAuthCode(ctx context.Context, code string, redirectURI string, scopes []string, ...) (AuthResult, error)
- func (pca Client) AcquireTokenByDeviceCode(ctx context.Context, scopes []string, opts ...AcquireByDeviceCodeOption) (DeviceCode, error)
- func (pca Client) AcquireTokenByUsernamePassword(ctx context.Context, scopes []string, username, password string, ...) (AuthResult, error)
- func (pca Client) AcquireTokenInteractive(ctx context.Context, scopes []string, opts ...AcquireInteractiveOption) (AuthResult, error)
- func (pca Client) AcquireTokenSilent(ctx context.Context, scopes []string, opts ...AcquireSilentOption) (AuthResult, error)
- func (pca Client) AuthCodeURL(ctx context.Context, clientID, redirectURI string, scopes []string, ...) (string, error)
- func (pca Client) RemoveAccount(ctx context.Context, account Account) error
- type DeviceCode
- type DeviceCodeResult
- type Option
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func WithAuthenticationScheme ¶ added in v1.2.0
func WithAuthenticationScheme(authnScheme AuthenticationScheme) interface { AcquireSilentOption AcquireInteractiveOption AcquireByUsernamePasswordOption 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 code for the .AcquireTokenByAuthCode() call.
func WithClaims ¶ added in v0.8.0
func WithClaims(claims string) interface { AcquireByAuthCodeOption AcquireByDeviceCodeOption AcquireByUsernamePasswordOption AcquireInteractiveOption 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 ¶ added in v0.8.0
func WithDomainHint(domain string) interface { AcquireInteractiveOption AuthCodeURLOption options.CallOption }
WithDomainHint adds the IdP domain as domain_hint query parameter in the auth url.
func WithLoginHint ¶ added in v0.8.0
func WithLoginHint(username string) interface { AcquireInteractiveOption AuthCodeURLOption options.CallOption }
WithLoginHint pre-populates the login prompt with a username.
func WithOpenURL ¶ added in v1.1.0
func WithOpenURL(openURL func(url string) error) interface { AcquireInteractiveOption options.CallOption }
WithOpenURL allows you to provide a function to open the browser to complete the interactive login, instead of launching the system default browser.
func WithRedirectURI ¶
func WithRedirectURI(redirectURI string) interface { AcquireInteractiveOption options.CallOption }
WithRedirectURI sets a port for the local server used in interactive authentication, for example http://localhost:port. All URI components other than the port are ignored.
func WithSilentAccount ¶
func WithSilentAccount(account Account) interface { AcquireSilentOption options.CallOption }
WithSilentAccount uses the passed account during an AcquireTokenSilent() call.
func WithTenantID ¶ added in v0.8.0
func WithTenantID(tenantID string) interface { AcquireByAuthCodeOption AcquireByDeviceCodeOption AcquireByUsernamePasswordOption AcquireInteractiveOption AcquireSilentOption AuthCodeURLOption options.CallOption }
WithTenantID specifies a tenant for a single authentication. It may be different than the tenant set in New by WithAuthority. This option is valid for any token acquisition method.
Types ¶
type AcquireByAuthCodeOption ¶ added in v0.8.0
type AcquireByAuthCodeOption interface {
// contains filtered or unexported methods
}
AcquireByAuthCodeOption is implemented by options for AcquireTokenByAuthCode
type AcquireByDeviceCodeOption ¶ added in v0.8.0
type AcquireByDeviceCodeOption interface {
// contains filtered or unexported methods
}
AcquireByDeviceCodeOption is implemented by options for AcquireTokenByDeviceCode
type AcquireByUsernamePasswordOption ¶ added in v0.8.0
type AcquireByUsernamePasswordOption interface {
// contains filtered or unexported methods
}
AcquireByUsernamePasswordOption is implemented by options for AcquireTokenByUsernamePassword
type AcquireInteractiveOption ¶ added in v0.8.0
type AcquireInteractiveOption interface {
// contains filtered or unexported methods
}
AcquireInteractiveOption is implemented by options for AcquireTokenInteractive
type AcquireSilentOption ¶ added in v0.8.0
type AcquireSilentOption interface {
// contains filtered or unexported methods
}
AcquireSilentOption is implemented by options for AcquireTokenSilent
type AuthCodeURLOption ¶ added in v0.9.0
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 ¶ added in v1.2.0
type AuthenticationScheme = authority.AuthenticationScheme
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a representation of authentication client for public applications as defined in the package doc. For more information, visit https://docs.microsoft.com/azure/active-directory/develop/msal-client-applications.
func (Client) Accounts ¶
Accounts gets all the accounts in the token cache. If there are no accounts in the cache the returned slice is empty.
func (Client) AcquireTokenByAuthCode ¶
func (pca 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) AcquireTokenByDeviceCode ¶
func (pca Client) AcquireTokenByDeviceCode(ctx context.Context, scopes []string, opts ...AcquireByDeviceCodeOption) (DeviceCode, error)
AcquireTokenByDeviceCode acquires a security token from the authority, by acquiring a device code and using that to acquire the token. Users need to create an AcquireTokenDeviceCodeParameters instance and pass it in.
Options: WithClaims, WithTenantID
func (Client) AcquireTokenByUsernamePassword ¶
func (pca 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) AcquireTokenInteractive ¶
func (pca Client) AcquireTokenInteractive(ctx context.Context, scopes []string, opts ...AcquireInteractiveOption) (AuthResult, error)
AcquireTokenInteractive acquires a security token from the authority using the default web browser to select the account. https://docs.microsoft.com/en-us/azure/active-directory/develop/msal-authentication-flows#interactive-and-non-interactive-authentication
Options: WithDomainHint, WithLoginHint, WithOpenURL, WithRedirectURI, WithTenantID
func (Client) AcquireTokenSilent ¶
func (pca 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 ¶ added in v0.9.0
func (pca Client) AuthCodeURL(ctx context.Context, clientID, redirectURI string, scopes []string, opts ...AuthCodeURLOption) (string, error)
AuthCodeURL creates a URL used to acquire an authorization code.
Options: WithClaims, WithDomainHint, WithLoginHint, WithTenantID
type DeviceCode ¶
type DeviceCode struct {
// Result holds the information about the device code (such as the code).
Result DeviceCodeResult
// contains filtered or unexported fields
}
DeviceCode provides the results of the device code flows first stage (containing the code) that must be entered on the second device and provides a method to retrieve the AuthenticationResult once that code has been entered and verified.
func (DeviceCode) AuthenticationResult ¶
func (d DeviceCode) AuthenticationResult(ctx context.Context) (AuthResult, error)
AuthenticationResult retreives the AuthenticationResult once the user enters the code on the second device. Until then it blocks until the .AcquireTokenByDeviceCode() context is cancelled or the token expires.
type DeviceCodeResult ¶
type DeviceCodeResult = accesstokens.DeviceCodeResult
type Option ¶
type Option func(o *clientOptions)
Option is an optional argument to the New constructor.
func WithAuthority ¶
WithAuthority allows for a custom authority to be set. This must be a valid https url.
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 ¶ added in v0.8.0
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 ¶ added in v0.8.0
WithInstanceDiscovery set to false to disable authority validation (to support private cloud scenarios)
Source Files