ImportOAuth

The ImportOAuth command registers endpoints provided by an identity provider using OAuth2 Single sign-on.

Set the environment

Before executing the command, set the environment using the envoidc script, found in $FGLDIR/web_utilities/services/openid-connect. On Microsoft® Windows, the script is named envoidc.bat.

The ImportOAuth.4gl source code is provided in $FGLDIR/web_utilities/services/openid-connect/src/. The compiled version is in the bin directory.

Syntax

fglrun ImportOAuth [ options ] IdP

options are described in Table 1.
IdP is the URL of an OAuth2 identity provider (IdP).

The ImportOAuth command line tool follows the convention of other Genero command line tools for both short and long versions of options.

Table 1. ImportOAuth options
Option	Description	Usage example
`-h, --help`	Display help with the command.	`fglrun ImportOAuth -h`
`-l, --list`	List all imported IdPs stored in the database.	`fglrun ImportOAuth -l`
`-r, --remove`	Remove the OAuth2 entry for the specified IdP from the database.	`fglrun ImportOAuth -r https://www.instagram.com`
`-i, --import`	Import the IdP endpoints and register them in the database for OAuth2.	See Import option usage example
`-a, --authz IdP_endpoint`	OAuth2 authorization end point URL (mandatory).	See Import option usage example
`-t, --token IdP_endpoint`	OAuth2 token end point URL (mandatory).	See Import option usage example
`-o, --logout IdP_endpoint`	OAuth2 logout end point URL (optional).	See Import option usage example
`-k, --keys IdP_endpoint`	OAuth2 public JWK keys URL (recommended). Not all OAuth providers have public keys; however, if an IdP public keys URL is available, provide it to get the ID token signature validated.	See Import option usage example
`-p, --profile IdP_endpoint`	OAuth2 user profile end point URL (optional).	See Import option usage example

Usage

When implementing Single sign-on for an application or web service with an OAuth2 identity provider, you need to use the ImportOAuth command to register the IdP endpoints in the GAS because OAuth2 does not have a metadata feature that enables the GAS to automatically find the required IdP endpoints.

With the ImportOAuth command, you can:

Register a new OAuth2 IdP.
List all registered OAuth2 IdPs.
Remove OAuth2 IdP identified by its URI.

Important:

If the IdP is using the OpenID Connect protocol, there is no need to use the ImportOAuth program as OpenID Connect has the metadata feature that allows Genero's OpenID Connect service to automatically fetch the metadata, including all the endpoint URLs, from the IdP.

Import option usage example

To import an IdP as OAuth2, you must execute the ImportOAuth program with the --import option.

Open a command prompt.
Type the command to change to the Genero BDL installation directory:
- On Linux®/UNIX®/macOS™:
```
cd $FGLDIR/web_utilities/services/openid-connect
```
  On Windows®:
```
cd %FGLDIR%\web_utilities\services\openid-connect
```
Execute the script to set the environment.
- On Linux/UNIX/macOS (using sh as shell script):
```
./envoidc
```
  On Windows:
```
envoidc.bat
```
Run the ImportOAuth program. This example provides the command for Instagram; line breaks have been added for readability.
```
fglrun ImportOAuth --import 
            --authz https://api.instagram.com/oauth/authorize 
            --token https://api.instagram.com/oauth/access_token 
            --logout https://instagram.com/accounts/logout 
            --profile https://api.instagram.com/v1/users/self?
            https://www.instagram.com
```
The first two parameters --authz and --token are mandatory, and the endpoint URLs of the IdP are required:
1. --authz URL: mandatory authorization endpoint URL.
2. --token URL: mandatory token endpoint URL.
3. --logout URL: optional logout endpoint URL.
4. --profile URL: optional user profile endpoint URL.
5. URL of the IdP: mandatory
  
  Important:
  The profile URL requires an access_token to get user profile information. In some cases, the access_token must be provided via the query string (for example, Instagram requires it). Therefore you must add an ending question mark (?) during importation so that OpenID-Connect service providers know how to generate that request.