Guides
Encrypt Access Tokens with Outbound Relay
Many services collect and manage access tokens for third-party APIs. Access tokens include secrets like OAuth Access Tokens, API keys and raw credentials that developers collect from their end-users to authenticate with third-party APIs.
Access tokens are generally extremely sensitive pieces of data. If they are compromised, they potentially grant an attacker complete access to a customer’s account on the service. This could be anything from access to online banking, sensitive cloud infrastructure or email inboxes. In this section, you will encrypt an access token using outbound relay.
Using Outbound Relay, you can interact with any third-party REST API without ever handling your customers’ sensitive access tokens in plaintext. Outbound Relay is fully compatible with standards like OAuth 2.
Getting Started
Outbound Relay is an invisible decryption proxy that lets you share encrypted data with third-party APIs, without the third-party having to decrypt any fields themselves. With Outbound Relay, you can use Evervault-encrypted access tokens to access any third-party service, without implementing any decryption logic yourself.
The Evervault docs site exposes two API endpoints to emulate what a typical authentication flow might look like.
POST /api/fetchToken
Accepts a password and returns an ephemeral JWT access token
If your request was successfully authenticated using the password provided, the API will return the following response with an access token:
If the authentication failed, the API will return the following response:
POST /api/authenticatedEndpoint
Accepts an Authorization
header with a JWT access token and returns a 200 OK
status code if authentication was successful, or a 401 Unauthorized
status code if authentication failed.
If your request was successfully authenticated, the API will return the following response:
If the authentication failed, the API will return the following response:
The code below contains a sample application which will authenticate with the API and fetch an access token which can later be stored.
By default, Outbound Relay will automatically decrypt the password being passed to the API, so it is received in plaintext.
Encrypt the access token in the response using Outbound Relay
To encrypt the access token in the JSON response, go to the Outbound Relay section in the Evervault Dashboard and add a new Outbound Relay Destination, specifying docs.evervault.com as the domain name.
Once you have added the Outbound Relay Destination, navigate to the Response Encryption section and add $.accessToken
as a field to encrypt. Fields to encrypt can be defined using JSONPath Selectors.
If you run the application again, the code should continue to run as normal, and authentication will be successful. If you check the application logs, you will see that the access token is logged as an Evervault-encrypted string. This means your infrastructure is never handling the access token in plaintext, and it can be stored in your database fully-encrypted.
When you send the request to /api/authenticatedEndpoint
, Outbound Relay will automatically decrypt the Evervault-encrypted access token within the Authorization
header. No additional code changes are required to use the third-party API with encrypted access tokens.
Congratulations! You have successfully encrypted access tokens using Outbound Relay.