Configure the primary Genero Identity Provider

The Genero Identity Provider (GIP) must be configured and enabled on a Genero Application Server (GAS) before it can be used.

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 Configure FastCGI for Apache 2.4 page in Genero Application Server User Guide

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;
Access to the StarterApp
By default, access to the StarterApp application is allowed only to localhost (127.0.0.1). If your are not running the GAS via the standalone dispatcher (httpdispatch), you must define access in the StarterApp.xcf configuration file; otherwise, error 403 will be thrown when you try to access the StarterApp:
  • Open the $FGLDIR\web_utilities\services\gip\bin\starterapp\StarterApp.xcf file.
  • Configure the ALLOW_FROM element with the IP address of the only machine that will be allowed to run the StarterApp. For example:
    <ALLOW_FROM>192.168.0.100</ALLOW_FROM>
Important:
Once you have installed the GIP, remember to reset the ALLOW_FROM back to the default (NOBODY) to prevent users, who normally should not have access, from running the StarterApp.
<ALLOW_FROM>NOBODY</ALLOW_FROM>

For more information on using ALLOW_FROM, refer to the Genero Application Server User Guide

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 an external Genero Identity Provider.

Warning:

Any URL used with the GIP must contain a valid hostname; it cannot contain "localhost". The GIP uses cookies; 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; if used at installation, it must be used in all its endpoints thereafter.

  1. 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[s]://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.

    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. Accept the default SQLite database for the IDP database, or provide the details for a database from a different database vendor.
    7. Accept the default SQLite database for the user info profile service database, or provide the details for a database from a different database vendor.
    8. Select whether you want the Deployment Service.

      If you plan to deploy and secure applications found on this GAS, you must install the Deployment Service on this GAS; otherwise, you won't be able to deploy and secure applications running on this GAS. You would, however, be able to install the Deployment Service on a separate GAS to deploy applications sitting on that separate GAS.

      By default, Deployment Service is selected.
    9. Select whether you want the Deployment App.
      The Deployment App requires the Deployment Service to be installed.
      The default is no.
    10. Select whether you want the shared file demo.
      The default is no.
    11. 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.

  2. Update the defaults for the admin user.
    1. Start the Console App as the administrator, using the login set in the previous step.
      The Console App 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 Save 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 Save 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 Save to save your changes.
    5. When you have finished with your changes, click Back until you reach the front page of the Console App.
  3. Change the default authorization roles for the Console App and the Deployment App.
    By default, only users with the Role.Admin authorization role can access these apps.
    1. Modify the authorization roles for the Console App.
      Adding the authorization roles mentioned below should allow all users and supervisors to access the Console App (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 roles, however that can be managed by ensuring that each user has at least one of these default roles.
      Navigate to Applications > Manage apps.
      Select the row containing ConsoleApp and click Modify.
      In the Authorization roles tab of the page, select the Role.Supervisor and Role.User authorization roles.
      When you have finished your modifications, click Save to save your changes.
    2. Modify the authorization roles for the Deployment App.
      This step assumes you want users with the Role.Supervisor authorization role to access the Deployment App.
      Select the row containing Deployment App and click Modify.
      In the Authorization roles tab of the page, select the Role.Supervisor authorization role.
      When you have finished your modifications, click Save to save your changes.
  4. 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 Console App, create a deploy user.
      See Manage users.
    2. Assign the user to the Supervisor 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 Deployment App.
  5. 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.
  6. Deploy and secure your applications.