OAuth 2.0 Client Certificate Grant

The Client Certificate Grant is used to send a signed SAML assertion, along with the Client ID and Client Secret of the OAuth application you registered in EmpowerID to the EmpowerID token endpoint in exchange for an access token, a refresh token, and an ID token (when scope=openid). This article describes how to use this grant in your applications.

You can download sample .NET framework code at https://dl1.empowerid.com/files/OAuthTestSampleCode.zip

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

Header Parameter	Required/Optional	Description
`Content-Type`	required	Must be `application/x-www-form-urlencoded`.

Post Body Parameter	Required/Optional	Description

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

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.

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

IN THIS ARTICLE