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://dl.empowerid.com/OAuthTestSamplecode.zip |
https://<EID Server>/oauth/.well-know/openid-configuration
Initiate a login request to the EmpowerID Authorization URL.
https://<EID Server>/oauth/v2/ui/authorize ?client_id=xxxxxxxxxxxxxxxxxx &redirect_uri=https%3A%2F%2Ftestoauthapp.com%2FcallbackUrl &response_type=code id_token &state=xxxxxxxxxxxxxxxxxx &nonce=xxxxxxxxxxxxxxxxxx &scope=openid |
Authorization server redirects to the redirect_uri with the response parameters in the query string.
https://testoauthapp.com/callbackUrl ?state=xxxxxxxxxxxxxxxxxx &code= xxxxxxxxxxxxxxxxxx &id_token= xxxxxxxxxxxxxxxxxx |
Exchange the code for an access token
https://<EID Server>/oauth/v2/token ?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=authorization_code &code=xxxxxxxxxxxxxxxxxx |
Returns access token and refresh token in the response
{ "access_token": "xxxxxxxxxxxxxxxxxxxxxx", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "xxxxxxxxxxxxxxxxxxxxxx", "id_token": "xxxxxxxxxxxxxxxxxxxxxx", "id": "xxxxxxxxxxxxxxxxxxxxxx" } |
Create a ClientSettings model, which contains consumerKey (client_id), consumerSecret (client_secret), callbackUrl (redirect_uri), accessUrl, authorizeUrl, tokenInfoUrl, and userInfoUrl, and then initialize a new AuthorizationCodeGrant object passing to it 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 AuthorizationCodeGrant(clientSettings); |
Call the BuildAuthorizationRequestPacket() method to build the fully qualified URL to redirect to the authentication endpoint.
//Generate random nonce and state var nonce = Guid.NewGuid().ToString("N"); var state = Guid.NewGuid().ToString("N"); //Use the below commented code for "code" flow to build parameters var parameters = handler.BuildAuthorizationRequestPacket (ParameterFormat.FormUrlEncoded, state, null, nonce, null); //Use the below commented code for "code id_token" flow to build parameters //var responseTypes = new List<ResponseType> { ResponseType.id_token }; //var parameters = handler.BuildAuthorizationRequestPacket //(ParameterFormat.FormUrlEncoded, state, "openid", nonce, responseTypes); //Generate redirect URL var redirectUrl = string.Format("{0}?{1}", clientSettings.AuthorizeUrl, parameters); |
In the application Callback URL method, extract the “code” and “state,” build an AuthorizationResponseModel object and send it to the GetAccessToken() method.
AuthorizationResponseModel authorizationResponseModel = new AuthorizationResponseModel() {Code = "xxxxxxx", State = state}; AccessTokenResponseModel tokenResponseModel = null; try { tokenResponseModel = handler.GetAccessToken<AccessTokenResponseModel>( RequestMethod.POST, ParameterFormat.FormUrlEncoded, authorizationResponseModel, false); } Catch { //Handle error } |
Initiate a login request to the EmpowerID Authorization URL
https://<EID Server>/oauth/v2/ui/authorize ?client_id=xxxxxxxxxxxxxxxxxx &redirect_uri=https%3A%2F%2Ftestoauthapp.com%2FcallbackUrl &response_type=token id_token &state=xxxxxxxxxxxxxxxxxx &nonce=xxxxxxxxxxxxxxxxxx |
Authorization server redirects to the redirect_uri with the response parameters in the fragment part of URL.
https://testoauthapp.com/callbackUrl #access_token=xxxxxxxxxxxxxxxxxx &state=xxxxxxxxxxxxxxxxxx &token_type=Bearer &expires_in=3600 &id_token= xxxxxxxxxxxxxxxxxx |
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 Authorization: Basic base64Encode(<username>:<password>) 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=password &scope=openid |
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" } |
Create a ClientSettings model, which contains consumerKey (client_id), consumerSecret (client_secret), callbackUrl (redirect_uri), accessUrl, authorizeUrl, tokenInfoUrl, and userInfoUrl, and then initialize a new ResourceOwnerPasswordGrant object passing to it 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 ResourceOwnerPasswordGrant(clientSettings); |
Call the GetAccessToken() method to retrieve the access_token, refresh_token, and other token related information.
AccessTokenResponseModel responseModel = null; try { responseModel = handler.GetAccessToken<AccessTokenResponseModel> (RequestMethod.POST, ParameterFormat.FormUrlEncoded, “username”, “password”, “openid”); } catch (Exception e) { //Handle error } |
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:jwt-bearer &assertion=xxxxxxxxxxxxxxxxxx &scope=openid |
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" } |
The JWT assertion should follow the below format and be signed with the signing certificate and converted to Base64 string - Base64 (Sign (JWT Assertion))
{ Issuer: <EmpowerID OAuth application client identifier> Subject: <Signing Certificate Thumbprint> Audience: https://<EID Server>/WebIdPForms/OAuth/v2 IssuedAt: UnixTime(DateTime.UtcNow) NotBefore: UnixTime(DateTime.UtcNow – 5 minutes) Expiration: UnixTime(DateTime.UtcNow + 5 minutes) } |
Create the ClientSettings model which contains consumerKey (client_id), consumerSecret (client_secret), callbackUrl (redirect_uri), accessUrl, authorizeUrl, tokenInfoUrl, and userInfoUrl.
Initialize JWTBearerGrant object by passing the ClientSettings configuration object.
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 JWTBearerGrant (clientSettings); |
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 } |
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 |
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" } |
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:
|
<?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> |
Create a ClientSettings model, which contains consumerKey (client_id), consumerSecret (client_secret), callbackUrl (redirect_uri), accessUrl, authorizeUrl, tokenInfoUrl, and userInfoUrl, and then initialize a new ClientCertificateGrant object passing to it 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); |
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 } |
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=refresh_token &refresh_token={The refresh token received when requesting an access token} |
Returns a new access token and refresh token in the response
{ "access_token": "xxxxxxxxxxxxxxxxxxxxxx", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "xxxxxxxxxxxxxxxxxxxxxx", "id_token": null, "id": "00000000-0000-0000-0000-000000000000" } |
Create a ClientSettings model, which contains consumerKey (client_id), consumerSecret (client_secret), callbackUrl (redirect_uri), accessUrl, authorizeUrl, tokenInfoUrl, and userInfoUrl, and then initialize a new RefreshTokenGrant object passing to it 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 RefreshTokenGrant (clientSettings); |
Call the GetAccessToken() method to retrieve the access_token, refresh_token, and other token related information.
AccessTokenResponseModel responseModel = null; String refreshToken= “The refresh token you received when requesting the access token”; try { responseModel = handler.GetAccessToken<AccessTokenResponseModel> (RequestMethod.POST, ParameterFormat.Json, refreshToken); } catch (Exception e) { //Handle error } |
Initiate a request to the EmpowerID Token Information endpoint, https://<EID Server>/oauth/v2/tokeninfo
POST /oauth/v2/tokeninfo HTTP/1.1 Host: <EID Server> Content-Type: application/x-www-form-urlencoded Cache-Control: no-cache Authorization: Basic base64Encode(<ClientID>:<ClientSecret>) token={Your access token} &token_type_hint=refresh_token/access_token |
Returns token information in the response
{ "active": true, "client_id": "Bearer", "username": {name of the user to whom the token belongs, "exp": 1555698438, "iat": 1555694839, "nbf": 1555694839, "sub": "xxxxxxxxxxxxx", "iss": "xxxxxxxxxxxxx" } |
Initiate a request to the EmpowerID Token Revoke endpoint, https://<EID Server>/oauth/v2/tokenrevoke
POST /oauth/v2/tokenrevoke HTTP/1.1 Host: <EID Server> Content-Type: application/x-www-form-urlencoded Cache-Control: no-cache Authorization: Basic base64Encode(<ClientID>:<ClientSecret>) token={Your access token} &token_type_hint=refresh_token/access_token |
Returns null if the token has been successfully revoked
Initiate a request to the EmpowerID User Information endpoint, https://<EID Server>/oauth/v2/userinfo
POST /oauth/v2/userinfo HTTP/1.1 Host: <EID Server> Content-Type: application/x-www-form-urlencoded Cache-Control: no-cache Authorization: Basic base64Encode(<ClientID>:<ClientSecret>) access_token={Access token of the user} |
Returns user information in the response
{ "id": "d399765d-fcd7-45c9-913f-2b0c9e65f8b7", "username": "xxxxxxxxxxx", "first_name": " xxxxxxxxxxx ", "last_name": " xxxxxxxxxxx ", "email": " xxxxxxxxxxx", "organization": "Hosting Organization", "business_role_locations": [ "Any Role in Anywhere", "Standard Employee in Anywhere", "All Employee Roles in Anywhere", "All Employee Roles in All Business Locations", "Any Role in All Business Locations", "Default Organization All Roles in All Business Locations", "Standard Employee in All Business Locations", "All Business Roles in Anywhere", "All Business Roles in Default Organization", "All Employee Roles in Default Organization", "Any Role in Default Organization", "Standard Employee in Default Organization" ] } |
|