Client Certificate Grant

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

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

Header Parameter	Required/Optional	Description
`Content-Type`	required	Must be `application/x-www-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`
`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 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. Initialize ClientSettings by passing the client_id, client_secret, redirect_uri, token_endpoint, authorization_endpoint, tokeninfo_endpoint and userinfo_endpoint. Also initialize a new ClientCertificateGrant 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 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
}

IN THIS ARTICLE