Page Comparison

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.

Tip
You can download sample .NET framework code at https://dl.empowerid.com/OAuthTestSamplecode.zip

OAuth Discovery Endpoint

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

Authorization Code Grant

1. Initiate a login request to the EmpowerID Authorization

URL

endpoint, https://<EID Server>/oauth/v2/ui/authorize

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

id_token


 &scope=openid
 &state=xxxxxxxxxxxxxxxxxx
 &nonce=xxxxxxxxxxxxxxxxxx

&scope=openid

Request Parameter	Required/Optional	Description
`response_type`

=code —

required

Must be

"

code

"

to initiate authorization code flow. For OpenID Connect flowuse

"

code id_token

"

as

a

response type.

client_id

— This specifies

	required	Must be the EmpowerID OAuth application client identifier.
`redirect_`

uri — This specifies the client endpoint

uri

required

The client app URL to which the authorization server

should

will redirect after request approval

state — This is a

. This URL should be registered in the Callback URLs on the EmpowerID OAuth application.
`scope`	required	A space-separated list of strings that the user consents to. Values include `openid` for OpenID Connect flow.
`state`	optional	A random string value sent by the client to maintain session and prevent CSR attacks

nonce — This is a

nonce

optional

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

with the response parameters in the query string.

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

Response Parameter	Description
`state`

—

	The value sent by the client to maintain the session
`code`

code —

The authorization code generated by the authorization server

id_

token —

token

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

4. Exchange the code for an access

token.

token by calling the EmpowerID Token endpoint, https://<EID Server>/oauth/v2/token

Code Block

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

Request Parameter	Required/Optional	Description
`grant_type`

=

required

Must be authorization_code

— Must be “authorization_code” to continue

to initiate authorization code flow.

client_id

—

	required	Must be the EmpowerID OAuth application client identifier.
`client_`

secret —

`secret`	required	Must be the EmpowerID OAuth application client secret.
`code`	required

code —

The authorization code received from the authorization server

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

Code Block

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

Authorization Code Grant using .NET Client Library

Create a ClientSettings model, which contains consumerKey (

1. Initialize ClientSettings by passing the client_id

)

,

consumerSecret (

client_secret

)

,

callbackUrl (

redirect_uri

)

,

accessUrl, authorizeUrl, tokenInfoUrl, and userInfoUrl, and then

token_endpoint, authorization_endpoint, tokeninfo_endpoint and userinfo_endpoint. Also initialize a new AuthorizationCodeGrant

object

by passing

to it

the

ClientSettings

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 AuthorizationCodeGrant(clientSettings);

2. Call the BuildAuthorizationRequestPacket() method to build

the fully qualified URL to redirect to the authentication endpoint

authorization code flow parameters.

Code Block

//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

application’s callback method AuthorizationCodeGrantResponse() for example, extract the

“code”

code and

“state

state,

”

build an

AuthorizationResponseModel object

AuthorizationResponseModel model and send it to the GetAccessToken() method.

Code Block

public ActionResult AuthorizationCodeGrantResponse(AuthorizationResponseModel model)
{
  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 (Proof Key for Code Exchange) Extension

1. Initiate a login request to the EmpowerID Authorization

URL

endpoint, https://<EID Server>/oauth/v2/ui/authorize

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

method=S256

Request Parameter	Required/Optional	Description
`response_type`

=code —

required

Must be

"

code

"

to initiate authorization code flow

with PKCE extension

. For OpenID Connect flowuse

"

code id_token

"

as a response type.

client_id

— This specifies

	required	Must be the EmpowerID OAuth application client identifier.
`redirect_`

uri — This specifies the client endpoint

uri

required

The client app URL to which the authorization server

should

will 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

. This URL should be registered in the CallBack URLs on the EmpowerID OAuth application.
`scope`	required	A space-separated list of strings that the user consents to. Values include `openid` for OpenID Connect flow.
`code_challenge_method`	recommended	Specifies the transformation method used for the `code_challenge`. Permitted values are plain S256 Defaults to `plain` if not present in the request
`code_challenge`	required	The string 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

Please refer to the PKCE RFC for generating the Code Verifier.
`state`	optional	A random string value sent by the client to maintain session and prevent CSR attacks
`nonce`	optional	A random string value sent by client to uniquely identify each 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.

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

Response Parameter	Description
`state`

—

The value sent by the client to maintain the session

code —

`code`	The authorization code generated by the authorization server
`id_`

token —

token

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

4. Exchange

the code for an access token.

the code for an access token by calling the EmpowerID Token endpoint, https://<EID Server>/oauth/v2/token

Code Block

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

Request Parameter	Required/Optional	Description
`grant_type`

=

required

Must be authorization_code

— Must be “authorization_code” to continue

to initiate authorization code flow.

client_id

—

	required	Must be the EmpowerID OAuth application client identifier.
`client_`

secret —

`secret`	required	Must be the EmpowerID OAuth application client secret.
`code`	required

code —

The authorization code received from the authorization server

code_verifier

— The code_verifier

required

The Code Verifier valuegenerated by the client during the initial authorization request

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

Code Block

{
    "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

Create a ClientSettings model, which contains consumerKey (

1. Initialize ClientSettings by passing the client_id

)

,

consumerSecret (

client_secret

)

,

callbackUrl (

redirect_uri

)

,

accessUrl, authorizeUrl, tokenInfoUrl, and userInfoUrl, and then

token_endpoint, authorization_endpoint, tokeninfo_endpoint and userinfo_endpoint. Also initialize a new AuthorizationCodeGrant

object

by passing

to it

the

ClientSettings

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 AuthorizationCodeGrant(clientSettings);

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

Code Block

//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

application’s callback method AuthorizationCodeGrantWithPKCE() for example, extract the

“code” and “state,” build an AuthorizationResponseModel object

code ,state and the generated code_verifier , build an AuthorizationResponseModel model and send it to the GetAccessToken() method.

Code Block

public ActionResult AuthorizationCodeGrantWithPKCE(AuthorizationCodeGrantViewModel model)
{
  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

endpoint, https://<EID Server>/oauth/v2/ui/authorize

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

id_token


 &scope=openid
 &state=xxxxxxxxxxxxxxxxxx
 &nonce=xxxxxxxxxxxxxxxxxx

Request Parameter	Required/Optional	Description
`response_type`

=code —

required

Must be

“token”

token to initiate

authorization code

implicit grant flow. ForOpenID

connect

Connect flowuse

“token

token id_

token”

token as a response type.

client_id

—

required

Must be the EmpowerID OAuth application

client identifierredirect_uri — Client endpoint

client identifier.
`redirect_uri`	required	The client app URL to which the authorization server

should

will redirect after request approval

state — Random

. This URL should be registered in the CallBack URLs on the EmpowerID OAuth application.
`scope`	required	A space-separated list of strings that the user consents to. Values include `openid` for OpenID Connect flow.
`state`	optional	A random string value sent by the client to maintain session and prevent CSR attacks

nonce — Random


`nonce`	optional	A random string value sent by client to uniquely identify each

request

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

request

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.

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

Code Block

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

Header Parameter	Required/Optional	Description
`Authorization`

—

	required	Base64 encoded value of the username and password of the EmpowerID Person requesting the token.
`Content-Type`

—

required

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

Post Body Parameter	Required/Optional	Description
`client_`

id —

id

required

Must be the EmpowerID OAuth application client

identitfier

identifier.

client_secret

—

	required	Must be the EmpowerID OAuth application client secret.
`grant_type`

=password —

required

Must be

"

password

for resource owner password grant type

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


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

2. Returns access token and refresh token (optionally

id_

ID token) in the response

Code Block

{
    "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

Create a ClientSettings model, which contains consumerKey (

1. Initialize ClientSettings by passing the client_id

)

,

consumerSecret (

client_secret

)

,

callbackUrl (

redirect_uri

)

,

accessUrl, authorizeUrl, tokenInfoUrl, and userInfoUrl, and then

token_endpoint, authorization_endpoint, tokeninfo_endpoint and userinfo_endpoint. Also initialize a new ResourceOwnerPasswordGrant

object

by passing

to it

the

ClientSettings

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 ResourceOwnerPasswordGrant(clientSettings);

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

Code Block

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

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

Headers

Header Parameter	Required/Optional	Description
`Content-Type`

— application

required

Must be application/x-www-

form

from-form-urlencoded.

Post Body Parameter	Required/Optional	Description
`client_`

id —

id

required

Must be the EmpowerID OAuth application client

identitfier

identifier.

client_secret

—

required

Must be the EmpowerID OAuth application client secret

assertion — Please refer to the Generate JWT Assertion section below

.

grant_type

=

required

Must be 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

`bearer`
`scope`	required	A space-separated list of strings that the user consents to. Values include `openid` for OpenID Connect flow.
`assertion`	required	Must be JWT assertion string. Please refer to the Generate JWT Assertion section below.

2. Returns access token and refresh token (optionally

id_

ID token) in the response

Code Block

{
    "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

base64(

Sign

sign(

JWT Assertion

<JWT Assertion>))

Code Block

{
    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

Create a ClientSettings model, which contains consumerKey (

1. Initialize ClientSettings by passing the client_id

)

,

consumerSecret (

client_secret

)

,

callbackUrl (

redirect_uri

)

,

accessUrl, authorizeUrl, tokenInfoUrl, and userInfoUrl, and then

token_endpoint, authorization_endpoint, tokeninfo_endpoint and userinfo_endpoint. Also initialize a new JWTBearerGrant

object

by passing

to it

the

ClientSettings

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 JWTBearerGrant (clientSettings);

2. Call the

GetAccessToken

GetAccessToken() method to retrieve

the “access

the access_

token”

token,

“refresh

refresh_

token”

token, and other token related information.

Code Block

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

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=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=

Header Parameter	Required/Optional	Description
`Content-Type`	required	Must be `application/x-www-from-form-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 `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


`scope`	required	A space-separated list of strings that the user consents to. Values include `openid` for OpenID Connect flow.
`assertion`	required	Must be SAML assertion string. Please refer to Generate SAML Assertion section below.

2. Returns access token and refresh token (optionally

id_

ID token) in the response

Code Block

{
    "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

base64(

Sign

sign(

SAML Assertion

<SAML Assertion>)).

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

For <saml:Issuer>,

replace <EmpowerID

replace <EmpowerID OAuth Application

ClientID> with

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

replace <Signing Certificate

Thumbprint> with

Thumbprint> with the thumbprint of your signing certificate
The value for <saml:AuthnContextClassRef> is a constant and must not be changed.

Code Block

<?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

Create a ClientSettings model, which contains consumerKey (

1. Initialize ClientSettings by passing the client_id

)

,

consumerSecret (

client_secret

)

,

callbackUrl (

redirect_uri

)

,

accessUrl, authorizeUrl, tokenInfoUrl, and userInfoUrl, and then

token_endpoint, authorization_endpoint, tokeninfo_endpoint and userinfo_endpoint. Also initialize a new ClientCertificateGrant

object

by passing

to it

the

ClientSettings

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 ClientCertificateGrant (clientSettings);

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

Code Block

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

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}

Headers

Header Parameter	Required/Optional	Description
`Content-Type`

—

required

Must be application/x-www-

form

from-form-urlencoded.

Post Body Parameter	Required/Optional	Description
`client_`

id —

id

required

Must be the EmpowerID OAuth application client

identitfier

identifier.

client_secret

—

	required	Must be the EmpowerID OAuth application client secret.
`grant_type`

=urefresh_token—

required

Must be

“refresh

refresh_

token” for refresh

token

grant type

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

Create a ClientSettings model, which contains consumerKey (

1. Initialize ClientSettings by passing the client_id

)

,

consumerSecret (

client_secret

)

,

callbackUrl (

redirect_uri

)

,

accessUrl, authorizeUrl, tokenInfoUrl, and userInfoUrl, and then

token_endpoint, authorization_endpoint, tokeninfo_endpoint and userinfo_endpoint. Also initialize a new RefreshTokenGrant

object

by passing

to it

the

ClientSettings

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 Info 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

access

 token}
&token_type_hint=refresh_token/access_token

Headers

Header Parameter	Required/Optional	Description
`Content-Type`

—

required

Must be application/x-www-

form

from-form-urlencoded.

Authorization

—

required

Base64 encoded value

of <clientID>:<clientSecret>

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

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

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

access

 token}
&token_type_hint=refresh_token/access_

tokenHeaders

token

Header Parameter	Required/Optional	Description
`Content-Type`

—

required

Must be application/x-www-

form

from-form-urlencoded.

Authorization

—

required

Base64 encoded value

of <clientID>:<clientSecret>

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

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

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={

Access

Your access token

of the user}Headers

Header Parameter	Required/Optional	Description
`Content-Type`

—

required

Must be application/x-www-

form

`from-form-urlencoded`.
`Authorization`	required	Base64 encoded value of ClientID and Client Secret `base64Encode(<client_id>:<client_secret>)`

Post Body

access_token — Must be access token string

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

style	float: left; position: fixed;

Live Search

size	large
labels	2020

IN THIS ARTICLE

Table of Contents

minLevel	2
maxLevel	4
style	none

Versions Compared

Old Version 18

New Version 19

Key

OAuth Discovery Endpoint

Authorization Code Grant

Authorization Code Grant using .NET Client Library

Authorization Code Grant with PKCE (Proof Key for Code Exchange) Extension

Authorization Code Grant with PKCE Extension using .NET Client Library

Implicit Grant

Resource Owner Password Grant

Resource Owner Password Grant using .NET Client Library

JWT (JSON Web Token) Bearer Grant

Generate JWT Assertion

JWT Bearer Grant using .NET Client Library

Client Certificate Grant

Generate SAML Assertion

Client Certificate Grant using .NET Client Library

Refresh Token Grant

Refresh Token Grant using .NET Client Library

Token Info Endpoint

Token Revoke Endpoint

User Info Endpoint