OAuth Authentication

OAuth authentication — the channel's EXTERNAL authentication method — is used when accounts authenticate through an external identity provider instead of typing credentials into PDX. The user is redirected to the provider's OAuth authorization page; after they authorize, the provider redirects back to PDX with an authorization code, PDX forwards that code to the adapter, and the adapter exchanges it for an access token which it stores. This is how channels such as Amazon SP-API authenticate.

To use it, set the channel's channelAuthenticationMethod to EXTERNAL and provide the identity providers' OAuth URLs — see External Channel Attributes for the underlying configuration attributes.

Channel configuration

With the SDK, register one or more identity-provider URLs — this switches the channel to the EXTERNAL authentication method automatically (call it again for additional providers):

ChannelBuilder.defaultChannel("amazon", "amazon-adapter", "Amazon Channel", logoUrl)
    .withExternalAuthenticationUrl(
        "Seller Central",
        "https://sellercentral.amazon.com/apps/authorize/consent?application_id=YOUR_APPLICATION_ID&version=beta")
    .build();

If you are not using the SDK, configure the channel's externalChannelAttributes directly — the builder above produces exactly this configuration:

"externalChannelAttributes": {
    "channelAdapterSupportsAuthentication": true,
    "channelAuthenticationMethod": "EXTERNAL",
    "externalAuthenticationUrls": [
        {
            "name": "Seller Central",
            "url": "https://sellercentral.amazon.com/apps/authorize/consent?application_id=YOUR_APPLICATION_ID&version=beta"
        }
    ]
}

📘

The authorization URL is static — provide it with your application/client id and any provider-specific parameters. PDX appends the dynamic parameters at runtime: the redirect URI (https://pdx.stibosystems.com/channels-management/external-authorization-callback) and a generated state value.

You can register multiple externalAuthenticationUrls; each is shown as a selectable identity provider in the PDX authentication form.

Adapter implementation

After the user authorizes, PDX calls your AuthenticationHandler with the OAuth authorization code passed as a property on the AuthenticationRequest. Exchange it — together with your application id and client secret — for an access token and store it:

@Override
public AuthenticationResponse authenticate(AuthenticationRequest request) {
    // The property key holding the code depends on the identity provider
    // (for example, Amazon SP-API uses "spapi_oauth_code").
    String oauthCode = request.getProperties().get("spapi_oauth_code");

    // Exchange oauthCode + applicationId + clientSecret for an access token,
    // then store it keyed by clientId + channelId + accountId:
    //   request.getClientId(), request.getChannelId(), request.getAccountId()

    return AuthenticationResponseBuilder.success().build();
}

📘

The application id is shared between PDX and the adapter, while the client secret is known only to the adapter.