Amplify GraphQL Auth Transformer

Common errors

• GraphQL schema validation failed.

  cause Incorrect syntax or conflicting `@auth` rules in `schema.graphql` prevents the Amplify CLI from processing the schema.
  fix Review the error message for specific validation failures. Common issues include missing required fields in `AuthRule`, incorrect `AuthStrategy` values, or conflicting authorization definitions. Use a GraphQL linter for schema validation during development.

• Unauthorized: user is not authorized to perform this operation.

  cause The client attempting the GraphQL operation does not meet the criteria defined in the `@auth` rules for the specific model or field. This often points to incorrect `allow`, `groups`, or `ownerField` configurations, or the client lacking appropriate credentials (e.g., invalid JWT token, insufficient IAM permissions).
  fix Verify the `@auth` rules in `schema.graphql` align with expected access patterns. Ensure the client is providing correct authorization headers (e.g., Cognito User Pool JWT, API Key, AWS IAM credentials). Check Cognito User Pool groups and IAM policies if `groups` or `private` rules are used.

• Expected `ownerField` to be present on type `X` but was not found.

  cause An `@auth` rule using `allow: owner` or `allow: owners` expects a field on the GraphQL type to store the owner's identifier (defaulting to `owner`). If this field is missing or named differently without being specified via `ownerField`, this error occurs.
  fix Ensure the GraphQL type has a field (e.g., `owner: String`) to store ownership information, or explicitly define the `ownerField` argument in your `@auth` rule (e.g., `@auth(rules: [{ allow: owner, ownerField: "userId" }])`).

Warnings

• breaking The GraphQL Transformer v1 to v2 migration introduced significant changes to `@auth` directive behavior. Authorization is now 'deny-by-default', meaning explicit rules are required for any access. The `operations` field within `AuthRule` now specifies allowed operations, rather than denied ones. Field-level `@auth` rules now explicitly override model-level rules.
  Fix: Review and migrate your `schema.graphql` to align with the deny-by-default paradigm and updated `operations` semantics. Utilize `amplify migrate api` tool and thoroughly test migrated schemas.
• gotcha Misunderstanding the interplay between different authorization providers (API Key, IAM, Cognito User Pools, OpenID Connect) and how `@auth` rules are evaluated can lead to unintended access patterns or 'Unauthorized' errors.
  Fix: Carefully design your authorization strategy and explicitly define providers for each `@auth` rule when mixing authorization types. Test access thoroughly from various client contexts (authenticated, unauthenticated, different user groups).
• gotcha Combining multiple `@auth` rules, especially with different `allow` strategies or at both model and field levels, can become complex. The order and specificity of rules matter, and field-level rules take precedence.
  Fix: Start with simpler rules and progressively add complexity. Use the Amplify CLI's generated resolver code (in `amplify/backend/api/<api-name>/build/resolvers`) to understand how rules are translated. Consider using `amplify mock api` for local testing.

Install

• npm install graphql-auth-transformer npm
• yarn add graphql-auth-transformer yarn
• pnpm add graphql-auth-transformer pnpm

Imports

• AuthTransformer

  import { AuthTransformer } from 'graphql-auth-transformer';

  This package is primarily consumed internally by the Amplify CLI's GraphQL transformation pipeline. Direct programmatic import is typically for advanced custom transformer development, not general application usage.
• AuthRule

  import { AuthRule } from 'graphql-auth-transformer';

  Represents the structure of an authorization rule. Rarely imported directly by end-users; primarily defined within GraphQL SDL.
• AuthStrategy

  import { AuthStrategy } from 'graphql-auth-transformer';

  Enum for authorization strategies (e.g., owner, groups, public, private). Used internally and implicitly when defining `@auth` rules in SDL.

Quickstart

This quickstart demonstrates how to define a GraphQL model with owner-based, group-based, and public authorization rules using the `@auth` directive, and then deploy it with the Amplify CLI.

/* amplify/backend/api/myapi/schema.graphql */

type Todo @model @auth(rules: [
  { allow: owner },
  { allow: groups, groups: ["Admins"], operations: [create, read, update, delete] },
  { allow: public, operations: [read] }
]) {
  id: ID!
  name: String!
  description: String
  owner: String
}

// To apply this schema and provision backend resources:
// 1. Save this file as amplify/backend/api/<your-api-name>/schema.graphql
// 2. Ensure Amplify CLI is initialized in your project:
//    amplify init
// 3. Add the API category:
//    amplify add api
//    (Choose GraphQL, provide a name, select 'Authorize and configure with AWS IAM and Amazon Cognito User Pools', etc.)
// 4. Push the changes to deploy your backend:
//    amplify push --yes