cache

README

Microsoft Authentication Library (MSAL) Extensions for Go

This module contains a persistent cache for Microsoft Authentication Library (MSAL) for Go public client applications such as CLI tools. It isn't recommended for web applications or RPC APIs, in which it can cause scaling and performance problems.

The cache supports encrypted storage on Linux, macOS and Windows. The encryption facility depends on the platform:

• Linux: libsecret (used as a DBus Secret Service client)
• macOS: keychain
• Windows: data protection API (DPAPI)

See the accessor package for more details. The file package has a plaintext storage provider to use when encryption isn't possible.

Plaintext storage is dangerous. Bearer tokens are not cryptographically bound to a machine and can be stolen. In particular, the refresh token can be used to get access tokens for many resources. It's important to warn end-users before falling back to plaintext. End-users should ensure they store the tokens in a secure location (e.g. encrypted disk) and must understand they are responsible for their safety.

Installation

go get -u github.com/AzureAD/microsoft-authentication-extensions-for-go/cache

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Documentation

Overview

Example

This example shows how to configure an MSAL public client to store data in a peristent, encrypted cache.

package main

import (
	"github.com/AzureAD/microsoft-authentication-extensions-for-go/cache"
	"github.com/AzureAD/microsoft-authentication-extensions-for-go/cache/accessor"
	"github.com/AzureAD/microsoft-authentication-library-for-go/apps/public"
)

func main() {
	// On Linux and macOS, "s" is an arbitrary name identifying the cache.
	// On Windows, it's the path to a file in which to store cache data.
	s := "..."
	a, err := accessor.New(s)
	if err != nil {
		// TODO: handle error
	}
	c, err := cache.New(a, s)
	if err != nil {
		// TODO: handle error
	}
	app, err := public.New("client-id", public.WithCache(c))
	if err != nil {
		// TODO: handle error
	}

	_ = app
}

Index

• type Cache
  • func New(a accessor.Accessor, p string) (*Cache, error)
  • func (c *Cache) Export(ctx context.Context, m cache.Marshaler, h cache.ExportHints) (err error)
  • func (c *Cache) Replace(ctx context.Context, u cache.Unmarshaler, h cache.ReplaceHints) error

Examples

• Package

Types

type Cache

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

Cache caches authentication data in external storage, using a file lock to coordinate access with other processes.

func New

func New(a accessor.Accessor, p string) (*Cache, error)

New is the constructor for Cache. "p" is the path to a file used to track when stored data changes. Cache.Export will create this file and any directories in its path which don't already exist.

func (*Cache) Export

func (c *Cache) Export(ctx context.Context, m cache.Marshaler, h cache.ExportHints) (err error)

Export writes the bytes marshaled by "m" to the accessor. MSAL clients call this method automatically.

func (*Cache) Replace

func (c *Cache) Replace(ctx context.Context, u cache.Unmarshaler, h cache.ReplaceHints) error

Replace reads bytes from the accessor and unmarshals them to "u". MSAL clients call this method automatically.