The utiladoCloudOAuth operation is an APIScript operation that is used to facilitate the OAuth authentication and refresh flows.

The provider includes stored procedures that invoke this operation to complete the OAuth exchange. The following example schema briefly lists some of the typically required inputs before the following sections explain them in more detail.

Writing the GetOAuthAuthorizationURL Stored Procedure

Call utiladoCloudOAuth in the GetOAuthAuthorizationURL stored procedure.

<api:script xmlns:api="http://www.rssbus.com/ns/rsbscript/2">

  <api:info title="Get OAuth Authorization URL" description="Obtains the OAuth authorization URL used for authentication with various APIs."                                                          >
    <input  name="Scope"                        desc="Defines the level of access granted to APIs. By default, access is provided to all APIs supported by this data provider. " />
    <input  name="Prompt"                       desc="Controls the type of authentication prompt displayed to the user. Options: 'NONE' (no prompt), 'CONSENT' (always display the consent screen), 'SELECT_ACCOUNT' (prompt the user to choose an account). " />
    <input  name="CallbackURL"                  desc="The URL to which the user is redirected after completing the OAuth authorization process. " />

    <output name="URL"                          desc="The OAuth authorization URL that users must visit to authenticate and grant access to the application. "                                                               />
  </api:info>

  <!-- Set ResponseType to the desired authorization grant type. OAuth 2.0 only.-->
  <api:set attr="ResponseType"           value="CODE"                               />
  <api:set attr="Operation"              value="GetOAuthAuthorizationUrl"           />
  <api:call op="utiladoCloudOAuth" out="toout" ignoreprefix="gll" >
    <api:push item="toout" />
  </api:call>
  
</api:script>

<p>

Writing the GetOAuthAccessToken Stored Procedure

Invoke the utiladoCloudOAuth with the GetOAuthAccessToken stored procedure. The following inputs are required for most data sources and will provide default values for the connection properties of the same name.

<api:script xmlns:api="http://www.rssbus.com/ns/rsbscript/2">

  <api:info title="GetOAuthAccessToken"   description="Obtains the OAuth access token to be used for authentication with various APIs."                                                         >
    <input  name="AuthMode"               desc="The OAuth flow. APP or WEB."                                                                                                                    />
    <input  name="CallbackURL"            desc="The URL to be used as a trusted redirect URL, where the user will return with the token that verifies that they have granted your app access. " />
    <input  name="GrantType"              desc="Defines the OAuth 2.0 authorization grant type, such as 'authorization_code' or 'client_credentials'."                                          />
    <input  name="Verifier"               desc="The verifier code obtained when the user grants permissions to your app."                                                                       />
    <input  name="Scope"                  desc="Defines the level of access granted to APIs. By default, access is provided to all APIs supported by this data provider. "                      />

    <output name="OAuthAccessToken"       desc="The access token."                                                                                                                              />
    <output name="OAuthTokenSecret"       desc="The access token secret."                                                                                                                       />
    <output name="OAuthRefreshToken"      desc="A token that may be used to obtain a new access token."                                                                                         />
    <output name="ExpiresIn"              desc="The duration (in seconds) before the access token expires. A value of -1 indicates that the token does not expire."                             />
 </api:info>

  <!-- Set Scope. -->
  <api:set attr="Scope"                                     value="[_input.Scope]"                           />
  <api:set attr="Operation"              value="GetOAuthAccessToken"           />
  <api:call op="utiladoCloudOAuth" out="toout" ignoreprefix="gll" >
    <api:push item="toout" />
  </api:call>
  
</api:script>

Writing the RefreshOAuthAccessToken Stored Procedure

You can also use utiladoCloudOAuth to refresh the access token by providing the following inputs:

<api:script xmlns:api="http://www.rssbus.com/ns/rsbscript/2">

  <api:info title="RefreshOAuthAccessToken" description="Refreshes the OAuth access token used for authentication." >
    <input  name="OAuthRefreshToken"        desc="A token that may be used to obtain a new access token."           />

    <output name="OAuthAccessToken"         desc="The authentication token returned."                               />
    <output name="OAuthTokenSecret"         desc="The authentication token secret returned. OAuth 1.0 only."        />
    <output name="OAuthRefreshToken"        desc="A token that may be used to obtain a new access token."           />
    <output name="ExpiresIn"                desc="The remaining lifetime on the access token."                      />

  </api:info>

    <!-- Set GrantType to REFRESH. -->
    <api:set attr="GrantType"            value="REFRESH" />
    <!-- Set AuthMode to 'WEB' when calling RefreshOAuthAccessToken -->
    <api:set attr="AuthMode" value="WEB"/>
    <api:set attr="Operation"              value="GetOAuthAccessToken"           />
    <api:call op="utiladoCloudOAuth" out="toout" ignoreprefix="gll" >
      <api:push item="toout" />
  </api:call>
  
</api:script>

Input Parameters

• OAuthVersion: The OAuth version. The allowed values are 1.0, 2.0. The default value is 1.0.
• AuthMode: The OAuth flow. OAuth 2.0 only. If you choose the App mode, this operation will launch your browser and prompt you to authenticate with your account credentials. Set this parameter to WEB to authenticate a Web app or if the provider is not allowed to open a Web browser. The default value is APP.
• OAuthRequestTokenURL: The URL where the provider makes a request for the request token. OAuth 1.0 only. Required for OAuth 1.0.
• OAuthAuthorizationURL: The URL where the user logs into the service and grants permissions to the application. In OAuth 1.0, if permissions are granted the request token is authorized.
• OAuthAccessTokenURL: The URL where the request for the access token is made. In OAuth 1.0, the authorized request token is exchanged for the access token.
• Scope: Defines the level of access granted to APIs. By default, access is provided to all APIs supported by this data provider.
• CallbackURL: The URL to be used as a trusted redirect URL, where the user will return with the token that verifies that they have granted your app access. This value must match the callback URL you specify when you register an app. Note that your data source may additionally require the port.
• OAuthClientId: The client Id obtained when you register an app. Also called a consumer key.
• OAuthClientSecret: The client secret obtained when you register an app. Also called a consumer secret.
• OAuthAccessToken: The request token. OAuth 1.0 only.
• OAuthAccessTokenSecret: The request token secret. OAuth 1.0 only.
• OAuthRefreshToken: A token that may be used to obtain a new access token.
• GrantType: Authorization grant type. OAuth 2.0 only. The allowed values are CODE, PASSWORD, CLIENT, REFRESH. The default value is CODE.
• Verifier: The verifier code obtained when the user grants permissions to the provider. In the OAuth 2.0 code grant type, the verifier code is located in the code query string parameter of the callback URL. In OAuth 1.0, the verifier is located in the oauth_verifier query string parameter of the callback URL.
• SignMethod: The signature method used to calculate the signature for OAuth 1.0. The allowed values are HMAC-SHA1, PLAINTEXT. The default value is HMAC-SHA1.
• Cert: Path for the PFX personal certificate file. OAuth 1.0 only.
• CertPassword: Personal certificate password. OAuth 1.0 only.
• Proxy_Auto: Whether or not the proxy should be detected from Windows system settings. This takes precedence over other proxy settings and is not available in Java. The allowed values are TRUE, FALSE. The default value is FALSE.
• Proxy_Server: IP address or host name of the proxy server used for the request.
• Proxy_Port: The port number of the proxy server.
• Proxy_User: The user Id used to authenticate with the proxy server.
• Proxy_Password: The password used to authenticate with the proxy server.
• Proxy_AuthScheme: The authentication scheme of the proxy server. The allowed values are BASIC, DIGEST, NONE, NTLM. The default value is BASIC.
• Proxy_AuthToken: The proxy authentication token.
• Proxy_SSLType: The SSL type of the proxy server. The allowed values are AUTO, ALWAYS, NEVER, TUNNEL. The default value is AUTO.
• Firewall_Type: The type of the firewall. The allowed values are NONE, TUNNEL, SOCKS4, SOCKS5. The default value is NONE.
• Firewall_Server: The IP address or host name of the firewall.
• Firewall_Port: The port number of the firewall.
• Firewall_User: The user Id used to authenticate with the firewall.
• Firewall_Password: The password used to authenticate with the firewall.
• PostData: The HTTP POST data.
• OtherOptions: Other options to control the behavior of OAuth.
• OAuthParam:*: Other parameters.

Output Parameters

• URL: The URL where the user logs in and is prompted to grant permissions to the app. In OAuth 1.0, if permissions are granted the request token is authorized.
• PKCEVerifier: A randomly generated key used in the OAuth PKCE (Proof Key for Code Exchange) flow. Required when 'AuthScheme=OAuthPKCE'
• AuthToken: A temporary authorization token that must be passed into the GetOAuthAccessToken stored procedure to obtain an access token.
• AuthKey: A secret token associated with the authorization request, required for OAuth 1.0 authentication.
• AuthSecret: A legacy alias for 'AuthKey', included for backward compatibility.
• OAuthAccessToken: The access token.
• OAuthTokenSecret: The access token secret.
• OAuthRefreshToken: A token that may be used to obtain a new access token.
• ExpiresIn: The remaining lifetime on the access token.
• OAuthParam:*: Other parameters sent from the server.