Set up and configure IIS

To set up and configure Internet Information Services (IIS), perform the following steps:

1. In the IIS manager, create an application pool.
   

2. Adjust the following advanced settings in the application pool: Enable 32-bit Applications and Identity.
   

3. Copy the SAML webservice folder to webservices.

4. Copy the user.config file from a different webservice into the SAML folder. If there are multiple SAML login installations, you must adjust the appSettings type. We recommend to give the type the same name as the SAML folder. Example of the user.config file:

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <appSettings>
     <add key="MasterConfigType" value="SamlLogin" />
     <add key="MasterConfigDir" value="\\<path to master.config>\master.config"/>
   </appSettings>

5. Convert the application pool into an application.
   

Create a Grassfish certificate

To create a Grassfish certificate for the SAML webservice, perform the following steps:

1. Create a certificate. For example, via Azure.
   

2. Enable the certificate and download the file.
   

3. Save the file on the server where the SAML login is installed. For example: configs/Saml/Grassfish-Saml-certificate.pfx

Configure SAML application

To configure the SAML application, perform the following steps:

1. Update the master.config file. Learn more about SAML config parameters.

   <appSettings type="SamlLogin">
   	<add key="MaxLogLevel_File" value="5"/>	
   	
   	<add key="CustomerCode" value="dev"/>
   	
   	<!-- If there is a specific implementation for a customer, please use this Login type but normally the value should be "Generic" -->
   	<add key="CustomerLoginType" value="Generic"/>
   	
   	<!-- update URL -->
   	<add key="CmsPageUrl" value="https://<IXM-Platform-URL>/gv2/gf/GFWebHtml/cms/index.html#external"/>
   	
   	<!-- Path to the certificate file -->
   	<add key="GrassfishSignature" value="\\path\to\certificate\configs\Saml\Grassfish-Saml-certificate.pfx"/>
   	<!-- Password of the certificate file if required, otherwise remove this line -->
   	<add key="GrassfishSignaturePassword" value="SAMLPassword"/>
   	
   	<!-- Should be the path to the SAML Login installation ending with a slash -->
   	<add key="ServiceProviderEntityID" value="https://<IXM-Platform-URL>/gv2/webservices/SamlLogin/"/>
   	<add key="ServiceProviderDescriptorID" value="137C691B812344F997264EC5DB0FD8F8"/>
   	
   	<!-- Identity Provider Metadata file provided from the customer (also called federationmetadata.xml) -->
   	<add key="IdentityProviderMetadata" value="\\path\to\identity-provider-meta-data-file\configs\Saml\idp-metadata.xml"/>
   	<!-- URL from customer where we forward the Service Provider initiated Login request -->
   	<add key="SignOnUrl" value="https://login.microsoftonline.com/<Azure application ID>/saml2"/>
   	
   	<!-- Setting up using Assertion-Attribute (user claims) -->
   	<!-- You can find the specific values in the SAML response while first login -->
   	<!-- Must be unique because it will be used as username for the login, for example email address -->
   	<add key="Generic.ExternalUserIdAttribute" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"/>
   	<add key="Generic.EmailAttribute" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"/>
   	<add key="Generic.FirstNameAttribute" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"/>
   	<add key="Generic.LastNameAttribute" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"/>
   	
   	<add key="Generic.CustomerCodeValue" value="dev"/>
   	
   	<add key="Generic.UpdatePermissionGroupForExistingUsers" value="false"/>
   	<add key="Generic.PermissionGroupValue" value="Default"/>
   	
   	<add key="Generic.UpdateUserGroupsForExistingUsers" value="false"/>
   	<add key="Generic.ClearUserGroupsForExistingUsers" value="false"/>
   	<add key="Generic.UserGroupValue" value="Default"/>
   	
   	<!-- True for analyzing the SAML attributes and response. After the setup works set these configs to false -->
   	<add key="DebugSaveSamlAttributes" value="true"/>
   	<add key="DebugSaveSamlResponse" value="true"/>
   	<add key="EnableSamlTraceLog" value="true"/>	
   	
   	<!-- update URL template -->
   	<add key="LoginSuccessRedirectUrl" value="https://<IXM-Platform-URL>/gv2/gf/GFWebHtml/cms/index.html#external?autologin=bysession&amp;sh=@@sh@@&amp;cid=@@customerId@@&amp;userID=@@userId@@&amp;customerName=@@customerCode@@"/>
   </appSettings>

2. Update the config.json file in the 00000 customer folder located at: www\gv2\gf\GfWebHtmlCustomer\00000

   • common > login > mode > sessionID: enter the session ID. This entry is mandatory.

   • common > applicationPath > redirectOnLogoutToUrlByUserOrigin > Saml: optionally enter the application’s URL.

{
	"cms": {
		....
	},
	"common": {
		/* If a logout to a portal where specific apps from the customer are available 
		is required then setup this redirect url */
		"applicationPath": {
			"redirectOnLogoutToUrlByUserOrigin": {
				"Saml": "https://path.to.portal"
			}
		},
		"login": {
			"mode": "sessionID"
		}
	}
}

Provide the XML file to the customer

To provide the customer with the grassfish-metadata.xml file, perform the following steps:

1. Recycle the application pool.

2. Open the Metadata.aspx site: https://<IXM-Platform-URL>/gv2/webservices/SamlLogin/Metadata.aspx

3. Download it as an XML file and send it to the customer.

Request configurations from the customer

To get the configurations from the customer, perform the following steps:

1. Once the customer has imported the grassfish-metadata.xml file, they can provide an idp-metadata.xml (identity provider) file.

2. Save the file in a folder to which the server with the SAML login installation has access. For example: configs/Saml/idp-metadata.xml

3. Update the IdentityProviderMetadata value with the path to the idp-metadata.xml in the master.config file.

4. Request the Sign-On URL for the service provider initiated login. For example, the URL from Azure looks like this: https://login.microsoftonline.com/63b569d3-0965-41ec-af3f-2247dff6a5f1/saml2

5. Update the SignOnUrl value with the provided URL in the master.config file.

Note

You must recycle the application pool after every master.config file update, change of the idp-metadata.xml file, and certificate update.