Personal access token rotation in 3scale

How to rotate 3scale access tokens

Co-author: Kev Price

Summary

This guide is meant to show how it is possible to enable “Access token rotation”, allowing 3scale to use temporary Access Tokens that will be invalidated once they have been used for their purpose.

By the end of this tutorial you should be able to implement a similar setup where the Access token rotation is taken care of completely by 3scale and your external webhook listener service and will take place automatically after a specific event occurs upon which a webhook is triggered.

Important: This guide has nothing to do with access tokens used with the 3scale gateway as part of any OAuth or OpenID Connect flows.

Example scenario

Creating an Application via the 3scale API requires an Access Token to be provided in order for the request to be authorized. Access tokens need Read and Write permissions to the Account Management API and do not expire by default: for this reason the default settings may not be considered secure enough and hence this solution would be applicable.

It is possible to configure 3scale to revoke (delete) an Access Token that was specifically created to be used against the Application Create endpoint, once the task that it was meant for is finalised.

This guide demonstrates how this configuration can be implemented for the following scenario: I want my Access Tokens to be single-use, so that after the token is used for creating an Application via the 3scale API it will be automatically revoked.

Step by step guide

Prerequisites

• 3scale 2.8 On-premises and later OR 3scale SaaS Enterprise
• Webhook listener service (example app can be used to follow this tutorial)

Setup

The following steps should be completed in full before proceeding to the End to End flow in action section. For the purpose of following this tutorial the example app AccessTokenRevoker can be used but it’s recommended that you implement your own webhook listener service in the language you prefer.

• Create a custom field definition on the Application object, make it Hidden. Set the Name field and Label field, in this example they will be token_value and Token Value respectively. The Name field is important here because that is the parameter which will be parsed from the webhook object later.

Creation of a new custom field definition

• Configure 3scale webhooks to deliver upon admin portal actions and specifically for the Application created event.

Webhooks configuration

• Deploy an application running as an external service to 3scale where the 3scale webhooks will be delivered, parsed and that subsequently makes an API call to 3scale to rotate the Access token.
• See the example app instructions to deploy and configure it to follow along with the steps. Here is an example command that can be used to start the example app:

node app.js --url "https://{TENANT | ACCOUNT}-admin.{WILDCARD_DOMAIN | 3scale.net}"

• API call to 3scale should pass the value of the custom field Token Value as both the access_token and id parameters to the Personal Access Token Delete API. Here is an example of a curl request the application should implement in order to successfully revoke the token:

curl -X DELETE "https://{TENANT | ACCOUNT}-admin.{WILDCARD_DOMAIN | 3scale.net}/admin/api/personal/access_tokens/${ACCESS_TOKEN}.json" -d 'access_token=${ACCESS_TOKEN}'

End to end flow in action

• Admin user creates an access token with read/write permissions and scope for the Account Management API
• User creates an application from the 3scale API and will be required to add a value to the field created in the Setup section. The value of this field should be equal to the Access Token created in the previous step.
• Here is an example of a curl request to the 3scale API that can be used to create a new application and rotate the token (notice the token_value field is being assigned the Access Token as a value in the request POST data):

curl -X POST "https://{TENANT | ACCOUNT}-admin.{WILDCARD_DOMAIN | 3scale.net}/admin/api/accounts/${ACCOUNT_ID}/applications.xml" -d 'access_token=${ACCESS_TOKEN}&plan_id=${PLAN_ID}&name=${APPLICATION_NAME}&description=demo&token_value=${ACCESS_TOKEN}'

• The 3scale webhook will be triggered on the Application created event.
• This is an example of what the webhook’s request body looks like. The token value is visible as part of the extra_fields object in: req.body.event.object[0].application[0].extra_fields[0].token_value[0]

Webhook object

• The external service listening for 3scale webhooks will receive the object and should parse the body for the custom field defined previously e.g. token_value and then store this value for the API call to 3scale.

Once the token has been deleted then it will no longer function and cleaning it up from the hidden field on the Application at this point is optional given that the field is configured as hidden at the beginning and is no longer valid.

Alternatively in the set up phase you can set the custom field definition to required instead of hidden which will prevent the user from creating an application without setting this important field. Bear in mind that by doing this the custom field will be visible by default to developers if they have access to the developer portal and that can pose a security threat while the access token is still valid. As a further step you can ensure that the field is not rendered in HTML by customising the liquid templates in the developer portal. That’s beyond the scope of this article, hence will not be covered.

Conclusion

In this article you have learned how some of the 3scale features can be combined to form a flow that can be used for access tokens rotation. This is an example of how 3scale users can make use of access tokens to access all the features available via the 3scale API, by still avoiding any security leak thanks to the temporary tokens.

What’s next?

This workflow can be configured to fit the requirements of the API provider to rotate tokens after any of the supported webhook events are triggered.

Available webhook events