LinkedIn
Twitter
This article is Part 2 of the topic "OAuth and Two-Factor Authentication for Maven" and describes how Two-Factor Authentication can be used with apigee-deploy-maven-plugin
Two-Factor Authentication
Two-Factor Authentication provides an additional layer of security to access Apigee Edge. The second factor is the popular OTP (One Time Password) based on the TOTP (Time-based One Time Password) algorithm commonly setup using Google Authenticator mobile app.
Two-Factor Authentication is also referred to as 2FA and is sometimes called generically as MFA (Multi-Factor Authentication) or simply OTP (One Time Password).
Management API
When Two-Factor Authentication is enabled for Apigee login, management API access is also protected using Two-Factor Authentication. This is applicable when OAuth 2.0 security of management API is in effect and does not affect the default Basic Authentication security at the moment.
In future, Basic Authentication will be removed and OAuth 2.0 will be the only security mechanism to access management API. Check Apigee documentation to know more about the latest on OAuth 2.0 support.
Maven and Two-Factor Authentication
apigee-deploy-maven-plugin uses Apigee Edge management API to perform its functions. When Two-Factor Authentication is enabled in Apigee Edge it applies to the plugin as well.
The plugin supports Two-Factor Authentication in 1.1.0 release and accepts the OTP as a parameter. OTP generation is a sensitive operation and needs to be managed securely. The plugin only accepts a generated OTP and does not perform the OTP generation itself.
OTP generation is a well understood concept and can be easily managed. Described below is a way to generate OTP in automated environments to comply with Two-Factor Authentication security.
OTP generation for bots
OTP is based on TOTP algorithm and relies on a alphanumeric code called the "shared secret" held by the server and the client. Apigee creates the "shared secret" and makes it available to OTP generators. This code does not expire and remains valid as long as Two-Factor authentication is enabled for the Apigee account.
The OTP generators (clients) use the "shared secret" to generate a valid OTP independently.
Extracting Shared Secret
The first step is to extract and secure the "shared secret". Follow the steps below to setup Two-Factor authentication and extract the shared secret.
CAUTION: The shared secret is as sensitive as Apigee credentials and needs to be handled extremely carefully. Do not store in your source code repo or hard-code it in scripts. Use the secure credentials handling capability of your CI tool to ensure "shared secret" is encrypted on storage and handled securely upon usage. A few tool specific facilities are given below:
Jenkins: Credentials Plugin
Travis: Encrypted variables in .travis.yml
| Note |
| If you have already enabled Two-Factor authentication you may have to unlink your device and redo it. This would invalidate the setup in an app like Google Authenticator. |
http://docs.apigee.com/api-services/content/enable-two-factor-auth-your-apigee-account1) Following steps in this document to enable Two-Factor authentication for your account.
2) In the step that shows the barcode click on "Unable to scan Barcode" link below the barcode.
3) Copy the code that appears.
OTP Generation
A few CLI tools are available to generate OTP. Refer to individual tool documentation for usage instructions. The general pattern is that they accept the "shared secret" and print out the OTP every time they are invoked.
- http://www.nongnu.org/oath-toolkit/
- https://github.com/tadeck/onetimepass
- https://github.com/pcarrier/gauth
- npm totp-generator
A handy node.js script based on npm totp-generator is available for reference here. To use,
export SHARED_SECRET=TOPSECRETKEEPSAFE node mfatoken.js
The script can also be tweaked to generate a token that has sufficient validity time left for a subsequent usage. Please check script source for details.
Usage with apigee-deploy-maven-plugin
The OTP generation step is inserted before invoking any call to apigee-deploy-maven-plugin. The maven plugin accepts the OTP as a command-line parameter.
A sample invocation of the Maven deploy plugin with the OTP is as follows. The "mfatoken" parameter takes the generated OTP.
mvn install -Ptest -Dusername=$ae_username -Dpassword=$ae_password \
-Dorg=testmyapi -Dauthtype=oauth -Dmfatoken=123456
You will see the following in the Maven logs.
[INFO] Acquiring mgmt API token from https://login.apigee.com/oauth/token [INFO] Making use of the MFA token provided.
In each management API call performed by the Maven plugin you will see the following header.
authorization: Bearer [Not shown in log]
The OTP is valid for 30 seconds and typically can be used for one Maven command invocation. Also, ensure the generated OTP has enough validity left (OTP aligns to 30 second system clock time).
While the OTP has a short lifetime, it is also sensitive information that needs to be handled carefully.
Security Important
- Treat "shared secret" as you would treat your password. Store it in a secure facility like the encrypted secure environment variables in CI tools.
- OTP is a sensitive information as well and should not be visible beyond the scope of usage.
- DO NOT log "shared secret" or OTP in build logs.
- If "shared secret" is compromised immediately unlink device and re-enable Two-Factor Authentication in Apigee User Settings to get a new "shared secret".
- DO NOT use an Apigee administrator account for CI bots. Create a new Apigee account for CI bots with a custom role only including minimal privileges required for the job.
- DO NOT hardcode "shared secret" in your code or scripts.
- DO NOT checkin "shared secret" in your source control.
