Quick start: Set up SAML in the GAS

Follow these steps to set up SAML for your Genero Application Server (GAS) and Genero Web applications.

1. Configure the GAS for SAML SSO:
   1. If your GAS is located behind a proxy, configure the proxy in the SAML fglprofile file, located in $FGLDIR/web_utilities/services/saml/res. Uncomment and set values for these proxy entries. Enclose the server address and port number in quotes:

      proxy.http.location = "myproxy.server.com:3128"
      proxy.https.location = "myproxy.server.com:3128"

   2. SAML requires digital signatures. Create a X.509 Certificate and its private key (see the Create the client certificate page in Genero Business Development Language User Guide for details), then modify the SAML configuration file located in $FGLDIR/web_utilities/services/saml/res:
      • Set values for the SAML signature X.509 and RSA private key entries. Enclose the path to the files in quotes. In the example the path is relative to $FGLDIR/web_utilities/services/saml/res

        xml.saml_signature.x509             = "../crt/MyCert.crt"
        xml.saml_signature.key              = "../crt/MyCert.pem"

      • If your Genero Web applications must be accessible by HTTPS, to be fully secured you must use that certificate and key for XML-Encryption. Uncomment and set the same value for the encryption entries. Enclose the path to the files in quotes. In the example the path is relative to $FGLDIR/web_utilities/services/saml/res

        xml.saml_encryption.x509            = "../crt/MyCert.crt"
        xml.saml_encryption.key             = "../crt/MyCert.pem"

   3. Create a circle of trust between the GAS and a SAML Identity Provider (IdP).
      In this step you are configuring the GAS to trust the IdP you are going to access via SAML.

      • Set the SAML environment.
        On UNIX™ (using sh as shell script):

        cd $FGLDIR/web_utilities/services/saml
        . ./envsaml.sh

        On Windows®:

        cd "%FGLDIR%\web_utilities\services\saml"
        envsaml.bat

      • Register the SAML IdP with Genero SAML by launching the ImportIdP application with the SAML IdP URL.

        • Refer to the IdP documentation for information on generating the metadata file (or the URL) from the SAML identity provider.
        • Example:
          On UNIX:

          cd $FGLDIR/web_utilities/services/saml/bin
          fglrun ImportIdP --import http[s]://host:port/openam_954/saml2/jsp/exportmetadata.jsp

          On Windows:

          cd "%FGLDIR%\web_utilities\services\saml\bin"
          fglrun ImportIdP --import http[s]://host:port/openam_954/saml2/jsp/exportmetadata.jsp

      • Retrieve the SAML provider Certificate and add it as a trusted certificate in the SAML configuration file (if needed).

        • Uncomment and set the correct values for the entry xml.keystore.calist; see Certificate authority for more details.
        • Refer to the SAML Identity Provider (IdP) documentation for information about retrieving its X.509 certificate.
   4. Create a circle of trust between the SAML provider and the GAS.
      In this step you are integrating the IdP with the GAS so that trust is established.

      • Start the dispatcher (if needed).
      • Log in to your SAML provider and create a circle of trust based on the GAS SAML metadata.
        Generate the metadata from this URL:

        http[s]://host:port/gas/ws/r/services/SAMLServiceProvider/Metadata

        An XML descriptor page should open. If the page fails to open, make sure you have the certificates (.crt and .pem) in $FGLDIR/web_utilities/services/saml/res/crt as specified in the $FGLDIR/web_utilities/services/saml/res/configuration file.
        • For instance, you may need to configure URLs in the IdP with URLs specified in the Genero SAML metadata page. Refer to the SAML Identity Provider (IdP) documentation for information about importing the Genero SAML metadata.
        • Make sure Genero applications are configured to use HTTPS.
        • GAS default SAML identity name is "urn:genero". If needed, you can change the identifier by modifying the saml.entityID entry in the SAML configuration file.
2. Add SAML SSO to a Genero Web application:
   1. Add the DELEGATE tag to all Genero Web applications requiring SSO.

      <DELEGATE service="services/SAMLServiceProvider" />

      For example:

      <APPLICATION Parent="defaultgwc">
        <EXECUTION>
          <PATH>$(res.path.mypath)/myapplication</PATH>
          <MODULE>myapp.42r</MODULE>
          <DELEGATE service="services/SAMLServiceProvider" />
        </EXECUTION>
      </APPLICATION> 

3. Execute a Genero Web application with SSO:
   1. Start your browser and enter the application URL.
      You are redirected to the SAML provider and prompted to enter your credentials.
   2. Enter your credentials and click the signin button.
      If your credentials are valid, your browser is redirected to the Web application. The application starts and runs as the entered SAML user.