{"section":"tutorials","requestedLocale":"en","requestedSlug":"creating-an-oauth2-authentication","locale":"en","slug":"creating-an-oauth2-authentication","path":"docs/en/tutorials/authentication/creating-an-oauth2-authentication.md","branch":"main","content":"In some circumstances, you may want to create an additional authentication in VTEX with your own login database. For example: \n- A customer \"loyalty club\", with login and password created on your own platform.\n- Employee login for purchases in your \"staff store\".\n\nTo match those needs, VTEX provides a VTEX ID integrated __authentication OAuth2__ .\n\n> ⚠️ As this is a complicated technical matter, we recommend that you consult a partner or IT team.\n\n### About OAuth2\n\nOAuth is an authorization protocol used mostly in scalable web applications. The latest version is the 2.0, which uses tokens to access your data in another system.\n\n### What is OAuth2 used for\n\nOAuth2's main benefit for VTEX stores is the possibility of using logins and passwords previously created in external systems which are integrated with VTEX. This speeds up the authentication process when necessary, and works in the same way as authentication via Facebook or Google+, for example.\n\n### Official reference guide\n\nHave a look at the OAuth2 protocol official guide on https://tools.ietf.org/html/rfc6749\n\n### Integrating OAuth2 with VTEX ID\n\nBased on the official documentation, have a look at the illustration below explaining how to integrate OAuth2 with VTEX ID:\n![Fluxo OAuth2 VTEX ID (EN)](https://cdn.statically.io/gh/vtexdocs/help-center-content/refs/heads/main/docs/en/tutorials/authentication/creating-an-oauth2-authentication_1.png)\n\nKeeping the illustration in mind, let's have a closer look at some of the things you'll need to know.\n\nBear in mind that any part of the process takes place exclusively through __HTTPS__.\n\n### 1. Authorization URL (getAuthorizationCode)\n\nThe user (store customer) will see the VTEX ID login screen and will choose the appropriate external identity provider.\n\nVTEX ID will redirect the user to an authorization URL belonging to the identity provider, this being a requisition using the GET method on that server.\n\nThe authorization URL is supplied by the retailer and has at least three parameters (querystrings):\n- Client ID: VTEX ID identifier for the identity provider. The parameter's name can be set to anything (we suggest using `client_id`) and its value is set by the provider;\n- Return URL: will be used in the next steps of the flow. Its value is set by VTEX ID but its parameter name can be set to anything (we suggest using `return_url`);\n- State: used together with the return URL, having its name and value set by VTEX ID, neither of which should be altered.\n\nYou can include additional parameters in VTEX ID by setting their values and name of their keys.\n\nFrom the authorization URL, the user will move on to the authentication process of the external identity provider.\n\nOnce successfully authenticated, the provider will redirect the user back to VTEX ID. The destination URL should include:\n- the return URL sent by VTEX ID;\n- the state parameter, keeping its original value;\n- a new parameter which will represent the authentication code generated by the identity provider. The parameter name can be set to anything, we recommend using `auth_code`.\n\n### 2. URL for changing authorization code with access code (getAccessCode) \n\nWhen the user returns to the return URL, VTEX ID captures the authorization code to obtain an access code from the backend servers.\n\nThis access code will be used to securely obtain customer data and create cookies that identify the user within VTEX services.\n\nThis URL warrants the use of the POST method.\n\nThe authorization code must be sent with in the requisition body, either in JSON format (content-type `application/json`) or form-urlencoded (content-type `application/x-www-form-urlencoded`). You should let us know both the desired method and the name of the key that will represent that method.\n\nAdditional parameter can be sent to the querystring and/or body. If warranted, indicate the keys and values, which will be fixed.\n\nFor the security of the process, VTEX ID needs the Client ID and the Client Secret (the ID is the same as the one at the beginning of the process, functioning as appKey and appToken, respectively). The Client ID and Client Secret can be sent with a header entitled \"Authorization\" or with the URL parameters (keys whose name can be set to anything).\n\nAs response we expect to receive the access code in the body, either in JSON format or as form-urlencoded (just as the requisition); you can pass a property name for mapping, the name range being free.\n\nAdditional parameters can be part of the response but are usually not useful.\n\n### 3. URL to obtain user data (getUserInfo)\n\nThis URL should only be used with the GET method.\n\nThe user should be recognized according to their own access code, which will be sent either as an Authorization Bearer or as a querystring.\n\nYou may also include additional parameters in VTEX ID by indicating the key names and their respective values.\n\nThe expected response is the user's email and their identity provider ID, along with the user's name, however this last part is optional. Data can be delivered in either JSON format or as form-urlencoded.\n\nAdditional information can be part of the response but are usually not useful.\n\n__Important__: The email is the sole VTEX platform key. The identity provider may request other type of information for authentication (such as ID number, company registration number, login, phone number, etc.) but what should be sent to VTEX integration is the email that was authenticated. This scenario is valid for B2B, B2C and B2E.\n\nWith this step concluded, the user will receive a cookie containing an authorization token that will identify them within VTEX services.\n\n### Use cases\n\nThe following examples show the process of using an OAuth2 integration with Google as the identity provider:\n\n#### getAuthorizationCode\n\nRequest:\n```\nGET https://accounts.google.com/o/oauth2/auth?redirect_uri=https://vtexid.vtex.com.br/VtexIdAuthSiteKnockout/ReceiveAuthorizationCode.ashx&scope=https://www.googleapis.com/auth/userinfo.profile%20https://www.googleapis.com/auth/userinfo.email&access_type=offline&response_type=code&client_id={clientId}&state={state}\n```\n\n#### getAccessCode \n\nRequest:\n```\nPOST https://accounts.google.com/o/oauth2/token\n\nBody: redirect_uri=https://vtexid.vtex.com.br/VtexIdAuthSiteKnockout/ReceiveAuthorizationCode.ashx&grant_type=authorization_code&client_id={clientId}&client_secret={clientSecret}&code={authorizationCode}\n```\n\nResponse:\n```\n{\n\t\"access_token\" : {accessToken},\n\t\"expires_in\" : 3600,\n\t\"id_token\" : {jwt},\n\t\"token_type\" : \"Bearer\"\n}\n```\n\n#### getUserInfo \n\nRequest:\n```\nGET https://www.googleapis.com/oauth2/v1/userinfo?access_token={accessToken}\n```\n\nResponse:\n```\n{\n\t\"id\": {id},\n\t\"email\": {email},\n\t\"verified_email\": true,\n\t\"name\": \"John Smith\",\n\t\"given_name\": \"John\",\n\t\"family_name\": \"Smith\",\n\t\"link\": \"xxxxxx\",\n\t\"picture\": \"xxxx\",\n\t\"gender\": \"male\",\n\t\"locale\": \"en-US\"\n}\n```\n\n## Conclusion\n\nAs soon as the service is developed and published, you can send the above-mentioned data to VTEX (by opening a ticket). VTEX will then be able to complete environment integration with VTEX ID, providing your store with another login option.\n\n> ℹ️ If you have multiple stores (subaccounts) listed in **Account Settings > Account management > Account**, please note that each one will require their own OAuth2 Identity Provider configuration.\n\nImportant things to remember:\n\n- all endpoints are enabled through HTTPS\n- credentials (Client ID and Client Secret, or equivalent)\n- credentials (username/email and password) for configuration test \n- desired name for the identity provider, which in the final result will be displayed as the text of the \"Sign in as \\{provider name\\}\" button\n\nFor __getAuthorizationCode__:\n\n- requisition URL (GET method)\n- parameter name for Client ID\n- parameter name for response URL\n- additional parameters (if any, indicate key and value)\n- key containing the authorization code (in the response)\n\nFor __getAccessCode__:\n\n- requisition URL (POST method)\n- authorization code format (JSON or form-urlencoded body)\n- additional URL parameters (if any)\n- additional body parameters (if any)\n- credentials format (Authorization header)\n- response format (JSON or form-urlencoded body)\n- key containing the access code (in the response)\n\nFor __getUserInfo__:\n\n- requisition URL (GET method)\n- additional parameters (if any)\n- key containing the user ID (in the response)\n- key containing the email (in the response)\n- key containing the name (in the response, if any)"}