ag-auth is the official authentication module for SocketCluster (now Asyngular), providing a robust mechanism for securing real-time applications using JSON Web Tokens (JWT). It handles the signing, verification, and management of authentication tokens. Currently at version 2.1.1, the package is actively maintained, with the latest significant update published in November 2025. It serves as the underlying engine for SocketCluster's `agServer.auth` object, abstracting the complexities of JWT handling. While alternative methods for JWT exist (e.g., direct `jsonwebtoken` usage), ag-auth integrates seamlessly into the SocketCluster ecosystem, offering a standardized and convenient approach to user authentication across HTTP and WebSocket flows. Its primary differentiator is this tight integration, ensuring compatibility and streamlined development within SocketCluster projects.
npm install ag-authVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how `ag-auth` (via `agServer.auth`) is used to sign and verify JWT tokens in a SocketCluster server, handling client authentication.
Update all calls to `agServer.auth.signToken` and `agServer.auth.verifyToken` (and similar) to use `await` or `.then()` for Promise resolution.
Refactor authentication logic to exclusively use JWTs, leveraging `agServer.auth.signToken` and `agServer.auth.verifyToken` for all authentication flows. Migrate any persistent session data to be included within JWT payloads or external stores.
Only store non-sensitive user identifiers (e.g., user ID, roles) in JWT payloads. Fetch sensitive user data from a secure database or service after verifying the token.
Always use a strong, randomly generated, long secret key for `agServer.authKey`. Store it securely (e.g., in environment variables) and rotate it periodically. Never hardcode it in source code.
Ensure the `authKey` used when initializing `AGServer` is identical to the key used to sign the token. Check for accidental whitespace or character discrepancies. If tokens are issued by an external service, verify key synchronization.
Implement token refresh mechanisms on the client-side, where a valid refresh token is used to obtain a new access token before the current one expires. Configure appropriate `expiresIn` values during token signing.
Pass a secure secret key to the `authKey` option of the `AGServer` constructor: `new AGServer({ authKey: process.env.AUTH_SECRET_KEY });`