ra-auth-cognito React-Admin Authentication Provider

Common errors

• Auth error: Invalid session

  cause The user's Cognito session has expired, they are unauthenticated, or they are trying to log in with a temporary password that requires a change, but the application isn't handling the temporary password flow.
  fix Ensure the application handles temporary password changes on first login (using `<Login>` component). If not a first login, the user needs to re-authenticate. Check network requests for more specific Cognito error codes.

• CORS error: Redirect URI mismatch

  cause When using OAuth, the redirect URI configured in your `ra-auth-cognito` setup (or derived from your application's URL) does not match the allowed callback URLs specified in your AWS Cognito User Pool's App Client settings.
  fix Verify that the `hostedUIUrl` in your `CognitoAuthProvider` configuration (if using OAuth) and the 'Callback URLs' list in your Cognito App Client settings in the AWS console are identical, including scheme (http/https), hostname, and path.

• User is not confirmed.

  cause The user account exists in Cognito but has not yet been confirmed (e.g., through email verification or admin confirmation).
  fix Either have the user complete the confirmation process (if email/SMS verification is enabled) or manually confirm the user in the AWS Cognito console.

• Missing required parameter UserPoolId

  cause The `UserPoolId` or `ClientId` for the `CognitoUserPool` constructor (or `CognitoAuthProvider` options in OAuth mode) is missing or incorrectly provided.
  fix Double-check that `UserPoolId` and `ClientId` environment variables or direct values are correctly set and passed to the `CognitoUserPool` constructor or `CognitoAuthProvider` options.

Warnings

• breaking Version 2.0.0 of `ra-auth-cognito` introduces breaking changes by updating its peer dependency to `react-admin` v5. Applications using `react-admin` v4 or older must remain on `ra-auth-cognito` v1.x.
  Fix: Upgrade `react-admin` to v5 or greater, or pin `ra-auth-cognito` to version 1.x if staying on an older `react-admin` version.
• gotcha When using username/password authentication, AWS Cognito often requires users to change a temporary password on their first login. Failing to use the provided `<Login>` component or `useCognitoLogin` hook will result in a stuck user experience.
  Fix: Ensure your `Admin` component's `loginPage` prop is set to the exported `Login` component, or implement a custom login page using the `useCognitoLogin` hook to handle the temporary password change flow.
• gotcha All users attempting to sign in must first be added to the configured Cognito user pool and have a valid email address associated with their profile for the authentication flow to succeed.
  Fix: Verify that users exist in your AWS Cognito User Pool and have a confirmed status with an email attribute.
• gotcha Configuring OAuth with AWS Hosted UI requires precise setup of the `hostedUIUrl`, `clientId`, and `userPoolId`, along with correctly configured redirect URLs in your Cognito App Client settings. An incorrect setup often leads to redirect failures or authentication errors.
  Fix: Double-check your `CognitoAuthProvider` configuration parameters for `mode: 'oauth'` and ensure the `hostedUIUrl` and Cognito App Client redirect URLs match exactly.
• gotcha The `authProvider.getPermissions()` method returns an array of Cognito user groups. If your Cognito user pool does not use groups, or the user is not assigned to any, this method will return an empty array, potentially leading to incorrect authorization behavior in `react-admin`.
  Fix: Ensure your Cognito User Pool is configured with groups, and users are assigned to relevant groups to leverage `react-admin`'s permission-based access control.

Install

• npm install ra-auth-cognito npm
• yarn add ra-auth-cognito yarn
• pnpm add ra-auth-cognito pnpm

Imports

• CognitoAuthProvider
  wrong:

  const { CognitoAuthProvider } = require('ra-auth-cognito');

  correct:

  import { CognitoAuthProvider } from 'ra-auth-cognito';

  This is a named export for creating the authentication provider instance. TypeScript types are included.
• Login
  wrong:

  import Login from 'ra-auth-cognito/Login';

  correct:

  import { Login } from 'ra-auth-cognito';

  A pre-built React component for the login page, particularly useful for handling temporary passwords on first login. It's a named export.
• LoginForm
  wrong:

  import { Login } from 'ra-auth-cognito/LoginForm';

  correct:

  import { LoginForm } from 'ra-auth-cognito';

  A component used internally by `Login` and for custom login page development. It's a named export.
• useCognitoLogin

  import { useCognitoLogin } from 'ra-auth-cognito';

  A React hook to manage login logic, offering more granular control for custom login page implementations.

Quickstart

This quickstart demonstrates how to integrate `ra-auth-cognito` with `react-admin` for username/password authentication. It configures the `CognitoAuthProvider` using a `CognitoUserPool` instance and sets the custom `Login` component to handle initial logins with temporary passwords, common in Cognito setups.

import React from 'react';
import { Admin, Resource } from 'react-admin';
import { CognitoAuthProvider, Login } from 'ra-auth-cognito';
import { CognitoUserPool } from 'amazon-cognito-identity-js';

// Mock data provider and resources for demonstration
const dataProvider = {
    getList: () => Promise.resolve({ data: [{ id: 1, title: 'Post 1' }], total: 1 }),
    getOne: () => Promise.resolve({ data: { id: 1, title: 'Post 1' } }),
    getMany: () => Promise.resolve({ data: [{ id: 1, title: 'Post 1' }] }),
    getManyReference: () => Promise.resolve({ data: [{ id: 1, title: 'Post 1' }], total: 1 }),
    update: () => Promise.resolve({ data: { id: 1, title: 'Post 1' } }),
    updateMany: () => Promise.resolve({ data: [{ id: 1, title: 'Post 1' }] }),
    create: () => Promise.resolve({ data: { id: 1, title: 'New Post' } }),
    delete: () => Promise.resolve({ data: { id: 1, title: 'Post 1' } }),
    deleteMany: () => Promise.resolve({ data: [{ id: 1, title: 'Post 1' }] })
};
const posts = { list: () => <div>Posts List</div>, edit: () => <div>Edit Post</div> };

// Ensure these environment variables are set in your .env file or build process
const userPoolId = process.env.REACT_APP_COGNITO_USERPOOL_ID ?? 'us-east-1_XXXXX';
const clientId = process.env.REACT_APP_COGNITO_APP_CLIENT_ID ?? 'XXXXXXXXXXXX';

const userPool = new CognitoUserPool({
    UserPoolId: userPoolId,
    ClientId: clientId
});

const authProvider = CognitoAuthProvider(userPool);

const App = () => {
    if (!userPoolId || !clientId) {
        console.error('Cognito UserPoolId or ClientId not set. Please check your environment variables.');
        return <div>Configuration Error: Cognito details missing.</div>;
    }
    return (
        <Admin
            authProvider={authProvider}
            dataProvider={dataProvider}
            title="Example Admin"
            loginPage={Login} // Use the provided Login component for temporary password handling
        >
            <Resource name="posts" {...posts} />
        </Admin>
    );
};

export default App;