Skip to main content

Privacy

The Policy option in the schema allows configuring privacy policy for queries and mutations of entities in the database.

gopher-privacy

The main advantage of the privacy layer is that, you write the privacy policy once (in the schema), and it is always evaluated. No matter where queries and mutations are performed in your codebase, it will always go through the privacy layer.

In this tutorial, we will start by going over the basic terms we use in the framework, continue with a section for configuring the policy feature to your project, and finish with a few examples.

Basic Termsโ€‹

Policyโ€‹

The ent.Policy interface contains two methods: EvalQuery and EvalMutation. The first defines the read-policy, and the second defines the write-policy. A policy contains zero or more privacy rules (see below). These rules are evaluated in the same order they are declared in the schema.

If all rules are evaluated without returning an error, the evaluation finishes successfully, and the executed operation gets access to the target nodes.

privacy-rules

However, if one of the evaluated rules returns an error or a privacy.Deny decision (see below), the executed operation returns an error, and it is cancelled.

privacy-deny

Privacy Rulesโ€‹

Each policy (mutation or query) includes one or more privacy rules. The function signature for these rules is as follows:

// EvalQuery defines the a read-policy rule.
func(Policy) EvalQuery(context.Context, Query) error

// EvalMutation defines the a write-policy rule.
func(Policy) EvalMutation(context.Context, Mutation) error

Privacy Decisionsโ€‹

There are three types of decision that can help you control the privacy rules evaluation.

  • privacy.Allow - If returned from a privacy rule, the evaluation stops (next rules will be skipped), and the executed operation (query or mutation) gets access to the target nodes.
  • privacy.Deny - If returned from a privacy rule, the evaluation stops (next rules will be skipped), and the executed operation is cancelled. This equivalent to returning any error.
  • privacy.Skip - Skip the current rule, and jump to the next privacy rule. This equivalent to returning a nil error.

privacy-allow

Now that weโ€™ve covered the basic terms, letโ€™s start writing some code.

Configurationโ€‹

In order to enable the privacy option in your code generation, enable the privacy feature with one of two options:

If you are using the default go generate config, add --feature privacy option to the ent/generate.go file as follows:

ent/generate.go
package ent

//go:generate go run -mod=mod entgo.io/ent/cmd/ent generate --feature privacy ./schema

It is recommended to add the schema/snapshot feature-flag along with the privacy flag to enhance the development experience, for example:

//go:generate go run -mod=mod entgo.io/ent/cmd/ent generate --feature privacy,schema/snapshot ./schema

Privacy Policy Registrationโ€‹

info

You should notice that similar to schema hooks, if you use the Policy option in your schema, you MUST add the following import in the main package, because a circular import is possible between the schema package, and the generated ent package:

import _ "<project>/ent/runtime"

Examplesโ€‹

Admin Onlyโ€‹

We start with a simple example of an application that lets any user read any data, and accepts mutations only from users with admin role. We will create 2 additional packages for the purpose of the examples:

  • rule - for holding the different privacy rules in our schema.
  • viewer - for getting and setting the user/viewer who's executing the operation. In this simple example, it can be either a normal user or an admin.

After running the code-generation (with the feature-flag for privacy), we add the Policy method with 2 generated policy rules.

examples/privacyadmin/ent/schema/user.go
package schema

import (
    "entgo.io/ent"
    "entgo.io/ent/examples/privacyadmin/ent/privacy"
)

// User holds the schema definition for the User entity.
type User struct {
    ent.Schema
}

// Policy defines the privacy policy of the User.
func (User) Policy() ent.Policy {
    return privacy.Policy{
        Mutation: privacy.MutationPolicy{
            // Deny if not set otherwise. 
            privacy.AlwaysDenyRule(),
        },
        Query: privacy.QueryPolicy{
            // Allow any viewer to read anything.
            privacy.AlwaysAllowRule(),
        },
    }
}

We defined a policy that rejects any mutation and accepts any query. However, as mentioned above, in this example, we accept mutations only from viewers with admin role. Let's create 2 privacy rules to enforce this:

examples/privacyadmin/rule/rule.go
package rule

import (
    "context"

    "entgo.io/ent/examples/privacyadmin/ent/privacy"
    "entgo.io/ent/examples/privacyadmin/viewer"
)

// DenyIfNoViewer is a rule that returns Deny decision if the viewer is
// missing in the context.
func DenyIfNoViewer() privacy.QueryMutationRule {
    return privacy.ContextQueryMutationRule(func(ctx context.Context) error {
        view := viewer.FromContext(ctx)
        if view == nil {
            return privacy.Denyf("viewer-context is missing")
        }
        // Skip to the next privacy rule (equivalent to returning nil).
        return privacy.Skip
    })
}

// AllowIfAdmin is a rule that returns Allow decision if the viewer is admin.
func AllowIfAdmin() privacy.QueryMutationRule {
    return privacy.ContextQueryMutationRule(func(ctx context.Context) error {
        view := viewer.FromContext(ctx)
        if view.Admin() {
            return privacy.Allow
        }
        // Skip to the next privacy rule (equivalent to returning nil).
        return privacy.Skip
    })
}

As you can see, the first rule DenyIfNoViewer, makes sure every operation has a viewer in its context, otherwise, the operation rejected. The second rule AllowIfAdmin, accepts any operation from viewer with admin role. Let's add them to the schema, and run the code-generation:

examples/privacyadmin/ent/schema/user.go
// Policy defines the privacy policy of the User.
func (User) Policy() ent.Policy {
    return privacy.Policy{
        Mutation: privacy.MutationPolicy{
            rule.DenyIfNoViewer(),
            rule.AllowIfAdmin(),
            privacy.AlwaysDenyRule(),
        },
        Query: privacy.QueryPolicy{
            privacy.AlwaysAllowRule(),
        },
    }
}

Since we define the DenyIfNoViewer first, it will be executed before all other rules, and accessing the viewer.Viewer object is safe in the AllowIfAdmin rule.

After adding the rules above and running the code-generation, we expect the privacy-layer logic to be applied on ent.Client operations.

examples/privacyadmin/example_test.go
func Do(ctx context.Context, client *ent.Client) error {
    // Expect operation to fail, because viewer-context
    // is missing (first mutation rule check).
    if err := client.User.Create().Exec(ctx); !errors.Is(err, privacy.Deny) {
        return fmt.Errorf("expect operation to fail, but got %w", err)
    }
    // Apply the same operation with "Admin" role.
    admin := viewer.NewContext(ctx, viewer.UserViewer{Role: viewer.Admin})
    if err := client.User.Create().Exec(admin); err != nil {
        return fmt.Errorf("expect operation to pass, but got %w", err)
    }
    // Apply the same operation with "ViewOnly" role.
    viewOnly := viewer.NewContext(ctx, viewer.UserViewer{Role: viewer.View})
    if err := client.User.Create().Exec(viewOnly); !errors.Is(err, privacy.Deny) {
        return fmt.Errorf("expect operation to fail, but got %w", err)
    }
    // Allow all viewers to query users.
    for _, ctx := range []context.Context{ctx, viewOnly, admin} {
        // Operation should pass for all viewers.
        count := client.User.Query().CountX(ctx)
        fmt.Println(count)
    }
    return nil