git-credential-msal

This repository contains tooling to help with git over HTTP flows using Microsoft SSO with OIDC Id tokens. For information on how to configure the server for this flow, please look at the related blog post.

Dependencies

Must be manually installed by the user

• git>=2.54
  • Installation instructions
    • Linux/UNIX
    • Windows
    • macOS
  • Support for SSO authentication via the credential helper protocol was initially added with commit c5c9acf77d, which first appears in Git v2.46; however, a bug prevented it working correctly. This bug was fixed by commit ed0f7a62f7, which first appears in Git v2.54.

Handled by the installation process

• msal-python
• pyjwt
• keyring
• pyxdg

Installation

Installing from source

cd git-credential-msal
python3 -m pipx install .

If you run into issues with the above, first verify that the latest version of pipx is installed. To avoid a conflict with the system's package manager, installing a newer version of pipx in the user site-packages is recommended.

python3 -m pipx install --upgrade --user pipx

Setup

Run the following to have git utilize the credential helper.

git config --global --add credential.helper msal

If you are only going to use this helper for a select few repos, you could consider not using the --global flag.

You may want to use this helper in combination with another helper that supports the store action. This is especially helpful if your system does not have a keyring provider present, so you can use the auxiliary credential helper to minimize Microsoft SSO prompts during a development session. The order is important since you want the cache credential helper checked before msal.

NOTE: This does not store the cache related to the OAuth2.0 refresh token that is stored in the keyring. This cache is useful for not needing to re-authenticate for up to 90 days. Have a look at the Device Authorization Grant section of the documentation for more details.

git config --global --add credential.helper cache
git config --global --add credential.helper msal

In the situation where you are using git on a headless device, you may want to use OAuth 2.0 Device Authorization Grant to do the authentication flow on a different system. git-credential-msal can easily be configured to do so by using the -d / --device-code in your .gitconfig.

[credential]
    helper = msal -d

Many headless setups will likely not have a keyring provider such as GNOME Keyring or KDE Wallet since such providers on Linux are heavily tied into desktop environments. If wishing to persist the Microsoft Authentication cache (which enables authentication persistence for up to 90 days), use the -i / --insecure flag along with the device code flag in your .gitconfig.

• https://learn.microsoft.com/en-us/entra/identity-platform/refresh-tokens#token-lifetime
• https://learn.microsoft.com/en-us/entra/identity-platform/refresh-tokens#token-revocation

[credential]
    helper = msal -d -i

To configure the Microsoft Entra Id application client id and tenant id that git-credential-msal will use for SSO, the following commands can be used.

git config --global credential.https://git.example.com.msalClientId <MSFT Entra Id App Client Id>
git config --global credential.https://git.example.com.msalTenantId <MSFT Entra Id App Tenant Id>

In special cases where your git server can provide a WWW-Authenticate HTTP response header like below, the git config above will not be necessary. The git config values take precedence over what is advertised by the server.

WWW-Authenticate: Bearer msal-client-id=<MSFT Entra Id App Client Id>,msal-tenant-id=<MSFT Entra Id App Tenant Id>

git will feed the above HTTP header to the credential helper program to consume.

NOTE: the server does need to at minimum advertise WWW-Authenticate: Bearer in its initial 401 response for git-credential-msal to consider forwarding the bearer token to the server.