You are viewing the preview version of this book
Click here for the full version.

Context

The context contains the input for the template. It is accessible under $context or $ctx, and I prefer the shorter form. What values are present depends on the GraphQL query, whether it is for a request or a response mapping template, and whether it's a pipeline or a unit resolver.

The reference contains an up-to-date list of the available values in the context. Here, we are going to discuss the available values briefly.

arguments

The $ctx.arguments, or $ctx.args for short, contains the arguments for the field being resolved. For example, in this query:

query Query1 {
  user(username: "user1") {
    username
    tickets(after: 1639907490) {
      text
      created
    }
  }
}

The $ctx.args contains a username for the Query.user and an after for the User.tickets resolver.

Arguments are defined only for the resolver for the field

source

The $ctx.source contains the result of the parent field and is only defined for nested fields. The source provides a way to pass data down the object hierarchy until only leaf nodes remain.

For example, the query contains two levels of nesting:

query Query1 {
  user(username: "user1") {
    username
    tickets(after: 1639907490) {
      text
      created
    }
  }
}

First, the Query.user resolver will run, where the $ctx.source is undefined. Then the User.username runs, where the source is the result of the Query.user. The same happens with User.tickets. Then the Ticket.text and the Ticket.created resolvers run, both getting one object from the result of the User.tickets.

Source object in nested resolvers

identity

The $ctx.identity is shared by all resolvers in the query and it contains information about the caller. This information is essential for access control and personalized responses. For example, you'll need to know who the user is to determine if it has access to an object. Moreover, it is a best practice to provide a getCurrentUser query that provides an entry point for users. And to know who the user is, you can use the information in the $ctx.identity.

The structure depends on the authorization provider used. For example, a Cognito User has a sub field that is the identifier of the user. But an IAM user has a userArn that is the ARN of the signed-in user. The $ctx.identity always reflects the authorization method used for the call if multiple are configured.

AppSync provides a convenience function to decide the authorization type so you don't need to inspect the structure: the $util.authType(). This returns a unique string:

Returns a String describing the multi-auth type being used by a request, returning back either "IAM Authorization", "User Pool Authorization", "Open ID Connect Authorization", or "API Key Authorization".

Let's see some examples for different authorization types!

Cognito User Pool

Here, the $util.authType() is User Pool Authorization.

And the $ctx.identity looks like this:

{
  "claims": {
    "sub": "af08acd8-f118-4016-a35d-2e47d43015a3",
    "cognito:groups": [
      "user"
    ],
    "email_verified": true,
    "iss": "https://cognito-idp.eu-central-1.amazonaws.com/...",
    "cognito:username": "user1",
    "origin_jti": "c98cc3d8-0e89-490e-91b2-e0c209452d4e",
    "aud": "10f1mu8jtpi9asm1drp3a0cclo",
    "event_id": "d29a170c-4474-41e9-ae56-867eaa584604",
    "token_use": "id",
    "auth_time": 1664354661,
    "exp": 1664358261,
    "iat": 1664354661,
    "jti": "bf352d13-d551-4655-adeb-7fbb9506533f",
    "email": "user1@example.com"
  },
  "defaultAuthStrategy": "DENY",
  "groups": [
    "user"
  ],
  "issuer": "https://cognito-idp.eu-central-1.amazonaws.com/...",
  "sourceIp": [
    "83.173.202.165"
  ],
  "sub": "af08acd8-f118-4016-a35d-2e47d43015a3",
  "username": "user1"
}

As you can see, there are some duplications here. The $ctx.identity.sub as well as the $ctx.identity.claims.sub both contains the same identifier. Moreover, the $ctx.identity.groups duplicates $ctx.identity.claims["cognito:groups"].

Apart from these slightly strange things, the object contains a lot of information. The most important are the the sub, the username, the group, and in some cases the issuer. Also, the claims contains the Cognito User attributes, such as an email if present for the user.

IAM

For IAM users, $ctx.authType() is IAM Authorization.

The $ctx.identity:

{
  "accountId": "278868411450",
  "cognitoIdentityAuthProvider": null,
  "cognitoIdentityAuthType": null,
  "cognitoIdentityId": null,
  "cognitoIdentityPoolId": null,
  "sourceIp": [
    "83.173.202.165"
  ],
  "userArn": "arn:aws:iam::278868411450:user/sandbox_admin",
  "username": "AIDAUB3O2IQ5MG6P2QH3Z"
}

There is more, but you've reached the end of this preview
Read this and all other chapters in full and get lifetime access to:
  • all future updates
  • full web-based access
  • PDF and Epub versions