@fromClaim directive

The @fromClaim is one of the most powerful yet magical features of WunderGraph. In a Nutshell, it allows you to inject Claims into an Operation.

Here's an example:

mutation (
    $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}}}}){
        id
        message
        user {
            id
            name
        }
    }
}

Let's unpack this "magic" step-by-step.

What are Claims#

Simply put, Claims are name value pairs of information about a user. The term is coming from OpenID Connect (OIDC), because WunderGraph is using OpenID Connect! If you configure an authentication provider, you've actually integrated WunderGraph with OpenID Connect. This means, if a user authenticates with your WunderGraph application, the WunderGraph Server (WunderNode) will get the Claims for the user from the OIDC provider.

These are my Claims when I use the Google OIDC provider to login with my WunderGraph application:

{
  "provider":"oidc",
  "provider_id":"google",
  "email":"jens@wundergraph.com",
  "email_verified":true,
  "name":"Jens Neuse",
  "first_name":"Jens",
  "last_name":"Neuse",
  "user_id":"113191162795099390701",
  "avatar_url":"https://lh3.googleusercontent.com/a/AATXAJxirUyEJlM18Z2Q6GAXIA6DuAw3WGAJ6g3igFL4=s96-c",
  "location":"de"
}

What does it mean to "inject" claims#

Looking back at the Operation example above, we would expect that this Operation allows the user to enter their name, email and a message.

Because we're using the @fromClaim directive on both name and email, the user is actually not allowed to send these variables. If they tried, the operation would fail.

Additionally, using the directive on an Operation also means that the user MUST be authenticated to be able to use the Operation. If you think about it, that's the only way it could work. Otherwise, how could we inject a Claim if the user is not authenticated and therefore has no Claims attached.

How does it work?#

When a request hits the WunderGraph Server (WunderNode), the authentication middleware will first check if the user is authenticated. We're doing so by looking at the secure and encrypted cookie of the user. If the user is authenticated, we'll extract all their Claims from the cookie and make them available to the request chain.

Next, we'll verify if the user tried to inject the variable themselves. If that's the case, the operation will fail.

Once we're sure that the Request is valid, we'll check if any variables need to be injected into the request. If there are variables configured to be injected, we'll use the Claims from the authentication middleware and configure them for the request input.

Finally, we'll proceed with the request execution as if the above never happened.

How secure is this?#

Keep in mind that WunderGraph keeps Operations on the server-side only. That is, at runtime, no client is able to configure their own custom operation. Creating an Operation is like defining an RPC endpoint. Adding directives to configure the Operation simply modifies the server-side middleware chain.

The users' claims are stored in encrypted http-only cookies. This means, there's no way to manipulate the injection.