OAuth 2.0 Flows

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.

OAuth Discovery Endpoint

https://<EID Server>/oauth/.well-know/openid-configuration

Authorization Code Grant

1. Initiate a login request to the EmpowerID Authorization URL, https://<EID Server>/oauth/v2/ui/authorize

   https://<EID Server>/oauth/v2/ui/authorize
   ?client_id=xxxxxxxxxxxxxxxxxx
    &redirect_uri=https%3A%2F%2Ftestoauthapp.com%2FcallbackUrl
    &response_type=code id_token
    &state=xxxxxxxxxxxxxxxxxx
    &nonce=xxxxxxxxxxxxxxxxxx
    &scope=openid

   • response_type=code — Must be "code" to initiate authorization code flow. For OpenID Connect use "code id_token" as a response type.

   • client_id — This specifies the EmpowerID OAuth application client identifier

   • redirect_uri — This specifies the client endpoint to which the authorization server should redirect after request approval

   • state — This is a random string value sent by the client to maintain session and prevent CSR attacks

   • nonce — This is a random string value sent by client to uniquely identify each request

   • scope=openid — Include scope as id_token for OpenID Connect flow
     

2. Authenticate using username and password or any of the allowed external identity providers to authorize the request.

3. Authorization server redirects to the redirect_uri with the response parameters in the query string.

   https://testoauthapp.com/callbackUrl
   ?state=xxxxxxxxxxxxxxxxxx
    &code= xxxxxxxxxxxxxxxxxx
    &id_token= xxxxxxxxxxxxxxxxxx

   • state — The value sent by the client to maintain the session

   • code — The authorization code generated by the authorization server

   • id_token — The identity token issued by the authorization server for OpenID Connect flow
     

4. Exchange the code for an access token.

   https://<EID Server>/oauth/v2/token
   ?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=authorization_code
    &code=xxxxxxxxxxxxxxxxxx

   • grant_type=authorization_code — Must be “authorization_code” to continue authorization code flow

   • client_id — EmpowerID OAuth application client identifier

   • client_secret — EmpowerID OAuth application client secret

   • code — The authorization code received from the authorization server
     

5. Returns access token and refresh token in the response.

   {
       "access_token": "xxxxxxxxxxxxxxxxxxxxxx",
       "token_type": "Bearer",
       "expires_in": 3600,
       "refresh_token": "xxxxxxxxxxxxxxxxxxxxxx",
       "id_token": "xxxxxxxxxxxxxxxxxxxxxx",
       "id": "xxxxxxxxxxxxxxxxxxxxxx"
   }

Authorization Code Grant using .NET Client Library

1. Create a ClientSettings model, which contains consumerKey (client_id), consumerSecret (client_secret), callbackUrl (redirect_uri), accessUrl, authorizeUrl, tokenInfoUrl, and userInfoUrl, and then initialize a new AuthorizationCodeGrant object passing to it 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 AuthorizationCodeGrant(clientSettings);

2. Call the BuildAuthorizationRequestPacket() method to build the fully qualified URL to redirect to the authentication endpoint.

   //Generate random nonce and state
   var nonce = Guid.NewGuid().ToString("N");
   var state = Guid.NewGuid().ToString("N");
    
   //Use the below code for "code" flow to build parameters
   var parameters = handler.BuildAuthorizationRequestPacket
   (ParameterFormat.FormUrlEncoded, state, null, nonce, null);
           
   //Use the below code for "code id_token" flow to build parameters
   //var responseTypes = new List<ResponseType> { ResponseType.id_token };
   //var parameters = handler.BuildAuthorizationRequestPacket     
   //(ParameterFormat.FormUrlEncoded, state, "openid", nonce, responseTypes);
    
   //Generate redirect URL
   var redirectUrl = string.Format("{0}?{1}", clientSettings.AuthorizeUrl, parameters);

3. In the application Callback URL method, extract the “code” and “state,” build an AuthorizationResponseModel object and send it to the GetAccessToken() method.

   AuthorizationResponseModel authorizationResponseModel = new AuthorizationResponseModel() {Code = "xxxxxxx", State = state};
    
   AccessTokenResponseModel tokenResponseModel = null;
   try
   {
       tokenResponseModel = handler.GetAccessToken<AccessTokenResponseModel>(
           RequestMethod.POST,
           ParameterFormat.FormUrlEncoded,
           authorizationResponseModel,
           false);
   }
   catch {  //Handle error   }

Authorization Code Grant with PKCE Extension

1. Initiate a login request to the EmpowerID Authorization URL, https://<EID Server>/oauth/v2/ui/authorize

   https://<EID Server>/oauth/v2/ui/authorize
   ?client_id=xxxxxxxxxxxxxxxxxx
    &redirect_uri=https%3A%2F%2Ftestoauthapp.com%2FcallbackUrl
    &response_type=code id_token
    &state=xxxxxxxxxxxxxxxxxx
    &nonce=xxxxxxxxxxxxxxxxxx
    &scope=openid
    &code_challenge=xxxxxxxxxxxxxxxxxx
    &code_challenge_method=plain

   • response_type=code — Must be "code" to initiate authorization code flow with PKCE extension. For OpenID Connect use "code id_token" as a response type.

   • client_id — This specifies the EmpowerID OAuth application client identifier

   • redirect_uri — This specifies the client endpoint to which the authorization server should redirect after request approval

   • state — This is a random string value sent by the client to maintain session and prevent CSR attacks

   • nonce — This is a random string value sent by client to uniquely identify each request

   • scope=openid — Include scope as id_token for OpenID Connect flow

   • code_verifier — This is a high-entropy cryptographic random string using the unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", with a minimum length of 43 characters and a maximum length of 128 characters. This is generated internally by the client but NOT sent to the authorization server in the initial request

   • code_challenge — This string is derived from the code_verifier.

     • plain - code_challenge = code_verifier

     • S256 - code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

   • code_challenge_method — This specifies the transformation method used for the code_challenge. Permitted values are “plain” or “S256”. Defaults to “plain” if not present in the request
     

2. Authenticate using username and password or any of the allowed external identity providers to authorize the request.

3. Authorization server redirects to the redirect_uri with the response parameters in the query string.

   https://testoauthapp.com/callbackUrl
   ?state=xxxxxxxxxxxxxxxxxx
    &code= xxxxxxxxxxxxxxxxxx
    &id_token= xxxxxxxxxxxxxxxxxx

   • state — The value sent by the client to maintain the session

   • code — The authorization code generated by the authorization server

   • id_token — The identity token issued by the authorization server for OpenID Connect flow
     

4. Exchange the code for an access token.

   https://<EID Server>/oauth/v2/token
   ?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=authorization_code
    &code=xxxxxxxxxxxxxxxxxx
    &code_verifier=xxxxxxxxxxxxxxxxxx

   • grant_type=authorization_code — Must be “authorization_code” to continue authorization code flow

   • client_id — EmpowerID OAuth application client identifier

   • client_secret — EmpowerID OAuth application client secret

   • code — The authorization code received from the authorization server

   • code_verifier — The code_verifier generated by the client during the initial authorization request
     

5. Returns access token and refresh token in the response.

   {
       "access_token": "xxxxxxxxxxxxxxxxxxxxxx",
       "token_type": "Bearer",
       "expires_in": 3600,
       "refresh_token": "xxxxxxxxxxxxxxxxxxxxxx",
       "id_token": "xxxxxxxxxxxxxxxxxxxxxx",
       "id": "xxxxxxxxxxxxxxxxxxxxxx"
   }

Authorization Code Grant with PKCE Extension using .NET Client Library

1. Create a ClientSettings model, which contains consumerKey (client_id), consumerSecret (client_secret), callbackUrl (redirect_uri), accessUrl, authorizeUrl, tokenInfoUrl, and userInfoUrl, and then initialize a new AuthorizationCodeGrant object passing to it 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 AuthorizationCodeGrant(clientSettings);

2. Call the BuildAuthorizationRequestPacketWithPKCE() method to build the fully qualified URL to redirect to the authentication endpoint.

   //Generate random nonce and state
   var nonce = Guid.NewGuid().ToString("N");
   var state = Guid.NewGuid().ToString("N");
   
   //Generate code_verifier
   var unreservedChars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789.-_`";
   Random random = new Random();
   var code_verifier = new string(Enumerable.Repeat(unreservedChars, 43).Select(s => s[random.Next(s.Length)]).ToArray());
   
   //Store the generated code_verifier in cookie for example
   CookieHelper.SetCookieData("OAuthCodeVerifier", code_verifier);
   
   //Generate code_challenge (if plain)
   //var code_challenge = code_verifier;
   //var code_challenge_method = "plain";
   
   //Generate code_challenge (if S256)
   var bytes = new SHA256CryptoServiceProvider().ComputeHash(Encoding.ASCII.GetBytes(code_verifier));
   var code_challenge = Convert.ToBase64String(bytes).Split('=')[0].Replace('+', '-').Replace('/', '_');
   var code_challenge_method = "S256";
   
   //Use the below code for "code" flow to build parameters
   var parameters = handler.BuildAuthorizationRequestPacketWithPKCE
   (ParameterFormat.FormUrlEncoded, state, null, nonce, code_challenge, code_challenge_method, null);
           
   //Use the below code for "code id_token" flow to build parameters
   //var responseTypes = new List<ResponseType> { ResponseType.id_token };
   //var parameters = handler.BuildAuthorizationRequestPacketWithPKCE
   //(ParameterFormat.FormUrlEncoded, state, "openid", nonce, code_challenge, code_challenge_method, responseTypes);
    
   //Generate redirect URL
   var redirectUrl = string.Format("{0}?{1}", clientSettings.AuthorizeUrl, parameters);

3. In the application Callback URL method, extract the “code” and “state,” build an AuthorizationResponseModel object and send it to the GetAccessToken() method.

   AuthorizationResponseModel authorizationResponseModel = new AuthorizationResponseModel() {Code = "xxxxxxx", State = state};
   
   //Retrieve the code_verifier stored in the cookie
   var code_verifier = CookieHelper.GetCookieData("OAuthCodeVerifier");
   var additionalParams = new Dictionary<string, string>();
   additionalParams["code_verifier"] = code_verifier;
   
   AccessTokenResponseModel tokenResponseModel = null;
   try
   {
       tokenResponseModel = handler.GetAccessToken<AccessTokenResponseModel>(
           RequestMethod.POST,
           ParameterFormat.FormUrlEncoded,
           authorizationResponseModel,
           false,
           null,
           additionalParams);
   }
   catch {  //Handle error   }

Implicit Grant

1. Initiate a login request to the EmpowerID Authorization URL, https://<EID Server>/oauth/v2/ui/authorize

   https://<EID Server>/oauth/v2/ui/authorize
   ?client_id=xxxxxxxxxxxxxxxxxx
    &redirect_uri=https%3A%2F%2Ftestoauthapp.com%2FcallbackUrl
    &response_type=token id_token
    &state=xxxxxxxxxxxxxxxxxx
    &nonce=xxxxxxxxxxxxxxxxxx

   • response_type=code — Must be “token” to initiate authorization code flow. For OpenID connect use “token id_token” as response type

   • client_id — EmpowerID OAuth application client identifier

   • redirect_uri  — Client endpoint to which the authorization server should redirect after request approval

   • state — Random string value sent by the client to maintain session and prevent CSR attacks

   • nonce — Random string value sent by client to uniquely identify each request 

   • scope=openid — Include scope as id_token for OpenID connect flow
     

2. Authenticate using Username, Password or any of the allowed external identity providers to authorize the request

3. Authorization server redirects to the redirect_uri with the response parameters in the fragment part of URL.

   https://testoauthapp.com/callbackUrl
   #access_token=xxxxxxxxxxxxxxxxxx
    &state=xxxxxxxxxxxxxxxxxx
    &token_type=Bearer
    &expires_in=3600
    &id_token= xxxxxxxxxxxxxxxxxx

 Resource Owner Password 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
   Authorization: Basic base64Encode(<username>:<password>)
   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=password
   &scope=openid

   
   Headers

   • Authorization — Base64 encoded value of the username and password of the EmpowerID Person requesting the token.

   • Content-Type — application/x-www-from-form-urlencoded
     

   Post Body

   • client_id — EmpowerID OAuth application client identitfier

   • client_secret — EmpowerID OAuth application client secret

   • grant_type=password — Must be "password for resource owner password grant type

   • scope=openid — Include scope as "id_token" for OpenID connect flow
     

2. Returns 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": "xxxxxxxxxxxxxxxxxxxxxx",
       "id": "xxxxxxxxxxxxxxxxxxxxxx"
   }

Resource Owner Password Grant using .NET Client Library

1. Create a ClientSettings model, which contains consumerKey (client_id), consumerSecret (client_secret), callbackUrl (redirect_uri), accessUrl, authorizeUrl, tokenInfoUrl, and userInfoUrl, and then initialize a new ResourceOwnerPasswordGrant object passing to it 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 ResourceOwnerPasswordGrant(clientSettings);

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

   AccessTokenResponseModel responseModel = null;
   try
   {
        responseModel = handler.GetAccessToken<AccessTokenResponseModel>
           (RequestMethod.POST,
           ParameterFormat.FormUrlEncoded,
           “username”,
           “password”,
           “openid”);
   }
   catch (Exception e)
   {
        //Handle error
   }

JWT Bearer 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=urn:ietf:params:oauth:grant-type:jwt-bearer
   &assertion=xxxxxxxxxxxxxxxxxx
   &scope=openid

   
   Headers

   • Content-Type — application/x-www-form-form-urlencoded
     

   Post Body

   • client_id — EmpowerID OAuth application client identitfier

   • client_secret — EmpowerID OAuth application client secret

   • assertion — Please refer to the Generate JWT Assertion section below

   • grant_type= urn:ietf:params:oauth:grant-type:jwt-bearer – Must be “urn:ietf:params:oauth:grant-type:jwt-bearer” for JWT Bearer grant type

   • scope=openid — Include scope as "id_token" for OpenID connect flow
     

2. Returns 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": "xxxxxxxxxxxxxxxxxxxxxx",
       "id": "xxxxxxxxxxxxxxxxxxxxxx"
   }

Generate JWT Assertion

1. The JWT assertion should follow the below format and be signed with the signing certificate and converted to Base64 string - Base64 (Sign (JWT Assertion))

   {
       Issuer: <EmpowerID OAuth application client identifier>
       Subject: <Signing Certificate Thumbprint>
       Audience:  https://<EID Server>/WebIdPForms/OAuth/v2
       IssuedAt: UnixTime(DateTime.UtcNow)
       NotBefore: UnixTime(DateTime.UtcNow – 5 minutes)
       Expiration: UnixTime(DateTime.UtcNow + 5 minutes)
   }

JWT Bearer Grant using .NET Client Library

1. Create a ClientSettings model, which contains consumerKey (client_id), consumerSecret (client_secret), callbackUrl (redirect_uri), accessUrl, authorizeUrl, tokenInfoUrl, and userInfoUrl, and then initialize a new JWTBearerGrant object passing to it 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 JWTBearerGrant (clientSettings);

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

   AccessTokenResponseModel responseModel = null;
   String certificateThumbprint= “xxxxxxxxxxxxxxxxxxxxx”;
   try
   {
      var signingCert = handler.GetSigningCertificate(certificateThumbprint);
      responseModel = handler.GetAccessToken<AccessTokenResponseModel>
           (RequestMethod.POST,
            ParameterFormat.Json,
            signingCert);           
   }
   catch (Exception e)
   {
        //Handle error
   }

Client Certificate 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=urn:ietf:params:oauth:grant-type:certificate-bearer
   &assertion=xxxxxxxxxxxxxxxxxx
   &scope=openid

   
   Headers

   • Authorization — Base64 encoded value of the username and password of the EmpowerID Person requesting the token.

   
   Post Body

   • client_id — EmpowerID OAuth application client identitfier

   • client_secret — EmpowerID OAuth application client secret

   • assertion – Please refer to Generate SAML Assertion section below

   • grant_type=urn:ietf:params:oauth:grant-type:certificate-bearer — Must be “urn:ietf:params:oauth:grant-type:certificate-bearer” for client credential grant type

   • scope=openid — Include scope as "id_token" for OpenID connect flow
     

2. Returns 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": "xxxxxxxxxxxxxxxxxxxxxx",
       "id": "xxxxxxxxxxxxxxxxxxxxxx"
   }

Generate SAML Assertion

1. The SAML assertion should follow the below format and be signed with the signing certificate and converted to Base64 string - Base64 (Sign (SAML Assertion)). 

   When using the below SAML assertion, please do the following:

   • For <saml:Issuer>, replace <EmpowerID OAuth Application ClientID> with the actual ClientID of the EmpowerID OAuth Application

   • For <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">, replace <Signing Certificate Thumbprint> with the thumbprint of your signing certificate

   The value for <saml:AuthnContextClassRef> is a constant and must not be changed.

   <?xml version="1.0"?>
   <saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Version="2.0" ID="_2f665070-6a35-4899-a113-234d8ffa7676" IssueInstant="2019-09-20T14:00:13.357Z">
     <saml:Issuer><EmpowerID OAuth Application ClientID></saml:Issuer>
     <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
       <SignedInfo>
         <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
         <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
         <Reference URI="#_2f665070-6a35-4899-a113-234d8ffa7676">
           <Transforms>
             <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
             <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
               <InclusiveNamespaces xmlns="http://www.w3.org/2001/10/xml-exc-c14n#" PrefixList="#default saml ds xs xsi"/>
             </Transform>
           </Transforms>
           <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
           <DigestValue>dlp3Cn+. . .. . .. .. .. W5hXA=</DigestValue>
         </Reference>
       </SignedInfo>
       <SignatureValue>Q+Ftb+nyCD0Ey9qQ. . .... . . OsFtxAfopOcaprm4=</SignatureValue>
     </Signature>
     <saml:Subject>
       <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"><Signing Certificate Thumbprint></saml:NameID>
     </saml:Subject>
     <saml:Conditions/>
     <saml:AuthnStatement AuthnInstant="2019-09-20T14:00:13.638Z">
       <saml:AuthnContext>
   <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:X509</saml:AuthnContextClassRef>
       </saml:AuthnContext>
     </saml:AuthnStatement>
   </saml:Assertion>

Client Certificate Grant using .NET Client Library

1. Create a ClientSettings model, which contains consumerKey (client_id), consumerSecret (client_secret), callbackUrl (redirect_uri), accessUrl, authorizeUrl, tokenInfoUrl, and userInfoUrl, and then initialize a new ClientCertificateGrant object passing to it 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 ClientCertificateGrant (clientSettings);

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

   AccessTokenResponseModel responseModel = null;
   String certificateThumbprint= “xxxxxxxxxxxxxxxxxxxxx”;
   try
   {
       var signingCert = handler.GetSigningCertificate(certificateThumbprint);
       responseModel = handler.GetAccessToken<AccessTokenResponseModel>
           (RequestMethod.POST,
            ParameterFormat.Json,
            signingCert);           
   }
   catch (Exception e)
   {
        //Handle error
   }

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}

   
   Headers

   • Content-Type — application/x-www-form-form-urlencoded

   
   Post Body

   • client_id — EmpowerID OAuth application client identitfier

   • client_secret — EmpowerID OAuth application client secret

   • grant_type=urefresh_token— Must be “refresh_token” for refresh token grant type

   • refresh_token — Refresh token string for retrieving a new access token
     

2. Returns a new access token and refresh 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. Create a ClientSettings model, which contains consumerKey (client_id), consumerSecret (client_secret), callbackUrl (redirect_uri), accessUrl, authorizeUrl, tokenInfoUrl, and userInfoUrl, and then initialize a new RefreshTokenGrant object passing to it 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 Info 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 access token}
   &token_type_hint=refresh_token/access_token

   
   Headers

   • Content-Type — application/x-www-form-form-urlencoded

   • Authorization — Base64 encoded value of <clientID>:<clientSecret>

   
   Post Body

   • token — Must be access token or refresh token string

   • token_type_hint=refresh_token or token_type_hint=access_token — Set to the value to refresh_token if the “token” is a refresh token string; else set to the value to access_token if the “token” is an access token string
     

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 access token}
   &token_type_hint=refresh_token/access_token

   
   Headers

   • Content-Type — application/x-www-form-form-urlencoded

   • Authorization — Base64 encoded value of <clientID>:<clientSecret>

   
   Post Body

   • token — Must be access token or refresh token string

   • token_type_hint=refresh_token or token_type_hint=access_token — Set to the value to refresh_token if the “token” is a refresh token string; else set to the value to access_token if the “token” is an access token string
     

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={Access token of the user}

   
   Headers

   • Content-Type — application/x-www-form-form-urlencoded

   
   Post Body

   • access_token — Must be access token string
     

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"
       ]
   }