iss
) - The issuer of the token (defaults to the application's base URL)iat
) - When the token was issued (unix timestamp)sub
) - This holds the identifier for the token (defaults to user id)exp
) - The token expiry date (unix timestamp)jti
) - A unique identifier for the token (md5 of the sub and iat claims)scope)
- A space delimited string of scopes attached to the tokencbsecurity_refresh
) - If you are using refresh tokens, this custom claim will be added to the payload.cbsecurity.models.JWTService
and can be retrieved by either injecting the service ([email protected]
) or using our helper method (jwtAuth()
).prc
scope that will be used to store an authenticated user object if the JWT request is valid. The default is prc.oCurrentUser
iss
claim of the token. If empty, we will use the event.buildLink()
to create the issuer. By default, our validators also check that tokens are created by the same issuer.JWT_SECRET
, if that setting is also empty, then we will auto-generate a secret token that will last as long as the ColdFusion application scope lasts. So technically, your secret will rotate only if a secret is not specified.authorization
header for a bearer token. However, it can also look in a custom header by this name, which defaults to x-auth-token
. Finally, if not found, it will also look into the rc
scope for a rc[ 'x-auth-token' ]
as well.RS
and ES
algorithms, asymmetric keys are expected to be provided in unencrypted PEM or JWK format (in the latter case first deserialize the JWK to a CFML struct). When using PEM, private keys need to be encoded in PKCS#8 format.cbjwt_
User
object must implement our JWTSubject
interface with the following functions:getJwtCustomClaims( payload )
- This is a struct of custom claims to incorporate into the token payload at construction time. This can be ANYTHING you like.getJwtScopes()
- We will also call this at construction time in order to incorporate the right permission scopes into the token according to your user. This must be an array of scopes/permissions.attempt( username, password, [ customClaims:struct ] ):token
- Attempt to authenticate a user with the authentication service and if successful, return the token using the identifier and custom claims. Exception if invalid authenticationfromUser( user, [ customClaims:struct ] ):token
- Generate a token according to the passed user object and custom claims.encode( struct payload ):token
- Generate a raw jwt token from a native payload struct.verify( required token ):boolean
- Verify a token string or throws exceptiondecode( required token ):struct
- Decode and retrieve the passed in token to CFML structparseToken( token, storeInContext, authenticate ):struct
- Get the decoded token using the headers strategy and store it in the prc.jwt_token
and the decoded data as prc.jwt_payload
if it verifies correctly. Throws: TokenExpiredException
if the token is expired, TokenInvalidException
if the token doesn't verify decoding, TokenNotFoundException
if not foundgetToken():string
- Get the stored token from prc.jwt_token
, if it doesn't exist, it tries to parse it via parseToken()
, if not token is set this will be an empty string.getPayload():struct
- Get the stored token from prc.jwt_payload
, if it doesn't exist, it tries to parse it via parseToken()
, if not token is set this will be an empty struct.setToken( token ):JWTService
- Store the token in prc.jwt_token
, and store the decoded version in prc.jwt_payload
authenticate( [payload] ):User
- Authenticates a passed or detected token payload and return the user it representsgetuser()
- Get the authenticated user according to the access token detectedlogout()
- Logout a user and invalidate their tokeninvalidateAll( async:false )
- Invalidate all access and refresh tokens in permanent storageinvalidate( token )
- Invalidates the incoming token by removing it from the permanent storage.isTokenInStorage( token )
- Checks if the passed token exists in permanent storage.getTokenStorage( force:false )
- Get the current token storage implementation. You can also force create it again if needed.attempt( username, password, [ customClaims:struct ] ):struct
- Attempt to authenticate a user with the authentication service and if successful, return a struct containing an access and refresh token.fromUser( user, [ customClaims:struct ] ):struct
- Generate a struct of refresh and access token according to the passed user object and custom claims.Auth
controllerhttp
configuration block to allow for the presence of tokens in both the request and response headers:HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\HTTP\Parameters\MaxFieldLength
- Sets an upper limit, in bytes, for each header. The default value is 65534 bytes and the maximum value is 65534 bytes ( 64kb )HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\HTTP\Parameters\MaxRequestBytes
- Sets the upper limit for the request line and the headers, combined. As such 128K should allow for both long URLs, as well as JWT tokens in the headers. The default value is 16384 bytes and the maximum value is 16777216 bytes ( 16 MB )LimitRequestFieldSize
setting in each <VirtualHost...>
entry in order increase the default header size from the default 8 kilobytes. Example, with a setting of 128 kilobytes: