Rule Examples

In this article, you'll find a collection of sample Auth0 Rules. For more examples, see our Github repo at auth0/rules.

This Rule will add a hello claim (with the value world) to the ID Token that will be afterwards sent to the application.

function (user, context, callback) {
  context.idToken["http://mynamespace/hello"] = "world";
  console.log('===> set "hello" for ' + user.name);
  callback(null, user, context);
}

Note that the claim is namespaced: we named it http://mynamespace/hello instead of just hello. This is what you have to do in order to add arbitrary claims to an ID Token or Access Token. To learn more, read Create Namespaced Custom Claims.

Any non-Auth0 HTTP or HTTPS URL can be used as a namespace identifier, and any number of namespaces can be used. Exceptions are webtask.io and webtask.run, which are Auth0 domains and therefore cannot be used. The namespace URL does not have to point to an actual resource; it's only used as an identifier and will not be called by Auth0. To learn more, see OpenID Connect Scopes and API Scopes.

In this example, all authenticated users will get a guest role, but johnfoo@gmail.com will also be an admin:

function (user, context, callback) {
  if (user.email === 'johnfoo@gmail.com') {
    context.idToken["http://mynamespace/roles"] = ['admin', 'guest'];
  }else{
    context.idToken["http://mynamespace/roles"] = ['guest'];
  }

  callback(null, user, context);
}

At the beginning of the Rules pipeline, John's context object will be:

{
  "clientID": "{yourClientId}",
  "clientName": "{yourClientName}",
  "clientMetadata": {},
  "connection": "{yourConnectionName}",
  "connectionStrategy": "auth0",
  "protocol": "oidc-implicit-profile",
  "accessToken": {},
  "idToken": {},
  //... other properties ...
}

After the Rule executes, the context object will have the added namespaced claim as part of the ID Token:

{
  "clientID": "{yourClientId}",
  "clientName": "{yourClientName}",
  "clientMetadata": {},
  "connection": "{yourConnectionName}",
  "connectionStrategy": "auth0",
  "protocol": "oidc-implicit-profile",
  "accessToken": {},
  "idToken": { "http://mynamespace/roles": [ "admin", "guest" ] },
  //... other properties ...
}

When your application receives the ID Token, it will verify and decode it in order to access this added custom claim. The payload of the decoded ID Token will be similar to the following sample:

{
  "iss": "https://{yourDomain}/",
  "sub": "auth0|{userId}",
  "aud": "{yourClientId}",
  "exp": 1490226805,
  "iat": 1490190805,
  "nonce": "...",
  "at_hash": "...",
  "http://mynamespace/roles": [
    "admin",
    "guest"
  ]
}

For more information on the ID Token, refer to ID Token.

In addition to adding claims to the ID Token, you can return an access denied error.

function (user, context, callback) {
  if (context.clientID === "BANNED_CLIENT_ID") {
    return callback(new UnauthorizedError('Access to this application has been temporarily revoked'));
  }

  callback(null, user, context);
}

This will cause a redirect to your callback URL with an error query string parameter containing the message you set. For example:

https://yourapp.com/callback?error=unauthorized&error_description=Access%20to%20this%20application%20has%20been%20temporarily%20revoked

Make sure to call the callback with an instance of UnauthorizedError (not Error).

Error reporting to the app depends on the protocol. OpenID Connect (OIDC) apps will receive the error in the query string. SAML apps will receive the error in a SAMLResponse.

This will read the favorite_color user metadata, and add it as a namespaced claim at the ID Token.

function(user, context, callback) {

  // copy user metadata value in ID Token
  context.idToken['http://fiz/favorite_color'] = user.user_metadata.favorite_color;

  callback(null, user, context);
}

This will add one custom namespaced claim at the Access Token.

function(user, context, callback) {

  // add custom claims to Access Token
  context.accessToken['http://foo/bar'] = 'value';

  callback(null, user, context);
}

After this Rule executes, the Access Token will contain one additional namespaced claim: http://foo/bar=value.