Setting up the Genero Identity Provider

The Genero Identity Provider (GIP) must be configured and enabled before it can be used. This procedure configures and enables the GIP on a Genero Application Server (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.

Enable the GIP on a GAS

These steps enable the local GIP on a GAS. You follow this procedure one time only. To enable an external GIP - where a GAS connects to the GIP already enabled on another GAS - see Configure for an external GIP.

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
```
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.
The StarterApp configures the GIP. It is only accessible on the localhost and will only start once.

Tip: For additional detail regarding the fields and options of the StarterApp configuration forms, see Genero Identity Platform StarterApp reference.
1. Select the local GIP.
2. Enter the new GIP administrator login and password.
3. Enter the new OAuth secret generator password.
4. Enter your GIP base URL.
  
  Note: HTTPS is recommended for the base URL, however HTTPS is not valid when using httpdispatch for the GAS.
  
  By default, the GIP base URL will be the GAS base URL. If the GAS is configured with a Web server in HTTPS, you can accept the default.
5. Select whether you want the User Info Profile Service.
  The default is Integrated.
6. Select whether you want 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.
  
  By default, Deployment Service is selected.
7. Select whether you want the Deployment App.
  The Deployment App requires the Deployment Service to be installed.
  
  The default is no.
8. Select whether you want the shared file demo.
  The default is no.
9. Click Install.
  Check that everything installed properly. You can check in the Output panel.
  
  The installation creates the file idp.xml with endpoints to GIP services and creates and initializes databases in the GIP working directory at $(home)/.genero-sso.
  To restart your Starter App, remove this directory completely.
Update the defaults for the admin user.
1. Start the ConsoleApp as the administrator, using the login set in the previous step.
  The ConsoleApp is located at http://host:port[/gas]/ua/r/admin/ConsoleApp.
2. If you have installed the User Info Profile Service, update your profile.
  If you kept the default of "Integrated", then you have installed the User Info Profile Service.
  
  Navigate to Users > Update me and click Profile.
  
  Update your avatar and any additional profile details. First Name, Last Name and Email are mandatory.
  
  Click Update to save your changes.
3. Click Groups.
  By default, the administrator belongs to group Administrator. You can add the administrator to any additional groups, if desired. As the administrator, you can always return to this page to update group membership at a later time.
  
  If you made modifications, click Register to save your changes.
4. Click Permissions.
  View the permissions of the admin user. While not necessary at this time, you can add scopes. You can remove scopes that are not inherited based on your group memberships.
  
  If you made modifications, click Change to save your changes.
5. When you have finished with your changes, click Back until you reach the front page of the ConsoleApp.
Change the default authorization scopes for the ConsoleApp and the DeploymentApp.
By default, only users with the Role.Admin authorization scope can access these apps.
1. Modify the authorization scopes for the ConsoleApp.
  Adding the authorization scopes mentioned below should allow all users and supervisors to access the ConsoleApp (to update their profile details or change their password, for example). It may still be possible that you have a user that does not have one of the three default authorization scopes, however that can be managed by ensuring that each user has at least one of these default scopes.
  
  Navigate to Applications > Manage apps.
  
  Select the row containing ConsoleApp and click Modify.
  
  The authorization scopes are listed at the bottom of the page. Select the Role.Supervisor and Role.User authorization scopes.
  
  When you have finished your modifications, click Save to save your changes.
2. Modify the authorization scopes for the DeploymentApp.
  This step assumes you want users with the Role.Supervisor authorization scope to access the DeploymentApp.
  
  Select the row containing DeploymentApp and click Modify.
  
  The authorization scopes are listed at the bottom of the page. Select the Role.Supervisor authorization scope.
  
  When you have finished your modifications, click Save to save your changes.
Create a dedicated user that is allowed to deploy new apps on any GAS protected by this GIP.

Note: It is recommended that you create a dedicated user, however it is not a requirement.
1. Using the ConsoleApp, create a deploy user.
  See Manage users.
2. Assign the user to the Superviser group.
  Click Groups. Select the Supervisor group. Click Save.
3. Add scopes for this user.
  Click Permissions.
  Select the permissions:
  - register (OpenIDRegister service)
  - deployment (Deployment service)
  Click Save.
  
  The deploy user is now able to deploy and secure applications using the DeploymentApp.
Create an account for each user whose access is to be controlled by the GIP. In other words, each user that requires permissions to access applications will need an account.
See Manage users.
Deploy and secure your applications.
See Deploying and securing applications and Web services.