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://dl.empowerid.com/OAuthTestSamplecode.zip |
OAuth Discovery Endpoint
https://<EID Server>/oauth/.well-know/openid-configuration
Authorization Code Grant
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 &Code Block response_type=code
response_type=code — Must be "code" to initiate authorization code flow. For OpenID connect use "code id_token" as a response type.
client_id — This specifies the EmpowerID OAuth application client identifier
redirect_uri — This specifies the client endpoint to which the authorization server should redirect after request approval
state — This is a random string value sent by the client to maintain session and prevent CSR attacks
nonce — This is a random string value sent by client to uniquely identify each request
scope=openid — Include scope as id_token for OpenID connect flow
Authenticate using username and password or any of the allowed external identity providers to authorize the request.
Authorization server redirects to the redirect_uri with the response parameters in the query string.
Code Block https://testoauthapp.com/callbackUrl ?state=xxxxxxxxxxxxxxxxxx &code= xxxxxxxxxxxxxxxxxx &id_token= xxxxxxxxxxxxxxxxxx
state — The value sent by the client to maintain the session
code — The authorization code generated by the authorization server
id_token — The identity token issued by the authorization server for OpenID connect flow
Exchange the code for an access token
Code Block 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
Authenticate using Username, Password or any of the allowed external identity providers to authorize the request
Authorization server redirects to the redirect_uri with the response parameters in the fragment part of URL.
Code Block |
---|
https://testoauthapp.com/callbackUrl
#access_token=xxxxxxxxxxxxxxxxxx
&state=xxxxxxxxxxxxxxxxxx
&token_type=Bearer
&expires_in=3600
&id_token= xxxxxxxxxxxxxxxxxx |
Resource Owner Password Grant
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 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
Headers
Authorization — Base64 encoded value of the username and password of the EmpowerID Person requesting the token.
Content-Type — application/x-www-from-form-urlencoded
Post Body
client_id — EmpowerID OAuth application client identitfier
client_secret — EmpowerID OAuth application client secret
grant_type=password — Must be "password for resource owner password grant type
scope=openid — Include scope as "id_token" for OpenID connect flow
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" }
Resource Owner Password Grant using .NET Client Library
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.
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 ResourceOwnerPasswordGrant(clientSettings);
Call the GetAccessToken() method to retrieve the access_token, refresh_token, and other token related information.
Code Block AccessTokenResponseModel responseModel = null; try { responseModel = handler.GetAccessToken<AccessTokenResponseModel> (RequestMethod.POST, ParameterFormat.FormUrlEncoded, “username”, “password”, “openid”); } catch (Exception e) { //Handle error }
JWT Bearer Grant
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:jwt-bearer &assertion=xxxxxxxxxxxxxxxxxx &scope=openid
Headers
Content-Type — application/x-www-form-form-urlencoded
Post Body
client_id — EmpowerID OAuth application client identitfier
client_secret — EmpowerID OAuth application client secret
assertion — Please refer to the Generate JWT Assertion section below
grant_type= urn:ietf:params:oauth:grant-type:jwt-bearer – Must be “urn:ietf:params:oauth:grant-type:jwt-bearer” for JWT Bearer grant type
scope=openid — Include scope as "id_token" for OpenID connect flow
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 JWT Assertion
The JWT assertion should follow the below format and be signed with the signing certificate and converted to Base64 string - Base64 (Sign (JWT Assertion))
Code Block { 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) }
JWT Bearer Grant using .NET Client Library
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.
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 JWTBearerGrant (clientSettings);
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 }
Client Certificate Grant
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
Headers
Authorization — Base64 encoded value of the username and password of the EmpowerID Person requesting the token.
Post Body
client_id — EmpowerID OAuth application client identitfier
client_secret — EmpowerID OAuth application client secret
assertion – Please refer to Generate SAML Assertion section below
grant_type=urn:ietf:params:oauth:grant-type:certificate-bearer — Must be “urn:ietf:params:oauth:grant-type:certificate-bearer” for client credential grant type
scope=openid — Include scope as "id_token" for OpenID connect flow
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 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.
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
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.
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);
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 }
Refresh Token Grant
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=refresh_token &refresh_token={The refresh token received when requesting an access token}
Headers
Content-Type — application/x-www-form-form-urlencoded
Post Body
client_id — EmpowerID OAuth application client identitfier
client_secret — EmpowerID OAuth application client secret
grant_type=urefresh_token— Must be “refresh_token” for refresh token grant type
refresh_token — Refresh token string for retrieving a new access token
Returns a new access token and refresh token in the response
Code Block { "access_token": "xxxxxxxxxxxxxxxxxxxxxx", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "xxxxxxxxxxxxxxxxxxxxxx", "id_token": null, "id": "00000000-0000-0000-0000-000000000000" }
Refresh Token Grant using .NET Client Library
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.
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 RefreshTokenGrant (clientSettings);
Call the GetAccessToken() method to retrieve the access_token, refresh_token, and other token related information.
Code Block 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 }
Token Info Endpoint
Initiate a request to the EmpowerID Token Information endpoint,
https://<EID Server>/oauth/v2/tokeninfo
Code Block 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
Headers
Content-Type — application/x-www-form-form-urlencoded
Authorization — Base64 encoded value of <clientID>:<clientSecret>
Post Body
token — Must be access token or refresh token string
token_type_hint=refresh_token or token_type_hint=access_token — Set to the value to refresh_token if the “token” is a refresh token string; else set to the value to access_token if the “token” is an access token string
Returns token information in the response
Code Block { "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" }
Token Revoke Endpoint
Initiate a request to the EmpowerID Token Revoke endpoint,
https://<EID Server>/oauth/v2/tokenrevoke
Code Block 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
Headers
Content-Type — application/x-www-form-form-urlencoded
Authorization — Base64 encoded value of <clientID>:<clientSecret>
Post Body
token — Must be access token or refresh token string
token_type_hint=refresh_token or token_type_hint=access_token — Set to the value to refresh_token if the “token” is a refresh token string; else set to the value to access_token if the “token” is an access token string
Returns null if the token has been successfully revoked
User Info Endpoint
Initiate a request to the EmpowerID User Information endpoint,
https://<EID Server>/oauth/v2/userinfo
Code Block 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}
Headers
Content-Type — application/x-www-form-form-urlencoded
Post Body
access_token — Must be access token string
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" ] }Code Block grant_type=authorization_code — Must be “authorization_code” to continue authorization code flow
client_id — EmpowerID OAuth application client identifier
client_secret — EmpowerID OAuth application client secret
code — The authorization code received from the authorization server
Returns access token and refresh token in the response
Code Block { "access_token": "xxxxxxxxxxxxxxxxxxxxxx", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "xxxxxxxxxxxxxxxxxxxxxx", "id_token": "xxxxxxxxxxxxxxxxxxxxxx", "id": "xxxxxxxxxxxxxxxxxxxxxx" }
Authorization Code Grant using .NET Client Library
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.
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 AuthorizationCodeGrant(clientSettings);
Call the BuildAuthorizationRequestPacket() method to build the fully qualified URL to redirect to the authentication endpoint.
Code Block //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.
Code Block 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 }
Implicit Grant
Initiate a login request to the EmpowerID Authorization URL
Code Block |
---|
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 |
response_type=code — Must be “token” to initiate authorization code flow. For OpenID connect use “token id_token” as response type
client_id — EmpowerID OAuth application client identifier
redirect_uri — Client endpoint to which the authorization server should redirect after request approval
state — Random string value sent by the client to maintain session and prevent CSR attacks
nonce — Random string value sent by client to uniquely identify each request
scope=openid — Include scope as id_token for OpenID connect flow
Live Search | ||||
---|---|---|---|---|
|
IN THIS ARTICLE
Table of Contents | ||||||
---|---|---|---|---|---|---|
|