msauth

README

msauth

A Go client library for easy Microsoft authentication

This package is a heavily modified Microsoft Identity Platform client borrowing ideas and code from https://github.com/open-networks/go-msgraph package. In order to enable sharing authentication with a msgraph package, a mspowerbi package and any other Microsoft package which uses the same authentication flow, this has been built into its own package.

Other projects of interest:

1. https://github.com/AzureAD/microsoft-authentication-library-for-go - a Microsoft supported Go authentication package. Still in preview.
2. https://github.com/open-networks/go-msgraph - a Microsoft Graph client which has the auth client built in.

Documentation

Overview

Package msauth provides an authenticated http Client which has been authenticated using the Microsoft identity platform and OAuth 2.0 authorization flow. The resulting client can be used for the Microsoft Graph API, Power BI and other API's.

See: https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow

Index

• Constants
• type Client
  • func New(tenantID, applicationID, clientSecret, resource string) (*Client, error)
  • func NewWithCustomEndpoint(tenantID, applicationID, clientSecret string, ...) (*Client, error)
  • func (g *Client) Do(ctx context.Context, method, path string, headers http.Header, ...) error
  • func (g *Client) GetClient() (*sling.Sling, error)
  • func (g *Client) SetDefaults(setter func(client *sling.Sling) *sling.Sling)
• type Token
  • func (t Token) GetAccessToken() string
  • func (t Token) HasExpired() bool
  • func (t Token) IsAlreadyValid() bool
  • func (t Token) IsStillValid() bool
  • func (t Token) IsValid() bool
  • func (t *Token) UnmarshalJSON(data []byte) error
  • func (t Token) WantsToBeRefreshed() bool

Constants

const (
	// Azure AD authentication endpoint "Global". Used to acquire a token for the ms graph API connection.
	//
	// Microsoft Documentation: https://docs.microsoft.com/en-us/azure/active-directory/develop/authentication-national-cloud#azure-ad-authentication-endpoints
	AzureADAuthEndpointGlobal string = "https://login.microsoftonline.com"

	// Azure AD authentication endpoint "Germany". Used to acquire a token for the ms graph API connection.
	//
	// Microsoft Documentation: https://docs.microsoft.com/en-us/azure/active-directory/develop/authentication-national-cloud#azure-ad-authentication-endpoints
	AzureADAuthEndpointGermany string = "https://login.microsoftonline.de"

	// Azure AD authentication endpoint "US Government". Used to acquire a token for the ms graph API connection.
	//
	// Microsoft Documentation: https://docs.microsoft.com/en-us/azure/active-directory/develop/authentication-national-cloud#azure-ad-authentication-endpoints
	AzureADAuthEndpointUSGov string = "https://login.microsoftonline.us"

	// Azure AD authentication endpoint "China by 21 Vianet". Used to acquire a token for the ms graph API connection.
	//
	// Microsoft Documentation: https://docs.microsoft.com/en-us/azure/active-directory/develop/authentication-national-cloud#azure-ad-authentication-endpoints
	AzureADAuthEndpointChina string = "https://login.partner.microsoftonline.cn"
)

const APIVersion string = "v1.0"

APIVersion represents the APIVersion of msauth used by this implementation

Types

type Client

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

func New

func New(tenantID, applicationID, clientSecret, resource string) (*Client, error)

New creates a new AuthClient instance with the given parameters and grabs a token. Returns an error if the token cannot be initialized. The default Microsoft Identity Platfrom URL is used.

func NewWithCustomEndpoint

func NewWithCustomEndpoint(tenantID, applicationID, clientSecret string, azureADAuthEndpoint, resource string) (*Client, error)

NewWithCustomEndpoint creates a new Microsoft Identity Platform client instance with the given parameters and tries to get a valid token. All available public endpoints for azureADAuthEndpoint and serviceRootEndpoint are available via msauth.azureADAuthEndpoint*

For available endpoints from Microsoft, see documentation:

• Authentication Endpoints: https://docs.microsoft.com/en-us/azure/active-directory/develop/authentication-national-cloud#azure-ad-authentication-endpoints

func (*Client) Do

func (g *Client) Do(ctx context.Context, method, path string, headers http.Header, urlParams url.Values, bodyJSON, result, errResult interface{}) error

func (*Client) GetClient

func (g *Client) GetClient() (*sling.Sling, error)

func (*Client) SetDefaults

func (g *Client) SetDefaults(setter func(client *sling.Sling) *sling.Sling)

type Token

type Token struct {
	TokenType   string    // should always be "Bearer" for msgraph API-calls
	NotBefore   time.Time // time when the access token starts to be valid
	ExpiresOn   time.Time // time when the access token expires
	Resource    string    // will most likely be https://graph.microsoft.*, hence the Service Root Endpoint
	AccessToken string    // the access-token itself
}

Token struct holds the Microsoft Graph API authentication token used by GraphClient to authenticate API-requests to the ms graph API

func (Token) GetAccessToken

func (t Token) GetAccessToken() string

GetAccessToken teturns the API access token in Bearer format representation ready to send to the API interface.

func (Token) HasExpired

func (t Token) HasExpired() bool

HasExpired returns true if the token has already expired.

Hint: this is a wrapper for >>!token.IsStillValid()<<

func (Token) IsAlreadyValid

func (t Token) IsAlreadyValid() bool

IsAlreadyValid returns true if the token is already valid, hence the NotBefore is before the current time. Otherwise false.

Hint: The current time is determined by time.Now()

func (Token) IsStillValid

func (t Token) IsStillValid() bool

IsStillValid returns true if the token is still valid, hence the current time is before ExpiresOn. Does NOT check it the token is yet valid or in the future.

Hint: The current time is determined by time.Now()

func (Token) IsValid

func (t Token) IsValid() bool

IsValid returns true if the token is already valid and is still valid. Otherwise false.

Hint: this is a wrapper for >>token.IsAlreadyValid() && token.IsStillValid()<<

func (*Token) UnmarshalJSON

func (t *Token) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json unmarshal to be used by the json-library.

Hint: the UnmarshalJSON also checks immediately if the token is valid, hence the current time.Now() is after NotBefore and before ExpiresOn

func (Token) WantsToBeRefreshed

func (t Token) WantsToBeRefreshed() bool

WantsToBeRefreshed returns true if the token is already invalid or close to expire (10 second before ExpiresOn), otherwise false. time.Now() is used to determine the current time.