{"id":16881,"library":"ra-auth-cognito","title":"ra-auth-cognito React-Admin Authentication Provider","description":"ra-auth-cognito is an authentication provider designed specifically for React-Admin applications, integrating seamlessly with AWS Cognito user pools. The current stable version is 2.0.0, which introduced compatibility with React-Admin v5. The package typically releases new major versions aligned with React-Admin's major updates, alongside minor and patch releases for features and bug fixes. Key differentiators include robust support for username/password authentication, OAuth flows via AWS Hosted UI, and multi-factor authentication (MFA) including TOTP. It provides specialized components and hooks, such as `Login` and `useCognitoLogin`, to manage the initial login process for users with temporary passwords. This library simplifies common Cognito integration challenges within React-Admin, allowing developers to handle user identity, group-based permissions, and various authentication flows directly within their admin interfaces. Users must be pre-registered in Cognito with an email for the system to function correctly.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/marmelab/ra-auth-cognito","tags":["javascript","typescript"],"install":[{"cmd":"npm install ra-auth-cognito","lang":"bash","label":"npm"},{"cmd":"yarn add ra-auth-cognito","lang":"bash","label":"yarn"},{"cmd":"pnpm add ra-auth-cognito","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core UI library dependency for React components.","package":"react","optional":false},{"reason":"DOM rendering library for React applications.","package":"react-dom","optional":false},{"reason":"The primary framework this package extends and integrates with.","package":"react-admin","optional":false},{"reason":"Used for rendering QR codes, specifically for TOTP MFA setup.","package":"qrcode.react","optional":false},{"reason":"The underlying AWS SDK for managing Cognito user authentication and identity.","package":"amazon-cognito-identity-js","optional":false}],"imports":[{"note":"This is a named export for creating the authentication provider instance. TypeScript types are included.","wrong":"const { CognitoAuthProvider } = require('ra-auth-cognito');","symbol":"CognitoAuthProvider","correct":"import { CognitoAuthProvider } from 'ra-auth-cognito';"},{"note":"A pre-built React component for the login page, particularly useful for handling temporary passwords on first login. It's a named export.","wrong":"import Login from 'ra-auth-cognito/Login';","symbol":"Login","correct":"import { Login } from 'ra-auth-cognito';"},{"note":"A component used internally by `Login` and for custom login page development. It's a named export.","wrong":"import { Login } from 'ra-auth-cognito/LoginForm';","symbol":"LoginForm","correct":"import { LoginForm } from 'ra-auth-cognito';"},{"note":"A React hook to manage login logic, offering more granular control for custom login page implementations.","symbol":"useCognitoLogin","correct":"import { useCognitoLogin } from 'ra-auth-cognito';"}],"quickstart":{"code":"import React from 'react';\nimport { Admin, Resource } from 'react-admin';\nimport { CognitoAuthProvider, Login } from 'ra-auth-cognito';\nimport { CognitoUserPool } from 'amazon-cognito-identity-js';\n\n// Mock data provider and resources for demonstration\nconst dataProvider = {\n    getList: () => Promise.resolve({ data: [{ id: 1, title: 'Post 1' }], total: 1 }),\n    getOne: () => Promise.resolve({ data: { id: 1, title: 'Post 1' } }),\n    getMany: () => Promise.resolve({ data: [{ id: 1, title: 'Post 1' }] }),\n    getManyReference: () => Promise.resolve({ data: [{ id: 1, title: 'Post 1' }], total: 1 }),\n    update: () => Promise.resolve({ data: { id: 1, title: 'Post 1' } }),\n    updateMany: () => Promise.resolve({ data: [{ id: 1, title: 'Post 1' }] }),\n    create: () => Promise.resolve({ data: { id: 1, title: 'New Post' } }),\n    delete: () => Promise.resolve({ data: { id: 1, title: 'Post 1' } }),\n    deleteMany: () => Promise.resolve({ data: [{ id: 1, title: 'Post 1' }] })\n};\nconst posts = { list: () => <div>Posts List</div>, edit: () => <div>Edit Post</div> };\n\n// Ensure these environment variables are set in your .env file or build process\nconst userPoolId = process.env.REACT_APP_COGNITO_USERPOOL_ID ?? 'us-east-1_XXXXX';\nconst clientId = process.env.REACT_APP_COGNITO_APP_CLIENT_ID ?? 'XXXXXXXXXXXX';\n\nconst userPool = new CognitoUserPool({\n    UserPoolId: userPoolId,\n    ClientId: clientId\n});\n\nconst authProvider = CognitoAuthProvider(userPool);\n\nconst App = () => {\n    if (!userPoolId || !clientId) {\n        console.error('Cognito UserPoolId or ClientId not set. Please check your environment variables.');\n        return <div>Configuration Error: Cognito details missing.</div>;\n    }\n    return (\n        <Admin\n            authProvider={authProvider}\n            dataProvider={dataProvider}\n            title=\"Example Admin\"\n            loginPage={Login} // Use the provided Login component for temporary password handling\n        >\n            <Resource name=\"posts\" {...posts} />\n        </Admin>\n    );\n};\n\nexport default App;\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Verify that users exist in your AWS Cognito User Pool and have a confirmed status with an email attribute.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Double-check your `CognitoAuthProvider` configuration parameters for `mode: 'oauth'` and ensure the `hostedUIUrl` and Cognito App Client redirect URLs match exactly.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","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.","error":"Auth error: Invalid session"},{"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.","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.","error":"CORS error: Redirect URI mismatch"},{"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.","cause":"The user account exists in Cognito but has not yet been confirmed (e.g., through email verification or admin confirmation).","error":"User is not confirmed."},{"fix":"Double-check that `UserPoolId` and `ClientId` environment variables or direct values are correctly set and passed to the `CognitoUserPool` constructor or `CognitoAuthProvider` options.","cause":"The `UserPoolId` or `ClientId` for the `CognitoUserPool` constructor (or `CognitoAuthProvider` options in OAuth mode) is missing or incorrectly provided.","error":"Missing required parameter UserPoolId"}],"ecosystem":"npm","meta_description":null}