Entity-Level Authorization | Yext Hitchhikers Platform
The feature is to allow anyone to create expressions within their entity templates, using entity fields, to determine authorization for specific content generated by that entity template. Expressions can be used to 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
getAuthScope.
To start using your custom expressions to define authorization, you’ll need to export the getAuthScopes function within your entity template. This allows you to use a combination of entity-level data and common expression language to return a boolean (true or false).
- If the expression returns
true, we allow the logged-in user to access the page. - If the expression returns
false, we do not let the logged-in user access the page.
Below is an example that uses the claims and token information within an OIDC response as input variables to the expression with the expectation that the expression returns a boolean value:
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 the CEL?
The Common Expression Language (CEL) is maintained by Google and allows users to build expressions which can be compiled and run in code.
The CEL has support for variables and other powerful items, all of which can be found in the code lab here . If you want a deep dive, this is the language specification . To help you get started with CEL, here are some basics:
The expected boolean syntax applies here.
&&means AND||means OR==means equal!=means not equal()can be used to define how expressions are grouped
We allow for the injection of two variables: token and claims. These can be accessed like objects with dot notation.
Some common functions to use are:
<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)- returnstrueif the evaluation of every element in the array with the function returns true
Below is an example where we check if the email in the claims ends with @yext.com.
has(claims.email) && claims.email.endsWith("@yext.com")