Configure for an external GIP

Complete this procedure to configure the Genero Application Server (GAS) to use an external Genero Identity Provider (GIP) installed on another GAS.

Before you begin

Ensure that users using the ConsoleApp and DeploymentApp have write access to the openid-connect directory. See Provide access to the openid-connect directory.
If in HTTPS, ensure that all certificates are installed in $FGLDIR/web_utilities/certs. For instance, during an SSO handshake, fglrun will fetch the GIP metadata that may be in HTTPS, thus all appropriate certificate authority must be set.

Apache Users

Apache discards the Authorization header if it is not a base64-encoded user/password combination. A rewrite rule can be used to rewrite it from the server variable to set HTTP Authorization for requests.

For an example configuration, see Apache 2.4: mod_proxy_fcgi.

For more information on Apache, see the Apache documentation.

IIS users

Ensure that your IIS has the appropriate rights to access the GIP home directory.

NGINX users

Ensure that your FastCGI Params configuration has the following directives for GIP:

Add the HTTP authorization header:

fastcgi_param HTTP_AUTHORIZATION $http_authorization;

As GIP requires a fully qualified name, the nginx SERVER_NAME must be configured as follows:
```
fastcgi_param SERVER_NAME $host; 
```

GIP working directory

The default GIP working directory is set to the user's home directory at $(home)/.genero-sso. It can be changed by setting the res.path.idp resource in the GAS configuration file.

Warning: If the GIP is started behind an Apache or IIS server, the user's home directory is not set. In a production environment (behind Apache, nginx, or IIS), we recommend you set res.path.idp to a directory that is accessible when the GAS (and therefore the fglrun command) is started from the Web server.

Steps to enable an external GIP

This procedure is for a multi-GAS environment architecture, where the initial GIP configuration has already occurred on a different Genero Application Server. You follow this procedure one time only.

Warning: Any URL used with the GIP must contain a valid hostname; it cannot contain "localhost".The GIP uses cookies, and cookies do not work well with "localhost". It is recommended to use the name of the machine for the hostname. Using the IP address is not recommended, and if used at installation, then it must be used thereafter in all its endpoints.

Start the StarterApp application located at http://host:port[/gas]/ua/r/idp/StarterApp.
Tip: The square brackets around the [/gas] element of the URL indicates that it is optional. In development, you may be using the httpdispatch standalone dispatcher. For the standalone dispatcher, the StarterApp URL is:
```
http://host:port/ua/r/idp/StarterApp
```
The application is only accessible on the localhost and will only start once.

Tip: You can access the StarterApp from the demos page for the GAS, however you must have started the demos page using a valid hostname instead of localhost.

Tip: For additional detail regarding the fields and options of the StarterApp configuration forms, see Genero Identity Platform StarterApp reference.
1. Select External.
  When the External radio button is selected, an edit field appears.
2. Provide the external GIP Issuer URL of the GAS.
```
https://host:port[/gas]/ws/r/services/GeneroIdentityProvider 
```
  Tip: The StarterApp concatenates the URL with the /.well-known/openid-configuration string to fetch the GIP metadata. You can view the metadata at:
```
https://host:port[/gas]/ws/r/services/GeneroIdentityProvider/.well-known/openid-configuration
```
3. Click Ok.
  A second form opens.
4. In the GAS base URL field, enter the URL of the gas you are currently configuring.
5. Select whether you want to install the Deployment Service.
  You must install the Deployment Service on the GAS, otherwise you won't be able to deploy on that GAS protected by the GIP.
  
  The default is yes.
6. Select whether you want to install the Deployment App.
  The Deployment App requires the Deployment Service to be installed.
  
  The default is no. For further information, see Table 3.
7. Select whether you want the shared file demo.
  The default is no.
8. Click Install.
  You will be queried for the credentials of an user authorized to register applications on the GIP.
  
  The installation creates an idp.xml file in the GIP working directory.
  
  Check that everything installed properly. You can check in the Output console.
Deploy applications created with fglgar on a GAS protected by an external GIP.
1. Start the Deployment App as an authorized user.
2. When deploying a Genero Archive (gar) file, enter the roles and scopes for each xcf of the Genero Archive.
3. Click Register All.
  The GIP registers the Genero Archive.
4. If the same Genero Archive (gar) file must be deployed on several GAS, repeat the procedure; however the role will not be updated. Only the initial deployment can set the role.