{"id":16753,"library":"amphora-auth","title":"Amphora Authentication Adapter","description":"amphora-auth serves as an authentication adapter specifically designed for the Amphora content management system, providing robust user authentication capabilities within the Clay ecosystem. It facilitates both local username/password authentication and seamless integration with a variety of third-party OAuth providers, including Google, Twitter, Slack, Cognito, and LDAP. This broad support enables flexible and secure authentication strategies for applications built on the Clay platform. The current stable version is 2.1.0. While a specific release cadence isn't explicitly stated, updates likely align with developments in the broader Clay platform. Its primary differentiator is its deep, opinionated integration with Amphora and Clay, which significantly simplifies the setup and management of diverse authentication backends for Clay-based applications, streamlining security configuration.","status":"active","version":"2.1.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript"],"install":[{"cmd":"npm install amphora-auth","lang":"bash","label":"npm"},{"cmd":"yarn add amphora-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add amphora-auth","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for template rendering within the Clay ecosystem, potentially for login pages or email templates.","package":"clayhandlebars","optional":false}],"imports":[{"note":"The module typically exports a single function as its default export, which is then immediately invoked for configuration.","wrong":"import { amphoraAuth } from 'amphora-auth';\nconst amphoraAuth = require('amphora-auth');","symbol":"amphoraAuth","correct":"import amphoraAuth from 'amphora-auth';"},{"note":"While the primary usage is the default export, advanced scenarios might require direct access to internal services like AuthService.","wrong":"const { AuthService } = require('amphora-auth');","symbol":"AuthService","correct":"import { AuthService } from 'amphora-auth';"}],"quickstart":{"code":"import amphoraAuth from 'amphora-auth';\nimport express from 'express';\nimport redis from 'redis';\nimport session from 'express-session';\nimport connectRedis from 'connect-redis';\n\nconst app = express();\nconst router = express.Router();\nconst RedisStore = connectRedis(session);\n\n// Dummy implementations for required parameters\nconst providers = {\n  google: {\n    // In a real app, these would come from env vars\n    consumerKey: process.env.GOOGLE_CONSUMER_KEY ?? '',\n    consumerSecret: process.env.GOOGLE_CONSUMER_SECRET ?? ''\n  }\n  // ... other providers like twitter, slack, cognito, ldap\n};\n\nconst redisClient = redis.createClient();\nconst store = new RedisStore({ client: redisClient });\n\nconst site = { slug: 'my-site', host: 'localhost:3001' }; // Example site metadata\nconst storage = { \n  get: () => Promise.resolve({ data: {} }),\n  put: () => Promise.resolve({})\n}; // Mock DB instance\nconst bus = { \n  publish: () => {},\n  subscribe: () => {}\n}; // Mock Redis bus instance\n\n// Initialize auth module\namphoraAuth({\n  router, // Site router for auth routes\n  providers, // Authentication providers configuration\n  store, // Redis Session Store for sessions\n  site, // Site metadata\n  storage, // DB instance for user storage\n  bus // Redis bus instance for inter-process communication\n});\n\napp.use(session({\n  store: store,\n  secret: 'supersecretkey',\n  resave: false,\n  saveUninitialized: false,\n  cookie: { secure: false } // Set to true in production with HTTPS\n}));\n\napp.use(router);\n\napp.get('/', (req, res) => {\n  res.send('Amphora Auth is running!');\n});\n\napp.listen(3000, () => {\n  console.log('Server running on port 3000');\n});","lang":"javascript","description":"This quickstart demonstrates how to initialize `amphora-auth` within an Express application, showing the required parameters for basic setup and mocking dependencies like Redis store, site metadata, and storage. It highlights the primary configuration function of the module."},"warnings":[{"fix":"Ensure all necessary environment variables (e.g., `GOOGLE_CONSUMER_KEY`, `TWITTER_CONSUMER_SECRET`, `COGNITO_CONSUMER_DOMAIN`, `LDAP_URL`) are correctly set in the deployment environment where `amphora-auth` is running.","message":"Missing or incorrectly configured environment variables for authentication providers will prevent users from authenticating via those methods. Each provider (Google, Twitter, Slack, Cognito, LDAP) requires specific `_CONSUMER_KEY`, `_CONSUMER_SECRET`, and potentially other variables to be exported.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Verify that `clayhandlebars@5` is installed in your project's dependencies alongside `amphora-auth`. Use `npm install clayhandlebars@5` or `yarn add clayhandlebars@5` if missing or incorrect.","message":"The `clayhandlebars` package is a peer dependency, specifically requiring version `5`. Mismatches with other versions of `clayhandlebars` or its absence can lead to runtime errors, particularly in template rendering related to authentication pages.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Be mindful of this flag's impact. Only enable `MAINTENANCE_MODE_ENABLED=true` when intended for a system-wide maintenance event. Ensure clear communication with users if this feature is used unexpectedly.","message":"Setting the `MAINTENANCE_MODE_ENABLED` environment variable to `true` will prevent all users from entering edit mode or making any edits, redirecting them to a login page with a maintenance message. This can be enabled even if users were already in an editing session.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Double-check the `user.yml` configuration (username, provider, password, auth role) and ensure `clay import` is run with the correct API key and target instance. For OAuth users, the username must match the provider's identifier (e.g., full email for Google).","message":"User accounts must be imported correctly using `claycli` with a `user.yml` file. Incorrect `username`, `provider`, `password`, or `auth` roles will result in failed login attempts, even if provider configurations are otherwise correct.","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 `storage` object passed during initialization conforms to the expected interface with `get` and `put` methods, typically an Amphora storage instance.","cause":"The `storage` parameter passed to `amphoraAuth` is not a valid DB instance or lacks the required `get` and `put` methods.","error":"TypeError: Cannot read properties of undefined (reading 'get') or storage.get is not a function"},{"fix":"Set the required environment variables for the specified provider (e.g., `export GOOGLE_CONSUMER_KEY='your_key'`) in the environment where the application runs.","cause":"An authentication provider (e.g., Google, Twitter) is configured, but its corresponding environment variables (consumer key, secret, etc.) are not set.","error":"Error: Missing environment variable for [ProviderName] provider"},{"fix":"Verify the user exists in your Clay instance and that their `username` and `provider` in `user.yml` (and thus in the database) match the login attempt. Re-import the `user.yml` if necessary.","cause":"The user account does not exist in the database or the `user.yml` import was incorrect/incomplete, or the specified provider doesn't match the imported user's provider.","error":"Error: Failed to fetch user data for [username]"},{"fix":"Ensure `express-session` is initialized with a `store` (e.g., `RedisStore`) and mounted on the Express app *before* `amphora-auth` is called, and that `redis` and `connect-redis` are correctly configured.","cause":"The Express session middleware is not correctly configured with a session store before `amphora-auth` is initialized, or `connect-redis` is not properly set up.","error":"Error: Passport session setup requires a session store."}],"ecosystem":"npm","meta_description":null}