# OAUTH2 Setup

> [HTML Version](oauth2-setup.htm)

As a preliminary to OAUTH2 authentication, you'll need to establish an account with a service provider (e.g. Google API, Microsoft Azure, etc.), typically through an online portal; this is independent of A-Shell. The provider will issue you a client ID and secret, and probably some other attribute values (e.g. authorization endpoint, scope, etc.) which you'll need to save locally (typically in JSON format) in order to provide them as part of the opcode 1 request. As an example, here is a typical set of client attributes for Gmail: 

\{

"client\_id":"123456789012-abc123xyz456jkl789pqr321ack.apps.googleusercontent.com",

"project\_id":"emailx-123456",

"auth\_uri":"https://accounts.google.com/o/oauth2/auth",

"token\_uri":"https://oauth2.googleapis.com/token",

"auth\_provider\_x509\_cert\_url":"https://www.googleapis.com/oauth2/v1/certs",

"client\_secret":"XXXXXX-aBcDeFgHiJkLm123456789",

"redirect\_uris":\["http://localhost"\],

"scope":"https://mail.google.com/"

\}



For the initial opcode 1, you'll need to match up the necessary attribute values with the corresponding OAUTH2 parameters. Using the example, above, _clientid\$_ is "client\_id" ("123456..."), _clientsecret\$_ is "client\_secret" ("XXXXX..."), _auth'endpoint\$_ is "auth\_uri," _token'endpoint\$_ is "token\_uri," etc.

The _response\$_ from a successful opcode 1 will be a URL which you'll then need to launch a browser to, in order for the user to interactively acknowledge the desire to access the service. This is the big difference between the OAUTH2 protocol and most other authentication schemes, i.e. that it requires a level of user interactivity. However, this interaction step is normally only required for the first access after which the application will be able to re-use and even refresh the access token for a substantial period or time or number of requests without further interaction.

To launch the browser to the specified URL for the initial authorization step, under local A-Shell/Windows you can use [MX\_SHELLEX](mx_shellex.md)[XS](keyword-types.md).In the telnet/ssh environment, it won't be possible to use MX\_SHELLEX directly from the server/application side, so you'll need another way to arrange for the user to browse to the specified URL. If the client workstation is running ATE, you could use [AG\_SHLEXEC](ag_shlexec.md)[XS](keyword-types.md), although the easiest approach is probably to use [XOAUTH2](xoauth2_sbr.md)[XS](keyword-types.md) in place of OAUTH2. [XOAUTH2](xoauth2_sbr.md) is an SBX that offers the identical application interface as OAUTH2, but in the case of ATE executes the operation on the ATE client, eliminating the need for additional logic in the application code to handle the two scenarios.

Once the browser has been launched, the application can proceed to _opcode_ 2, which waits (up to the specified time out) for the user to complete the interactive authorization via the browser, after which it will either succeed (returning the _status_ 0, with the access token and related details in response\$) or fail with a non-zero _status_ value.

In code, the sequence of requesting a new access token may be summarized as ...

xcall OAUTH2, 1, status, clientid\$, clientsecret\$, option, auth'endpoint\$, token'endpoint\$, challenge\$, scope\$, refresh'token\$, response\$, handle, stsmsg\$



if status = 0 then    \! on success, launch the browser to the response URL...

    xcall MIAMEX, MX\_SHELLEX, status, response\$, "", "", "", SW\_SHOWNORMAL, 0





    \! after launching the browser, proceed to opcode 2 (waiting for the user to complete

    \! the authorization and for the web service to accept and issue the token)...

    xcall OAUTH2, op, status, clientid\$, clientsecret\$, wait, auth'endpoint\$, token'endpoint\$, challenge\$, scope\$, refresh'token\$, response\$, handle, stsmsg\$

...



The successful _response\$_ is also typically in JSON form, for example...

\{

    "access\_token": "xy12.x1Bux\_KpEC0z...",

    "expires\_in": 3599,

    "refresh\_token": "9//23-42ZxTgy8I6...",

    "scope": "https://mail.google.com/",

    "token\_type": "Bearer",

    "refresh\_token\_expires\_in": 604798

\}



The access token may then be used to access the desired service. In most cases that will involve an [HTTP](http_sbr.md)[XS](keyword-types.md) operation with the access code included in the request header. Or, In the case of [EMAILX](emailxsbr.md)[XS](keyword-types.md), the access code is used in place of the password.

Access tokens typically last for a certain period of time (one hour in the example above), after which you'll need to use _opcode_ 3, (passing the refresh token in the _refresh'token\$_ parameter) to get a new access token. Once the refresh token expires, the request for a refresh will fail and you'll need to start over with _opcode_ 1.