Versions Compared

Old Version 2

changes.mady.by.user Phillip Hanegan

Saved on

compared with

New Version 3

changes.mady.by.user Phillip Hanegan

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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

Code Block
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

Code Block
{
    "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.

Code Block
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.

Code Block
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
}

Token Exchange Grant

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

Code Block
POST /oauth/v2/token HTTP/1.1
Host: <EID Server>
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache
Authorization: Basic base64Encode(<ClientID>:<ClientSecret>)
 
subject_token={Your token}
&subject_token_type={Your token type}
&grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&scope=openid

Header Parameter

Required/Optional

Description

Content-Type

required

Must be application/x-www-from-urlencoded.

Authorization

required

Base64 encoded value of ClientID and Client Secret base64Encode(<client_id>:<client_secret>)

Post Body Parameter

Required/Optional

Description

subject_token

required

A security token that represents the identity of the party on behalf of whom the request is being made.

subject_toke_type

recommended

Specifies the type of the subject token. Please refer to allowed Token Type Identifiers

grant_type

required

Must be urn:ietf:params:oauth:grant-type:token-exchange

scope

required

A space-separated list of strings that the user consents to. Values include openid for OpenID Connect flow.

  1. Returns token information in the response

Code Block
{
    "access_token": "xxxxxxxxxxxxxxxxxxxxxx",
    "token_type": "Bearer",
    "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "expires_in": 3600,
    "refresh_token": "xxxxxxxxxxxxxxxxxxxxxx",
    "id_token": null,
    "id": "00000000-0000-0000-0000-000000000000"
}

Token Introspection Endpoint

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

Code Block
POST /oauth/v2/tokeninfo HTTP/1.1
Host: <EID Server>
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache
Authorization: Basic base64Encode(<ClientID>:<ClientSecret>)
 
token={Your token}
&token_type_hint=refresh_token/access_token

Header Parameter

Required/Optional

Description

Content-Type

required

Must be application/x-www-from-urlencoded.

Authorization

required

Base64 encoded value of ClientID and Client Secret base64Encode(<client_id>:<client_secret>)

Post Body Parameter

Required/Optional

Description

token

required

Must be the EmpowerID access token or refresh token

token_type_hint

recommended

Specifies the type of the token. Supported values are access_token or refresh_token. Defaults to access_token if not specified.

2. Returns token information in the response

Code Block
{
    "active": true,
    "client_id": "Bearer",
    "username": {name of the user to whom the token belongs,
    "exp": 1555698438,
    "iat": 1555694839,
    "nbf": 1555694839,
    "sub": "xxxxxxxxxxxxx",
    "iss": "xxxxxxxxxxxxx"
}

Token Revoke Endpoint

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

Code Block
POST /oauth/v2/tokenrevoke HTTP/1.1
Host: <EID Server>
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache
Authorization: Basic base64Encode(<ClientID>:<ClientSecret>)
 
token={Your token}
&token_type_hint=refresh_token/access_token

Header Parameter

Required/Optional

Description

Content-Type

required

Must be application/x-www-form-urlencoded.

Authorization

required

Base64 encoded value of ClientID and Client Secret base64Encode(<client_id>:<client_secret>)

Post Body Parameter

Required/Optional

Description

token

required

Must be the EmpowerID access token or refresh token

token_type_hint

recommended

Specifies the type of the token. Supported values are access_token or refresh_token. Defaults to access_token if not specified.

2. Returns null if the token has been successfully revoked

User Info Endpoint

1. Initiate a request to the EmpowerID User Information endpoint, https://<EID Server>/oauth/v2/userinfo

Code Block
POST /oauth/v2/userinfo HTTP/1.1
Host: <EID Server>
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache
Authorization: Basic base64Encode(<ClientID>:<ClientSecret>)
 
access_token={Your access token}

Header Parameter

Required/Optional

Description

Content-Type

required

Must be application/x-www-form-urlencoded.

Authorization

required

Base64 encoded value of ClientID and Client Secret base64Encode(<client_id>:<client_secret>)

Post Body Parameter

Required/Optional

Description

token

required

Must be the EmpowerID access token

2. Returns user information in the response

Code Block
{
    "id": "d399765d-fcd7-45c9-913f-2b0c9e65f8b7",
    "username": "xxxxxxxxxxx",
    "first_name": " xxxxxxxxxxx ",
    "last_name": " xxxxxxxxxxx ",
    "email": " xxxxxxxxxxx",
    "organization": "Hosting Organization",
    "business_role_locations": [
        "Any Role in Anywhere",
        "Standard Employee in Anywhere",
        "All Employee Roles in Anywhere",
        "All Employee Roles in All Business Locations",
        "Any Role in All Business Locations",
        "Default Organization All Roles in All Business Locations",
        "Standard Employee in All Business Locations",
        "All Business Roles in Anywhere",
        "All Business Roles in Default Organization",
        "All Employee Roles in Default Organization",
        "Any Role in Default Organization",
        "Standard Employee in Default Organization"
    ]
}
Div
stylefloat: left; position: fixed;

IN THIS ARTICLE

Table of Contents
minLevel2
maxLevel4
stylenone