|
| 1 | +# OAuth Configuration Guide |
| 2 | + |
| 3 | +kminion supports OAUTHBEARER SASL mechanism with two flavors: |
| 4 | + |
| 5 | +1. **Generic OAuth** - Standard OAuth 2.0 client credentials flow |
| 6 | +2. **Adobe IMS OAuth** - Adobe Identity Management System integration |
| 7 | + |
| 8 | +## Generic OAuth Configuration |
| 9 | + |
| 10 | +For standard OAuth 2.0 providers, configure the following: |
| 11 | + |
| 12 | +```yaml |
| 13 | +kafka: |
| 14 | + sasl: |
| 15 | + enabled: true |
| 16 | + mechanism: "OAUTHBEARER" |
| 17 | + oauth: |
| 18 | + # Leave type empty for generic OAuth |
| 19 | + type: "" |
| 20 | + tokenEndpoint: "https://your-oauth-provider.com/oauth/token" |
| 21 | + clientId: "your-client-id" |
| 22 | + clientSecret: "your-client-secret" |
| 23 | + scope: "kafka" |
| 24 | +``` |
| 25 | +
|
| 26 | +### Environment Variables |
| 27 | +
|
| 28 | +```bash |
| 29 | +KAFKA_SASL_ENABLED=true |
| 30 | +KAFKA_SASL_MECHANISM=OAUTHBEARER |
| 31 | +KAFKA_SASL_OAUTH_TYPE="" |
| 32 | +KAFKA_SASL_OAUTH_TOKENENDPOINT=https://your-oauth-provider.com/oauth/token |
| 33 | +KAFKA_SASL_OAUTH_CLIENTID=your-client-id |
| 34 | +KAFKA_SASL_OAUTH_CLIENTSECRET=your-client-secret |
| 35 | +KAFKA_SASL_OAUTH_SCOPE=kafka |
| 36 | +``` |
| 37 | + |
| 38 | +## Adobe IMS OAuth Configuration |
| 39 | + |
| 40 | +For Adobe Identity Management System, configure the following: |
| 41 | + |
| 42 | +```yaml |
| 43 | +kafka: |
| 44 | + sasl: |
| 45 | + enabled: true |
| 46 | + mechanism: "OAUTHBEARER" |
| 47 | + oauth: |
| 48 | + type: "AdobeIMS" |
| 49 | + tokenEndpoint: "https://ims-na1.adobelogin.com" |
| 50 | + clientId: "your-ims-client-id" |
| 51 | + clientSecret: "your-ims-client-secret" |
| 52 | + additional: |
| 53 | + clientCode: "your-ims-code" |
| 54 | +``` |
| 55 | +
|
| 56 | +### Environment Variables |
| 57 | +
|
| 58 | +```bash |
| 59 | +KAFKA_SASL_ENABLED=true |
| 60 | +KAFKA_SASL_MECHANISM=OAUTHBEARER |
| 61 | +KAFKA_SASL_OAUTH_TYPE=AdobeIMS |
| 62 | +KAFKA_SASL_OAUTH_TOKENENDPOINT=https://ims-na1.adobelogin.com |
| 63 | +KAFKA_SASL_OAUTH_CLIENTID=your-ims-client-id |
| 64 | +KAFKA_SASL_OAUTH_CLIENTSECRET=your-ims-client-secret |
| 65 | +KAFKA_SASL_OAUTH_ADDITIONAL_CLIENTCODE=your-ims-code |
| 66 | +``` |
| 67 | + |
| 68 | +## How It Works |
| 69 | + |
| 70 | +### Generic OAuth Flow |
| 71 | + |
| 72 | +1. kminion uses the client credentials grant type |
| 73 | +2. Sends a POST request to the token endpoint with client ID and secret |
| 74 | +3. Receives an access token |
| 75 | +4. Uses the token for Kafka authentication |
| 76 | + |
| 77 | +### Adobe IMS Flow |
| 78 | + |
| 79 | +1. kminion uses the Adobe IMS Go SDK (`github.com/adobe/ims-go`) |
| 80 | +2. Creates an IMS client with the configured endpoint |
| 81 | +3. Requests a token using the IMS-specific authentication flow |
| 82 | +4. Stores both the access token and refresh token |
| 83 | +5. Uses the access token for Kafka authentication |
| 84 | +6. **Automatically refreshes the token** when it expires in less than 15 minutes |
| 85 | +7. Updates the refresh token if a new one is provided during refresh |
| 86 | + |
| 87 | +## Switching Between Providers |
| 88 | + |
| 89 | +The `type` field determines which OAuth provider to use: |
| 90 | + |
| 91 | +- **Empty or omitted**: Uses generic OAuth with `tokenEndpoint`, `clientId`, `clientSecret`, and `scope` |
| 92 | +- **"AdobeIMS"**: Uses Adobe IMS with `tokenEndpoint`, `clientId`, `clientSecret`, and `additional.clientCode` |
| 93 | + |
| 94 | +### Field Reuse |
| 95 | + |
| 96 | +Both generic OAuth and Adobe IMS share common fields: |
| 97 | +- `tokenEndpoint`: OAuth token endpoint URL (for Adobe IMS, this is the IMS endpoint) |
| 98 | +- `clientId`: OAuth client ID |
| 99 | +- `clientSecret`: OAuth client secret |
| 100 | + |
| 101 | +Provider-specific fields go in the `additional` block: |
| 102 | +- For Adobe IMS: `clientCode` (authorization code) |
| 103 | + |
| 104 | +## Validation |
| 105 | + |
| 106 | +- **Generic OAuth**: Validates that `tokenEndpoint`, `clientId`, and `clientSecret` are provided |
| 107 | +- **Adobe IMS**: Validation happens during client creation when connecting to Kafka |
| 108 | + |
| 109 | +## Token Refresh Behavior |
| 110 | + |
| 111 | +### Generic OAuth |
| 112 | + |
| 113 | +Generic OAuth fetches a new token on every authentication request using the client credentials flow. This is simple but may result in more frequent token requests to the OAuth provider. |
| 114 | + |
| 115 | +### Adobe IMS |
| 116 | + |
| 117 | +Adobe IMS implements intelligent token refresh with resilient error handling: |
| 118 | + |
| 119 | +- **Initial Token**: Obtained during startup using the authorization code with retry logic |
| 120 | +- **Refresh Token**: Stored securely and used for token renewal |
| 121 | +- **Automatic Refresh**: Tokens are automatically refreshed when they expire in less than 15 minutes |
| 122 | +- **Thread-Safe**: Token refresh is protected by mutex to prevent race conditions in concurrent environments |
| 123 | +- **Long-Running Support**: Designed for long-running Kafka clients that need to maintain connections for extended periods |
| 124 | +- **Retry Logic**: Automatic retry with exponential backoff for transient network errors |
| 125 | + |
| 126 | +The 15-minute refresh threshold ensures that: |
| 127 | +- Tokens are refreshed proactively before expiration |
| 128 | +- There's sufficient time to complete the refresh operation |
| 129 | +- Kafka connections remain authenticated without interruption |
| 130 | + |
| 131 | +### Error Resilience |
| 132 | + |
| 133 | +Adobe IMS token operations (both initial fetch and refresh) include automatic retry logic for transient errors: |
| 134 | + |
| 135 | +**Retryable Errors:** |
| 136 | +- Network timeouts (connection timeout, i/o timeout) |
| 137 | +- DNS resolution failures (temporary errors, timeouts) |
| 138 | +- Connection refused errors (service not ready) |
| 139 | +- Connection reset errors (connection dropped) |
| 140 | +- Network dial errors (can't establish connection) |
| 141 | +- Closed network connection errors |
| 142 | +- IMS HTTP errors (408, 429, 500, 502, 503, 504) |
| 143 | + |
| 144 | +**Retry Strategy:** |
| 145 | +- Maximum 3 retry attempts |
| 146 | +- Exponential backoff: 1s, 2s, 4s, 8s, 16s (capped at 30s) |
| 147 | +- Non-retryable errors (e.g., invalid credentials) fail immediately |
| 148 | +- Context cancellation is respected during retry backoff |
| 149 | + |
| 150 | +This ensures that temporary network issues or IMS service hiccups don't cause permanent authentication failures. |
| 151 | + |
| 152 | +## Dependencies |
| 153 | + |
| 154 | +- Generic OAuth: Built-in HTTP client |
| 155 | +- Adobe IMS: `github.com/adobe/ims-go` v0.19.1+ |
| 156 | + |
0 commit comments