Authorization code:
Secure and common flow. Recommended option for secure
server-side apps.
Resource owner password credentials:
To be used
only
for securely
hosted, first-party services. GitLab recommends against use of this flow.
Device Authorization Grant is not supported.
Issue 332682
proposes to add support.
The draft specification for
OAuth 2.1
specifically omits both the
Implicit grant and Resource Owner Password Credentials flows.
Refer to the
OAuth RFC
to find out
how all those flows work and pick the right one for your use case.
Authorization code (with or without PKCE) flow requires
application
to be
registered first via the
/profile/applications
page in your user’s account.
During registration, by enabling proper scopes, you can limit the range of
resources which the
application
can access. Upon creation, you obtain the
application
credentials:
Application ID
and
Client Secret
. The
Client Secret
must be kept secure
. It is also advantageous to keep the
Application ID
secret when your application architecture allows.
To
protect redirect-based flows
,
the OAuth specification recommends the use of “One-time use CSRF tokens carried in the state
parameter, which are securely bound to the user agent”, with each request to the
/oauth/authorize
endpoint. This can prevent
CSRF attacks
.
In the following sections you can find detailed instructions on how to obtain
authorization with each flow.
Authorization code with Proof Key for Code Exchange (PKCE)
The
PKCE RFC
includes a
detailed flow description, from authorization request through access token.
The following steps describe our implementation of the flow.
The Authorization code with PKCE flow, PKCE for short, makes it possible to securely perform
the OAuth exchange of client credentials for access tokens on public clients without
requiring access to the
Client Secret
at all. This makes the PKCE flow advantageous
for single page JavaScript applications or other client side apps where keeping secrets
from the user is a technical impossibility.
Before starting the flow, generate the
STATE
, the
CODE_VERIFIER
and the
CODE_CHALLENGE
.
The
STATE
a value that can’t be predicted used by the client to maintain
state between the request and callback. It should also be used as a CSRF token.
The
CODE_VERIFIER
is a random string, between 43 and 128 characters in length,
which use the characters
A-Z
,
a-z
,
0-9
,
-
,
.
,
_
, and
~
.
The
CODE_CHALLENGE
is an URL-safe base64-encoded string of the SHA256 hash of the
CODE_VERIFIER
The SHA256 hash must be in binary format before encoding.
In Ruby, you can set that up with
Base64.urlsafe_encode64(Digest::SHA256.digest(CODE_VERIFIER), padding: false)
.
For reference, a
CODE_VERIFIER
string of
ks02i3jdikdo2k0dkfodf3m39rjfjsdk0wk349rj3jrhf
when hashed
and encoded using the Ruby snippet above produces a
CODE_CHALLENGE
string
of
2i0WFA-0AerkjQm4X4oDEhqA17QIAKNjXpagHBXmO_U
.
Request authorization code. To do that, you should redirect the user to the
/oauth/authorize
page with the following query parameters:
This page asks the user to approve the request from the app to access their
account based on the scopes specified in
REQUESTED_SCOPES
. The user is then
redirected back to the specified
REDIRECT_URI
. The
scope parameter
is a space-separated list of scopes associated with the user.
For example,
scope=read_user+profile
requests the
read_user
and
profile
scopes.
The redirect includes the authorization
code
, for example:
With the authorization code returned from the previous request (denoted as
RETURNED_CODE in the following example), you can request an access_token, with
any HTTP client. The following example uses Ruby’s rest-client:
Before starting the flow, generate the
STATE
. It is a value that can’t be predicted
used by the client to maintain state between the request and callback. It should also
be used as a CSRF token.
Request authorization code. To do that, you should redirect the user to the
/oauth/authorize
page with the following query parameters:
This page asks the user to approve the request from the app to access their
account based on the scopes specified in
REQUESTED_SCOPES
. The user is then
redirected back to the specified
REDIRECT_URI
. The
scope parameter
is a space-separated list of scopes associated with the user.
For example,
scope=read_user+profile
requests the
read_user
and
profile
scopes.
The redirect includes the authorization
code
, for example:
With the authorization code returned from the previous request (shown as
RETURNED_CODE in the following example), you can request an access_token, with
any HTTP client. The following example uses Ruby’s rest-client:
In this flow, a token is requested in exchange for the resource owner credentials
(username and password).
The credentials should only be used when:
There is a high degree of trust between the resource owner and the client. For
example, the client is part of the device operating system or a highly
privileged application.
Other authorization grant types are not available (such as an authorization code).
Never store the user’s credentials and only use this grant type when your client
is deployed to a trusted environment, in 99% of cases
personal access tokens
are a better
choice.
Even though this grant type requires direct client access to the resource owner
credentials, the resource owner credentials are used for a single request and
are exchanged for an access token. This grant type can eliminate the need for
the client to store the resource owner credentials for future use, by exchanging
the credentials with a long-lived access token or refresh token.
To request an access token, you must make a POST request to
/oauth/token
with
the following parameters:
echo'grant_type=password&username=<your_username>&password=<your_password>'> auth.txt
curl --data"@auth.txt"--request POST "https://gitlab.example.com/oauth/token"
You can also use this grant flow with registered OAuth applications, by using
HTTP Basic Authentication with the application’s
client_id
and
client_secret
:
echo'grant_type=password&username=<your_username>&password=<your_password>'> auth.txt
curl --data"@auth.txt"--user client_id:client_secret \--request POST "https://gitlab.example.com/oauth/token"
Then, you receive a response containing the access token:
A token with
scope
read_repository
or
write_repository
can access Git over HTTPS. Use the token as the password.
The username must be
oauth2
, not your username:
If you didn't find what you were looking for,
search the docs
.
If you want help with something specific and could use community support,
post on the GitLab forum
.
For problems setting up or using this feature (depending on your GitLab
subscription).
