Firebase Data Connect provides robust client-side security with:

• Mobile and web client authorization
• Individual query- and mutation-level authorization controls
• App attestation withFirebase App Check.

Data Connect extends this security with:

• Server-side authorization
• Firebase project and Cloud SQL user security with IAM.

Authorize client queries and mutations

Data Connect is fully integrated withFirebase Authentication, so you canuse rich data about users who are accessing your data (authentication) inyour design for what data those users can access (authorization).

Data Connect provides an@auth directive for queries andmutations that lets you set the level of authentication required to authorizethe operation. This guideintroduces the@auth directive, with examples.

In addition,Data Connect supports execution of queries embedded inmutations, so you can retrieve additional authorization criteria you've storedin your database, and use those criteria in@check directives to decide ifenclosing mutations are authorized. For this authorization case, the@redactdirective allows you control whether query results are returned to clients inthe wire protocol and the embedded query omitted in generated SDKs. Find theintroduction to these directives, with examples.

Understand the@auth directive

You can parameterize the@auth directive to follow one of several presetaccess levels that cover many common access scenarios. These levels range fromPUBLIC (which allows queries and mutations from all clients withoutauthentication of any kind) toNO_ACCESS (which disallows queries andmutations outside ofprivileged server environments using the Firebase AdminSDK). Each of these levels is correlated with authenticationflows provided byFirebase Authentication.

Using these preset access levels as a starting point, you can define complex androbust authorization checks in the@auth directive usingwhere filters andCommon Expression Language (CEL) expressions evaluated on the server.

Use the@auth directive to implement common authorization scenarios

The preset access levels are thestarting point for authorization.

TheUSER access level is the most widely useful basic level to start with.

Fully secure access will build on theUSER level plus filters and expressionsthat check user attributes, resource attributes, roles and other checks. TheUSER_ANON andUSER_EMAIL_VERIFIED levels are variations on theUSER case.

Expression syntax lets you evaluate data using anauth object representingauthentication data passed with operations, both standard data in auth tokensand custom data in tokens. For the list of fields available in theauthobject, see thereference section.

There are of course use cases wherePUBLIC is the correct access level tostart with. Again, an access level is always a starting point, and additionalfilters and expressions are needed for robust security.

This guide now gives examples of how to build onUSER andPUBLIC.

A motivating example

The following best practice examples refer to the following schema for ablogging platform with certain content locked behind a payment plan.

Such a platform would likely modelUsers andPosts.

typeUser@table(key:"uid"){uid:String!name:Stringbirthday:DatecreatedAt:Timestamp!@default(expr:"request.time")}typePost@table{author:User!text:String!# "one of 'draft', 'public', or 'pro'"visibility:String!@default(value:"draft")# "the time at which the post should be considered published. defaults to# immediately"publishedAt:Timestamp!@default(expr:"request.time")createdAt:Timestamp!@default(expr:"request.time")updatedAt:Timestamp!@default(expr:"request.time")}

User-owned resources

Firebase recommends that you write filters and expressions that test userownership of a resource, in the following cases, ownership ofPosts.

In the following examples, data from auth tokens is read and compared usingexpressions. The typical pattern is to use expressions likewhere: {authorUid:{eq_expr: "auth.uid"}} to compare a storedauthorUid to theauth.uid(user ID) passed in the authentication token.

Create

This authorization practice starts by adding theauth.uid from theauth token to each newPost as anauthorUid field to allow comparison insubsequence authorization tests.

# Create a new post as the current usermutationCreatePost($text:String!,$visibility:String)@auth(level:USER){post_insert(data:{# set the author's uid to the current user uidauthorUid_expr:"auth.uid"text:$textvisibility:$visibility})}

Update

When a client attempts to update aPost, you can test the passedauth.uidagainst the storedauthorUid.

# Update one of the current user's postsmutationUpdatePost($id:UUID!,$text:String,$visibility:String)@auth(level:USER){post_update(# only update posts whose author is the current userfirst:{where:{id:{eq:$id}authorUid:{eq_expr:"auth.uid"}}}data:{text:$textvisibility:$visibility# insert the current server time for updatedAtupdatedAt_expr:"request.time"})}

Delete

The same technique is used to authorize delete operations.

# Delete one of the current user's postsmutationDeletePost($id:UUID!)@auth(level:USER){post_delete(# only delete posts whose author is the current userfirst:{where:{id:{eq:$id}authorUid:{eq_expr:"auth.uid"}}})}

# Common display information for a postfragmentDisplayPostonPost{id,text,createdAt,updatedAtauthor{uid,name}}

# List all posts belonging to the current userqueryListMyPosts@auth(level:USER){posts(where:{userUid:{eq_expr:"auth.uid"}}){# See the fragment above...DisplayPost# also show visibility since it is user-controlledvisibility}}

# Get a post only if it belongs to the current userqueryGetMyPost($id:UUID!)@auth(level:USER){post(key:{id:$id},first:{where:{id:{eq:$id}authorUid:{eq_expr:"auth.uid"}}}},{# See the fragment above...DisplayPost# also show visibility since it is user-controlledvisibility}}

# List all posts marked as 'public' visibilityqueryListPublicPosts@auth(level:PUBLIC){posts(where:{# Test that visibility is "public"visibility:{eq:"public"}# Only display articles that are already publishedpublishedAt:{lt_expr:"request.time"}}){# see the fragment above...DisplayPost}}

# List all public or pro posts, only permitted if user has "pro" plan claimqueryProListPosts@auth(expr:"auth.token.plan=='pro'"){posts(where:{# display both public posts and "pro" postsvisibility:{in:['public','pro']},# only display articles that are already publishedpublishedAt:{lt_expr:"request.time"},}){# see the fragment above...DisplayPost# show visibility so pro users can see which posts are pro\visibility}}

# Show 2 oldest Pro post as a previewqueryProTeaser@auth(level:USER){posts(where:{# show only pro postsvisibility:{eq:"pro"}# that have already been published more than 30 days agopublishedAt:{lt_time:{now:true,sub:{days:30}}}},# order by publish timeorderBy:[{publishedAt:DESC}],# only return two postslimit:2){# See the fragment above...DisplayPost}}

# List all posts unconditionally iff the current user has an admin claimqueryAdminListPosts@auth(expr:"auth.token.admin==true"){posts{...DisplayPost}}

# MoviePermission# Suppose a user has an authorization role with respect to records in the Movie tabletypeMoviePermission@table(key:["movie","user"]){movie:Movie!# implies another field: movieId: UUID!user:User!role:String!}

• A@transaction directive to ensure all authorization queries and checks arecompleted or fail atomically.
• The@redact directive to omit query results from the response, meaning ourauthorization check is performed on theData Connect server butsensitive data is not exposed to the client.

• A pair of@check directives to evaluate authorization logic on queryresults, such as testing that a given userID has an appropriate role to makemodifications.

  Note: Themessage argument for@check is optional, but it's useful incombination with the@redact directive, so you can define messages to returnto client code even though specific fields are redacted from the response.

mutationUpdateMovieTitle($movieId:UUID!,$newTitle:String!)@auth(level:USER)@transaction{# Step 1: Query and checkquery@redact{moviePermission(# Look up a join table called MoviePermission with a compound key.key:{movieId:$movieId,userId_expr:"auth.uid"}# Step 1a: Use @check to test if the user has any role associated with the movie# Here the `this` binding refers the lookup result, i.e. a MoviePermission object or null# The `this != null` expression could be omitted since rejecting on null is default behavior)@check(expr:"this != null",message:"You do not have access to this movie"){# Step 1b: Check if the user has the editor role for the movie# Next we execute another @check; now `this` refers to the contents of the `role` fieldrole@check(expr:"this == 'editor'",message:"You must be an editor of this movie to update title")}}# Step 2: Actmovie_update(id:$movieId,data:{title:$newTitle})}

Use in queries

Authorization data lookups are also useful to restrict queries based on rolesor other restrictions.

In the following example, which also uses theMoviePermission schema, thequery checks whether a requestor has an appropriate "admin" role to view userswho can edit a movie.

queryGetMovieEditors($movieId:UUID!)@auth(level:PUBLIC){moviePermission(key:{movieId:$movieId,userId_expr:"auth.uid"})@redact{role@check(expr:"this == 'admin'",message:"You must be an admin to view all editors of a movie.")}moviePermissions(where:{movieId:{eq:$movieId},role:{eq:"editor"}}){user{idusername}}}

Antipatterns to avoid in authorization

The previous section covers patterns to follow when using the@authdirective.

You should also be aware of important antipatterns to avoid.

Avoid passing user attributes IDs and authtoken parameters in query and mutation arguments

Firebase Authentication is a powerful tool for presenting authentication flows andsecurely capturing authentication data such as registered user IDs and numerousfields stored in auth tokens.

It's not a recommended practice to pass user IDs and auth token data in queryand mutation arguments.

# Antipattern!# This incorrectly allows any user to view any other user's postsqueryAllMyPosts($userId:String!)@auth(level:USER){posts(where:{authorUid:{eq:$userId}}){id,text,createdAt}}

Avoid using theUSER access level without any filters

As discussed several times in the guide, the core access levels likeUSER,USER_ANON,USER_EMAIL_VERIFIED are baselines and starting points forauthorization checks, to be enhanced with filters and expressions. Using theselevels without a corresponding filter or expression that checkswhich user isperforming the request is essentially equivalent to using thePUBLIC level.

# Antipattern!# This incorrectly allows any user to view all documentsqueryListDocuments@auth(level:USER){documents{idtitletext}}

# Antipattern!# This incorrectly allows anyone to delete any postmutationDeletePost($id:UUID!)@auth(level:PUBLIC){post:post_delete(id:$id,)}

# Antipattern!# Anyone can claim an email address during sign-inmutationCreatePost($text:String!,$visibility:String)@auth(expr:"auth.token.email.endsWith('@example.com')"){post_insert(data:{# set the author's uid to the current user uidauthorUid_expr:"auth.uid"text:$textvisibility:$visibility})}

mutationCreatePost($text:String!,$visibility:String)@auth(expr:"auth.token.email_verified &&auth.token.email.endsWith('@example.com')"){post_insert(data:{# set the author's uid to the current user uidauthorUid_expr:"auth.uid"text:$textvisibility:$visibility})}

Warnings and prompts always occur for:

• PUBLIC

And, warnings and prompts occur on the following access levels when youdon't augment them with filters usingauth.uid:

• USER
• USER_ANON
• USER_EMAIL_VERIFIED

Suppress insecure operation warnings with the@auth(insecureReason:) argument

In many cases, you will conclude that using thePUBLIC andUSER* accesslevels is perfectly appropriate.

When your connector contains many operations, you may want clearer, morerelevant security audit output that omits operations that would normally triggera warning, but you know have the correct access level.

You can suppress warnings for such operations with@auth(insecureReason:).For example:

querylistItem@auth(level:PUBLIC,insecureReason:"This operation is safe to expose to the public."){items{idname}}

UseFirebase App Check for app attestation

Authentication and authorization are critical components ofData Connect security. Authentication and authorization combined withapp attestation makes for a very robust security solution.

With attestation throughFirebase App Check, devicesrunning your app will use an app or device attestation provider that atteststhatData Connect operations originate from your authentic app andrequests originate from an authentic, untampered device. This attestation isattached to every request your app makes toData Connect.

To learn how to enableApp Check forData Connect and include itsclient SDK in your app, have alook at theApp Checkoverview.

Authentication levels for the@auth(level) directive

The following table lists all standard access levels and their CEL equivalents.Authentication levels are listed from broad to narrow -- each level encompassesall users who match following levels.

CEL Reference for@auth(expr)

As shown in examples elsewhere in this guide, you can and should useexpressions defined in Common Expression Language (CEL) to control authorizationforData Connect using@auth(expr:) and@check directives.

This section covers CEL syntax relevant to creating expressions for thesedirectives.

Complete reference information for CEL is provided in theCEL specification.

Test variables passed in queries and mutations

@auth(expr) syntax allows you access and test variables from queries andmutations.

For example, you can include an operation variable, such as$status, usingvars.status.

mutationUpdate($id:UUID!,$status:Any)@auth(expr:"has(vars.status)")

Data available to expressions: request, response, this

You use data for:

• Evaluation with CEL expressions in@auth(expr:) and@check(expr:)directives
• Assignment using server expressions,<field>_expr.

Both@auth(expr:) and@check(expr:) CEL expressions can evaluate thefollowing:

• request.operationName
• vars (alias forrequest.variables)
• auth (alias forrequest.auth)

In mutations, you can access and assign the contents of:

• response (to check partial results in multi-step logic)

Additionally,@check(expr:) expressions can evaluate:

• this (the value of the current field)
• response (to check partial results in multi-step logic)

The request.operationName binding

Therequest.operarationName binding stores the type of operation, either queryor mutation.

Thevars binding (request.vars)

Thevars binding allows your expressions to access all variablespassed in your query or mutation.

You can usevars.<variablename> in an expression as an alias for thefully-qualifiedrequest.variables.<variablename>:

# The following are equivalentmutationStringType($v:String!)@auth(expr:"vars.v=='hello'")mutationStringType($v:String!)@auth(expr:"request.variables.v=='hello'")

Theauth binding (request.auth)

Authentication identifies users requesting access to your data and providesthat information as a binding you can build on in your expressions.

In your filters and expressions, you can useauth as an alias forrequest.auth.

The auth binding contains the following information:

• uid: A unique user ID, assigned to the requesting user.
• token: A map of values collected byAuthentication.

For more details on the contents ofauth.token seeData in auth tokens

Theresponse binding

Theresponse binding contains the data being assembled by the server inresponse to a query or mutationas that data is being assembled.

As the operation proceeds, as each step is completed successfully,response contains response data from successfully-completed steps.

Theresponse binding is structured according the shape of its associatedoperation, including (multiple) nested fields and (if applicable) embeddedqueries.

Note that when you accessembedded query response data, fields can containany data type, depending on the data requested in the embedded query; when youaccess data returned by mutation fields like_inserts and_deletes, they maycontain UUID keys, number of deletes, nulls (see themutations reference).

For example:

• In a mutation that contains an embedded query, theresponsebinding contains lookup data atresponse.query.<fieldName>.<fieldName>...., inthis case,response.query.todoList andresponse.query.todoList.priority.

mutationCheckTodoPriority($uniqueListName:String!){# This query is identified as `response.query`query@check(expr:"response.query.todoList.priority == 'high'",message:"This list is not for high priority items!"){# This field is identified as `response.query.todoList`todoList(where:{name:$uniqueListName}){# This field is identified as `response.query.todoList.priority`priority}}}

• In a multi-step mutation, for example with multiple_insert fields, theresponse binding contains partial data atresponse.<fieldName>.<fieldName>....,in this case,response.todoList_insert.id.

mutationCreateTodoListWithFirstItem($listName:String!,$itemContent:String!)@transaction{# Step 1todoList_insert(data:{id_expr:"uuidV4()",name:$listName,})# Step 2:todo_insert(data:{listId_expr:"response.todoList_insert.id"# <-- Grab the newly generated ID from the partial response so far.content:$itemContent,})}

Thethis binding

mutationUpdateMovieTitle($movieId:UUID!,$newTitle:String!)@auth(level:USER)@transaction{# Step 1: Query and checkquery@redact{moviePermission(# Look up a join table called MoviePermission with a compound key.key:{movieId:$movieId,userId_expr:"auth.uid"}){# Check if the user has the editor role for the movie. `this` is the string value of `role`.# If the parent moviePermission is null, the @check will also fail automatically.role@check(expr:"this == 'editor'",message:"You must be an editor of this movie to update title")}}# Step 2: Actmovie_update(id:$movieId,data:{title:$newTitle})}

mutationUpdateMovieTitle2($movieId:UUID!,$newTitle:String!)@auth(level:USER)@transaction{# Step 1: Query and checkquery{moviePermissions(# Now we query for a list of all matching MoviePermissions.where:{movieId:{eq:$movieId},userId:{eq_expr:"auth.uid"}}# This time we execute the @check on the list, so `this` is the list of objects.# We can use the `.exists` macro to check if there is at least one matching entry.)@check(expr:"this.exists(p, p.role == 'editor')",message:"You must be an editor of this movie to update title"){role}}# Step 2: Actmovie_update(id:$movieId,data:{title:$newTitle})}

mutationUpsertUser($username:String!)@auth(expr:"(auth!=null) &&(vars.username=='joe')")

• Firebase Data Connect provides an Admin SDK to let you performqueries and mutations from privileged environments.
• Learn about IAM security in theguide for managing services and databases.