Mantine Cognito

This project provides a Mantine based front end for an AWS Cognito login.

The code is working, but the project is super early in its lifespan and is still coming together. Documentation is in the works.

Quickstart

Install the package and its dependencies:

yarn add @mantine/core @mantine/hooks @emotion/react @mantine/form @mantine/notifications @tabler/icons-react mantine-cognito

To use it in your code, first wrap your app with a new provider above any components that need access to authentication information:

import { CognitoProvider } from 'mantine-cognito';

root.render(
  <React.StrictMode>
    <CognitoProvider cognitoClientID={clientID} cognitoUserPoolID={userPoolID} cognitoIdentityPoolID={identityPoolID}>
      <App />
    </CognitoProvider>
  </React.StrictMode>
);

The Client ID and User Pool ID are required and are the IDs of the AWS Cognito User Pool controlling access and the configured UI Client for the User Pool.

The Identity Pool ID is optional and is used if you want the users in the User Pool to access other AWS services using their authentication.

Once you have the provider installed, you can add in the Login component:

import { Login, LoginStage } from 'mantine-cognito';

export interface LoginPageProps {
  stage?: LoginStage;
}

export const LoginPage = ({ stage = 'login' }: LoginPageProps) => {
  return (
    <Login
      stage={stage}
      onLogin={(attributes) => {
        console.log(`User logged in ${attributes.email}`);
      }}
    />
  );
};

The Login component provides all the user interface needed for an unauthenticated user. It manages logging in (including support for MFA via an authenticator application), registering a new user, resetting passwords, and handling forgotten passwords.

If you want to provide direct access to any of those flows via their own URL it is possible to have the component start out in any of those states. For example using react router:

<Route path="/auth">
  <Route path="login" element={<LoginPage />} />
  <Route path="forgot" element={<LoginPage stage="forgot" />} />
  <Route path="reset" element={<LoginPage stage="reset" />} />
  <Route path="register" element={<LoginPage stage="register" />} />
</Route>

For the portions of your application that you want to be accessible only to authenticated user, you can (using react router):

import { ProtectedRoute } from "mantine-cognito"

<Route
  path="/app"
  element={
    <ProtectedRoute
      unauthenticated={<Navigate to="/" />}
      onValidate={(attributes) => {
        console.log(`User reverified: ${attributes.email}`)
      }}
    >
      <Contents />
    </ProtectedRoute>
  }
>

There is also a component available for users to enable / disable MFA on their accounts:

import { MFASetup } from 'mantine-cognito';

export const Settings = () => {
  return <MFASetup mfaAppName="My Example Application" />;
};

You also have access to some methods via a hook that is available anywhere under the CognitoProvider:

import { useCognito } from 'mantine-cognito';

export const SignoutButton = () => {
  const { logout } = useCognito();

  return <Button onClick={() => logout()}>Log Out</Button>;
};

Or for example, if you have an identity pool setup and need a signed AWS url to provide access to a protect AWS resource:

import { useCognito } from "mantine-cognito"

export interface WebsocketProviderProps {
    url: string
    children?: React.ReactNode
}

export const WebsocketProvider = ({ url, children }: WebsocketProviderProps) => {
    const { presign } = useCognito()

    useEffect(() => {
      presign(url, "execute-api")
        .then((presigned) => {
          const socket = new WebSocket(presigned)
          ...
        }
    }, [presign, url])

    ...
}

Code contributors

License

The MIT License.