{"id":16825,"library":"graphql-auth-transformer","title":"Amplify GraphQL Auth Transformer","description":"The `graphql-auth-transformer` is a core, internal component of the AWS Amplify CLI's API category, specifically designed to process the `@auth` directive within GraphQL schemas. It allows developers to declare comprehensive authorization rules directly in their GraphQL Schema Definition Language (SDL), which the Amplify CLI then translates into corresponding AWS AppSync resolvers, AWS Identity and Access Management (IAM) policies, and Amazon Cognito User Pool configurations. This package is part of the larger `@aws-amplify/amplify-category-api` umbrella, which receives frequent updates, with the current package version being 7.2.82. Its primary differentiator is simplifying the definition and deployment of granular access control for GraphQL APIs powered by AWS AppSync, abstracting away much of the underlying complex AWS security primitives into declarative schema directives. It significantly reduces the boilerplate traditionally associated with securing GraphQL endpoints on AWS, making robust authorization accessible to a wider range of developers.","status":"active","version":"7.2.82","language":"javascript","source_language":"en","source_url":"https://github.com/aws-amplify/amplify-category-api","tags":["javascript","graphql","appsync","aws","typescript"],"install":[{"cmd":"npm install graphql-auth-transformer","lang":"bash","label":"npm"},{"cmd":"yarn add graphql-auth-transformer","lang":"bash","label":"yarn"},{"cmd":"pnpm add graphql-auth-transformer","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","symbol":"AuthTransformer","correct":"import { AuthTransformer } from 'graphql-auth-transformer';"},{"note":"Represents the structure of an authorization rule. Rarely imported directly by end-users; primarily defined within GraphQL SDL.","symbol":"AuthRule","correct":"import { AuthRule } from 'graphql-auth-transformer';"},{"note":"Enum for authorization strategies (e.g., owner, groups, public, private). Used internally and implicitly when defining `@auth` rules in SDL.","symbol":"AuthStrategy","correct":"import { AuthStrategy } from 'graphql-auth-transformer';"}],"quickstart":{"code":"/* amplify/backend/api/myapi/schema.graphql */\n\ntype Todo @model @auth(rules: [\n  { allow: owner },\n  { allow: groups, groups: [\"Admins\"], operations: [create, read, update, delete] },\n  { allow: public, operations: [read] }\n]) {\n  id: ID!\n  name: String!\n  description: String\n  owner: String\n}\n\n// To apply this schema and provision backend resources:\n// 1. Save this file as amplify/backend/api/<your-api-name>/schema.graphql\n// 2. Ensure Amplify CLI is initialized in your project:\n//    amplify init\n// 3. Add the API category:\n//    amplify add api\n//    (Choose GraphQL, provide a name, select 'Authorize and configure with AWS IAM and Amazon Cognito User Pools', etc.)\n// 4. Push the changes to deploy your backend:\n//    amplify push --yes","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=5.0.0 (with GraphQL Transformer v2)"},{"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).","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"Incorrect syntax or conflicting `@auth` rules in `schema.graphql` prevents the Amplify CLI from processing the schema.","error":"GraphQL schema validation failed."},{"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.","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).","error":"Unauthorized: user is not authorized to perform this operation."},{"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\" }])`).","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.","error":"Expected `ownerField` to be present on type `X` but was not found."}],"ecosystem":"npm","meta_description":null}