JSON Web Token is a simple way to send information in the clear (usually in a URL) whose contents can be
verified to
be trusted. JWT are well suited for scenarios as:

In a Single Sign-On scenario where you want a separate authentication server that can then send user
information in a trusted way.

Stateless API servers, very well suited for simple page applications.

etc…​

Before deciding on using JWT, it’s important to note that JWT does not encrypt the payload, it only signs it. You
should not send any secret information using JWT, rather you should send information that is not secret but needs to
be verified. For instance, sending a signed user id to indicate the user that should be logged in would work great!
Sending a user’s password would be very, very bad.

Its main advantages are:

It allows you to verify token authenticity.

It has a json body to contain any variable amount of data you want.

It’s completely stateless.

To create an instance of the provider you use JWTAuth. You specify the configuration
in a JSON object.

A typical flow of JWT usage is that in your application you have one end point that issues tokens, this end point
should be running in SSL mode, there after you verify the request user, say by its username and password you would
do:

When no keystore is provided the implementation falls back in unsecure mode and signatures will not be verified, this
is useful for the cases where the payload if signed and or encrypted by external means.

Generate a new Keystore file

The only required tool to generate a keystore file is keytool, you can now specify which algorithms you need by
running:

AuthN/AuthZ with JWT

A common scenario when developing for example micro services is that you want you application to consume APIs. These
api’s are not meant to be consumed by humans so we should remove all the interactive part of authenticating the
consumer out of the picture.

In this scenario one can use HTTP as the protocol to consume this API and the HTTP protocol already defines that there
is a header Authorization that should be used for passing authorization information. In most cases you will see that
tokens are sent as bearer tokens, i.e.: Authorization: Bearer some+base64+string.

Authenticating (AuthN)

For this provider a user is authenticated if the token passes the signature checks and that the token is not expired.
For this reason it is imperative that private keys are kept private and not copy pasted across project since it would
be a security hole.

fields: exp, iat, nbf, audience, issuer are valid according to the config

If all these are valid then the token is considered good and a user object is returned.

While the fields exp, iat and nbf are simple timestamp checks only exp can be configured to be ignored:

# This string is what you see after the string "Bearer" in the# HTTP Authorization header# In this case we are forcing the provider to ignore the `exp` field
jwtAuth.authenticate({
'jwt' => "BASE64-ENCODED-STRING",
'options' => {
'ignoreExpiration' => true
}
}) { |res_err,res|
if (res_err == nil)
theUser = res
else# Failed!end
}

In order to verify the aud field one needs to pass the options like before:

# This string is what you see after the string "Bearer" in the# HTTP Authorization header# In this case we are forcing the provider to ignore the `exp` field
jwtAuth.authenticate({
'jwt' => "BASE64-ENCODED-STRING",
'options' => {
'audience' => [
"paulo@server.com"
]
}
}) { |res_err,res|
if (res_err == nil)
theUser = res
else# Failed!end
}

And the same for the issuer:

# This string is what you see after the string "Bearer" in the# HTTP Authorization header# In this case we are forcing the provider to ignore the `exp` field
jwtAuth.authenticate({
'jwt' => "BASE64-ENCODED-STRING",
'options' => {
'issuer' => "mycorp.com"
}
}) { |res_err,res|
if (res_err == nil)
theUser = res
else# Failed!end
}

Authorizing (AuthZ)

Once a token is parsed and is valid we can use it to perform authorization tasks. The most simple is to verify if a
user has a specific authority. In this case one needs to to:

By default the provider will lookup under the key permissions but like the other providers one can extend the
concept to authorities to roles by using the : as a splitter, so role:authority can be used to lookup the token.

Since JWT are quite free form and there is no standard on where to lookup for the claims the location can be
configured to use something else than permissions, for example one can even lookup under a path like this:

So in this example we configure the JWT to work with Keycloak token format. In this case the claims will be checked
under the path realm_access/roles rather than permissions.
<a href="mailto:julien@julienviet.com">Julien Viet</a><a href="http://tfox.org">Tim Fox</a><a href="mailto:pmlopes@gmail.com">Paulo Lopes</a>