Define the SAML user identifier format

Follow these steps to define the user ID format to receive from the SAML IdP.

As a prerequisite, see the SAML core specification for the list of supported user ID formats. There are several formats. The default ID format is transient, meaning that the returned ID is only valid for the current session and has only a meaning for the IdP the Genero Application Server/JGAS is connected to. Other formats exist, such as emailAddress or persistent, but you must be sure that your IdP supports them; otherwise, you will get an error. The IdP decides which format it supports.

The SAML Single sign-on (SSO) protocol allows federation of identities. This means that a single user can have different identities on different SAML IdPs. To federate the same user across several IdPs, the notion of ID format was introduced.

The ID format allows you to specify how the user is represented to a Service Provider. It defines what piece of data is sent from the IdP to the GAS/JGAS to represent the user.

SAML uses a Uniform Resource Name (URN) namespace to specify the protocol and the ID format. Examples are shown for the emailAddress and persistent formats:
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
urn:oasis:names:tc:SAML:1.1:nameid-format:persistent

The application configuration is slightly different for GAS and JGAS, choose the appropriate step.

  1. In the GAS application configuration file, add an IDFORMAT element with a valid SAML URN as a child of the SAML DELEGATE element in the application configuration (xcf) file.
    In this example, the IdP will return the email of the authenticated user to the GAS in the SAML_ID environment variable.
    <?xml version="1.0"?>
<APPLICATION Parent="defaultgwc"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:noNamespaceSchemaLocation="http://4js.com/ns/gas/5.00/cfextws.xsd">
  <EXECUTION>
    <PATH>$(res.path.qa)/applications/myapp</PATH>
    <MODULE>App.42r</MODULE>
    <DELEGATE service="services/SAMLServiceProvider">
      # ...
      <IDFORMAT>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</IDFORMAT> 
    </DELEGATE>
  </EXECUTION>
</APPLICATION>
  2. In the JGAS application configuration file, add an IDFORMAT element with a valid SAML URN as a child of the SAML DELEGATE element in the application configuration (xcf) file.
    In this example, the IdP will return the email of the authenticated user to the JGAS in the SAML_ID environment variable.
    <?xml version="1.0"?>
<APPLICATION Parent="defaultgwc">
  <EXECUTION>
    <PATH>$(res.path.qa)/applications/myapp</PATH>
    <MODULE>App.42r</MODULE>
    <DELEGATE service="SAMLServiceProvider">
      # ...
      <IDFORMAT>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</IDFORMAT>
    </DELEGATE>
  </EXECUTION>
</APPLICATION>

When set, the SAML_ID environment variable retrieved in the application program will be in the format specified in the IDFORMAT element of the configuration file.