Skip to content

Commit d6432f9

Browse files
mjcheethammjcheetham
authored
docs: add Azure Repos MI/SP docs (#1548)
Add documentation about Managed Identities and Service Principals for Azure Repos; how to configure them and use them with GCM. This will be useful for those that wish to adopt them as alternatives to PATs or other automated auth systems. [Rendered version](https://github.com/git-ecosystem/git-credential-manager/blob/8b93d631e315ca0d2563f28ce582439e19c0ac46/docs/azrepos-misp.md)
2 parents e51e1a4 + 8b93d63 commit d6432f9

File tree

2 files changed

+128
-1
lines changed

2 files changed

+128
-1
lines changed

‎docs/README.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,18 +11,19 @@ The following are links to GCM user support documentation:
1111
- [Credential stores][gcm-credstores]
1212
- [Host provider specification][gcm-host-provider]
1313
- [Azure Repos OAuth tokens][gcm-azure-tokens]
14+
- [Azure Managed Identities and Service Principals][gcm-misp]
1415
- [GitLab support][gcm-gitlab]
1516
- [Generic OAuth support][gcm-oauth]
1617

1718
[gcm-azure-tokens]: azrepos-users-and-tokens.md
1819
[gcm-config]: configuration.md
1920
[gcm-credstores]: credstores.md
20-
[gcm-dev]: development.md
2121
[gcm-enterprise-config]: enterprise-config.md
2222
[gcm-env]: environment.md
2323
[gcm-faq]: faq.md
2424
[gcm-gitlab]: gitlab.md
2525
[gcm-host-provider]: hostprovider.md
26+
[gcm-misp]: azrepos-misp.md
2627
[gcm-net-config]: netconfig.md
2728
[gcm-oauth]: generic-oauth.md
2829
[gcm-usage]: usage.md

‎docs/azrepos-misp.md

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Azure Managed Identities and Service Principals
2+
3+
Git Credential Manager supports Managed Identities and Service Principals for
4+
authentication with Azure Repos. This document provides an overview of Managed
5+
Identities and Service Principals and how to use them with GCM.
6+
7+
## Managed Identities
8+
9+
Azure Managed Identities can be used to authenticate and authorize applications
10+
and services to access Azure resources. Managed Identities are a secure way to
11+
access Azure resources without needing to store credentials in code or
12+
configuration files.
13+
14+
There are two types of Managed Identities:
15+
16+
**System-assigned**
17+
18+
System-assigned Managed Identities are tied to a specific Azure resource, such
19+
as a Virtual Machine or App Service. When a system-assigned Managed Identity is
20+
enabled, Azure creates an identity for the resource in the Azure AD tenant
21+
that's trusted by the subscription. The lifecycle of the identity is tied to the
22+
resource to which it's assigned.
23+
24+
**User-assigned**
25+
26+
User-assigned Managed Identities are created as standalone Azure resources and
27+
can be assigned to one or more Azure resources. This allows you to use the same
28+
Managed Identity across multiple resources.
29+
30+
You can read more about Managed Identities in the
31+
[Azure documentation][az-mi].
32+
33+
### How to configure Managed Identities
34+
35+
In order to use a Managed Identity with GCM, you need to ensure that the Managed
36+
Identity has the necessary permissions to access the Azure Repos repository.
37+
38+
You can read more about how to configure Managed Identities in the
39+
[Azure Repos documentation][azdo-misp].
40+
41+
Once you have configured the Managed Identity, you can use it with GCM by simply
42+
setting one of the following environment variables or Git configuration options:
43+
44+
**Git configuration:** [`credential.azreposManagedIdentity`][gcm-mi-config]
45+
46+
**Environment variable:** [`GCM_AZREPOS_MANAGEDIDENTITY`][gcm-mi-env]
47+
48+
Value|Description
49+
-|-
50+
`system`|System-Assigned Managed Identity
51+
`[guid]`|User-Assigned Managed Identity with the specified client ID
52+
`id://[guid]`|User-Assigned Managed Identity with the specified client ID
53+
`resource://[guid]`|User-Assigned Managed Identity for the associated resource
54+
55+
You can obtain the `[guid]` from the Azure Portal or by using the Azure CLI
56+
to inspect the Managed Identity or resource.
57+
58+
## Service Principals
59+
60+
Azure Service Principals are used to authenticate and authorize applications and
61+
services to access Azure resources. Service Principals are similar in many ways
62+
to Managed Identities (in fact Service Principals are used under the hood to
63+
implement Managed Identities), but they have expliclty defined credentials that
64+
are not managed by Azure.
65+
66+
There are a number of different ways to create and configure Service Principals,
67+
including using the Azure Portal or Azure CLI. You can read more about Service
68+
Principals in the [Azure documentation][az-sp].
69+
70+
### How to configure Service Principals
71+
72+
Much like with Managed Identities, to use a Service Principal with GCM you first
73+
need to ensure that the principal has the necessary permissions to access the
74+
Azure Repos repository.
75+
76+
You can read more about how to configure Service Principals in the
77+
[Azure Repos documentation][azdo-misp].
78+
79+
Once you have configured the Service Principal, you can use it with GCM by
80+
setting one of the following environment variables or Git configuration options:
81+
82+
**Git configuration:** [`credential.azreposServicePrincipal`][gcm-sp-config]
83+
84+
**Environment variable:** [`GCM_AZREPOS_SERVICE_PRINCIPAL`][gcm-sp-env]
85+
86+
The format of the value for these options must be in the format:
87+
88+
```text
89+
{tenantId}/{clientId}
90+
```
91+
92+
Where `{tenantId}` is the Azure tenant ID and `{clientId}` is the client ID of
93+
the Service Principal. These values can be found in the Azure Portal or by using
94+
the Azure CLI to inspect the Service Principal.
95+
96+
#### Authentication with Service Principals
97+
98+
When using a Service Principal with GCM, you will also need to provide the
99+
client secret or certificate that is associated with the Service Principal.
100+
101+
You can provide the client secret or certificate to GCM by setting one of the
102+
following environment variables or Git configuration options.
103+
104+
Type|Git Configuration|Environment Variable
105+
-|-|-
106+
Client Secret|[`credential.azreposServicePrincipalSecret`][gcm-sp-secret-config]|[`GCM_AZREPOS_SP_SECRET`][gcm-sp-secret-env]
107+
Certificate|[`credential.azreposServicePrincipalCertificateThumbprint`][gcm-sp-cert-config]|[`GCM_AZREPOS_SP_CERT_THUMBPRINT`][gcm-sp-cert-env]
108+
109+
The value for these options should be the client secret or the thumbrint of the
110+
certificate that is associated with the Service Principal.
111+
112+
The certificate itself should be installed on the machine where GCM is running
113+
and should be installed in personal store the certificate store for either the
114+
current user or the local machine.
115+
116+
[az-mi]: https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/overview
117+
[az-sp]: https://learn.microsoft.com/en-us/entra/identity-platform/app-objects-and-service-principals?tabs=browser
118+
[azdo-misp]: https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/service-principal-managed-identity?view=azure-devops
119+
[gcm-mi-config]: https://gh.io/gcm/config#credentialazreposmanagedidentity
120+
[gcm-mi-env]: https://gh.io/gcm/env#GCM_AZREPOS_MANAGEDIDENTITY
121+
[gcm-sp-config]: https://gh.io/gcm/config#credentialazreposserviceprincipal
122+
[gcm-sp-env]: https://gh.io/gcm/env#GCM_AZREPOS_SERVICE_PRINCIPAL
123+
[gcm-sp-secret-config]: https://gh.io/gcm/config#credentialazreposserviceprincipalsecret
124+
[gcm-sp-secret-env]: https://gh.io/gcm/env#GCM_AZREPOS_SP_SECRET
125+
[gcm-sp-cert-config]: https://gh.io/gcm/config#credentialazreposserviceprincipalcertificatethumbprint
126+
[gcm-sp-cert-env]: https://gh.io/gcm/env#GCM_AZREPOS_SP_CERT_THUMBPRINT

0 commit comments

Comments
 (0)