cognito-hoc

Higher Order Component for ReactJS that provides Authentication via the Cognito Hosted UI

Usage

The withCognitoHUI component can be used to wrap a React component with Authentication features that use the AWS Cognito Hosted UI, and handle all typical Authorization flows including for Social Providers such as Google and Facebook. The must be aware of the prop provided by withCognitoHUI, and respect it when rendering. To use withCognitoHUI, set up a Cognito backend first. For a discussion on how to do that, see:

https://www.sdpartners.com/blog/cognito-hoc

Typical usage in the frontend is within App.js:

...
import {withCognitoHUI} from 'cognito-hoc';
...

class MyApp extends React.Component {
  ...
}

export default withCognitoHUI(MyApp, myawsconfig, 'button');

And then index.js remains the usual:

ReactDOM.render(<MyApp myProp1="TestProp1" myProp2="Test Prop 2" />, document.getElementById('root'));

The withCognitoHUI component passes an all-important prop, userIsLoggedIn, which when 'true' (a string) indicates that it is safe for the wrapped component (MyApp) to display the protected content. At all other times, it is not safe to display protected content, because the user is not Authenticated.

Details

This HOC assumes the use of the Cognito Hosted UI with User Pool-based Federation. This approach to Federation using Cognito and Amplify allows the developer to automatically handle the Authentication flows for supported external Social Providers, as well as for Cognito User Pools. There is no need to use Cognito Identity Pools, and Cognito creates a linked user in its User Pool to represent any Socially Federated users. In your JS, the Amplify.Auth API facilitates automate handling of all Authentication flows such as Token refresh, Sign Up, Sign In, etc.

Available HOC Parameters

@param {string} WrappedComponent

The React.Component to be wrapped

@param {Object} inAmplifyConfig

The Amplify config object, expressed as it is typically exported by the aws-exports.js files generated by amplify-cli. I.e., a const JSON object typically imported via a statement: "import awsmobile from './aws-exports'" Or another form commonly seen in the AWS docs: "import awsconfig from './aws-exports'"

@param {string} inMode

Allowed values are 'button' or 'timer'. Anything but 'timer' defaults to 'button'. The inMode property is explained further below.

@param {number} inDelay

If mode is 'timer', inDelay is the number of milliseconds the timer will wait. See below.

The inMode property refers to the behavior of the HOC control when state indicates that authentication is required.

The 'button' mode means that in such cases, we will require the User to manually click a button to reach the Hosted UI login screen. Typically a wrapped component will render unprotected content when the User is not logged in.

The 'timer' mode means that in such cases, we will wait for a certain time before automatically redirecting the User to the Hosted UI. Typically the wrapped component will have no unprotected content to display. The wait time is needed because Amplify cannot immediately detect that the User has successfully logged in (this happens not only for Social providers but for Cognito User Pools as well). Thus without requiring a 'button', there is no feasible way to redirect the User to the Hosted UI without risking the chance that he or she is already logged in, hence creating an "infinite UI loop" where a User logs in, and then is again redirected to the Hosted UI. This time delay is usually between 700-800 ms on a typical network connection. The wait in milliseconds is configured via the inDelay property of the HOC. The default is around 1500ms. It is worth noting that if the default is exceeded, the infinite UI looping will occur for as long as that condition persists, so be conservative in adjusting this. 800ms is usually safe, but not always.

Typically, 'button' mode is fine for apps with meaningful unprotected content. For such apps, the UX of having to click another button before being redirected to a proper Sign Up / Sign In page is common. However for apps that need to Authenticate the User before doing anything, the 'button' UX is less desirable than the 'timer' UX.

With the Cognito Hosted UI, your app is technically not an SPA any longer, but only during Authentication. The look and feel of the Hosted UI is configurable and its use offloads a ton of the gruntwork required to support robust Authentication flows.

Notes

As of this writing (mid-2019), the aws-amplify package is huge, and it is pointless to use the smaller scoped packages (i.e., @aws-amplify/auth) because we also need aws-amplify-react, which itself does not use the scoped packages. The Amplify team is working on that with an RFC and it is likely that by the time you read this, the aws-amplify library will be ES6-modularized, so that Webpack 4 tree-shaking will slim down your production bundles automatically even without using the scoped packages.

The HOC is aware of three different classes that can be used for backing stores for the Cognito Auth configuration object: the default store (where the config's Auth.storage property does not exist), the AuthStorageMemory.js class, and the AuthStorageIDB.js class (the latter two from the https://www.npmjs.com/package/cognito-auth-storage package). The first two need no special handling, so this component need not import them. However AuthStorageIDB needs special handling on instantiation, so this project must install the cognito-auth-storage package so it can import AuthStorageIDB from it.

For a full set of examples on how to use the HOC, see the repo at https://github.com/systemdesignpartners/cognito-hoc-examples