Interface ITokenCacheSerializer

Namespace

Microsoft.Identity.Client

Assembly

Microsoft.Identity.Client.dll

This interface will be available in TokenCacheNotificationArgs callback to enable serialization/deserialization of the cache.

public interface ITokenCacheSerializer

Remarks

The methods in this class are not thread safe. It is expected that they will be called from the token cache callbacks, registered via SetBeforeAccess, SetAfterAccess. These callbacks thread safe because they are triggered sequentially.

Methods

DeserializeAdalV3(byte[])

Deserializes a part of the token cache - the refresh tokens - to the ADAL.NET 3.x cache format.
This API should only be used to maintain SSO between an application using ADAL 3.x and this application using MSAL 3.x or later. Use SerializeAdalV3()/DeserializeAdalV3(byte[]) in addition to SerializeMsalV3()/DeserializeMsalV3(byte[], bool).

See https://aka.ms/adal-to-msal-net/cache for details on how to use this advanced API correctly.

void DeserializeAdalV3(byte[] adalV3State)

Parameters

adalV3State byte[]

Byte stream representation of the cache

Remarks

Do not use SerializeAdalV3()/DeserializeAdalV3(byte[]) without also using SerializeMsalV3()/DeserializeMsalV3(byte[], bool), because only refresh tokens are exported in this format. Your applications will not cache access token and id tokens, and will instead need to get them from the identity provider (AAD), which will eventually throttle you. Later versions of ADAL (4.x and 5.x) use the same cache format as MSAL. Only SerializeMsalV3()/DeserializeMsalV3(byte[], bool) is compatible with other MSAL libraries such as MSAL for Python and MSAL for Java. ADAL to MSAL cache interop is only available for public client scenarios and for web site scenario.

DeserializeMsalV3(byte[], bool)

Deserializes the token cache to the MSAL.NET 3.x cache format, which is compatible with other MSAL desktop libraries, including MSAL.NET 4.x, MSAL for Python and MSAL for Java. If you need to maintain SSO between an application using ADAL 3.x and this application using MSAL 3.x or later, you might also want to serialize and deserialize with SerializeAdalV3()/DeserializeAdalV3(byte[]), otherwise just use SerializeMsalV3()/DeserializeMsalV3(byte[], bool).

void DeserializeMsalV3(byte[] msalV3State, bool shouldClearExistingCache = false)

Parameters

msalV3State byte[]

Byte stream representation of the cache

shouldClearExistingCache bool

Set to true to clear MSAL cache contents. Defaults to false. You would want to set this to true if you want the cache contents in memory to be exactly what's on disk. You would want to set this to false if you want to merge the contents of what's on disk with your current in memory state.

Remarks

This is the recommended format for maintaining SSO state between applications. SerializeMsalV3()/DeserializeMsalV3(byte[], bool) is compatible with other MSAL libraries such as MSAL for Python and MSAL for Java.

SerializeAdalV3()

Serializes a part of the token cache - the refresh tokens - to the ADAL.NET 3.x cache format. If you need to maintain SSO between an application using ADAL 3.x and this application using MSAL 3.x or later, use SerializeAdalV3()/DeserializeAdalV3(byte[]) in addition to SerializeMsalV3()/DeserializeMsalV3(byte[], bool).

See https://aka.ms/adal-to-msal-net/cache for details on how to use this advanced API correctly.

byte[] SerializeAdalV3()

Returns

byte[]

Byte stream representation of the cache

Remarks

Do not use SerializeAdalV3()/DeserializeAdalV3(byte[]) without also using SerializeMsalV3()/DeserializeMsalV3(byte[], bool), because only refresh tokens are exported in this format. Your applications will not cache access token and id tokens, and will instead need to get them from the identity provider (AAD), which will eventually throttle you. Later versions of ADAL (4.x and 5.x) use the same cache format as MSAL. Only SerializeMsalV3()/DeserializeMsalV3(byte[], bool) is compatible with other MSAL libraries such as MSAL for Python and MSAL for Java. ADAL to MSAL cache interop is only available for public client scenarios and for web site scenario.

SerializeMsalV3()

Serializes the token cache to the MSAL.NET 3.x cache format, which is compatible with other MSAL desktop libraries, including MSAL.NET 4.x, MSAL for Python and MSAL for Java. If you need to maintain SSO between an application using ADAL 3.x and this application using MSAL 3.x or later, you might also want to serialize and deserialize with SerializeAdalV3()/DeserializeAdalV3(byte[]), otherwise just use SerializeMsalV3()/DeserializeMsalV3(byte[], bool).

byte[] SerializeMsalV3()

Returns

byte[]

Byte stream representation of the cache

Remarks

This is the recommended format for maintaining SSO state between applications. SerializeMsalV3()/DeserializeMsalV3(byte[], bool) is compatible with other MSAL libraries such as MSAL for Python and MSAL for Java.