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 |
---|---|---|
| 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 | A space-separated list of strings that the user consents to. Values include |
| 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 ApplicationFor
<saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">
, replace <Signing Certificate Thumbprint> with the thumbprint of your signing certificateThe 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