Versions Compared
Key
- This line was added.
- This line was removed.
- Formatting was changed.
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://dl1.empowerid.com/files/OAuthTestSamplecode.zip |
OAuth Discovery Endpoint
https://<EID Server>/oauth/.well-know/openid-configuration
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.
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
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 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
|