# Proxy

# Introduction

Rocket provides reverse proxy implementations for the communication between frontend and commercetools. The main purpose is to prevent the exposure of critical credentials such as client id, client secret, access token and refresh token in the frontend application. The proxies are implemented using AWS Lambda Functions and AWS API Gateway HTTP API. There are two different implementations, one for the client credentials flow and one for the anoynmous session or password token flow.

# Client credentials flow

The proxy for the client credentials flow receives the request from the frontend, fetches an access token from the commercetools auth server, forwards the request to the commercetools api server (including access token) and then sends the response of the commercetools api server back to the frontend. The access token is cached in the execution environment and refreshed if necessary.

In this way, the client's credentials are not exposed in the frontend and are cached for at least a short period of time so that a new token is not fetched with every request.

# Architecture

The following diagram describes the architecture for the client credentials flow.

sequenceDiagram
    actor User
    participant Frontend
    participant Proxy
    box LIGHTGREY Commercetools
    participant Auth
    participant API
    end
    User->>Frontend: 
    autonumber 1
    activate Frontend
    Frontend->>Proxy: request
    activate Proxy
    Proxy->>Auth: clientId, secret, scopes(opt.)
    activate Auth
    Auth-)Auth: verify
    Auth-->>Proxy: token
    deactivate Auth
    deactivate Proxy
    Proxy->>API: request, token
    activate API
    activate Proxy
    API->>Auth: token
    activate Auth
    Auth-)Auth:verify
    Auth-->>API:ok / not ok
    deactivate Auth
    API-->>Proxy:response
    deactivate API
    Proxy-->>Frontend: response
    deactivate Proxy
  deactivate Frontend

# Flow chart

The following flowchart provides an overview of the lambda function for requests with client credentials flow.

flowchart TD
    Start((Start))-->CheckToken
    CheckToken{Token in execution environment?}--true-->CheckValidity{Token is valid?}
    CheckValidity--true-->SendRequest[Send request to commercetools]
    CheckValidity--false-->FetchToken[Fetch access token]
    CheckToken--false-->FetchToken
    FetchToken-->SendRequest
    SendRequest-->SendResponse[Send response to frontend]
    SendResponse-->Stop((Stop))

# Anonymous session & password token flow

The proxy for user-specific requests is implemented differently, as each user must use their personal access token to identify their requests. The requests are sent without a token to the proxy, which fetches both an access token and a refresh token from the commercetools authentication server. The request is then forwarded to the commercetools api server (including access token), and the response of the commercetools api server is sent to the frontend with an HTTP-only cookie containing the tokens.

If a login or signup request is sent to the proxy via the me-endpoint, the proxy fetches a new token for the login data for the password flow and updates the cookie. In addition, the endpoint {proxy_url}/logout is provided to delete the cookie and revoke the access token and the refesh token.

In this way, is is possible to use the same apiRoot in the frontend, even if you want to switch from an anonymous session to a password session.

# Architecture

The following diagram describes the architecture for anonymous session & password token flow.

sequenceDiagram
    actor User
    participant Frontend
    participant Proxy
    box LIGHTGREY Commercetools
    participant Auth
    participant API
    end
    User->>Frontend: 
    autonumber 1
    activate Frontend
    Frontend->>Proxy: request, (cookie[token, refreshtoken])
    activate Proxy
    Proxy->>Auth: credentials, clientId, secret, scopes(opt.)
    activate Auth
    Auth-)Auth: verify
    Auth-->>Proxy: token, refreshToken
    deactivate Auth
    deactivate Proxy
    Proxy->>API: request, token
    activate API
    activate Proxy
    API->>Auth: token
    activate Auth
    Auth-)Auth:verify
    Auth-->>API:ok / not ok
    deactivate Auth
    API-->>Proxy:response
    deactivate API
    Proxy-->>Frontend: response, (cookie[token, refreshtoken])
    deactivate Proxy
  deactivate Frontend

# Flow chart

The following flowchart provides an overview of the lambda function for user-specific requests.

flowchart TD
    Start((Start))-->CheckCookie
    CheckCookie{Cookie in request?}--true-->CheckValidity{Token is valid?}
    CheckValidity--true-->SendRequest[Send request to commercetools]
    CheckValidity--false-->RefreshToken[Fetch token with refresh token]
    RefreshToken-->SendRequest
    CheckCookie--false-->StartAnonymous[Fetch token for anonymous session]
    StartAnonymous-->SendRequest
    SendRequest-->AuthRoute{Is login or signup?}
    AuthRoute--false-->SendResponse[Send response to frontend]
    AuthRoute--true-->StartPassword[Fetch token for password session]
    StartPassword-->SendResponse
    SendResponse-->Stop((Stop))

The proxy for anoynmous session & password token flow should not be used for non-user-specific requests, as otherwise a unnecessary anonymous session in commercetools could be started.

clients proxy commercetools