@fromClaim Directive

WunderGraph builds on top of OpenID Connect for authentication. When a user is authenticated, we're storing all their claims in a cookie.

When defining your GraphQL Operations, you're able to use the @fromClaim directive to access the claims of the user and inject them into variables.

Here's an example:

mutation (
  $userId: String! @fromClaim(name: USERID)
  $name: String! @fromClaim(name: NAME)
  $email: String! @fromClaim(name: EMAIL)
  $message: String! @jsonSchema(pattern: "^[a-zA-Z 0-9]+$")
) {
  createOnepost(
    data: {
      message: $message
      user: { connectOrCreate: { where: { email: $email }, create: { email: $email, name: $name, userID: $userID } } }
    }
  ) {
    id
    message
    user {
      id
      name
    }
  }
}

We're injecting the name and email claims into the $name and $email variables. The variables are removed from the exported JSON RPC API. This means, the user cannot set them manually, JSON Schema validation would prevent this automatically.

Additionally, applying the @jsonSchema directive to an operation will automatically enable an authentication check. So, the user must be authenticated to execute the operation.

WunderGraph supports the following well known claims:

WunderGraph also supports defining your custom claims and using them in the same as well known ones. First, define your custom claims when configuring your WunderGraph application:

// configureWunderGraph emits the configuration
configureWunderGraphApplication({
  ...
	authentication: {
		customClaims: {
			// Implicit: required
			SHOPID: {
				jsonPath: 'shop.id', // Nested 'id' field inside a 'shop' object
				type: 'int', // Must be an integer
			},
			// Implicit: string
			TENANTID: {
				jsonPath: 'teid',
				required: false, // Optional
			},
	},
});

Defining your custom claims allows to generate all the plumbing required to access them in a type-safe manner and get instant errors in your IDE if you accidentally misuse them.

Then use them in your operations to assign values to variables depending on the claim:

mutation ($shopID: Int! @fromClaim(name: SHOPID), $productID: Int!) {
  createOneOrder(data: { shop: $shopID, product: $productID }) {
    id
    created
  }
}

Additionaly, custom claims are also available in User instances in both hooks and functions, under User.customClaims.<claimID> (e.g. User.customClaims.shopID).

@fromClaim accepts a second optional on: argument that might be used to inject a value into an specific field. Given the following type:

input countries_CountryFilterInput {
  code: String!
}

We can use @fromClaim to set the value of code using:

mutation ($filter: countries_CountryFilterInput! @fromClaim(name: COUNTRY_CODE, on: "code")) {
  countries_Countries(filter: $filter) {
    id
    name
  }
}

@fromClaim can be used multiple times on the same operation, injecting data into different fields. Additionally, @fromClaim can be combined with other directives for injecting or manipulating data like @injectCurrentDateTime, @injectEnvironmentVariable, @injectGeneratedUUID and @jsonSchema.