OAuth 2.0 Refresh Token Grant

The Refresh Token Grant is used to send a refresh token, along with the Client ID and Client Secret of the OAuth application you registered in EmpowerID to the EmpowerID token endpoint in exchange for a new access token, a refresh token, and an ID token (when scope=openid) when the previously issued access token has expired. This article describes how to use this grant in your applications.

tip

You can download sample .NET framework code at https://dl1.empowerid.com/files/OAuthTestSampleCode.zip.

Refresh Token Grant

1. Initiate a request to the EmpowerID Token endpoint, https://<EID Server>/oauth/v2/token

   POST /oauth/v2/token HTTP/1.1
   Host: <EID Server>
   Content-Type: application/x-www-form-urlencoded
   Cache-Control: no-cache
   
   client_id={The Client ID of the OAuth app you registered in EmpowerID}
   &client_secret={The Client Secret of the OAuth app you registered in EmpowerID}
   &grant_type=refresh_token
   &refresh_token={The refresh token received when requesting an access token}

   Header Parameter	Required/Optional	Description
   Content-Type	required	Must be application/x-www-from-urlencoded.

   Post Body Parameter	Required/Optional	Description
   client_id	required	Must be the EmpowerID OAuth application client identifier.
   client_secret	required	Must be the EmpowerID OAuth application client secret.
   grant_type	required	Must be refresh_token
   refresh_token	required	Refresh token string for retrieving a new access token

2. Returns a new access token and refresh token (optionally ID token) in the response

   {
     "access_token": "xxxxxxxxxxxxxxxxxxxxxx",
     "token_type": "Bearer",
     "expires_in": 3600,
     "refresh_token": "xxxxxxxxxxxxxxxxxxxxxx",
     "id_token": null,
     "id": "00000000-0000-0000-0000-000000000000"
   }

Refresh Token Grant using .NET Client Library

1. Initialize ClientSettings by passing the client_id, client_secret, redirect_uri, token_endpoint, authorization_endpoint, tokeninfo_endpoint and userinfo_endpoint. Also initialize a new RefreshTokenGrant by passing the clientSettings model.

   var clientSettings = new ClientSettings(
     "client_id",
     "client_secret",
     "redirect_uri",
     "https://<EID Server>/oauth/v2/token",
     "https://<EID Server>/oauth/v2/ui/authorize",
     "https://<EID Server>/oauth/v2/tokeninfo",
     "https://<EID Server>/oauth/v2/userinfo");
               
   var handler = new RefreshTokenGrant(clientSettings);

2. Call the GetAccessToken() method to retrieve the access_token, refresh_token, and other token related information.

   AccessTokenResponseModel responseModel = null;
   string refreshToken = "The refresh token you received when requesting the access token";
   try
   {
     responseModel = handler.GetAccessToken<AccessTokenResponseModel>
         (RequestMethod.POST,
         ParameterFormat.Json,
         refreshToken);           
   }
   catch (Exception e)
   {
     //Handle error
   }