Commit a86de290 authored by Drew Blessing's avatar Drew Blessing Committed by Evan Read

Add OAuth Refresh Token documentation

parent 86abff01
......@@ -167,7 +167,11 @@ curl --header "Authorization: Bearer OAUTH-TOKEN" "https://gitlab.example.com/ap
Read more about [GitLab as an OAuth2 provider](oauth2.md).
NOTE:
We recommend that OAuth access tokens have an expiration. You can use a `refresh_token` to refresh tokens. Integrations may need to be updated to refresh tokens prior to expiration, which is based on the [expires_in](https://datatracker.ietf.org/doc/html/rfc6749#appendix-A.14) property in the token endpoint response.
We recommend OAuth access tokens have an expiration. You can use the `refresh_token` parameter
to refresh tokens. Integrations may need to be updated to use refresh tokens prior to
expiration, which is based on the [expires_in](https://datatracker.ietf.org/doc/html/rfc6749#appendix-A.14)
property in the token endpoint response. See [OAuth2 token](oauth2.md) documentation
for examples requesting a new access token using a refresh token.
A default refresh setting of two hours is tracked in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336598).
......
......@@ -124,6 +124,28 @@ Before starting the flow, generate the `STATE`, the `CODE_VERIFIER` and the `COD
}
```
1. To retrieve a new `access_token`, use the `refresh_token` parameter. Refresh tokens may
be used even after the `access_token` itself expires. This request:
- Invalidates the existing `access_token` and `refresh_token`.
- Sends new tokens in the response.
```ruby
parameters = 'client_id=APP_ID&client_secret=APP_SECRET&refresh_token=REFRESH_TOKEN&grant_type=refresh_token&redirect_uri=REDIRECT_URI&code_verifier=CODE_VERIFIER'
RestClient.post 'https://gitlab.example.com/oauth/token', parameters
```
Example response:
```json
{
"access_token": "c97d1fe52119f38c7f67f0a14db68d60caa35ddc86fd12401718b649dcfa9c68",
"token_type": "bearer",
"expires_in": 7200,
"refresh_token": "803c1fd487fec35562c205dac93e9d8e08f9d3652a24079d704df3039df1158f",
"created_at": 1628711391
}
```
NOTE:
The `redirect_uri` must match the `redirect_uri` used in the original
authorization request.
......@@ -182,6 +204,28 @@ be used as a CSRF token.
}
```
1. To retrieve a new `access_token`, use the `refresh_token` parameter. Refresh tokens may
be used even after the `access_token` itself expires. This request:
- Invalidates the existing `access_token` and `refresh_token`.
- Sends new tokens in the response.
```ruby
parameters = 'client_id=APP_ID&client_secret=APP_SECRET&refresh_token=REFRESH_TOKEN&grant_type=refresh_token&redirect_uri=REDIRECT_URI'
RestClient.post 'https://gitlab.example.com/oauth/token', parameters
```
Example response:
```json
{
"access_token": "c97d1fe52119f38c7f67f0a14db68d60caa35ddc86fd12401718b649dcfa9c68",
"token_type": "bearer",
"expires_in": 7200,
"refresh_token": "803c1fd487fec35562c205dac93e9d8e08f9d3652a24079d704df3039df1158f",
"created_at": 1628711391
}
```
NOTE:
The `redirect_uri` must match the `redirect_uri` used in the original
authorization request.
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment