Guard API
Methods and properties of the guard returned by auth.use('jwt').
Methods
generate(user)
Issues an access token for the user, and a refresh token when refresh tokens are configured. Sets the cookies when useCookies / useCookiesForRefreshToken are enabled.
const result = await auth.use('jwt').generate(user)Returns a JwtGenerateResult:
type JwtGenerateResult = {
type: 'bearer'
token: string
expiresIn: number // seconds
refreshToken?: string
refreshTokenExpiresIn?: number // seconds
}expiresIn and refreshTokenExpiresIn are in seconds, whatever the format of tokenExpiresIn and refreshTokenExpiresIn in the config. When the guard has a refreshTokenUserProvider, refreshToken and refreshTokenExpiresIn are always set and typed accordingly, so no non-null assertion is needed.
Throws in JWKS mode.
authenticate()
Reads the access token from the request, verifies it and loads the user. Returns the user, with currentToken set to the access token. Throws E_UNAUTHORIZED_ACCESS if the request is not authenticated.
The auth middleware calls it for you. Calling it several times in the same request only authenticates once.
check()
Same as authenticate(), but returns true or false instead of throwing.
getUserOrFail()
Returns the authenticated user, or throws E_UNAUTHORIZED_ACCESS.
generateWithRefreshToken(refreshToken?)
Exchanges a refresh token for a new access token and a new refresh token, and deletes the used refresh token. Reads the refresh token from the request when it isn't passed. Returns a JwtGenerateResult, and authenticates the user, with currentToken set to the new access token.
Throws E_UNAUTHORIZED_ACCESS if the refresh token is missing, unknown, expired, already used or lacks the refreshTokenAbilities. See Refresh tokens.
revoke(refreshToken?)
Deletes the refresh token from the database and clears the cookies set by the guard. When it isn't passed, revokes the refresh token issued earlier in the same request, or else reads it from the request. Throws E_UNAUTHORIZED_ACCESS if no valid refresh token is found (the cookies are cleared anyway), or if refresh tokens are not configured. See Revoke a refresh token.
authenticateAsClient(user)
Used by Japa's loginAs. See Testing.
Properties
| Property | Description |
|---|---|
user | The authenticated user, with currentToken, or undefined |
isAuthenticated | true once the request is authenticated |
authenticationAttempted | true once an authentication has been attempted |
driverName | 'jwt' |
User provider
The provider option accepts any object implementing JwtUserProviderContract. sessionUserProvider() from @adonisjs/auth/session implements it for Lucid models. To authenticate something else, for example services identified by an external token, write your own:
import { symbols } from '@adonisjs/auth'
import type { JwtGuardUser, JwtUserProviderContract } from '@maximemrf/adonisjs-jwt/types'
type Service = { id: string; name: string }
export class ServiceUserProvider implements JwtUserProviderContract<Service> {
declare [symbols.PROVIDER_REAL_USER]: Service
async createUserForGuard(service: Service): Promise<JwtGuardUser<Service>> {
return {
getId: () => service.id,
getOriginal: () => service,
}
}
async findById(id: string | number | BigInt): Promise<JwtGuardUser<Service> | null> {
const service = await findServiceSomehow(String(id))
return service ? this.createUserForGuard(service) : null
}
}findByIdreceives the id returned bygetUserId(by default theuserIdclaim). Returnnullto reject the token.createUserForGuardwraps the user passed togenerate().
Exports
// main entrypoint
import { jwtGuard, JwtGuard, DEFAULT_TOKEN_EXPIRES_IN } from '@maximemrf/adonisjs-jwt'
// types
import type {
JwtGuardConfig,
JwtGuardOptions,
JwtGuardUser,
JwtUserProviderContract,
JwtGenerateResult,
BaseJwtContent,
JwtCookieOptions,
} from '@maximemrf/adonisjs-jwt/types'JwtGuardConfig is the type of the jwtGuard() config, and JwtGuardOptions the type of the JwtGuard constructor options. @maximemrf/adonisjs-jwt/types only exports types.
@maximemrf/adonisjs-jwt/jwt_config still exports jwtGuard, for compatibility with 0.x.