Webstore (OAuth 2.0)

VTEX stores are capable of identifying returning clients by requesting that they provide login information. That way, logged-in clients can access their previous purchases and the store can present personalized content based on a client's profile data.

By default, our platform stores users' information in our secure servers, but sometimes it is useful to integrate external identity providers to the authentication process. The framework described in this guide will allow the VTEX platform to connect pre-existing user bases in private servers and is the same protocol used to allow clients to use their Google accounts to login to a 3rd party application.

In this guide you can learn about:

OAuth2

The OAuth2 specification defines a framework that enables applications (Service Providers) to ask anyone requesting access to protected data for user authentication without having to interact with their private credentials. It achieves that by interacting with a trusted partner (identity provider) that handles user identification, validates their credentials, and returns to the application the data it needs to safely proceed.
You can learn more about the OAuth2 Authorization Framework by reading its specification document.

See an example of VTEX's custom OAuth2 authentication flow:

VTEX ID
VTEX ID
Custom Identity Provider
Custom Identity...
Request secure content
Request secure...
Identity Provider List
Identity Provider List
Select Custom Identity Provider
Select Custom I...
Redirect to Custom Idp getAuthorizationCode endpoint
Redirect to Custom Idp getAuthorizationCode endpoint
Query parameters
redirect_uri
state
Query parameters...
Custom IdP's ge...
Query parameters
redirect_uri
state

Query parameters...
Present Login Page / Request Credentials
Present Login Page / Request Credentials
Send Valid Credentials
Send Valid Cred...
Redirect to VTEX ID's authorizationCode endpoint
Query parameters
code
state

Query parameters...
VTEX ID's authorizationCode endpoint
VTEX ID's autho...
Query parameters
code
state

Query parameters...
/POST to Custom...
Body parameters
code
client_id
client_secret

Body parameters...
Response
Response
Body parameters
access_token
expires_in

Body parameters...
/GET to Custom...
Header or query parameter
access_token


Header or query parameter...
Response
Response
Body parameters
userId
email
name
Body parameters...
setCookie with VTEX ID's token
setCookie with VTEX ID's token
and redirect (302) to finish endpoint
and redirect (302) to finish en...
VTEX ID's oauth/finish endpoint
VTEX ID's oauth...
Redirect to secure content (redirect_uri)
Redirect to secure content (redirect_uri)
User
Agent
User...
Text is not SVG - cannot display

User Agent

User Agent in this context represents the user's browser. The user interacts with its browser manually, but it's the application that sends the requests to any server, follows redirects and renders pages to the user.

Redirects

All server communications in the context of this guide happen via the HTTPS protocol. One of the features of this protocol is responding to a request by redirecting the User Agent to a different URI. When the browser receives a redirect response, it proceeds to the specified URI instantly. For example, when a user tries to access protected areas of a store it can be redirected to a login page.

VTEX ID

VTEX ID is the service used for identifying users on our platform. Usually, applications talk to it so they can obtain the token required to access protected information.

Relevant requests

There are some steps of the OAuth2 authentication process which are worth noting and going into more detail.

📘

Note that some of the variable names for the requests mentioned below are customizable when implementing a Custom OAuth option. You can adapt them according to the specification of your identity provider.

Authorization request

When an unauthenticated user requests access to protected resources in a store, VTEX ID will start the authentication process by generating a unique identifier for this authentication session, storing the URI of the requested resource for this session, and redirecting the User Agent to this endpoint with the following query variables:

  • Client ID: Identification of the client
  • state: the state containing the unique identifier
  • redirect_uri: will always be https://vtexid.vtex.com.br/VtexIdAuthSiteKnockout/ReceiveAuthorizationCode.ashx.

At this endpoint, it is expected that the user will be presented with a way to send their credentials or redirected to an endpoint that presents it. This is usually a form requesting a username and password. It is also common practice to check for cookies that indicate that the user is already logged in.

Once the Identity Provider has safely identified the user, it should generate an authorization code with more than 64 characters, store it so it can be used later to identify this session, and redirect the User Agent to the authorizationCode endpoint with the code in a query variable named code. The state variable will also be forwarded as received. The identity provider can also pass a query string parameter error to inform occasional errors on its side.

Authorization code callback request

The User Agent should be redirected to this endpoint after the Identity Provider has successfully checked its user's credentials. Two parameters will be retrieved from the query variables by VTEX ID: code and state.

  • code: single use code that should expire after a few minutes, as indicated by the RFC specification. In case of multiple attempts to use this code, the credentials must be revoked.
  • state: used to identify the authentication session, which is important to detect replay attacks. And the code variable will be used so VTEX ID can get the Access Token by using the Access Token Exchangeendpoint.

Access token exchange

This is a simple endpoint that expects a POST request with three parameters in its body:

  • client_id
  • client_secret
  • code
  • redirect_uri (https://vtexid.vtex.com.br/VtexIdAuthSiteKnockout/ReceiveAuthorizationCode.ashx)

The values of client_id and client_secret are stored in VTEX ID when the Identity Provider is configured and should be used by this endpoint as credentials that guarantee that only VTEX ID and other well-known clients can have access.
VTEX ID expects 2 parameters in the response body:

  • access_token: the credential that VTEX ID needs to use in the Get user information exchange.
  • expires_in: the time, in seconds, before the token expires.

Get user information

This endpoint should only allow requests with valid access_token credentials, which can be used to identify the user, and return the following user information in the request body:

  • userId (required)
  • email (required)
  • name

A user's email is the key used to uniquely identify each VTEX user. This is the information VTEX ID needs in order to finish the authentication process.

Custom OAuth

In addition to the default options to use Google and Facebook as identity providers for your store, VTEX allows you to implement a custom OAuth connection, in case you have another identity provider that you wish to make available for your customers.

You should understand all the expected behavior for the Identity Provider endpoints. But it is not necessarily a good idea to implement the server from scratch. Many certified OAuth2 libraries exist and you should take a look at them before writing your own code. Any lack of verification or mistreated steps can pose a serious security risk for your store and your customers.

Integration

You can implement a custom OAuth option by going to your Admin panel and providing some information about the communication between VTEX and your identity provider as shown on the relevant requests described above.

🚧

Each VTEX store may have up to one custom OAuth implementation, which will be active for all store names in that account.

See the table to learn what information you must configure for each request. And below you can learn more details about each of the configuration steps.

RequestFromToFields to configure
Authorization requestVTEXCustom identity provider

- URL

- Custom parameters (optional)

Authorization callback requestCustom identity providerVTEX- Authorization code key
Access token exchangeVTEXCustom identity provider

Request:

- URL

- Content-Type

- Authorization code key

- Custom parameters (optional)

Response:

- Access token key

- Token duration key

User information exchangeVTEXCustom identity provider

Request:

- URL

- Where to send access token (Bearer token or query string)

- Access token key (if sent on query string)

- Custom parameters (optional)

Response:

- User email key

- User ID key

- User name key

🚧

Note that many of the field values indicated in the table are dinamically generated or come from the identity provider. Because of this, you must define only the key under which this information will be sent to VTEX, so the platform knows how to properly handle each piece of information. Examples of this include the authorization code key, token duration key and user email key.

Configuration steps

In order to configure this process, follow the steps below:

  1. Go to the Admin panel > Account settings > Authentication.
  2. In the Webstore tab, click SET UP in the My Custom OAuth section
909909

Authentication settings screen with options: Access Key, Password, Facebook, Google and My Custom OAuth.

  1. Set provider details
  2. Configure authorization code requests
  3. Configure access token exchange request
  4. Configure get user information request

📘

When performing these steps, you will be able to preview the configuration outcome in the respective Request Preview and Expected Response Preview sections. We recommend you check them thoroughly when integrating.

3. Set provider details

When you start the custom OAuth setup, you must fill in the following information:

  • Identity provider’s name
  • client ID key
  • client ID value
  • client secret key
  • client secret value

📘

These keys are the names under which VTEX should send or expect to receive the information value when communicating with the identity provider.

878878

Provider details section, in the custom OAuth set up interface with the options described in the tutorial.

Click NEXT.

4. Configure authorization code requests

In this step, you must first provide the authorization request URL.

685685

Authorization code section, in the custom OAuth set up interface with the options described in the tutorial.

📘

If you wish, you can also add custom parameters to this request.

Then, scroll down to the Callback Request Information section and fill in the Key under which the authorization code will be sent by the identity provider to VTEX.

884884

Scrolling further down in the authorization code section, in the custom OAuth set up interface with the options described in the tutorial.

Click NEXT.

5. Configure access token exchange

In order to configure the access token exchange request, provide:

  • The request URL
  • Authorization code key, under which VTEX should send the authorization code to the identity provider.
883883

Access token exchange section, in the custom OAuth set up interface with the options described in the tutorial.

📘

If you wish, you can also add custom parameters to this request.

Then, you may scroll down to the Response Information section and inform the Keys under which VTEX should expect to receive user information:

  • Access token key
  • Token duration key
876876

Scrolling further down in the Access token exchange section, in the custom OAuth set up interface with the options described in the tutorial.

Click NEXT.

6. Configure user information exchange

Now you must provide information regarding the user information exchange:

  • Request URL
  • Where to send Access Token. It is sent as a bearer token by default. Use the toggle if you wish to change it to Send on query string.

Check the Request Preview section to make sure it matches the format expected by the identity provider. Also, note that if you toggle Send on query string, you can edit the access token key under which VTEX will send it to the identity provider.

877877

Get user info section, in the custom OAuth set up interface with the options described in the tutorial.

📘

If you wish, you can also add custom parameters to this request.

Scroll down to the Response Information section, and provide the Keys under which VTEX should expect to receive user information:

  • User e-mail key
  • User ID key
  • User name key
882882

Scrolling further down in the Get user info section, in the custom OAuth set up interface with the options described in the tutorial.

To finalize your Custom OAuth configuration, click FINISH.

Custom parameters

For each of the relevant requests that are sent by VTEX to the identity provider, you can configure custom parameters with static values. To do this, follow these steps:

  1. Click + NEW PARAMETER.
  2. Fill in the custom parameter Key.
  3. Inform the custom parameter Value.

Edit custom OAuth

After you set your custom OAuth option up, you can edit it by following the same steps described below for implementation.

❗️

If your implementation was initially set up via VTEX support instead of the process described above, you must be extra careful when editing it via the Admin panel. Incorrect edits may cause your custom OAuth to stop working. We recommend you check the previews thoroughly and make sure they match what is expected by the identity provider.


Did this page help you?