- Created by Phillip Hanegan on Aug 17, 2020
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
Version 1 Next »
This topic describes how to consume the EmpowerID REST API with the different OAuth 2.0 flows. Please note that before you can use the framework with your application, you must register that application in EmpowerID. This generates an API Key, Client Secret and Client ID for your application.
You can download sample .NET framework code at https://dl1.empowerid.com/files/OAuthTestSamplecode.zip
OAuth Discovery Endpoint
https://<EID Server>/oauth/.well-know/openid-configuration
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 |
---|---|---|
| required | Must be |
Post Body Parameter | Required/Optional | Description |
---|---|---|
| required | Must be the EmpowerID OAuth application client identifier. |
| required | Must be the EmpowerID OAuth application client secret. |
| required | Must be |
| 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 }
Token Exchange Grant
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 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 |
---|---|---|
| required | Must be |
| required | Base64 encoded value of ClientID and Client Secret |
Post Body Parameter | Required/Optional | Description |
---|---|---|
| required | A security token that represents the identity of the party on behalf of whom the request is being made. |
| recommended | Specifies the type of the subject token. Please refer to allowed Token Type Identifiers |
| required | Must be |
| required | A space-separated list of strings that the user consents to. Values include |
Returns token information in the response
{ "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
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 |
---|---|---|
| required | Must be |
| required | Base64 encoded value of ClientID and Client Secret |
Post Body Parameter | Required/Optional | Description |
---|---|---|
| required | Must be the EmpowerID access token or refresh token |
| recommended | Specifies the type of the token. Supported values are |
2. Returns token information in the response
{ "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
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 |
---|---|---|
| required | Must be |
| required | Base64 encoded value of ClientID and Client Secret |
Post Body Parameter | Required/Optional | Description |
---|---|---|
| required | Must be the EmpowerID access token or refresh token |
| recommended | Specifies the type of the token. Supported values are |
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
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 |
---|---|---|
| required | Must be |
| required | Base64 encoded value of ClientID and Client Secret |
Post Body Parameter | Required/Optional | Description |
---|---|---|
| required | Must be the EmpowerID access token |
2. Returns user information in the response
{ "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" ] }
IN THIS ARTICLE
- No labels