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 token
cbsecurity_refresh) - If you are using refresh tokens, this custom claim will be added to the payload.
prcscope that will be used to store an authenticated user object if the JWT request is valid. The default is
issclaim 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.
authorizationheader 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
rcscope for a
rc[ 'x-auth-token' ]as well.
ESalgorithms, 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.
Userobject must implement our
JWTSubjectinterface 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 authentication
fromUser( 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 exception
decode( required token ):struct- Decode and retrieve the passed in token to CFML struct
parseToken( token, storeInContext, authenticate ):struct- Get the decoded token using the headers strategy and store it in the
prc.jwt_tokenand the decoded data as
prc.jwt_payloadif it verifies correctly. Throws:
TokenExpiredExceptionif the token is expired,
TokenInvalidExceptionif the token doesn't verify decoding,
TokenNotFoundExceptionif not found
getToken():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
authenticate( [payload] ):User- Authenticates a passed or detected token payload and return the user it represents
getuser()- Get the authenticated user according to the access token detected
logout()- Logout a user and invalidate their token
invalidateAll( async:false )- Invalidate all access and refresh tokens in permanent storage
invalidate( 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.
httpconfiguration 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 )
LimitRequestFieldSizesetting in each
<VirtualHost...>entry in order increase the default header size from the default 8 kilobytes. Example, with a setting of 128 kilobytes: