Token encryption cache - exception handling improvements when attempting to decrypt

[erwinkramer]

Related command
az account show
az account get-access-token

Is your feature request related to a problem? Please describe.
The core problem is the lack of interoperability of encrypted token caches between different OSes.

Related to a bunch of open issues (not limited to):
Azure/azure-sdk-for-net#19167
#21010
#27176
AzureAD/microsoft-authentication-library-for-dotnet#3033

Describe the solution you'd like
When attempting to access/decrypt an encrypted (MSAL) token cache on an unsupported OS, there should be a very clear message explaining the compatibility, and/or linked to a troubleshooting guide.

I'm not asking for a working encrypted token cache solution in this feature/issue, as there are already enough open issues for that opened (see above). I don't feel that those will be solved any time soon. And even if they will be solved, there will always popup new decryption issues somewhere.

Suggested error message would be something like: Encrypted credentials found but not able to decrypt, this would help a ton, because then i know:

1. there are actually credentials stored
2. there is a problem with the credentials in the way i attempt to use them on the OS

Additional context
Current error when calling az account get-access-token when the cache is encrypted but accessed from an OS that does not support it:

The command failed with an unexpected error. Here is the traceback:
Unable to import module 'gi'
Runtime dependency of PyGObject is missing.

Current error message when using DefaultAzureCredential when the cache is encrypted but accessed from an OS that does not support it:

- EnvironmentCredential authentication unavailable. Environment variables are not fully configured. See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/environmentcredential/troubleshoot
- WorkloadIdentityCredential authentication unavailable. The workload options are not fully configured. See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/workloadidentitycredential/troubleshoot
- ManagedIdentityCredential authentication unavailable. No response received from the managed identity endpoint.
- Visual Studio Token provider can't be accessed at /root/.IdentityService/AzureServiceAuth/tokenprovider.json
- Azure CLI authentication failed due to an unknown error. See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/azclicredential/troubleshoot ERROR: The command failed with an unexpected error. Here is the traceback:
ERROR: Unable to import module 'gi'
Runtime dependency of PyGObject is missing.
Depends on your Linux distro, you could install it system-wide by something like:
    sudo apt install python3-gi python3-gi-cairo gir1.2-secret-1
If necessary, please refer to PyGObject's doc:
https://pygobject.readthedocs.io/en/latest/getting_started.html
Traceback (most recent call last):
  File "/opt/az/lib/python3.12/site-packages/msal_extensions/libsecret.py", line 18, in <module>
    import gi  # https://github.com/AzureAD/microsoft-authentication-extensions-for-python/wiki/Encryption-on-Linux  # pylint: disable=line-too-long
    ^^^^^^^^^
ModuleNotFoundError: No module named 'gi'

etc...

The message when calling az account show is a 200 response with the account details, where it seems there are no problems. It is questionable that it should return a 200, maybe that should throw an error or at the very least a warning, explicitly noting that there is an issue with the current stored MSAL credentials.

Tagging @jiasli as recommended by @rayluo in AzureAD/microsoft-authentication-library-for-dotnet#3033 (comment)

[yonzhan]

Thank you for opening this issue, we will look into it.

[jiasli]

The core problem is the lack of interoperability of encrypted token caches between different OSes.

Token cache is meant to be used on only one machine, it is never expected to be copied to a different machine/OS.

The message when calling az account show is a 200 response with the account details, where it seems there are no problems.

I don't think this is true. az account show is a local command and makes no web request. You may add --debug to verify that. This command does not talk to MSAL either as it only returns which account has been logged into Azure CLI.

Suggested error message would be something like: Encrypted credentials found but not able to decrypt, this would help a ton

I agree a clearer error message such as Unable to load required libraries for token encryption/decryption is better than Unable to import module 'gi' (https://github.com/AzureAD/microsoft-authentication-extensions-for-python/blob/ba841e60dc2a8e23a1ce16bb87e8c3a75ee5b9a4/msal_extensions/libsecret.py#L17-L26).

[erwinkramer]

Token cache is meant to be used on only one machine, it is never expected to be copied to a different machine/OS.

.NET wasn't supposed to be cross-platform either but look at where we are now.

[rayluo]

I want to clarify a few things.

The core problem is the lack of interoperability of encrypted token caches between different OSes.

Token cache is meant to be used on only one machine, it is never expected to be copied to a different machine/OS.

.NET wasn't supposed to be cross-platform either but look at where we are now.

The token encryption's lack of interoperability across platforms is language-agnostic fact. Not sure why @erwinkramer initially brought it up in an MSAL .Net issue, but let's focus on Azure CLI from now on, because we are now discussing the possibility of a better error message from Azure CLI.

Additional context Current error when calling az account get-access-token when the cache is encrypted but accessed from an OS that does not support it:

The command failed with an unexpected error. Here is the traceback:
Unable to import module 'gi'
Runtime dependency of PyGObject is missing.

[More] Current error message when using DefaultAzureCredential ...

- Azure CLI authentication failed due to an unknown error. See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/azclicredential/troubleshoot ERROR: The command failed with an unexpected error. Here is the traceback:
ERROR: Unable to import module 'gi'
Runtime dependency of PyGObject is missing.
Depends on your Linux distro, you could install it system-wide by something like:
    sudo apt install python3-gi python3-gi-cairo gir1.2-secret-1
If necessary, please refer to PyGObject's doc:
https://pygobject.readthedocs.io/en/latest/getting_started.html

Suggested error message would be something like: Encrypted credentials found but not able to decrypt, this would help a ton

I agree a clearer error message such as Unable to load required libraries for token encryption/decryption is better than Unable to import module 'gi' (https://github.com/AzureAD/microsoft-authentication-extensions-for-python/blob/ba841e60dc2a8e23a1ce16bb87e8c3a75ee5b9a4/msal_extensions/libsecret.py#L17-L26).

I think the current error message "Unable to import module 'gi'", which even comes with instructions on how to install the missing package, looks appropriate IN ITS CONTEXT, FOR ITS AUDIENCE. It is an error emitted by a lower-level package msal-extensions, to tell msal-extensions's consumer how to use that functionality.

Since Azure CLI chose to not provide token encryption on Linux (therefore not shipping gi at all), Azure CLI better captures that ImportError (or perhaps a new EncryptionPackageNotFound error that we may agree to have msal-extensions throw instead) and provide a better error message such as "Token encryption on Linux is not yet supported. Please make sure your token cache file is not encrypted".