OAuthAPI.InitNativeApp()

Initializes the OAuthAPI for a native app.

Syntax

FUNCTION InitNativeApp(
  cnx_timeout INTEGER,
  tokens OpenIdCResponseType,
  client_id STRING,
  client_secret STRING,
  token_end_point STRING)
RETURNS BOOLEAN
  1. cnx_timeout is a connection timeout to the REST service with value in seconds.
  2. tokens is the record, provided by the OAuthAPI.RetrievePasswordTokenForNativeApp() function, containing the access token for accessing the RESTful Web service with information about its expiry, and so on, that allows it to be refreshed.
  3. client_id is the application ID assigned to the app when registered.
  4. client_secret is the application secret created for the app.
  5. token_end_point is the token endpoint of the Identity Provider (IdP) securing the service.
Returns FALSE if any of these values is null:
  • The access token in tokens
  • The refresh token in tokens
  • client_id
  • token_end_point

Usage

A native app is a Genero application that is not behind a Genero Application Server (GAS), such as a mobile, desktop, or Text User Interface (TUI) application. Use the InitNativeApp() function in a native app to access a RESTful web service protected by an Identity Provider and automatically refresh its access token.

The primary role of InitNativeApp() is to register the access token with the Genero Web Services (GWS). Once registered, you can call any of the OAuthAPI methods, such as CreateHTTPAuthorizationRequest, to perform requests to the service or services. The GWS will also be able to refresh the token automatically when it expires, eliminating the need to restart the application.

Before calling InitNativeApp(), ensure that the access token, its expiration date, and the refresh token are set by calling RetrievePasswordTokenForNativeApp to obtain these from the Identity Provider. You must pass the OpenIdCResponseType record, which contains the tokens, when calling InitNativeApp().

Some Identity Providers return a refresh token only when the request asks for one. For example, Microsoft Entra ID returns one only if the scope you pass to RetrievePasswordTokenForNativeApp() includes offline_access. Without a refresh token, InitNativeApp() returns FALSE.

If you need to retrieve metadata, you can call FetchOpenIDMetadata(), which will save the metadata in an OpenIDMetadataType record.

For the complete flow for a native app, go to Authenticate without GAS.

OAuthAPI.InitNativeApp function

IMPORT FGL OAuthAPI

DEFINE metadata OAuthAPI.OpenIDMetadataType
DEFINE tokens OAuthAPI.OpenIdCResponseType
DEFINE usr, pass STRING
DEFINE client_id, secret_id STRING
DEFINE idp_url STRING

MAIN

  # Enter the following information:
  LET idp_url=""   # The IdP's issuer URL
  LET usr=""       # A valid username
  LET pass=""      # Password for the above username
  LET client_id="" # The client ID of an application registered in IdP
  LET secret_id="" # The client secret from the same application

  TRY
      CALL OAuthAPI.FetchOpenIDMetadata(5, idp_url)
              RETURNING metadata
      IF metadata.issuer IS NULL THEN
              DISPLAY "Identity provider not available" 
              EXIT PROGRAM 1
      ELSE
          CALL OAuthAPI.RetrievePasswordTokenForNativeApp(5, metadata.token_endpoint, usr, pass, client_id, secret_id, NULL) 
              RETURNING tokens.*
          IF tokens.access_token IS NULL THEN
              DISPLAY "Unable to retrieve token"
              EXIT PROGRAM 1
          ELSE
              IF NOT OAuthAPI.InitNativeApp(5, tokens, client_id, secret_id, metadata.token_endpoint) THEN
                  DISPLAY "Cannot initiate refresh token service"
              END IF
          END IF
      END IF
  CATCH
      DISPLAY "ERROR: ", status, sqlca.sqlerrm
      EXIT PROGRAM 1
  END TRY

END MAIN