Entity-level authorization allows you to create expressions within your entity templates — using entity fields — to determine authorization for specific content generated by that entity template. Expressions can check data defined on entities (such as emails and roles) against claims data returned by your OIDC provider to create scalable, site-wide authorization rules.

getAuthScope

Note: You must be using @yext/pages version 1.1.0 (or any 1.1.0 beta version) or higher to use getAuthScope.

To use custom expressions to define authorization, export the getAuthScopes function within your entity template. This allows you to use a combination of entity-level data and the Common Expression Language (CEL) to return a boolean:

• If the expression returns true, the logged-in user is allowed to access the page.
• If the expression returns false, the logged-in user is denied access.

Below is an example that uses the claims and token information within an OIDC response as input variables to the expression:

import {
  GetAuthScope,
  TemplateProps,
} from "@yext/pages";

export const getAuthScope: GetAuthScope<TemplateProps> = ({document}) => {

  // A. Checks if user's role matches any of the roles defined on the entity
  const rolesCheck = `(claims.custom_roles.exists(role => document.externalAuthorizedIdentities.exists(r => r == role)))`;
  
  // B. Checks if user's email ends in @yext.com
  const emailCheck = `claims.email.endsWith("@yext.com")`;
  
  // Checks if A AND B are both true
  return `${rolesCheck} && ${emailCheck}`;
}

What is CEL?

The Common Expression Language (CEL) is maintained by Google and allows users to build expressions which can be compiled and run in code. Refer to the CEL code lab for a full walkthrough, or the language specification for a deep dive.

Basic Syntax

• && means AND
• || means OR
• == means equal
• != means not equal
• () can be used to define how expressions are grouped

Variables

Two variables are available for injection: token and claims. These can be accessed with dot notation.

Common Functions

• <string>.startsWith("substring") — check if a string starts with a certain substring
• <string>.endsWith("substring") — check if a string ends with a certain substring
• <string> in <array> — check if a string is in an array of strings
• <array>.filter(elem, func(elem) bool) — the filter function
• <array>.all(elem, func(elem) bool) — returns true if every element in the array evaluates to true with the function

Example

Check if the email in the claims ends with @yext.com:

has(claims.email) && claims.email.endsWith("@yext.com")