azrepos: support service principals and managed IDs

Allow a service principal or managed identity to be used to authenticate against Azure Repos. Required information for service principals is specified in Git config or environment variables, as is the ID for a managed identity.
git-ecosystem · Aug 7, 2023 · 57ab5d6 · 57ab5d6
1 parent 53f3466
commit 57ab5d6
Show file tree

Hide file tree

Showing 4 changed files with 352 additions and 5 deletions.
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -825,6 +825,86 @@ git config --global credential.azreposCredentialType oauth
 
 ---
 
+### credential.azreposManagedIdentity
+
+Use a [Managed Identity][managed-identity] to authenticate with Azure Repos.
+The value `system` will tell GCM to use the system-assigned Managed Identity.
+Any GUID-like value will tell GCM to use a user-assigned Managed Identity with
+the specified client ID.
+
+For more information about managed identities, see the Azure DevOps
+[documentation][azrepos-sp-mid].
+
+Value|Description
+-|-
+`system`|Use the System-Assigned Managed Identity
+`[guid]`|Use the User-Assigned Managed Identity with the specified client ID
+
+```shell
+git config --global credential.azreposManagedIdentity "11111111-1111-1111-1111-111111111111"
+```
+
+**Also see: [GCM_AZREPOS_MANAGEDIDENTITY][gcm-azrepos-credentialmanagedidentity]**
+
+---
+
+### credential.azreposServicePrincipal
+
+Specify the client and tenant IDs of a [service principal][service-principal]
+to use when performing Microsoft authentication for Azure Repos.
+
+The value of this setting should be in the format: `{tenantId}/{clientId}`.
+
+You must also set at least one authentication mechanism if you set this value:
+
+- [credential.azreposServicePrincipalSecret][credential-azrepos-sp-secret]
+- [credential.azreposServicePrincipalCertificateThumbprint][credential-azrepos-sp-cert-thumbprint]
+
+For more information about service principals, see the Azure DevOps
+[documentation] [azrepos-sp-mid].
+
+#### Example
+
+```shell
+git config --global credential.azreposServicePrincipal "11111111-1111-1111-1111-111111111111/22222222-2222-2222-2222-222222222222"
+```
+
+**Also see: [GCM_AZREPOS_SERVICE_PRINCIPAL][gcm-azrepos-service-principal]**
+
+---
+
+### credential.azreposServicePrincipalSecret
+
+Specifies the client secret for the [service principal][service-principal] when
+performing Microsoft authentication for Azure Repos with
+[credential.azreposServicePrincipalSecret][credential-azrepos-sp] set.
+
+#### Example
+
+```shell
+git config --global credential.azreposServicePrincipalSecret "da39a3ee5e6b4b0d3255bfef95601890afd80709"
+```
+
+**Also see: [GCM_AZREPOS_SP_SECRET][gcm-azrepos-sp-secret]**
+
+---
+
+### credential.azreposServicePrincipalCertificateThumbprint
+
+Specifies the thumbprint of a certificate to use when authenticating as a
+[service principal][service-principal] for Azure Repos when
+[GCM_AZREPOS_SERVICE_PRINCIPAL][credential-azrepos-sp] is set.
+
+#### Example
+
+```shell
+git config --global credential.azreposServicePrincipalCertificateThumbprint "9b6555292e4ea21cbc2ebd23e66e2f91ebbe92dc"
+```
+
+**Also see: [GCM_AZREPOS_SP_CERT_THUMBPRINT][gcm-azrepos-sp-cert-thumbprint]**
+
+---
+
 ### trace2.normalTarget
 
 Turns on Trace2 Normal Format tracing - see [Git's Trace2 Normal Format
@@ -910,6 +990,7 @@ Defaults to disabled.
 [gcm-authority]: environment.md#GCM_AUTHORITY-deprecated
 [gcm-autodetect-timeout]: environment.md#GCM_AUTODETECT_TIMEOUT
 [gcm-azrepos-credentialtype]: environment.md#GCM_AZREPOS_CREDENTIALTYPE
+[gcm-azrepos-credentialmanagedidentity]: environment.md#GCM_AZREPOS_MANAGEDIDENTITY
 [gcm-bitbucket-always-refresh-credentials]: environment.md#GCM_BITBUCKET_ALWAYS_REFRESH_CREDENTIALS
 [gcm-bitbucket-authmodes]: environment.md#GCM_BITBUCKET_AUTHMODES
 [gcm-credential-cache-options]: environment.md#GCM_CREDENTIAL_CACHE_OPTIONS
@@ -939,6 +1020,7 @@ Defaults to disabled.
 [http-proxy]: netconfig.md#http-proxy
 [autodetect]: autodetect.md
 [libsecret]: https://wiki.gnome.org/Projects/Libsecret
+[managed-identity]: https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/overview
 [provider-migrate]: migration.md#gcm_authority
 [cache-options]: https://git-scm.com/docs/git-credential-cache#_options
 [pass]: https://www.passwordstore.org/
@@ -949,3 +1031,11 @@ Defaults to disabled.
 [trace2-performance-docs]: https://git-scm.com/docs/api-trace2#_the_performance_format_target
 [trace2-performance-env]: environment.md#GIT_TRACE2_PERF
 [wam]: windows-broker.md
+[service-principal]: https://docs.microsoft.com/en-us/azure/active-directory/develop/app-objects-and-service-principals
+[azrepos-sp-mid]: https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/service-principal-managed-identity
+[credential-azrepos-sp]: #credentialazreposserviceprincipal
+[credential-azrepos-sp-secret]: #credentialazreposserviceprincipalsecret
+[credential-azrepos-sp-cert-thumbprint]: #credentialazreposserviceprincipalcertificatethumbprint
+[gcm-azrepos-service-principal]: environment.md#GCM_AZREPOS_SERVICE_PRINCIPAL
+[gcm-azrepos-sp-secret]: environment.md#GCM_AZREPOS_SP_SECRET
+[gcm-azrepos-sp-cert-thumbprint]: environment.md#GCM_AZREPOS_SP_CERT_THUMBPRINT
diff --git a/docs/environment.md b/docs/environment.md
@@ -938,6 +938,112 @@ export GCM_AZREPOS_CREDENTIALTYPE="oauth"
 
 ---
 
+### GCM_AZREPOS_MANAGEDIDENTITY
+
+Use a [Managed Identity][managed-identity] to authenticate with Azure Repos.
+The value `system` will tell GCM to use the system-assigned Managed Identity.
+Any GUID-like value will tell GCM to use a user-assigned Managed Identity with
+the specified client ID.
+
+Value|Description
+-|-
+`system`|Use the System-Assigned Managed Identity
+`[guid]`|Use the User-Assigned Managed Identity with the specified client ID
+
+For more information about managed identities, see the Azure DevOps
+[documentation][azrepos-sp-mid].
+
+#### Windows
+
+```batch
+SET GCM_AZREPOS_MANAGEDIDENTITY="11111111-1111-1111-1111-111111111111"
+```
+
+#### macOS/Linux
+
+```bash
+export GCM_AZREPOS_MANAGEDIDENTITY="11111111-1111-1111-1111-111111111111"
+```
+
+**Also see: [credential.azreposManagedIdentity][credential-azrepos-managedidentity]**
+
+---
+
+### GCM_AZREPOS_SERVICE_PRINCIPAL
+
+Specify the client and tenant IDs of a [service principal][service-principal]
+to use when performing Microsoft authentication for Azure Repos.
+
+The value of this setting should be in the format: `{tenantId}/{clientId}`.
+
+You must also set at least one authentication mechanism if you set this value:
+
+- [GCM_AZREPOS_SP_SECRET][gcm-azrepos-sp-secret]
+- [GCM_AZREPOS_SP_CERT_THUMBPRINT][gcm-azrepos-sp-cert-thumbprint]
+
+For more information about service principals, see the Azure DevOps
+[documentation] [azrepos-sp-mid].
+
+#### Windows
+
+```batch
+SET GCM_AZREPOS_SERVICE_PRINCIPAL="11111111-1111-1111-1111-111111111111/22222222-2222-2222-2222-222222222222"
+```
+
+#### macOS/Linux
+
+```bash
+export GCM_AZREPOS_SERVICE_PRINCIPAL="11111111-1111-1111-1111-111111111111/22222222-2222-2222-2222-222222222222"
+```
+
+**Also see: [credential.azreposServicePrincipal][credential-azrepos-sp]**
+
+---
+
+### GCM_AZREPOS_SP_SECRET
+
+Specifies the client secret for the [service principal][service-principal] when
+performing Microsoft authentication for Azure Repos with
+[GCM_AZREPOS_SERVICE_PRINCIPAL][gcm-azrepos-sp] set.
+
+#### Windows
+
+```batch
+SET GCM_AZREPOS_SP_SECRET="da39a3ee5e6b4b0d3255bfef95601890afd80709"
+```
+
+#### macOS/Linux
+
+```bash
+export GCM_AZREPOS_SP_SECRET="da39a3ee5e6b4b0d3255bfef95601890afd80709"
+```
+
+**Also see: [credential.azreposServicePrincipalSecret][credential-azrepos-sp-secret]**
+
+---
+
+### GCM_AZREPOS_SP_CERT_THUMBPRINT
+
+Specifies the thumbprint of a certificate to use when authenticating as a
+[service principal][service-principal] for Azure Repos when
+[GCM_AZREPOS_SERVICE_PRINCIPAL][gcm-azrepos-sp] is set.
+
+#### Windows
+
+```batch
+SET GCM_AZREPOS_SP_CERT_THUMBPRINT="9b6555292e4ea21cbc2ebd23e66e2f91ebbe92dc"
+```
+
+#### macOS/Linux
+
+```bash
+export GCM_AZREPOS_SP_CERT_THUMBPRINT="9b6555292e4ea21cbc2ebd23e66e2f91ebbe92dc"
+```
+
+**Also see: [credential.azreposServicePrincipalCertificateThumbprint][credential-azrepos-sp-cert-thumbprint]**
+
+---
+
 ### GIT_TRACE2
 
 Turns on Trace2 Normal Format tracing - see [Git's Trace2 Normal Format
@@ -1029,7 +1135,8 @@ Defaults to disabled.
 [credential-allowwindowsauth]: environment.md#credentialallowWindowsAuth
 [credential-authority]: configuration.md#credentialauthority-deprecated
 [credential-autodetecttimeout]: configuration.md#credentialautodetecttimeout
-[credential-azrepos-credential-type]: configuration.md#azreposcredentialtype
+[credential-azrepos-credential-type]: configuration.md#credentialazreposcredentialtype
+[credential-azrepos-managedidentity]: configuration.md#credentialazreposmanagedidentity
 [credential-bitbucketauthmodes]: configuration.md#credentialbitbucketAuthModes
 [credential-cacheoptions]: configuration.md#credentialcacheoptions
 [credential-credentialstore]: configuration.md#credentialcredentialstore
@@ -1068,6 +1175,7 @@ Defaults to disabled.
 [github-emu]: https://docs.github.com/en/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users
 [network-http-proxy]: netconfig.md#http-proxy
 [libsecret]: https://wiki.gnome.org/Projects/Libsecret
+[managed-identity]: https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/overview
 [migration-guide]: migration.md#gcm_authority
 [passwordstore]: https://www.passwordstore.org/
 [trace2-normal-docs]: https://git-scm.com/docs/api-trace2#_the_normal_format_target
@@ -1077,3 +1185,11 @@ Defaults to disabled.
 [trace2-performance-docs]: https://git-scm.com/docs/api-trace2#_the_performance_format_target
 [trace2-performance-config]: configuration.md#trace2perfTarget
 [windows-broker]: windows-broker.md
+[service-principal]: https://docs.microsoft.com/en-us/azure/active-directory/develop/app-objects-and-service-principals
+[azrepos-sp-mid]: https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/service-principal-managed-identity
+[gcm-azrepos-sp]: #gcm_azrepos_service_principal
+[gcm-azrepos-sp-secret]: #gcm_azrepos_sp_secret
+[gcm-azrepos-sp-cert-thumbprint]: #gcm_azrepos_sp_cert_thumbprint
+[credential-azrepos-sp]: configuration.md#credentialazreposserviceprincipal
+[credential-azrepos-sp-secret]: configuration.md#credentialazreposserviceprincipalsecret
+[credential-azrepos-sp-cert-thumbprint]: configuration.md#credentialazreposserviceprincipalcertificatethumbprint
diff --git a/src/shared/Microsoft.AzureRepos/AzureDevOpsConstants.cs b/src/shared/Microsoft.AzureRepos/AzureDevOpsConstants.cs
@@ -8,7 +8,8 @@ internal static class AzureDevOpsConstants
         public const string AadAuthorityBaseUrl = "https://login.microsoftonline.com";
 
         // Azure DevOps's app ID + default scopes
-        public static readonly string[] AzureDevOpsDefaultScopes = {"499b84ac-1321-427f-aa17-267ca6975798/.default"};
+        public const string AzureDevOpsResourceId = "499b84ac-1321-427f-aa17-267ca6975798";
+        public static readonly string[] AzureDevOpsDefaultScopes = {$"{AzureDevOpsResourceId}/.default"};
 
         public const string VstsHostSuffix = ".visualstudio.com";
         public const string AzureDevOpsHost = "dev.azure.com";
@@ -31,6 +32,10 @@ public static class EnvironmentVariables
         {
             public const string DevAadAuthorityBaseUri = "GCM_DEV_AZREPOS_AUTHORITYBASEURI";
             public const string CredentialType = "GCM_AZREPOS_CREDENTIALTYPE";
+            public const string ServicePrincipalId = "GCM_AZREPOS_SERVICE_PRINCIPAL";
+            public const string ServicePrincipalSecret = "GCM_AZREPOS_SP_SECRET";
+            public const string ServicePrincipalCertificateThumbprint = "GCM_AZREPOS_SP_CERT_THUMBPRINT";
+            public const string ManagedIdentity = "GCM_AZREPOS_MANAGEDIDENTITY";
         }
 
         public static class GitConfiguration
@@ -40,6 +45,10 @@ public static class Credential
                 public const string DevAadAuthorityBaseUri = "azreposDevAuthorityBaseUri";
                 public const string CredentialType = "azreposCredentialType";
                 public const string AzureAuthority = "azureAuthority";
+                public const string ServicePrincipal = "azreposServicePrincipal";
+                public const string ServicePrincipalSecret = "azreposServicePrincipalSecret";
+                public const string ServicePrincipalCertificateThumbprint = "azreposServicePrincipalCertificateThumbprint";
+                public const string ManagedIdentity = "azreposManagedIdentity";
             }
         }
     }