...
OpenID Connect (OIDC) is an identity layer that sits on top of the OAuth 2.0
...
| 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
1. Initiate a login request to the EmpowerID Authorization endpoint, https://<EID Server>/oauth/v2/ui/authorize
| Code Block |
|---|
https://<EID Server>/oauth/v2/ui/authorize
?client_id=xxxxxxxxxxxxxxxxxx
&redirect_uri=https%3A%2F%2Ftestoauthapp.com%2FcallbackUrl
&response_type=code
&scope=openid
&state=xxxxxxxxxxxxxxxxxx
&nonce=xxxxxxxxxxxxxxxxxx |
...
Request Parameter
...
Required/Optional
...
Description
...
response_type
...
required
...
client_id
...
required
...
Must be the EmpowerID OAuth application client identifier.
...
redirect_uri
...
required
...
The client app URL to which the authorization server will redirect after request approval. This URL should be registered in the Callback URLs on the EmpowerID OAuth application.
...
scope
...
required
...
A space-separated list of strings that the user consents to. Values include openid for OpenID Connect flow.
...
state
...
optional
...
A random string value sent by the client to maintain session and prevent CSR attacks
...
nonce
...
optional
...
A random string value sent by client to uniquely identify each request
2. Authenticate using username and password or any of the allowed external identity providers.
3. 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 |
...
Response Parameter
...
Description
...
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
4. Exchange the code for an access token by calling the EmpowerID Token endpoint, https://<EID Server>/oauth/v2/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 |
...
Request Parameter
...
Required/Optional
...
Description
...
grant_type
...
required
...
Must be authorization_code to initiate authorization code flow.
...
client_id
...
required
...
Must be the EmpowerID OAuth application client identifier.
...
client_secret
...
required
...
Must be the EmpowerID OAuth application client secret.
...
code
...
required
...
The authorization code received from the authorization server
5. 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
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 AuthorizationCodeGrant 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 AuthorizationCodeGrant(clientSettings); |
2. Call the BuildAuthorizationRequestPacket() method to build authorization code flow parameters.
| Code Block |
|---|
//Generate random nonce and state
var nonce = Guid.NewGuid().ToString("N");
var state = Guid.NewGuid().ToString("N");
//Use the below code for "code" flow to build parameters
var parameters = handler.BuildAuthorizationRequestPacket
(ParameterFormat.FormUrlEncoded, state, null, nonce, null);
//Use the below 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); |
3. In the application’s callback method AuthorizationCodeGrantResponse() for example, extract the code and state, build an AuthorizationResponseModel model and send it to the GetAccessToken() method.
| Code Block |
|---|
public ActionResult AuthorizationCodeGrantResponse(AuthorizationResponseModel model)
{
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 }
} |
Authorization Code Grant with PKCE (Proof Key for Code Exchange) Extension
1. Initiate a login request to the EmpowerID Authorization endpoint, https://<EID Server>/oauth/v2/ui/authorize
| Code Block |
|---|
https://<EID Server>/oauth/v2/ui/authorize
?client_id=xxxxxxxxxxxxxxxxxx
&redirect_uri=https%3A%2F%2Ftestoauthapp.com%2FcallbackUrl
&response_type=code
&state=xxxxxxxxxxxxxxxxxx
&nonce=xxxxxxxxxxxxxxxxxx
&scope=openid
&code_challenge=xxxxxxxxxxxxxxxxxx
&code_challenge_method=S256 |
...
Request Parameter
...
Required/Optional
...
Description
...
response_type
...
required
...
client_id
...
required
...
Must be the EmpowerID OAuth application client identifier.
...
redirect_uri
...
required
...
The client app URL to which the authorization server will redirect after request approval. This URL should be registered in the Callback URLs on the EmpowerID OAuth application.
...
scope
...
required
...
A space-separated list of strings that the user consents to. Values include openid for OpenID Connect flow.
...
code_challenge_method
...
recommended
...
Specifies the transformation method used for the code_challenge. Permitted values are
plain
S256
Defaults to plain if not present in the request
...
code_challenge
...
required
...
The string derived from the code_verifier.
plain -
code_challenge = code_verifierS256 -
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
Please refer to the PKCE RFC for generating the Code Verifier.
...
state
...
optional
...
A random string value sent by the client to maintain session and prevent CSR attacks
...
nonce
...
optional
...
A random string value sent by client to uniquely identify each request
2. Authenticate using username and password or any of the allowed external identity providers.
3. 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 |
...
Response Parameter
...
Description
...
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
4. Exchange the code for an access token by calling the EmpowerID Token endpoint, https://<EID Server>/oauth/v2/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
&code_verifier=xxxxxxxxxxxxxxxxxx |
...
Request Parameter
...
Required/Optional
...
Description
...
grant_type
...
required
...
Must be authorization_code to initiate authorization code flow.
...
client_id
...
required
...
Must be the EmpowerID OAuth application client identifier.
...
client_secret
...
required
...
Must be the EmpowerID OAuth application client secret.
...
code
...
required
...
The authorization code received from the authorization server
...
code_verifier
...
required
...
5. 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 with PKCE Extension 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 AuthorizationCodeGrant 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 AuthorizationCodeGrant(clientSettings); |
2. Call the BuildAuthorizationRequestPacketWithPKCE() 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");
//Generate code_verifier
var unreservedChars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789.-_`";
Random random = new Random();
var code_verifier = new string(Enumerable.Repeat(unreservedChars, 43).Select(s => s[random.Next(s.Length)]).ToArray());
//Store the generated code_verifier in cookie for example
CookieHelper.SetCookieData("OAuthCodeVerifier", code_verifier);
//Generate code_challenge (if plain)
//var code_challenge = code_verifier;
//var code_challenge_method = "plain";
//Generate code_challenge (if S256)
var bytes = new SHA256CryptoServiceProvider().ComputeHash(Encoding.ASCII.GetBytes(code_verifier));
var code_challenge = Convert.ToBase64String(bytes).Split('=')[0].Replace('+', '-').Replace('/', '_');
var code_challenge_method = "S256";
//Use the below code for "code" flow to build parameters
var parameters = handler.BuildAuthorizationRequestPacketWithPKCE
(ParameterFormat.FormUrlEncoded, state, null, nonce, code_challenge, code_challenge_method, null);
//Use the below code for "code id_token" flow to build parameters
//var responseTypes = new List<ResponseType> { ResponseType.id_token };
//var parameters = handler.BuildAuthorizationRequestPacketWithPKCE
//(ParameterFormat.FormUrlEncoded, state, "openid", nonce, code_challenge, code_challenge_method, responseTypes);
//Generate redirect URL
var redirectUrl = string.Format("{0}?{1}", clientSettings.AuthorizeUrl, parameters); |
3. In the application’s callback method AuthorizationCodeGrantWithPKCE() for example, extract the code ,state and the generated code_verifier , build an AuthorizationResponseModel model and send it to the GetAccessToken() method.
| Code Block |
|---|
public ActionResult AuthorizationCodeGrantWithPKCE(AuthorizationCodeGrantViewModel model)
{
AuthorizationResponseModel authorizationResponseModel = new AuthorizationResponseModel() {Code = "xxxxxxx", State = state};
//Retrieve the code_verifier stored in the cookie
var code_verifier = CookieHelper.GetCookieData("OAuthCodeVerifier");
var additionalParams = new Dictionary<string, string>();
additionalParams["code_verifier"] = code_verifier;
AccessTokenResponseModel tokenResponseModel = null;
try
{
tokenResponseModel = handler.GetAccessToken<AccessTokenResponseModel>(
RequestMethod.POST,
ParameterFormat.FormUrlEncoded,
authorizationResponseModel,
false,
null,
additionalParams);
}
catch { //Handle error }
} |
Implicit Grant
1. Initiate a login request to the EmpowerID Authorization endpoint, https://<EID Server>/oauth/v2/ui/authorize
| Code Block |
|---|
https://<EID Server>/oauth/v2/ui/authorize
?client_id=xxxxxxxxxxxxxxxxxx
&redirect_uri=https%3A%2F%2Ftestoauthapp.com%2FcallbackUrl
&response_type=token
&scope=openid
&state=xxxxxxxxxxxxxxxxxx
&nonce=xxxxxxxxxxxxxxxxxx |
...
Request Parameter
...
Required/Optional
...
Description
...
response_type
...
required
...
client_id
...
required
...
Must be the EmpowerID OAuth application client identifier.
...
redirect_uri
...
required
...
The client app URL to which the authorization server will redirect after request approval. This URL should be registered in the Callback URLs on the EmpowerID OAuth application.
...
scope
...
required
...
A space-separated list of strings that the user consents to. Values include openid for OpenID Connect flow.
...
state
...
optional
...
A random string value sent by the client to maintain session and prevent CSR attacks
...
nonce
...
optional
...
A random string value sent by client to uniquely identify each request
2. Authenticate using Username, Password or any of the allowed external identity providers.
3. 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
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
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 |
...
Header Parameter
...
Required/Optional
...
Description
...
Authorization
...
required
...
Base64 encoded value of the username and password of the EmpowerID Person requesting the token base64Encode(<username>:<password>)
...
Content-Type
...
required
...
Must be application/x-www-form-urlencoded.
...
Post Body Parameter
...
Required/Optional
...
Description
...
client_id
...
required
...
Must be the EmpowerID OAuth application client identifier.
...
client_secret
...
required
...
Must be the EmpowerID OAuth application client secret.
...
grant_type
...
required
...
Must be password
...
scope
...
required
...
A space-separated list of strings that the user consents to. Values include openid for OpenID Connect flow.
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"
} |
Resource Owner Password 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 ResourceOwnerPasswordGrant 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 ResourceOwnerPasswordGrant(clientSettings); |
2. 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 (JSON Web Token) Bearer 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:jwt-bearer
&assertion=xxxxxxxxxxxxxxxxxx
&scope=openid |
...
Header Parameter
...
Required/Optional
...
Description
...
Content-Type
...
required
...
Must be application/x-www-form-urlencoded.
...
Post Body Parameter
...
Required/Optional
...
Description
...
client_id
...
required
...
Must be the EmpowerID OAuth application client identifier.
...
client_secret
...
required
...
Must be the EmpowerID OAuth application client secret.
...
grant_type
...
required
...
Must be urn:ietf:params:oauth:grant-type:jwt-bearer
...
scope
...
required
...
A space-separated list of strings that the user consents to. Values include openid for OpenID Connect flow.
...
assertion
...
required
...
Must be JWT assertion string. Please refer to the Generate JWT 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 JWT Assertion
1. 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
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 JWTBearerGrant 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 JWTBearerGrant (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
} |
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
...
Content-Type
...
required
...
Must be application/x-www-form-urlencoded.
...
Post Body Parameter
...
Required/Optional
...
Description
...
client_id
...
required
...
Must be the EmpowerID OAuth application client identifier.
...
client_secret
...
required
...
Must be the EmpowerID OAuth application client secret.
...
grant_type
...
required
...
Must be urn:ietf:params:oauth:grant-type:certificate-bearer
...
scope
...
required
...
A space-separated list of strings that the user consents to. Values include openid for OpenID Connect flow.
...
assertion
...
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
} |
Refresh Token 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=refresh_token
&refresh_token={The refresh token received when requesting an access token} |
...
Header Parameter
...
Required/Optional
...
Description
...
Content-Type
...
required
...
Must be application/x-www-from-urlencoded.
...
Post Body Parameter
...
Required/Optional
...
Description
...
client_id
...
required
...
Must be the EmpowerID OAuth application client identifier.
...
client_secret
...
required
...
Must be the EmpowerID OAuth application client secret.
...
grant_type
...
required
...
Must be refresh_token
...
refresh_token
...
required
...
Refresh token string for retrieving a new access token
2. Returns a new 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": null,
"id": "00000000-0000-0000-0000-000000000000"
} |
Refresh Token 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 RefreshTokenGrant 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 RefreshTokenGrant (clientSettings); |
2. 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 Exchange 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
Authorization: Basic base64Encode(<ClientID>:<ClientSecret>)
subject_token={Your token}
&subject_token_type={Your token type}
&grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&scope=openid |
...
Header Parameter
...
Required/Optional
...
Description
...
Content-Type
...
required
...
Must be application/x-www-from-urlencoded.
...
Authorization
...
required
...
Base64 encoded value of ClientID and Client Secret base64Encode(<client_id>:<client_secret>)
...
Post Body Parameter
...
Required/Optional
...
Description
...
subject_token
...
required
...
A security token that represents the identity of the party on behalf of whom the request is being made.
...
subject_toke_type
...
recommended
...
Specifies the type of the subject token. Please refer to allowed Token Type Identifiers
...
grant_type
...
required
...
Must be urn:ietf:params:oauth:grant-type:token-exchange
...
scope
...
required
...
A space-separated list of strings that the user consents to. Values include openid for OpenID Connect flow.
Returns token information in the response
| Code Block |
|---|
{
"access_token": "xxxxxxxxxxxxxxxxxxxxxx",
"token_type": "Bearer",
"issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
"expires_in": 3600,
"refresh_token": "xxxxxxxxxxxxxxxxxxxxxx",
"id_token": null,
"id": "00000000-0000-0000-0000-000000000000"
} |
Token Introspection Endpoint
1. 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 token}
&token_type_hint=refresh_token/access_token |
...
Header Parameter
...
Required/Optional
...
Description
...
Content-Type
...
required
...
Must be application/x-www-from-urlencoded.
...
Authorization
...
required
...
Base64 encoded value of ClientID and Client Secret base64Encode(<client_id>:<client_secret>)
...
Post Body Parameter
...
Required/Optional
...
Description
...
token
...
required
...
Must be the EmpowerID access token or refresh token
...
token_type_hint
...
recommended
...
Specifies the type of the token. Supported values are access_token or refresh_token. Defaults to access_token if not specified.
2. 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
1. 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 token}
&token_type_hint=refresh_token/access_token |
...
Header Parameter
...
Required/Optional
...
Description
...
Content-Type
...
required
...
Must be application/x-www-form-urlencoded.
...
Authorization
...
required
...
Base64 encoded value of ClientID and Client Secret base64Encode(<client_id>:<client_secret>)
...
Post Body Parameter
...
Required/Optional
...
Description
...
token
...
required
...
Must be the EmpowerID access token or refresh token
...
token_type_hint
...
recommended
...
Specifies the type of the token. Supported values are access_token or refresh_token. Defaults to access_token if not specified.
2. Returns null if the token has been successfully revoked
User Info Endpoint
1. 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={Your access token} |
...
Header Parameter
...
Required/Optional
...
Description
...
Content-Type
...
required
...
Must be application/x-www-form-urlencoded.
...
Authorization
...
required
...
Base64 encoded value of ClientID and Client Secret base64Encode(<client_id>:<client_secret>)
...
Post Body Parameter
...
Required/Optional
...
Description
...
token
...
required
...
Must be the EmpowerID access token
2. Returns user information in the response
| Code Block |
|---|
{
"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"
]
} |
RP-Initiated Logout
1. Initiate a request to the EmpowerID End Session endpoint, https://<EID Server>/oauth/v2/ui/logout
| Code Block |
|---|
https://<EID Server>/oauth/v2/ui/logout
?post_logout_redirect_uri=xxxxxxxxxxxxxxxxxx
&id_token_hint=eyJhbGciOiJSUzyVGE3cG.............ahi-cCrWZfcow
&global_logout=true
&state=xxxxxxxxxxxxxxxxxx |
...
Request Parameter
...
Required/Optional
...
Description
...
post_logout_redirect_uri
...
recommended
...
URL the user will be redirected to after logout is performed. This URL should be registered in the Callback URLs on the EmpowerID OAuth application. If not present in the request, after logout the user will be redirected to the IdP login page.
...
id_token_hint
...
optional
...
Previously issued ID Token which is used to identify the user’s current authenticated session with the client.
...
global_logout
...
optional
...
Determines whether to terminate the user’s IdP session and all the service providers the user is currently authenticated with. Permitted values are,
true- Terminate both IdP and all active service provider sessionsfalse- Terminate only IdP session
Defaults to true if not present in the request.
...
state
...
optional
...
A random string value sent by the client to maintain state. This value will be sent back to the RP in the callback endpoint specified by the post_logout_redirect_uri parameter.
2. Based on the global_logout parameter, the user’s IdP and active service provider sessions will be terminated. After successful logout the user will redirected to the IdP login page or the callback endpoint specified by the post_logout_redirect_uri parameter.
...
| style | float: left; position: fixed; |
|---|
| Live Search | ||
|---|---|---|
|
IN THIS ARTICLE
...
protocol for the purpose of authenticating users needing to access protected APIs. OIDC does not provide authorization; that is handled by an OAuth 2.0 flow that presents the authenticated identity to an authorization server. In OIDC, the mechanism for delivery of the identity information is a security token, known as an “ID Token.” The ID Token contains authentication claims about a user as a JSON Web Token (JWT). When delivered by EmpowerID, the claims payload in an ID Token look similar to that shown below. Note that more or less claims could be in the token.
| Code Block |
|---|
{
"iss": "EmpowerID",
"sub": "khmcclure",
"aud": "5c168a71-d47b-4321-bdba-648984e99521",
"iat": 1597961104,
"nbf": 1595282704,
"exp": 1600639504,
"oid": "9b592c74-c014-4536-bfac-f706a4c8d89f",
"name": "Kris McClure",
"email": "kris.mcclure@eiddocs.onmicrosoft.com",
"azp": "5c168a71-d47b-4321-bdba-648984e99521",
"at_hash": "EJ04K1puK2OfKrouc_7t_g",
"c_hash": "3sEvqXZmp2hillFqkfwEZg",
"jti": "66054b39-9ce2-49be-88b4-b1bd0aa39bfa"
} |
The definition of the claims in the above token are as follows:
Claim Type | Value | Description |
|---|---|---|
| EmpowerID | Identifies the entity that issued the token. See OAuth 2.0 Authorization framework, section 4.1.1 for more information about this claim type. |
| khmcclure | Identifies the principal that is the subject of the token. See OAuth 2.0 Authorization framework, section 4.1.2 for more information about this claim type. |
| 5c168a71-d47b-4321-bdba-648984e99521 | Identifies the recipients for which the token is intended. See OAuth 2.0 Authorization framework, section 4.1.3 for more information about this claim type. |
| 1597961104 | Identifies the time EmpowerID issued the token. See OAuth 2.0 Authorization framework, section 4.1.6 for more information about this claim type. |
| 1595282704 | Identifies the time before which the token MUST NOT be accepted for processing. See OAuth 2.0 Authorization framework, section 4.1.5 for more information about this claim type. |
| 1600639504 | Identifies the expiration time on or after which the token MUST NOT be accepted for processing. See OAuth 2.0 Authorization framework, section 4.1.4 for more information about this claim type. |
| 9b592c74-c014-4536-bfac-f706a4c8d89f | Person GUID that uniquely identifies the subject of the token in EmpowerID. |
| Kris McClure | Full name of the token subject. |
| kris.mcclure@eiddocs.onmicrosoft.com | Email address of the token subject registered in EmpowerID. |
| 5c168a71-d47b-4321-bdba-648984e99521 | The authorized party to whom the token was issued. |
| 224a879a-275b-4d77-94eb-bebd645384c8 | GUID that uniquely identifies the token. See OAuth 2.0 Authorization framework, section 4.1.7 for more information about this claim type. |
The sequence for authenticating using OIDC looks like that shown in the following image. As OIDC is used in OAuth 2.0 flows, the image is incomplete in that it only depicts the authentication stage of the flow. A more complete presentation of what occurs when using OpenID Connect in an OAuth 2.0 grant in EmpowerID is shown in the OAuth 2.0 Authorization Code Grant.
...
| Insert excerpt | ||||||
|---|---|---|---|---|---|---|
|