Feature Release: Credential Rotation on Developer Portal to Enhance App Security
At PayPal, we take security seriously. Since the client-secret in the API world is akin to your password in the web world, it is a well-known security best practice to regularly change the client-secret that your application uses. Regularly scheduled changes to the client-secret keeps the attackers at bay and ensures that your app is less vulnerable to being compromised.
To simplify the credential rotation process, we have now enabled this capability as a self-service feature on the developer portal. We hope that this feature will provide greater flexibility to our developers in rotating credentials per their own schedule.
Lifecycle of a client-secret at PayPal
A client-secret can have the following three statuses:
1. Enabled
- The client-secret can be used to authenticate your application for API integration
2. Disabled
- The client-secret cannot be used to authenticate your application for API integration
- The client-secret can however be moved to “Enabled” status and made functional again
3. Deleted
- The client-secret is no longer available for use. A client-secret once deleted cannot be Enabled or recovered back
NOTE: There can only be a maximum of two client-secrets. These client-secrets can be in either “Enabled” or “Disabled” status.
Figure 1: Lifecycle of a client-secret at PayPal
Process of Rotating a client-secret
Rotating your client-secret is an easy process and can be performed in a completely self-service fashion on the Developer Portal. The steps are detailed below and are applicable to both your Live and Sandbox client-secret rotation.
1) Generate a new client-secret in addition to your existing “Enabled” one.
Figure 2: Generate a new client-secret
Figure 3: New client-secret created
2) Update your applications to utilize the new client-secret. 3) Validate your application’s functionality. 4) Disable the old client-secret.
Figure 4: Disable a client-secret
5) Validate that your applications continue to work after disabling the old client-secret and with the new client-secret.
6) If there are any issues, re-enable the “Disabled” client-secret.
7) If validation is successful, delete the old client-secret.
Figure 5: Delete a client-secret
Figure 6: Client-secret deleted after developer confirmation
Recommended Best Practices for client-secret rotation
- Rotate client-secrets when your credential custodians change.
- Define, describe, document and agree on a standard process and steps for client-secret rotation.
- Thoroughly validate that your application is working fine before deleting an older client-secret.
- You can always disable a “client-secret” immediately if you suspect that your credentials have been compromised. It is to be noted however, that your application will stop working until you integrate with a new client-secret in “Enabled” status.
- Delete “Disabled” credentials regularly after validating your application with the new client-secret.
In conclusion, regularly updating the client-secret associated with your applications is a security best practice. We recommend that developers utilize the self-service client-secret rotation feature on the developer portal on a regular schedule for maximum application security. We also recommend that developers define, describe, document, and agree on a standard process around client-secret rotation across your team. A well-defined process will ensure that rotating an application’s client-secret is never a pain and that there are no missed steps during application validation with the newly generated client-secret.
Author: Gagan Maheshwari
About the author: Gagan Maheshwari is an architect on the PayPal Developer Platform and is responsible for architecting and leading initiatives to enhance developer experience through solid developer product offerings. He is actively engaged in defining product architecture and executing roadmap for the PayPal Developer Portal and Developer Sandbox. He loves to collaborate with smart people to solve complex challenges.
- Twitter: https://twitter.com/iGaganM
- LinkedIn: https://www.linkedin.com/in/gaganmaheshwari
