Refresh Token flow
A Refresh Token is an opaque string that can be exchanged for an Access Token.
Refresh tokens typically have a long lifetime to avoid that users have to log in frequently.
Clients may obtain a refresh token by adding the offline_access to the scope query parameter during the Authorization Code with PKCE flow.
The refresh token can then be exchanged for an access and ID token as follows:
Your app sends a request to the Identity Suite Token endpoint. The
grant_type
has to berefresh_token
,client_id
andrefresh_token
have to be added to the request as POST parameters [1]:POST /auth/oauth/token HTTP/1.1
grant_type=refresh_token
&refresh_token=Z1FiWXJZV2...
&client_id=dbd00f622a1f805f
&client_secret=The token endpoint validates the client_id and refresh_token, and checks the user state. If the user is blocked [2], an error screen is shown. If all checks are successful, new tokens are issued and returned as a JSON response [1][3]:
{
"access_token":"ey...",
"refresh_token":"ey...",
"id_token":"ey...",
"token_type":"Bearer",
"expires_in":3600
}
Your app can now use the received access token to call a Resource Server.
- [1]: This is a simplified example. We omitted irrelevant headers, added line breaks, and truncated tokens to make the example easier to read.
- [2]: An ID Token is returned only if the scope openid is requested during the initial authentication code flow.
Refresh token revocation
You can revoke refresh and access tokens in case they become compromised. To revoke a refresh or access token, send a request with the token to https://put_your_Azure_domain_name_here/auth/oauth2/revoke
.
POST /auth/oauth2/revoke HTTP/1.1
Authorization: Basic base64(client_id:client_secret)
token=Z1FiWXJZV2...
The Authorization
header has to contain client_id
and client_secret
as Basic Auth credentials. If your application doesn't have a client_secret
, you can send any String as the client_secret
.
This can be tested on the command line using curl as follows:
export TOKEN=ZjNUREZxTEphY0hNaT...
curl 'https://put_your_Azure_domain_name_here/auth/oauth2/revoke' -i -X POST \
-H 'Authorization: Basic ZGJkMDBmNjIyYTFmODA1ZjpjbGllbnRfc2VjcmV0X2hlcmVfb3JfYW55X3N0cmluZw==' -d token=$TOKEN
This endpoint validates the client_id
and client_secret
and checks if the token was issued to the application sending the request. If this validation fails, the request is denied, and an error code is returned.
In case of successful validation, the endpoint revokes the token. The revocation takes place immediately, and the token cannot be used again.