Token Validation

Learn more about the token validation process

The Purpose of Token Validation

Token validation is the process of verifying the authenticity and integrity of a token issued by HyperID.

Token validation is essential to guarantee that the tokens your application receives from HyperID are legitimate and have not been tampered with during transmission. By validating tokens, applications can ensure that only authorized users are granted access to certain resources or actions. This process helps prevent unauthorized access and protects sensitive data.

Additionally, tokens have a limited lifespan for security reasons, and using an expired token should be avoided. Therefore, it is advisable to verify a token's expiration status before utilizing it.

Local Validation vs. HyperID API Call Validation

In the context of token validation, there are two primary approaches: local validation and HyperID validation via an API call.

Local validation involves inspecting tokens directly within your application. This method is advantageous because it's faster, since it doesn't require an additional API call to HyperID. Instead, you can validate the token's authenticity locally, which significantly reduces the response time.

On the other hand, API-based validation offers advanced token checking, resulting in enhanced security. By leveraging API calls, you can perform token validation in real time. You can also immediately detect any revocation, compromise, or change in user permissions, thereby strengthening your application's security posture.

Moreover, this approach ensures that token validation logic remains securely confined to the server side. You can leverage HyperID's scalability and dynamic updates for token validation to further enhance your application's resilience and adaptability.

What to Check Locally

When performing local validation, it's important to check everything you can, with a focus on the following token parameters (as detailed in the Token Payload Insights chapter):

• exp: Verify whether the token has expired.

• iss, aud: Verify if the token was issued by HyperID (equals to 'https://login-stage.hypersecureid.com/auth/realms/HyperID').

• azp: Verify if it is the same as your application's ClientID to which the token was issued.

• scope: Verify if it contains all the requested scopes (including any extras).

In some cases, you can also perform local token signature verification. For instance, if the alg (algorithm) in the token header equals 'RS256', you can also found a kid (key ID) there, which is needed to retrieve certificate. You can obtain the required certificate from the HyperID Certificates Endpoint.

How to Validate Tokens using an API Call

To validate a token through an API call, you'll need to make an HTTP request to HyperID's validation endpoint, passing the token as part of the request. HyperID's servers will then verify the token's authenticity and respond with the validation result. This approach is ideal if you need to ensure the token's status in real time, or if you have specific security requirements.

Request

POST /auth/realms/HyperID/protocol/openid-connect/token/introspect HTTP/1.1
Host: login.hypersecureid.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 118

token_type_hint=access_token
&token=your.access.token
&client_id=your_app_client_id
&client_secret=your_app_client_secret

token_type_hint contains the type of token (either access_token or refresh_token), followed by the token parameter, which holds the actual token for introspection. As usual, the client_id and client_secret are obtained from your client's configuration settings (see to the Client Registration chapter for details).

If the token has expired or is invalid, the response is as follows:

Response (invalid token)

HTTP/1.1 200 OK
Content-Type: application/json
{
   "active": false
}

Otherwise, if the token is valid, you will receive information about the token:

Response (valid token)

HTTP/1.1 200 OK
Content-Type: application/json
{
      "exp":1643666400,
      "iat":1640988000,
      "auth_time":1640988000,
      "iss":"https://login.hypersecureid.com/auth/realms/HyperID",
      "sub":"916e0e2e-46d9-4b80-8856-dd9fedb1b723",
      "typ":"Access",
      "azp":"your_app_client_id",
      "email":"[e-mail]",
      "email_verified":true,
      "scope":"email",
      "active":true
}

Token Validation Examples

cURL

curl --location 'http://login.hypersecureid.com/auth/realms/HyperID/protocol/openid-connect/token/introspect' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token_type_hint=access_token' \
--data-urlencode 'token=your.access.token' \
--data-urlencode 'client_id=your_app_client_id' \
--data-urlencode 'client_secret=your_app_client_secret'

JavaScript

var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/x-www-form-urlencoded");

var urlencoded = new URLSearchParams();
urlencoded.append("token_type_hint", "access_token");
urlencoded.append("token", "your.access.token");
urlencoded.append("client_id", "your_app_client_id");
urlencoded.append("client_secret", "your_app_client_secret");

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: urlencoded,
  redirect: 'follow'
};

fetch("http://login.hypersecureid.com/auth/realms/HyperID/protocol/openid-connect/token/introspect", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

NodeJS

const axios = require('axios');
const qs = require('qs');
let data = qs.stringify({
  'token_type_hint': 'access_token',
  'token': 'your.access.token',
  'client_id': 'your_app_client_id',
  'client_secret': 'your_app_client_secret' 
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'http://login.hypersecureid.com/auth/realms/HyperID/protocol/openid-connect/token/introspect',
  headers: { 
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Python

import http.client

conn = http.client.HTTPSConnection("login.hypersecureid.com")
payload = 'token_type_hint=access_token&token=your.access.token&client_id=your_app_client_id&client_secret=your_app_client_secret'
headers = {
  'Content-Type': 'application/x-www-form-urlencoded'
}
conn.request("POST", "/auth/realms/HyperID/protocol/openid-connect/token/introspect", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

C#

var options = new RestClientOptions("")
{
  MaxTimeout = -1,
};
var client = new RestClient(options);
var request = new RestRequest("http://login.hypersecureid.com/auth/realms/HyperID/protocol/openid-connect/token/introspect", Method.Post);
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
request.AddParameter("token_type_hint", "access_token");
request.AddParameter("token", "your.access.token");
request.AddParameter("client_id", "your_app_client_id");
request.AddParameter("client_secret", "your_app_client_secret");
RestResponse response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);