BrowserCacheManager class

Package:

@azure/msal-browser

This class implements the cache storage interface for MSAL through browser local or session storage. Cookies are only used if storeAuthStateInCookie is true, and are only used for parameters such as state and nonce, generally.

Extends

CacheManager

Constructors

BrowserCacheManager(string, Required<CacheOptions>, ICrypto, Logger)

Methods

cacheCodeRequest(CommonAuthorizationCodeRequest, ICrypto)
cleanRequestByInteractionType(InteractionType)	Looks in temporary cache for any state values with the provided interactionType and removes all temporary cache items for that state Used in scenarios where temp cache needs to be cleaned but state is not known, such as clicking browser back button.
cleanRequestByState(string)	Removes temporary cache for the provided state
clear()	Clears all cache entries created by MSAL.
clearItemCookie(string)	Clear an item in the cookies by key
clearMsalCookies()	Clear all msal-related cookies currently set in the browser. Should only be used to clear temporary cache items.
containsKey(string)	Checks whether key is in cache.
generateAuthorityKey(string)	Create authorityKey to cache authority
generateCacheKey(string)	Prepend msal. to each key; Skip for any JSON object as Key (defined schemas do not need the key appended: AccessToken Keys or the upcoming schema)
generateNonceKey(string)	Create Nonce key to cache nonce
generateStateKey(string)	Creates full cache key for the request state
getAccessTokenCredential(string)	generates accessToken entity from a string
getAccount(string)	fetch the account entity from the platform cache
getAccountInfoByFilter(Partial<Omit<AccountInfo, "idTokenClaims" | "name">>)	Gets a list of accounts that match all of the filters provided
getAccountInfoByHints(string, string)	Checks the cache for accounts matching loginHint or SID
getActiveAccount()	Gets the active account
getAppMetadata(string)	fetch appMetadata entity from the platform cache
getAuthorityMetadata(string)
getAuthorityMetadataKeys()
getCache()	Gets the cache object referenced by the browser
getCachedAuthority(string)	Gets the cached authority based on the cached state. Returns empty if no cached state found.
getCachedNativeRequest()	Gets cached native request for redirect flows
getCachedRequest(string, ICrypto)	Gets the token exchange parameters from the cache. Throws an error if nothing is found.
getCookieExpirationTime(number)	Get cookie expiration time
getIdTokenCredential(string)	generates idToken entity from a string
getInteractionInProgress()
getItem(string)	fetches the entry from the browser storage based off the key
getItemCookie(string)	Get one item by key from cookies
getKeys()	Gets all keys in window.
getLegacyLoginHint()	Returns username retrieved from ADAL or MSAL v1 idToken
getRefreshTokenCredential(string)	generates refreshToken entity from a string
getServerTelemetry(string)	fetch server telemetry entity from the platform cache
getTemporaryCache(string, boolean)	Gets cache item with given key. Will retrieve from cookies if storeAuthStateInCookie is set to true.
getThrottlingCache(string)	fetch throttling entity from the platform cache
getWrapperMetadata()	Returns wrapper metadata from in-memory storage
isInteractionInProgress(boolean)
removeItem(string)	Removes the cache item with the given key. Will also clear the cookie item if storeAuthStateInCookie is set to true.
resetRequestCache(string)	Reset all temporary cache items
setAccessTokenCredential(AccessTokenEntity)	set accessToken credential to the platform cache
setAccount(AccountEntity)	set account entity in the platform cache
setActiveAccount(AccountInfo | null)	Sets the active account's localAccountId in cache
setAppMetadata(AppMetadataEntity)	set appMetadata entity to the platform cache
setAuthorityMetadata(string, AuthorityMetadataEntity)
setCache()	interface compat, we cannot overwrite browser cache; Functionality is supported by individual entities in browser
setIdTokenCredential(IdTokenEntity)	set IdToken credential to the platform cache
setInteractionInProgress(boolean)
setItem(string, string)	sets the entry in the browser storage
setItemCookie(string, string, number)	Add value to cookies
setRefreshTokenCredential(RefreshTokenEntity)	set refreshToken credential to the platform cache
setServerTelemetry(string, ServerTelemetryEntity)	set server telemetry entity to the platform cache
setTemporaryCache(string, string, boolean)	Sets the cache item with the key and value given. Stores in cookie if storeAuthStateInCookie is set to true. This can cause cookie overflow if used incorrectly.
setThrottlingCache(string, ThrottlingEntity)	set throttling entity to the platform cache
setWrapperMetadata(string, string)	Sets wrapper metadata in memory
updateCacheEntries(string, string, string, string, AccountInfo | null)	Updates account, authority, and state in cache
updateCredentialCacheKey(string, ValidCredentialType)	Updates a credential's cache key if the current cache key is outdated

Inherited Methods

generateAuthorityMetadataCacheKey(string)	returns cache key used for cloud instance metadata
getAccountsFilteredBy(AccountFilter)	retrieve accounts matching all provided filters; if no filter is set, get all accounts not checking for casing as keys are all generated in lower case, remember to convert to lower case if object properties are compared
getAllAccounts()	Returns all accounts in cache
getAppMetadataFilteredBy(AppMetadataFilter)	retrieve appMetadata matching all provided filters; if no filter is set, get all appMetadata
getAuthorityMetadataByAlias(string)	retrieve authorityMetadata that contains a matching alias
getCredentialsFilteredBy(CredentialFilter)	retrieve credentails matching all provided filters; if no filter is set, get all credentials
isAppMetadataFOCI(string, string)	Return the family_id value associated with FOCI
readAccessTokenFromCache(string, AccountInfo, BaseAuthRequest)	Retrieve AccessTokenEntity from cache
readAccountFromCache(AccountInfo)	Retrieve AccountEntity from cache
readAccountFromCacheWithNativeAccountId(string)	Retrieve AccountEntity from cache
readAppMetadataFromCache(string, string)	Retrieve AppMetadataEntity from cache
readCacheRecord(AccountInfo, string, BaseAuthRequest, string)	Retrieve the cached credentials into a cacherecord
readIdTokenFromCache(string, AccountInfo)	Retrieve IdTokenEntity from cache
readRefreshTokenFromCache(string, AccountInfo, boolean)	Helper to retrieve the appropriate refresh token from cache
removeAccount(string)	returns a boolean if the given account is removed
removeAccountContext(AccountEntity)	Removes credentials associated with the provided account
removeAllAccounts()	Removes all accounts and related tokens from cache.
removeAppMetadata()	Removes all app metadata objects from cache.
removeCredential(CredentialEntity)	returns a boolean if the given credential is removed
saveCacheRecord(CacheRecord)	saves a cache record
toObject<T>(T, object)	Helper to convert serialized data to object

Constructor Details

BrowserCacheManager(string, Required<CacheOptions>, ICrypto, Logger)

new BrowserCacheManager(clientId: string, cacheConfig: Required<CacheOptions>, cryptoImpl: ICrypto, logger: Logger)

Parameters

clientId

string

cacheConfig

Required<CacheOptions>

cryptoImpl

ICrypto

logger

Logger

Method Details

cacheCodeRequest(CommonAuthorizationCodeRequest, ICrypto)

function cacheCodeRequest(authCodeRequest: CommonAuthorizationCodeRequest, browserCrypto: ICrypto)

Parameters

authCodeRequest

CommonAuthorizationCodeRequest

browserCrypto

ICrypto

cleanRequestByInteractionType(InteractionType)

Looks in temporary cache for any state values with the provided interactionType and removes all temporary cache items for that state Used in scenarios where temp cache needs to be cleaned but state is not known, such as clicking browser back button.

function cleanRequestByInteractionType(interactionType: InteractionType)

Parameters

interactionType

InteractionType

cleanRequestByState(string)

Removes temporary cache for the provided state

function cleanRequestByState(stateString: string)

Parameters

stateString

string

clear()

Clears all cache entries created by MSAL.

function clear(): Promise<void>

Returns

Promise<void>

clearItemCookie(string)

Clear an item in the cookies by key

function clearItemCookie(cookieName: string)

Parameters

cookieName

string

clearMsalCookies()

Clear all msal-related cookies currently set in the browser. Should only be used to clear temporary cache items.

function clearMsalCookies()

containsKey(string)

Checks whether key is in cache.

function containsKey(key: string): boolean

Parameters

key

string

Returns

boolean

generateAuthorityKey(string)

Create authorityKey to cache authority

function generateAuthorityKey(stateString: string): string

Parameters

stateString

string

Returns

string

generateCacheKey(string)

Prepend msal. to each key; Skip for any JSON object as Key (defined schemas do not need the key appended: AccessToken Keys or the upcoming schema)

function generateCacheKey(key: string): string

Parameters

key

string

Returns

string

generateNonceKey(string)

Create Nonce key to cache nonce

function generateNonceKey(stateString: string): string

Parameters

stateString

string

Returns

string

generateStateKey(string)

Creates full cache key for the request state

function generateStateKey(stateString: string): string

Parameters

stateString

string

State string for the request

Returns

string

getAccessTokenCredential(string)

generates accessToken entity from a string

function getAccessTokenCredential(accessTokenKey: string): AccessTokenEntity | null

Parameters

accessTokenKey

string

Returns

AccessTokenEntity | null

getAccount(string)

fetch the account entity from the platform cache

function getAccount(accountKey: string): AccountEntity | null

Parameters

accountKey

string

Returns

AccountEntity | null

getAccountInfoByFilter(Partial<Omit<AccountInfo, "idTokenClaims" | "name">>)

Gets a list of accounts that match all of the filters provided

function getAccountInfoByFilter(accountFilter: Partial<Omit<AccountInfo, "idTokenClaims" | "name">>): AccountInfo[]

Parameters

accountFilter

Partial<Omit<AccountInfo, "idTokenClaims" | "name">>

Returns

AccountInfo[]

getAccountInfoByHints(string, string)

Checks the cache for accounts matching loginHint or SID

function getAccountInfoByHints(loginHint?: string, sid?: string): AccountInfo | null

Parameters

loginHint

string

sid

string

Returns

AccountInfo | null

getActiveAccount()

Gets the active account

function getActiveAccount(): AccountInfo | null

Returns

AccountInfo | null

getAppMetadata(string)

fetch appMetadata entity from the platform cache

function getAppMetadata(appMetadataKey: string): AppMetadataEntity | null

Parameters

appMetadataKey

string

Returns

AppMetadataEntity | null

getAuthorityMetadata(string)

function getAuthorityMetadata(key: string): AuthorityMetadataEntity | null

Parameters

key

string

Returns

AuthorityMetadataEntity | null

getAuthorityMetadataKeys()

function getAuthorityMetadataKeys(): Array<string>

Returns

Array<string>

getCache()

Gets the cache object referenced by the browser

function getCache(): object

Returns

object

getCachedAuthority(string)

Gets the cached authority based on the cached state. Returns empty if no cached state found.

function getCachedAuthority(cachedState: string): string | null

Parameters

cachedState

string

Returns

string | null

getCachedNativeRequest()

Gets cached native request for redirect flows

function getCachedNativeRequest(): NativeTokenRequest | null

Returns

NativeTokenRequest | null

getCachedRequest(string, ICrypto)

Gets the token exchange parameters from the cache. Throws an error if nothing is found.

function getCachedRequest(state: string, browserCrypto: ICrypto): CommonAuthorizationCodeRequest

Parameters

state

string

browserCrypto

ICrypto

Returns

CommonAuthorizationCodeRequest

getCookieExpirationTime(number)

Get cookie expiration time

function getCookieExpirationTime(cookieLifeDays: number): string

Parameters

cookieLifeDays

number

Returns

string

getIdTokenCredential(string)

generates idToken entity from a string

function getIdTokenCredential(idTokenKey: string): IdTokenEntity | null

Parameters

idTokenKey

string

Returns

IdTokenEntity | null

getInteractionInProgress()

function getInteractionInProgress(): string | null

Returns

string | null

getItem(string)

fetches the entry from the browser storage based off the key

function getItem(key: string): string | null

Parameters

key

string

Returns

string | null

getItemCookie(string)

Get one item by key from cookies

function getItemCookie(cookieName: string): string

Parameters

cookieName

string

Returns

string

getKeys()

Gets all keys in window.

function getKeys(): string[]

Returns

string[]

getLegacyLoginHint()

Returns username retrieved from ADAL or MSAL v1 idToken

function getLegacyLoginHint(): string | null

Returns

string | null

getRefreshTokenCredential(string)

generates refreshToken entity from a string

function getRefreshTokenCredential(refreshTokenKey: string): RefreshTokenEntity | null

Parameters

refreshTokenKey

string

Returns

RefreshTokenEntity | null

getServerTelemetry(string)

fetch server telemetry entity from the platform cache

function getServerTelemetry(serverTelemetryKey: string): ServerTelemetryEntity | null

Parameters

serverTelemetryKey

string

Returns

ServerTelemetryEntity | null

getTemporaryCache(string, boolean)

Gets cache item with given key. Will retrieve from cookies if storeAuthStateInCookie is set to true.

function getTemporaryCache(cacheKey: string, generateKey?: boolean): string | null

Parameters

cacheKey

string

generateKey

boolean

Returns

string | null

getThrottlingCache(string)

fetch throttling entity from the platform cache

function getThrottlingCache(throttlingCacheKey: string): ThrottlingEntity | null

Parameters

throttlingCacheKey

string

Returns

ThrottlingEntity | null

getWrapperMetadata()

Returns wrapper metadata from in-memory storage

function getWrapperMetadata(): [string, string]

Returns

[string, string]

isInteractionInProgress(boolean)

function isInteractionInProgress(matchClientId?: boolean): boolean

Parameters

matchClientId

boolean

Returns

boolean

removeItem(string)

Removes the cache item with the given key. Will also clear the cookie item if storeAuthStateInCookie is set to true.

function removeItem(key: string): boolean

Parameters

key

string

Returns

boolean

resetRequestCache(string)

Reset all temporary cache items

function resetRequestCache(state: string)

Parameters

state

string

setAccessTokenCredential(AccessTokenEntity)

set accessToken credential to the platform cache

function setAccessTokenCredential(accessToken: AccessTokenEntity)

Parameters

accessToken

AccessTokenEntity

setAccount(AccountEntity)

set account entity in the platform cache

function setAccount(account: AccountEntity)

Parameters

account

AccountEntity

setActiveAccount(AccountInfo | null)

Sets the active account's localAccountId in cache

function setActiveAccount(account: AccountInfo | null)

Parameters

account

AccountInfo | null

setAppMetadata(AppMetadataEntity)

set appMetadata entity to the platform cache

function setAppMetadata(appMetadata: AppMetadataEntity)

Parameters

appMetadata

AppMetadataEntity

setAuthorityMetadata(string, AuthorityMetadataEntity)

function setAuthorityMetadata(key: string, entity: AuthorityMetadataEntity)

Parameters

key

string

entity

AuthorityMetadataEntity

setCache()

interface compat, we cannot overwrite browser cache; Functionality is supported by individual entities in browser

function setCache()

setIdTokenCredential(IdTokenEntity)

set IdToken credential to the platform cache

function setIdTokenCredential(idToken: IdTokenEntity)

Parameters

idToken

IdTokenEntity

setInteractionInProgress(boolean)

function setInteractionInProgress(inProgress: boolean)

Parameters

inProgress

boolean

setItem(string, string)

sets the entry in the browser storage

function setItem(key: string, value: string)

Parameters

key

string

value

string

setItemCookie(string, string, number)

Add value to cookies

function setItemCookie(cookieName: string, cookieValue: string, expires?: number)

Parameters

cookieName

string

cookieValue

string

expires

number

setRefreshTokenCredential(RefreshTokenEntity)

set refreshToken credential to the platform cache

function setRefreshTokenCredential(refreshToken: RefreshTokenEntity)

Parameters

refreshToken

RefreshTokenEntity

setServerTelemetry(string, ServerTelemetryEntity)

set server telemetry entity to the platform cache

function setServerTelemetry(serverTelemetryKey: string, serverTelemetry: ServerTelemetryEntity)

Parameters

serverTelemetryKey

string

serverTelemetry

ServerTelemetryEntity

setTemporaryCache(string, string, boolean)

Sets the cache item with the key and value given. Stores in cookie if storeAuthStateInCookie is set to true. This can cause cookie overflow if used incorrectly.

function setTemporaryCache(cacheKey: string, value: string, generateKey?: boolean)

Parameters

cacheKey

string

value

string

generateKey

boolean

setThrottlingCache(string, ThrottlingEntity)

set throttling entity to the platform cache

function setThrottlingCache(throttlingCacheKey: string, throttlingCache: ThrottlingEntity)

Parameters

throttlingCacheKey

string

throttlingCache

ThrottlingEntity

setWrapperMetadata(string, string)

Sets wrapper metadata in memory

function setWrapperMetadata(wrapperSKU: string, wrapperVersion: string)

Parameters

wrapperSKU

string

wrapperVersion

string

updateCacheEntries(string, string, string, string, AccountInfo | null)

Updates account, authority, and state in cache

function updateCacheEntries(state: string, nonce: string, authorityInstance: string, loginHint: string, account: AccountInfo | null)

Parameters

state

string

nonce

string

authorityInstance

string

loginHint

string

account

AccountInfo | null

updateCredentialCacheKey(string, ValidCredentialType)

Updates a credential's cache key if the current cache key is outdated

function updateCredentialCacheKey(currentCacheKey: string, credential: ValidCredentialType): string

Parameters

currentCacheKey

string

credential

ValidCredentialType

Returns

string

Inherited Method Details

generateAuthorityMetadataCacheKey(string)

returns cache key used for cloud instance metadata

function generateAuthorityMetadataCacheKey(authority: string): string

Parameters

authority

string

Returns

string

Inherited From CacheManager.generateAuthorityMetadataCacheKey

getAccountsFilteredBy(AccountFilter)

retrieve accounts matching all provided filters; if no filter is set, get all accounts not checking for casing as keys are all generated in lower case, remember to convert to lower case if object properties are compared

function getAccountsFilteredBy(accountFilter?: AccountFilter): AccountCache

Parameters

accountFilter

AccountFilter

Returns

AccountCache

Inherited From CacheManager.getAccountsFilteredBy

getAllAccounts()

Returns all accounts in cache

function getAllAccounts(): AccountInfo[]

Returns

AccountInfo[]

Inherited From CacheManager.getAllAccounts

getAppMetadataFilteredBy(AppMetadataFilter)

retrieve appMetadata matching all provided filters; if no filter is set, get all appMetadata

function getAppMetadataFilteredBy(filter: AppMetadataFilter): AppMetadataCache

Parameters

filter

AppMetadataFilter

Returns

AppMetadataCache

Inherited From CacheManager.getAppMetadataFilteredBy

getAuthorityMetadataByAlias(string)

retrieve authorityMetadata that contains a matching alias

function getAuthorityMetadataByAlias(host: string): AuthorityMetadataEntity | null

Parameters

host

string

Returns

AuthorityMetadataEntity | null

Inherited From CacheManager.getAuthorityMetadataByAlias

getCredentialsFilteredBy(CredentialFilter)

retrieve credentails matching all provided filters; if no filter is set, get all credentials

function getCredentialsFilteredBy(filter: CredentialFilter): CredentialCache

Parameters

filter

CredentialFilter

Returns

CredentialCache

Inherited From CacheManager.getCredentialsFilteredBy

isAppMetadataFOCI(string, string)

Return the family_id value associated with FOCI

function isAppMetadataFOCI(environment: string, clientId: string): boolean

Parameters

environment

string

clientId

string

Returns

boolean

Inherited From CacheManager.isAppMetadataFOCI

readAccessTokenFromCache(string, AccountInfo, BaseAuthRequest)

Retrieve AccessTokenEntity from cache

function readAccessTokenFromCache(clientId: string, account: AccountInfo, request: BaseAuthRequest): AccessTokenEntity | null

Parameters

clientId

string

account

AccountInfo

request

BaseAuthRequest

Returns

AccessTokenEntity | null

Inherited From CacheManager.readAccessTokenFromCache

readAccountFromCache(AccountInfo)

Retrieve AccountEntity from cache

function readAccountFromCache(account: AccountInfo): AccountEntity | null

Parameters

account

AccountInfo

Returns

AccountEntity | null

Inherited From CacheManager.readAccountFromCache

readAccountFromCacheWithNativeAccountId(string)

Retrieve AccountEntity from cache

function readAccountFromCacheWithNativeAccountId(nativeAccountId: string): AccountEntity | null

Parameters

nativeAccountId

string

Returns

AccountEntity | null

AccountEntity or Null

Inherited From CacheManager.readAccountFromCacheWithNativeAccountId

readAppMetadataFromCache(string, string)

Retrieve AppMetadataEntity from cache

function readAppMetadataFromCache(environment: string, clientId: string): AppMetadataEntity | null

Parameters

environment

string

clientId

string

Returns

AppMetadataEntity | null

Inherited From CacheManager.readAppMetadataFromCache

readCacheRecord(AccountInfo, string, BaseAuthRequest, string)

Retrieve the cached credentials into a cacherecord

function readCacheRecord(account: AccountInfo, clientId: string, request: BaseAuthRequest, environment: string): CacheRecord

Parameters

account

AccountInfo

clientId

string

request

BaseAuthRequest

environment

string

Returns

CacheRecord

Inherited From CacheManager.readCacheRecord

readIdTokenFromCache(string, AccountInfo)

Retrieve IdTokenEntity from cache

function readIdTokenFromCache(clientId: string, account: AccountInfo): IdTokenEntity | null

Parameters

clientId

string

account

AccountInfo

Returns

IdTokenEntity | null

Inherited From CacheManager.readIdTokenFromCache

readRefreshTokenFromCache(string, AccountInfo, boolean)

Helper to retrieve the appropriate refresh token from cache

function readRefreshTokenFromCache(clientId: string, account: AccountInfo, familyRT: boolean): RefreshTokenEntity | null

Parameters

clientId

string

account

AccountInfo

familyRT

boolean

Returns

RefreshTokenEntity | null

Inherited From CacheManager.readRefreshTokenFromCache

removeAccount(string)

returns a boolean if the given account is removed

function removeAccount(accountKey: string): Promise<boolean>

Parameters

accountKey

string

Returns

Promise<boolean>

Inherited From CacheManager.removeAccount

removeAccountContext(AccountEntity)

Removes credentials associated with the provided account

function removeAccountContext(account: AccountEntity): Promise<boolean>

Parameters

account

AccountEntity

Returns

Promise<boolean>

Inherited From CacheManager.removeAccountContext

removeAllAccounts()

Removes all accounts and related tokens from cache.

function removeAllAccounts(): Promise<boolean>

Returns

Promise<boolean>

Inherited From CacheManager.removeAllAccounts

removeAppMetadata()

Removes all app metadata objects from cache.

function removeAppMetadata(): boolean

Returns

boolean

Inherited From CacheManager.removeAppMetadata

removeCredential(CredentialEntity)

returns a boolean if the given credential is removed

function removeCredential(credential: CredentialEntity): Promise<boolean>

Parameters

credential

CredentialEntity

Returns

Promise<boolean>

Inherited From CacheManager.removeCredential

saveCacheRecord(CacheRecord)

saves a cache record

function saveCacheRecord(cacheRecord: CacheRecord): Promise<void>

Parameters

cacheRecord

CacheRecord

Returns

Promise<void>

Inherited From CacheManager.saveCacheRecord

toObject<T>(T, object)

Helper to convert serialized data to object

static function toObject<T>(obj: T, json: object): T

Parameters

obj

T

json

object

Returns

T

Inherited From CacheManager.toObject