115 lines
3.5 KiB
Plaintext
115 lines
3.5 KiB
Plaintext
---
|
|
title: OAuth Activation Flow
|
|
description: Implementation guide for secure user-verified license activation
|
|
date: 2024-01-31
|
|
---
|
|
|
|
## Overview
|
|
|
|
The Secure OAuth Activation flow ensures that licenses are only activated by their legitimate owners. Unlike simple API activation, this method requires the user to log in to the WooNooW portal and explicitly authorize the activation request.
|
|
|
|
### When to use OAuth?
|
|
|
|
* ✅ When you want strict control over license usage
|
|
* ✅ To prevent license key sharing (key + auth required)
|
|
* ✅ If specific user consent is legally required
|
|
|
|
---
|
|
|
|
## Authentication Flow
|
|
|
|
The flow involves three parties:
|
|
1. **Client Application**: The software requesting activation (e.g., a customer's WordPress site)
|
|
2. **Vendor Portal**: The WooNooW dashboard where the user manages licenses
|
|
3. **Vendor API**: The backend handling the activation logic
|
|
|
|
<Stepper>
|
|
<StepperItem title="Step 1: Client Requests Activation">
|
|
The client sends a request to the activation API with `activation_mode: "oauth"`.
|
|
|
|
```bash
|
|
POST /woonoow/v1/licenses/activate
|
|
{
|
|
"license_key": "XXXX-YYYY-ZZZZ-WWWW",
|
|
"domain": "https://client-site.com",
|
|
"activation_mode": "oauth"
|
|
}
|
|
```
|
|
</StepperItem>
|
|
|
|
<StepperItem title="Step 2: API Request Authorization">
|
|
The API responds with `oauth_required: true` and a redirect URL.
|
|
|
|
```json
|
|
{
|
|
"oauth_required": true,
|
|
"oauth_redirect": "https://woonoow.com/my-account/license-connect/...",
|
|
"state": "abc12345"
|
|
}
|
|
```
|
|
</StepperItem>
|
|
|
|
<StepperItem title="Step 3: User Authorizes Request">
|
|
The client redirects the user to the `oauth_redirect` URL. The user logs in and sees a confirmation screen:
|
|
|
|
> **Authorize this Request?**
|
|
> Site: https://client-site.com
|
|
> License: XXXX-YYYY-ZZZZ-WWWW
|
|
|
|
Once confirmed, the vendor generates a temporary **activation token**.
|
|
</StepperItem>
|
|
|
|
<StepperItem title="Step 4: Token Exchange">
|
|
The user is redirected back to the client site with the token. The client exchanges this token for the final activation.
|
|
|
|
```bash
|
|
POST /woonoow/v1/licenses/activate
|
|
{
|
|
"activation_token": "temporary-token-123"
|
|
}
|
|
```
|
|
</StepperItem>
|
|
</Stepper>
|
|
|
|
---
|
|
|
|
## Implementation Guide
|
|
|
|
### 1. Handling the Redirect
|
|
|
|
When your application receives the `oauth_redirect` response, you must open this URL in the user's browser.
|
|
|
|
<Note type="note" title="Security Check">
|
|
Always verify the `state` parameter when the user returns to your application to prevent CSRF attacks.
|
|
</Note>
|
|
|
|
### 2. Processing the Callback
|
|
|
|
Your application needs a callback route (e.g., `/admin.php?page=my-plugin&action=callback`). This URL must be provided in the initial `return_url` parameter.
|
|
|
|
The callback will receive:
|
|
* `activation_token`: The token needed to complete activation
|
|
* `license_key`: The license key being activated
|
|
* `nonce`: Random standard nonce for verification
|
|
|
|
### 3. Completing Activation
|
|
|
|
Once you have the `activation_token`, compare the `state` (if you stored it) and make the final request.
|
|
|
|
```javascript
|
|
const response = await fetch('https://api.woonoow.com/woonoow/v1/licenses/activate', {
|
|
method: 'POST',
|
|
headers: { 'Content-Type': 'application/json' },
|
|
body: JSON.stringify({
|
|
license_key: licenseKey,
|
|
activation_token: urlParams.get('activation_token')
|
|
})
|
|
});
|
|
|
|
const data = await response.json();
|
|
|
|
if (data.success) {
|
|
console.log('License Activated!', data);
|
|
}
|
|
```
|