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.sh 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 1 : list imported IdPs

List all imported IdPs stored in the database.

fglrun ImportOAuth { -l | --list }

Syntax 2 : show details for a given IdP

Show details for a specified IdP.

fglrun ImportOAuth { -s | --show } idp-issuer-url

idp-issuer-url is the URL of an OAuth2 identity provider (IdP).

For an example, go to Show IdP metadata.

Syntax 3 : importing OAuth2 endpoints

Import the IdP endpoints from an IdP supporting OAuth2 and register them in the database. You must specify the IdP endpoints to register in the database. The options are listed in Table 1.

fglrun ImportOAuth { -i | --import }
  { endpoint-options
  | { -d | --discover }
  } idp-issuer-url

endpoint-options is described in Table 1.
--discover option: If the IdP supports OpenID Connect, import automatically endpoints URLs provided by the IdP. For an example, go to Import IdP metadata as OpenID Connect.
idp-issuer-url is the URL of an OAuth2 identity provider (IdP).

The fglrun importOAuth --import option must be used together with Table 1, or with the --discover option (both methods are exclusive). For an example, go to Import IdP metadata as OAuth2

Table 1. IdP endpoint options
Option	Description
`-a` or `--authz idp-authz-endpoint`	OAuth2 authorization end point URL (mandatory).
`-t` or `--token idp-token-endpoint`	OAuth2 token end point URL (mandatory).
`-p` or `--profile idp-userinfo-endpoint`	OAuth2 userinfo end point URL (optional).
`-o` or `--logout idp-end-session-endpoint`	OAuth2 logout end session endpoint URL (optional).
`-k` or `--keys idp-jwks-uri-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.

Syntax 4 : removing an IdP

Remove details for a specified IdP from the database.

fglrun ImportOAuth { -r | --remove } idp-issuer-url

idp-issuer-url is the URL of an OAuth2 identity provider (IdP).

Removes the OAuth2 entry for the specified IdP from the database. For example:

fglrun ImportOAuth -r https://www.instagram.com

Syntax 5 : adding a parameter

Configure a custom parameter for authentication, such as a federated endpoint, for an IdP registered in the database.

fglrun ImportOAuth { -m | --parameter } custom-param idp-issuer-url

custom-param is the name of an authentication parameter such as a federated endpoint.
idp-issuer-url is the URL of an OAuth2 identity provider (IdP).

Additional parameter (optional). If an IdP registered in the database needs an extra parameter for authentication, such as a federated endpoint, the custom parameter can be configured.

This custom parameter can be any string not starting with the equals symbol "=", that will be added as is to the request sent to the IdP. For an example, go to Import IdP metadata as OAuth2.

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:

Import the endpoints and register a new OAuth2 IdP in the database. For an example, go to Import IdP metadata as OAuth2
Import the endpoints and register a new OpenID Connect IdP in the database. For an example, go to Import IdP metadata as OpenID Connect
List all registered OAuth2 IdPs stored in the database.
Show the endpoints for a given OAuth2 IdP registered in the database.
Remove an OAuth2 IdP identified by its URI from the database.

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. For more information on SSO implementation with OpenID Connect and OAuth2, see OpenID Connect/OAuth2 SSO.