SPEAKER: Hello, and welcome to this episode
of Apigee Accelerators.
In this video, we'll demonstrate how
to use Apigee to secure APIs using JSON Web Tokens.
JSON Web Token, also, known as JWT or "jwat"
is an open standard that describes
a compact and secure way to transfer information
between two parties.
The information is contained in a set of claims.
Encoded is JSON object, which can be digitally
signed and also encrypted.
JSON Web Tokens offer some advantages
over opaque access tokens as they're a self-contained token
that doesn't require the recipient to make
additional requests to validate or retrieve information.
In a typical scenario, an application
that needs to send information about itself or a user
may generate a JWT and send this to the receiving API
as a bearer token using the authorization header.
The server will verify the incoming token
and decode it to retrieve any claims contained within it.
Apigee offers three policies for handling JWTs The GenerateJWT
policy allows customers to generate a new token
and return it to the client or attach it to the request sent
through to the target back end.
The VerifyJWT policy is used to verify tokens and extract
claims.
Finally, the DecodeJWT policy allows
you to decode a token without verifying it.
Apigee also has similar policies for working with JSON Web
Signature, which is another standard in the same family
of specifications.
This sample contains a proxy that shows you how
to generate and verify tokens.
The proxy allows you to generate tokens
using the RS256 algorithm, which requires
a public private key pair.
The deployment script for this sample generates the key pair
and stores it in a key value map during the deployment.
The sample also shows how to verify
the token signature using the public key
and decrypt using the private key.
If you attempt to modify the token
or send a token, which is expired,
Apigee will return a 401 unauthorized response.
If the token's valid, the verification endpoints
will output the contents of the decoded token,
showing the claims and the algorithm that
was used to generate it.
Now, let's see how to deploy it and use a sample.
In order to run this sample, you'll need the following,
an Apigee X instance provisioned with access configured
for external traffic.
As a user, you'll need permissions
to deploy API proxies and create key value map entries.
This can be granted through the Apigee org admin
role or the API plus environment admin roles.
To deploy this sample, you'll also
need the command line tools shown here.
If you're using Google Cloud Shell,
these are already installed.
You can click the Cloud Shell tutorial link to begin.
Now that you're in the Cloud Shell environment,
you can follow the step by step instructions.
First, change to the directory for this sample.
To deploy the sample, first, open up the env.sh file
and set the configuration to reference
your Apigee project, external hostname, and the environment
name.
Next, run the included script to deploy the sample.
This may take a minute to complete.
When the script completes, you should
see a message showing the proxy URL and a set of sample code
commands.
First, set the proxy URL environment variable.
Next, run the first code command to generate assigned JWT.
You should see the value of the token returned in the output.
Now, you can use the next code command
to verify and decode the token returned
from the previous request.
If it's successful, you should see a response
containing JWT OK, followed by the decoded contents
of the token.
You can try modifying the token and replaying
the verify request.
This time, you should receive an invalid token error.
This is because modifying the contents
invalidates the digital signature.
Next, you can follow the remaining two
commands to generate and verify an encrypted JWT.
Notice, this time, the decoded output
also contains the encryption header.
If you copy the token into an external tool,
like JWT.io you'll see the contents are garbled,
because the token is encrypted.
Now, let's take a quick look at the proxy
deployed in this sample.
Go to the Apigee Management UI at apigee.google.com.
Under the API proxy section, you should
see the JSON Web Token's proxy.
Select the proxy and go to the Develop tab.
The generate signed endpoint uses the generate JWT policy
to generate a signed token.
The Policy Config references the private key and algorithm,
sets the expiry time, and also, specifies several other claims
to be included in the token.
The verify signed endpoint uses the verified JWT policy
to verify the incoming token.
This time, the policy specifies the public key
to use to validate the signature,
and also, the expected value of the claims
contained within the token.
The generate encrypted and verify encrypted endpoints
are configured in a similar way.
However, this uses the public key to encrypt the token
and uses the private key to decrypt
the token during verification.
Notice the verification policies also
specify a time allowance value of 30 seconds.
This provides an extra grace period for the tokens validity
window.
Finally, the proxy also contains two end points
you can use to output the values of the public and private keys.
The keys themselves are stored in a key value
map, which you can find under the environment section.
Now, you've seen how to use Apigee's built in policies
to handle JSON Web Tokens.
When you're done with the sample,
you can provide us with your feedback,
and then you can use the clean up script
to delete the configuration that was deployed to your Google
Cloud project.
We hope you found this useful.
And if you enjoyed the video, please,
hit the Like button below.
You can also subscribe to our channel
to see more videos in the Apigee Accelerator series.
And if you have questions, please, post them
on the Apache community.
Thanks for watching.