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_SHELLEXXS.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_SHLEXECXS, although the easiest approach is probably to use XOAUTH2XS in place of OAUTH2. XOAUTH2 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 HTTPXS operation with the access code included in the request header. Or, In the case of EMAILXXS, 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.
