Auth0 Integration: License Claims in Tokens
In short: an Auth0 Post Login Action runs while Auth0 signs a user in. The Action asks NetLicensing whether the user’s customer has a valid license, then puts the answer into the ID and access tokens as a custom claim, so your application sees the entitlement right after sign-in. The Action can also deny the login.
This guide uses Auth0 Actions, the replacement for the older Auth0 Rules. The older Labs64 NetLicensing-Auth0 sample is built on Rules, which are read-only since November 18, 2024 and reach end of life on January 31, 2028 (Auth0). Start new work with an Action.
What Auth0 runs and when
The post-login trigger runs when a user successfully authenticates against an application on your tenant, including authentication after signup, and when a refresh token is exchanged. Actions in this flow are blocking: Auth0 waits for the Action before it finishes the login. The Action is a JavaScript function:
exports.onExecutePostLogin = async (event, api) => { /* ... */ };
| Auth0 object | What you use it for |
|---|---|
event.user | Who signs in: email, email_verified, app_metadata and more |
event.organization | The Auth0 Organization of the login, if any: id, name, display_name, metadata |
event.secrets | Secret values you store with the Action, such as the NetLicensing API key |
api.idToken.setCustomClaim(key, value) | Adds a custom claim to the ID token |
api.accessToken.setCustomClaim(key, value) | Adds a custom claim to the access token |
api.access.deny(reason) | Stops the login; no further Actions run |
api.cache.get / set | A short-lived cache, see below |
What your Action does
| Auth0 step | What the Action does |
|---|---|
| The user signs in | The Action reads the customer’s identifier and calls validate licensee (POST /licensee/{licenseeNumber}/validate) |
| NetLicensing answers | The Action reads valid (and expires, for time-based models) of the product module you sell |
| Auth0 builds the tokens | The Action sets the custom claim, or denies the login |
Choose the licensee number
- One customer per Auth0 Organization. Use the organization’s
nameoridas the licenseenumber(event.organization). All users of the organization share one license. - One customer per user. Use the user’s email (
event.user.email, unique in Auth0) as the licenseenumber, or add it as an alias so you can validate by it. - Your own mapping. Store the NetLicensing licensee number in the user’s
app_metadataand read it fromevent.user.app_metadata.
NetLicensing numbers accept letters, digits and @ + % & $ : . - _, so an email address works as a number.
Secure the call
Use an API key with the role ROLE_APIKEY_LICENSEE, the lowest role that may validate. Store it as a Secret of the Action and read it with event.secrets. Each secret key may be up to 128 characters and each value up to 4096 characters.
For a sign-in check, send dryRun=true: the validation then runs without saving any changes on the NetLicensing side.
Name the claim
Auth0 recommends a collision-resistant, namespaced name for custom claims: any non-Auth0 http:// or https:// URL that you control, followed by the claim name, for example https://example.com/licensed. The URL does not have to point to anything. Auth0 domains such as auth0.com cannot be used as a namespace. To read custom claims in an access token, your application must use JWTs and pass an audience in the OIDC login flow.
Return small, explicit claims, for example whether the customer is licensed and until when. A claim is a snapshot at sign-in time; keep the entitlement logic in your product.
Time, limits and failures
- 20 seconds. Each execution of a trigger must complete in 20 seconds or less, or the processing ends in an error. Auth0 says that limiting HTTP requests is the best way to stay within this time, and that requests without a timeout must be avoided, so always set a timeout on the call to NetLicensing (the example uses 5 seconds).
- An unknown customer is HTTP 400. Validating a licensee that does not exist returns HTTP
400with the messageNotFoundException. Catch the error and decide what it means for you. - Refresh tokens run the Action too. The trigger also runs when a refresh token is exchanged, so a busy tenant calls NetLicensing often.
api.cachestores a string for the same Trigger, with a default lifetime of 15 minutes. Auth0 calls this cache short-lived and ephemeral: items may not be there in later transactions even within their lifetime. Use it to save calls, never as the only source of truth. Cache limits: 20 entries per trigger, keys up to 64 bytes, values up to 4 kB, 8 kB in total, at most 24 hours. Also cache the validation result in your product. - Size and code. An Action may be up to 100 kB (not counting
npmmodules). TypeScript is not supported; write JavaScript. Calls to external services come from these IP addresses, which you can allow in a firewall. - Deny with care.
api.access.deny(reason)blocks the login completely and stops further Actions, but it does not undo other changes that Actions requested (such as metadata). Most products are better served by a claim that the application evaluates; deny only if nobody without a license may sign in at all.
Example: the calls
Text version of this diagram (click to expand)
- User → Auth0: sign in
- Auth0 → NetLicensing: POST .../validate (dryRun=true, within the 20 s limit)
- NetLicensing → Auth0: valid, expires
- Auth0 → User: tokens with custom claim (or api.access.deny)
1. Create the Action
In the Auth0 Dashboard open Actions > Library, choose Create Action > Build from scratch, name it, and select the trigger Login / Post Login. Then:
- Add a Secret named
NETLICENSING_API_KEYwith your API key. - Add the
axiospackage as a dependency of the Action (Actions can usenpmpackages). - Paste the code below, then Save Draft, test it with the Test Runner, and Deploy. Auth0 runs only the deployed version.
- Open Actions > Flows, select the Login flow, drag your Action into it, and select Apply.
2. The Action code
const axios = require("axios");
const NLIC = "https://go.netlicensing.io/core/v2/rest";
const MODULE = "MGZRTP4UR"; // the product module you sell
const NS = "https://example.com/"; // a namespace you control
const prop = (node, name) => (node.property || []).find((p) => p.name === name)?.value;
exports.onExecutePostLogin = async (event, api) => {
// The customer: the Auth0 organization if there is one, else the user's email.
const licensee = event.organization ? event.organization.name : event.user.email;
const key = `nl:${licensee}`;
let result;
const cached = api.cache.get(key);
if (cached) {
result = JSON.parse(cached.value);
} else {
result = { valid: false, expires: null };
try {
const res = await axios.post(
`${NLIC}/licensee/${encodeURIComponent(licensee)}/validate`,
"dryRun=true",
{
auth: { username: "apiKey", password: event.secrets.NETLICENSING_API_KEY },
headers: { Accept: "application/json", "Content-Type": "application/x-www-form-urlencoded" },
timeout: 5000,
}
);
const item = (res.data.items?.item || []).find((i) => prop(i, "productModuleNumber") === MODULE);
if (item) {
const nested = item.list || [];
result.valid =
prop(item, "valid") === "true" || nested.some((l) => prop(l, "valid") === "true");
result.expires = prop(item, "expires") || null;
}
} catch (err) {
// An unknown licensee is HTTP 400 (NotFoundException); a network error or a timeout
// lands here too. Here we treat all of them as "not licensed".
}
api.cache.set(key, JSON.stringify(result), { ttl: 5 * 60 * 1000 });
}
api.idToken.setCustomClaim(NS + "licensed", result.valid);
api.accessToken.setCustomClaim(NS + "licensed", result.valid);
if (result.expires) {
api.accessToken.setCustomClaim(NS + "license_expires", result.expires);
}
};
We ran this code against a real validation response from the NetLicensing API (with a stand-in for axios and for the Auth0 objects): a customer with a valid module got licensed: true, and an unknown customer got false. To refuse the login instead, add if (!result.valid) api.access.deny("No valid license for this account."); before the claims.
3. What the Action sends to NetLicensing
curl --user "apiKey:$NETLICENSING_LICENSEE_KEY" --header "Accept: application/json" \
--data "dryRun=true" \
https://go.netlicensing.io/core/v2/rest/licensee/jane%40example.com/validate
The response has one ProductModuleValidation item per product module. Each item has a valid property; models such as Rental and Multi-feature also return valid per license or feature inside the item’s list, which is why the code checks both. Time-based models add expires.
4. What your application receives
The ID token and the access token carry the claim, for example:
{
"https://example.com/licensed": true
}
Sources
- Auth0: Post Login trigger
- Auth0: Post Login event object
- Auth0: Post Login API object
- Auth0: Actions limitations
- Auth0: Write your first Action
- Auth0: Create custom claims
You run this integration yourself; NetLicensing does not host an Auth0 connector. The Auth0 details on this page are based on the sources above, and the NetLicensing calls it relies on were tested against the live API. Auth0 changes its platform, so verify the details against the linked pages before you go live. Back to Identity Providers.