Connecting your WordPress plugin to AWeber’s API
OAuth 2.0 has become one of the most popular authorization schemes in the world of public APIs. Many clients across languages provide great support for OAuth 2.0 which makes it easy to integrate into any application. There are a few things to make sure you are doing specifically for WordPress plugins when using OAuth 2.0 and the authorization code grant type.
Key Points
- Use a public client type for your AWeber application
- Implement PKCE (Proof Key for Code Exchange) to obtain an access key
- Register a redirect uri of “urn:ietf:wg:oauth:2.0:oob”
- Make requests to the AWeber API
- Store and refresh access tokens when expired -- no need to reauthorize
WordPress plugins by design are individually downloaded by your customers. The customer then integrates your source code into their own hosted WordPress. Since we have each customer downloading the source code directly, our OAuth 2.0 client id and client secret would have to be bundled with the source code. As the name implies, client secrets are meant to be kept secret! When you package your source code with your client id and secret, you are vulnerable to several security concerns, the most notable being client impersonation (See RFC 6749#10.2), where bad actors can masquerade as your application.
Use a public client type for your AWeber application
To address security concerns presented in an open source code situation, like a WordPress plugin presents, we enact several measures. The first, is creating public clients. Public clients are identified as “Clients incapable of maintaining the confidentiality of their credentials (e.g., “...”such as an installed native application or a web browser-based application),” (See RFC 6749#2.1). By classifying applications as public, we can then restrict and enforce security measures that reduce the risk of vulnerabilities. Secondly, public applications do not have a client secret, which means that you can safely bundle the client id with your application and distribute the source code.
Implement PKCE (Proof Key for Code Exchange) to obtain an access key
So how does a public client authenticate without a client secret? The client secret is used to exchange the authorization code for an access token for confidential clients. The presence of the client secret (technically a shared secret between the client and the authorization server) guarantees that the authorization code was received by the originating client and not a bad actor. With public clients, we cannot guarantee that the client secret could remain secret (since it would require it to be packaged with the source code) so we use another method to prevent authorization code interception; PKCE. This method (See RFC 7636) uses a client generated code verifier, a challenge, and an agreed upon hashing algorithm to ensure that the authorization code was not intercepted. Check out our documentation on the specifics or our PHP code example.
Register a redirect uri of “ urn:ietf:wg:oauth:2.0:oob ”
The next step in building a WordPress plugin with OAuth 2.0 is to register a redirect URI. WordPress plugins are a bit complicated in this regard, since your application will be installed on any number of domains (e.g. mywordpress.wordpress.com) which makes it impossible to register a list of redirect URIs as required by OAuth 2.0 (See RFC 6749#3.1.2.2). So how do we address this? We use something called Out Of Band (OOB) verification (See How do I use the out of band redirect URI?) to display the authorization code in the browser instead of redirecting back to a registered endpoint. The WordPress plugin user then copies the authorization code, inserting it into your application in order to fetch an access token and refresh token.
Make requests to the AWeber API
After implementing PKCE with a OOB redirect uri, your application can freely make requests to retrieve AWeber resources via our API. We provide several code examples for PHP to get started including PKCE and adding a subscriber. The most common operation is to add a subscriber which only requires a single HTTP POST and you can even perform an upsert if the subscriber already exists using an “update_existing” parameter.
Store and refresh access tokens when expired -- no need to reauthorize!
The last piece to add to your WordPress plugin, once authentication is complete, is the storage and maintenance of your access token and refresh token. These tokens should be stored in the WordPress database for each customer’s plugin installation (and encrypted at rest). While refresh tokens have no expiration, access tokens expire around two hours after issue and will need to be refreshed (See Do AWeber API access tokens expire?). There is no interaction needed by your customer to refresh the tokens, and refreshing an access token can be completed as a background process triggered by an access token expired error.
Going one step further, a best practice to follow upon uninstallation of WordPress plugins is to revoke the refresh token, ensuring that the refresh tokens can no longer be used.
Closing Thoughts
If you have any questions, our team of developers are happy to help. Please email us at api@aweber.com.