0012: Targeted API Authentication and Authorization
STATUS
Approved
CONTEXT
AdAction wants to enable publishers to have secure access to the Targeted API.
Considered Options
- Amazon Cognito and Laravel Sanctum - DECISION
- Single Internal Admin Key and Laravel Sanctum
Option 1: Amazon Cognito and Laravel Sanctum
Description
Integrating Amazon Cognito involves installing and implementing an SDK in the Publisher Dashboard, Targeted API service, and Offer API service. It also requires setting up Laravel Sanctum in the Targeted API service.
Data Flow
Because this option will be iteratively implemented, the data flow will be broken down into phases.
PHASE 1
The first phase will assume Laravel Sanctum only, mimicking the current Offer API authentication integration.
Registering a Targeted API Property
sequenceDiagram
Publisher->>Publisher Dashboard: registers Targeted API property
Publisher Team Member->>Targeted API: requests new TA sanctum token<br/>(includes internal api key token)
Targeted API->>Targeted API: creates TA property and TA sanctum token
Targeted API->>Offer API: requests new OA sanctum token<br/>(includes internal api key token)
Offer API->>Offer API: creates OA property and OA sanctum token
Offer API->>Targeted API: returns new OA sanctum token
Targeted API->>Targeted API: associates OA sanctum token with TA property
Targeted API->>Publisher Team Member: returns new TA sanctum token
Publisher Team Member->>Publisher: shares sanctum token
Requesting Targeted Offers
sequenceDiagram
App->>Targeted API: requests targeted offers (includes bearer token)
Targeted API->>Offer API: requests untargeted offers<br/>(includes associated OA sanctum token)
Offer API->>Targeted API: returns untargeted offers
Targeted API->>App: returns targeted offers
PHASE 2
Because this phase involves refactoring the current flow for registering and authenticating a publisher, sequence diagrams for these data flows is included below. And, because the Offer API is a dependency of the Targeted API, Amazon Cognito can be integrated into the authorization flow for creating and recreating Offer API tokens before integrating Cognito into the Targeted API authorization flow (this will also be part of the process for moving the Offer API out of beta). Diagrams for this refactored sequence are also included.
Registering a Publisher
sequenceDiagram
Publisher->>Publisher Dashboard: registers
Publisher Dashboard->>Amazon Cognito: requests new identity tokens
Amazon Cognito->>Publisher Dashboard: returns new identity tokens
Publisher Dashboard->>Publisher Dashboard: associates new identity tokens with publisher
Publisher Dashboard->>Publisher: registers publisher
Authenticating a Publisher
sequenceDiagram
Publisher->>Publisher Dashboard: logs in
Publisher Dashboard->>Amazon Cognito: requests new access token<br/>(includes refresh token)
Amazon Cognito->>Publisher Dashboard: returns new access token
Publisher Dashboard->>Publisher Dashboard: associates new access token with publisher
Registering an Offer API Property
sequenceDiagram
Publisher->>Publisher Dashboard: registers Offer API property
Publisher Dashboard->>Offer API: requests new OA sanctum token<br/>(includes access token)
Offer API->>Amazon Cognito: requests authorization<br/>(includes access token)
Amazon Cognito->>Offer API: returns successful authorization
Offer API->>Offer API: creates OA property and OA sanctum token
Offer API->>Publisher Dashboard: returns new OA sanctum token
Publisher Dashboard->>Publisher: provides sanctum token
Regenerating a Token for an Offer API Property
sequenceDiagram
Publisher->>Publisher Dashboard: requests new OA sanctum token<br/>for existing Offer API property
Publisher Dashboard->>Offer API: requests new OA sanctum token<br/>(includes access token)
Offer API->>Amazon Cognito: requests authorization<br/>(includes access token)
Amazon Cognito->>Offer API: returns successful authorization
Offer API->>Offer API: destroys existing OA sanctum token<br/>and creates new OA sanctum token for existing OA property
Offer API->>Publisher Dashboard: returns new OA sanctum token
Publisher Dashboard->>Publisher: provides sanctum token
PHASE 3
Now that the Offer API has integrated Amazon Cognito, the Targeted API can follow suit. Sequence diagrams for these refactored data flows are included below.
Registering a Targeted API Property
sequenceDiagram
Publisher->>Publisher Dashboard: registers Targeted API property
Publisher Dashboard->>Targeted API: requests new TA sanctum token<br/>(includes access token)
Targeted API->>Amazon Cognito: requests authorization<br/>(includes access token)
Amazon Cognito->>Targeted API: returns successful authorization
Targeted API->>Targeted API: creates TA property and TA sanctum token
Targeted API->>Offer API: requests new OA sanctum token<br/>(includes access token)
Offer API->>Amazon Cognito: requests authorization<br/>(includes access token)
Amazon Cognito->>Offer API: returns successful authorization
Offer API->>Offer API: creates OA property and OA sanctum token
Offer API->>Targeted API: returns new OA sanctum token
Targeted API->>Targeted API: associates OA sanctum token with TA property
Targeted API->>Publisher Dashboard: returns new TA sanctum token
Publisher Dashboard->>Publisher: provides sanctum token
Regenerating a Token for a Targeted API Property
sequenceDiagram
Publisher->>Publisher Dashboard: requests new TA sanctum token<br/>for existing Targeted API property
Publisher Dashboard->>Targeted API: requests new TA sanctum token<br/>(includes access token)
Targeted API->>Amazon Cognito: requests authorization<br/>(includes access token)
Amazon Cognito->>Targeted API: returns successful authorization
Targeted API->>Targeted API: destroys existing TA sanctum token<br/>and creates new TA sanctum token for existing TA property
Targeted API->>Offer API: requests new OA sanctum token for existing TA property<br/>(includes access token)
Offer API->>Amazon Cognito: requests authorization<br/>(includes access token)
Amazon Cognito->>Offer API: returns successful authorization
Offer API->>Offer API: destroys existing TA sanctum token<br/>and creates new OA sanctum token for existing OA property
Offer API->>Targeted API: returns new OA sanctum token
Targeted API->>Targeted API: associates OA sanctum token with TA property
Targeted API->>Publisher Dashboard: returns new TA sanctum token
Publisher Dashboard->>Publisher: provides sanctum token
Requesting Targeted Offers
sequenceDiagram
App->>Targeted API: requests targeted offers (includes bearer token)
Targeted API->>Offer API: requests untargeted offers<br/>(includes bearer token)
Offer API->>Targeted API: returns untargeted offers
Targeted API->>App: returns targeted offers
Pros
- Sets up a more streamlined authentication and authorization processes for AdGem services.
- Adopts OAuth standards.
- Makes managing user identity and access easier.
Cons
- The scope of implementation would include the publisher dashboard.
Option 2: Single Internal Admin Key and Laravel Sanctum
Description
Integrating this option in the Targeted API involves duplicating the same authentication logic implemented in the Offer API. It also requires setting up Laravel Sanctum in the Targeted API service.
Pros
- Faster implementation because the scope does not include the publisher dashboard.
Cons
- AdGem services remain segregated in their authentication/authorization processes.
- Does not adopt OAuth standards.
DECISION
Choosing option 1 (Amazon Cognito and Laravel Sanctum) would result in more secure authentication/authorization practices for the Targeted API, as well as the publisher dashboard and Offer API (and beyond to other AdGem services in the future).
It also makes access management easier.
CONSEQUENCES
To execute option 1, the publisher dashboard authentication will need to be refactored.
Risks
The pub dashboard will need to be updated to use Amazon Cognito for its authentication, as well as updated to communicate with the Targeted and Offer APIs to retrieve security tokens.
NOTES
References
Original Author
Micah Wierenga
Approval date
Approved by
Appendix