Use VTEX authentication as an IdP for your applications using the well-known OAuth2 protocol (https://tools.ietf.org/html/rfc6749). You can choose between admin or store credentials, allowing other systems to use the VTEX login validation. This will not provide access to VTEX resources, only verify the user authentication.

The allowed flows so far are:

• Authentication Code (https://tools.ietf.org/html/rfc6749#section-1.3.1)

[IMPORTANT] As Authentication Code is the only flow implemented, for security reasons the client must have a server side application that will exchange the code for a token (Access Token Request), using the private client secret as authentication method.

The account must have the app vtex.oauth-provider-admin installed. It'll add "OAuth Provider" in "Account Settings".

An account can have many OAuth clients registered, with different settings:

• Name: readable identifier [IT IS NOT THE CLIENT ID]
• Allowed URI's : a list of URI`s that can be used as return uri in the flow
• Credential Type: the type of VTEX authentication that will be used to login: admin or store
  • Admin: uses default VTEX login page
  • Store: allows the account to set a custom login page url, which must have a VTEX ID login flow

After the registration, the client will be issued a Client Id and a Client Secret.

The application that want to use VTEX as an IdP using OAuth2 can implement the Authentication Code flow (https://tools.ietf.org/html/rfc6749#section-4.1), using the following endpoints:

[GET] https://{{account}}.myvtex.com/_v/oauth2/auth?client_id={{client_id}}&scope=&response_type=code&redirect_uri={{redirect_uri}} (https://tools.ietf.org/html/rfc6749#section-4.1.1)

• client_id: the Client Id issued after the client registration [REQUIRED]
• redirect_uri: the encoded URL that the authorization server will redirect the user-agent, with code and state as query string [OPTIONAL]
• scope: TBD [IGNORED]
• response_type: type of the authentication flow. Must be code [REQUIRED]
• state: An opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client [RECOMMENDED]

If the resource owner grants the access request, the authorization server issues an authorization code and delivers it to the client by adding the following parameters to the query component of the redirection URI (https://tools.ietf.org/html/rfc6749#section-4.1.2)

• code: the authorization code generated by the authorization server
• state: the same "state" parameter received in the client authorization request

[POST] https://{{account}}.myvtex.com/\_v/oauth2/token (https://tools.ietf.org/html/rfc6749#section-4.1.3). Send the following parameters using the "application/x-www-form-urlencoded" format in the HTTP request entity-body:

• grant_type: value MUST be set to "authorization_code" [REQUIRED]
• code: the authorization code received from the authorization server [REQUIRED]
• redirect_uri: [REQUIRED], if the "redirect_uri" parameter was included in the authorization request and their values MUST be identical.
• client_id: issued client_id [REQUIRED]
• client_secret: issued client_secret [REQUIRED]

The authorization server issues an access token as below:

The Introspect endpoint is a commmon extension to the OAuth2 framework that provides some information about the issued token, like username and user_id.

[GET] https://{{account}}.myvtex.com/oauth2/introspect?token={{access_token}}

• access_token: the token received from /token endpoint.

A json with the following token properties:

• active: if the token still active
• scope: the scopes allowed to this token
• client_id: the client_id of the token
• username: the username used in the authentication
• user_id: the user_id from the user in the authentication
• exp: expiration date of the token