feat(@aws-amplify/auth): UniversalStorage for SSR

[ericclemmons]

Why

window.localStorage isn't available to server-side processes, unless credentials are explicitly sent via headers, query params, or POST body.

However, cookies are, which means that loading https://example.com/profile can render a user-specific page on the server without making a round-trip on the client as you would in a SPA.

What

Add support for Next.js (#5435) via a new UniversalStorage adapter that persists the minimum subset of credentials in cookies, so that they're available on the server for authenticated requests.

The following real, working examples come from my private sample: https://github.com/aws-amplify/amplify-js-samples-staging/pull/90

// /pages/index.tsx

import { CognitoUser } from '@aws-amplify/auth'
import { GRAPHQL_AUTH_MODE } from '@aws-amplify/api-graphql'
import { Amplify, API, Auth, UniversalStorage } from 'aws-amplify'
import awsconfig from '../src/aws-exports'

const storage = new UniversalStorage()
Amplify.configure({ ...awsconfig, storage })

type Props = { user?: CognitoUser }

export default function Home(props: Props) {
	...
}

export const getServerSideProps: GetServerSideProps = async (context) => {
  storage.setServerContext(context)

  let user = null

  try {
    user = await Auth.currentAuthenticatedUser({ bypassCache: false })
  } catch (error) {
    console.error(error)
  }

  return {
    props: {
      user: JSON.parse(JSON.stringify(user)),
    },
  }
}

// /pages/api/profile.tsx
import { Amplify, Auth, UniversalStorage } from 'aws-amplify'
import { NextApiRequest, NextApiResponse } from 'next'

import awsconfig from '../../src/aws-exports'

const storage = new UniversalStorage()
Amplify.configure({ ...awsconfig, storage })

export default async (req: NextApiRequest, res: NextApiResponse) => {
  storage.setServerContext({ req })

  try {
    const user = await Auth.currentAuthenticatedUser()

    return res.status(200).json({ user })
  } catch (error) {
    console.error(error)
    return res.status(500).json({ error })
  }
}

How

• Use isomorphic-unfetch to support SSR fetch for Cognito
• Add UniversalStorage from my sample to be exported from both aws-amplify and @aws-amplify/core.
  • Only authToken and idToken are persisted for the server.
  • All tokens persist in localStorage, as usual.
• Determine if UniversalStorage is the default in the browser or not.
  • Opting not to do this, because UniversalStorage.setContext(ctx) is still required per-request.
• Works with User Pools
• Works with https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html (Thanks you @elorzafe!)

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[codecov]

Codecov Report

Merging #5710 into main will increase coverage by 0.02%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##             main    #5710      +/-   ##
==========================================
+ Coverage   73.48%   73.51%   +0.02%     
==========================================
  Files         205      204       -1     
  Lines       12611    11915     -696     
  Branches     2457     2335     -122     
==========================================
- Hits         9267     8759     -508     
+ Misses       3153     2979     -174     
+ Partials      191      177      -14     

Impacted Files	Coverage Δ
packages/core/src/Util/DateUtils.ts	66.66% <0.00%> (-15.69%)	⬇️
packages/datastore/src/datastore/datastore.ts	71.68% <0.00%> (-15.01%)	⬇️
packages/core/src/Logger/ConsoleLogger.ts	72.00% <0.00%> (-12.00%)	⬇️
packages/datastore/src/sync/merger.ts	28.57% <0.00%> (-6.73%)	⬇️
packages/datastore/src/storage/storage.ts	67.59% <0.00%> (-4.08%)	⬇️
packages/core/src/I18n/index.ts	65.85% <0.00%> (-2.44%)	⬇️
packages/datastore/src/util.ts	73.72% <0.00%> (-1.89%)	⬇️
packages/auth/src/OAuth/OAuth.ts	48.12% <0.00%> (-1.52%)	⬇️
packages/api-rest/src/RestAPI.ts	95.60% <0.00%> (-1.46%)	⬇️
packages/api-graphql/src/GraphQLAPI.ts	83.70% <0.00%> (-1.13%)	⬇️
... and 35 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update a75e9c3...e4cd76d. Read the comment docs.

[sammartinez]

Is this a breaking change that we would need to do a Major publish for?

[ericclemmons]

It would be a minor.

[ericclemmons]

There are a few // @ts-ignore comments that exist because of nookies' forked behavior between server & client. On the server, context is { req, res }, while on the browser, it comes from document.cookies.

[ericclemmons]

Remove this so that it's session storage only.

[ericclemmons]

Frameworks take care of XSRF.

[ericclemmons]

Set HTTP-only (document.cookie) & Secure (HTTPS) for live environments.

[ericclemmons]

Don't set it to the top-level domain.

[ericclemmons]

Fixed via #6146

[github-actions]

This pull request has been automatically locked since there hasn't been any recent activity after it was closed. Please open a new issue for related bugs.

Looking for a help forum? We recommend joining the Amplify Community Discord server *-help channels or Discussions for those types of questions.