Versions Compared
Key
- This line was added.
- This line was removed.
- Formatting was changed.
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.
Tip |
---|
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
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 |
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
Code Block |
---|
{ "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.
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
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.
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 } |
Div | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
IN THIS ARTICLE
|