Skip to content

Commit 4d7a46c

Browse files
mjcheethammjcheetham
committed
docs: add generic OAuth documentation
1 parent b840042 commit 4d7a46c

File tree

2 files changed

+119
-1
lines changed

2 files changed

+119
-1
lines changed

‎docs/README.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ The following are links to GCM user support documentation:
1212
- [Host provider specification][gcm-host-provider]
1313
- [Azure Repos OAuth tokens][gcm-azure-tokens]
1414
- [GitLab support][gcm-gitlab]
15+
- [Generic OAuth support][gcm-oauth]
1516

1617
[gcm-azure-tokens]: azrepos-users-and-tokens.md
1718
[gcm-config]: configuration.md
@@ -23,4 +24,5 @@ The following are links to GCM user support documentation:
2324
[gcm-gitlab]: gitlab.md
2425
[gcm-host-provider]: hostprovider.md
2526
[gcm-net-config]: netconfig.md
26-
[gcm-usage]: usage.md
27+
[gcm-oauth]: generic-oauth.md
28+
[gcm-usage]: usage.md

‎docs/generic-oauth.md

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Generic Host Provider OAuth
2+
3+
Many Git hosts use the popular standard OAuth2 or OpenID Connect (OIDC)
4+
authentication mechanisms to secure repositories they host.
5+
Git Credential Manager supports any generic OAuth2-based Git host by simply
6+
setting some configuration.
7+
8+
## Registering an OAuth application
9+
10+
In order to use GCM with a Git host that supports OAuth you must first have
11+
registered an OAuth application with your host. The instructions on how to do
12+
this can be found with your Git host provider's documentation.
13+
14+
When registering a new application you should make sure to set an HTTP based
15+
redirect URL that points to `localhost`; for example:
16+
17+
```text
18+
http://localhost
19+
http://localhost:<port>
20+
http://127.0.0.1
21+
http://127.0.0.1:<port>
22+
```
23+
24+
Note that you cannot use an HTTPS redirect URL. GCM does not require a specific
25+
port number be used; if your Git host requires you to specify a port number in
26+
the redirect URL then GCM will use that. Otherwise an available port will be
27+
selected at the point authentication starts.
28+
29+
You must ensure that all scopes required to read and write to Git repositories
30+
have been granted for the application or else credentials that are generated
31+
will cause errors when pushing or fetching using Git.
32+
33+
As part of the registration process you should also be given a Client ID and,
34+
optionally, a Client Secret. You will need both of these to configure GCM.
35+
36+
## Configure GCM
37+
38+
In order to configure GCM to use OAuth with your Git host you need to set the
39+
following values in your Git configuration:
40+
41+
- Client ID
42+
- Client Secret (optional)
43+
- Redirect URL
44+
- Scopes (optional)
45+
- OAuth Endpoints
46+
- Authorization Endpoint
47+
- Token Endpoint
48+
- Device Code Authorzation Endpoint (optional)
49+
50+
OAuth endpoints can be found by consulting your Git host's OAuth app development
51+
documentation. The URLs can be either absolute or relative to the host name;
52+
for example: `https://example.com/oauth/authorize` or `/oauth/authorize`.
53+
54+
In order to set these values, you can run the following commands, where `<HOST>`
55+
is the hostname of your Git host:
56+
57+
```shell
58+
git config --global credential.<HOST>.oauthClientId <ClientID>
59+
git config --global credential.<HOST>.oauthClientSecret <ClientSecret>
60+
git config --global credential.<HOST>.oauthRedirectUri <RedirectURL>
61+
git config --global credential.<HOST>.oauthAuthorizeEndpoint <AuthEndpoint>
62+
git config --global credential.<HOST>.oauthTokenEndpoint <TokenEndpoint>
63+
git config --global credential.<HOST>.oauthScopes <Scopes>
64+
git config --global credential.<HOST>.oauthDeviceEndpoint <DeviceEndpoint>
65+
```
66+
67+
**Example commands:**
68+
69+
- `git config --global credential.https://example.com.oauthClientId C33F2751FB76`
70+
71+
- `git config --global credential.https://example.com.oauthScopes "code:write profile:read"`
72+
73+
**Example Git configuration**
74+
75+
```ini
76+
[credential "https://example.com"]
77+
oauthClientId = 9d886e36-5771-4f2b-8c8b-420c68ad5baa
78+
oauthClientSecret = 4BC5BD4704EAE28FD832
79+
oauthRedirectUri = "http://127.0.0.1"
80+
oauthAuthorizeEndpoint = "/login/oauth/authorize"
81+
oauthTokenEndpoint = "/login/oauth/token"
82+
oauthDeviceEndpoint = "/login/oauth/device"
83+
oauthScopes = "code:write profile:read"
84+
oauthDefaultUserName = "OAUTH"
85+
oauthUseClientAuthHeader = false
86+
```
87+
88+
### Additional configuration
89+
90+
Depending on the specific implementation of OAuth with your Git host you may
91+
also need to specify additional behavior.
92+
93+
#### Token user name
94+
95+
If your Git host requires that you specify a username to use with OAuth tokens
96+
you can either include the username in the Git remote URL, or specify a default
97+
option via Git configuration.
98+
99+
Example Git remote with username: `https://[email protected]/repo.git`.
100+
In order to use special characters you need to URL encode the values; for
101+
example `@` becomes `%40`.
102+
103+
By default GCM uses the value `OAUTH-USER` unless specified in the remote URL,
104+
or overriden using the `credential.<HOST>.oauthDefaultUserName` configuration.
105+
106+
#### Include client authentication in headers
107+
108+
If your Git host's OAuth implementation has specific requirements about whether
109+
the client ID and secret should or should not be included in an `Authorization`
110+
header during OAuth requests, you can control this using the following setting:
111+
112+
```shell
113+
git config --global credential.<HOST>.oauthUseClientAuthHeader <true|false>
114+
```
115+
116+
The default behavior is to include these values; i.e., `true`.

0 commit comments

Comments
 (0)