Registry / aws / graphql-auth-transformer

graphql-auth-transformer

library7.2.82jsnpmunverified

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.

aws auth-security

npm install graphql-auth-transformer

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRAPHQL-AUTH-TRANS

graphql-auth-transformer

awsjavascriptv7.2.82

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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

Debug

Known issues

breakingThe 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.

affects: >=5.0.0 (with GraphQL Transformer v2)

gotchaMisunderstanding 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).

affects: >=1.0.0

gotchaCombining 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.

affects: >=1.0.0

Errors

Common errors & fixes

GraphQL schema validation failed.

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.

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.

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" }])`).

Upgrade

Version history

7.2.82latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/aws-amplify/amplify-category-api ↗

packagehttps://www.npmjs.com/package/graphql-auth-transformer ↗

homepagehttps://aws.amazon.com/amplify/ ↗