Configuring FlexNet Manager Suite as a SAML Service Provider

FlexNet Manager Suite 2023 R1 (On-Premises)

To set up authentication using any SAML 2.0 tool. you need to make changes to:

The web.config file for FlexNet Manager Suite
The web.config file for Flexera Analytics, if that is in use in your implementation
Microsoft Internet Information Services on affected servers
The identity provider.

Note: When SAML 2.0 is enabled, all operators of FlexNet Manager Suite must log in using the same configured identity provider. It is not possible to operate in a mixed mode where some operators use Windows Integrated Authentication and others use a single sign-on identity provider.

To configure use of a single sign-on tool using SAML 2.0:

In a flat text editor, open the web.config file for the web application server of FlexNet Manager Suite.
By default, this is located on your web application server (or, in a single-server implementation, your application server) in <drive>:\\Program Files (x86)\Flexera Software\FlexNet Manager Platform\WebUI.
Identify the authenticationType attribute in the signOn element, and update the value to Saml.
Original:
```
<signOn authenticationType="Default" allowSelfSigned="true" 
```
Updated:
```
<signOn authenticationType="Saml" allowSelfSigned="true" 
```
Tip: You can also customize the property of operators used to authenticate access to FlexNet Manager Suite. For more information, see Customizing Operator Login Data Type.
Optionally, update the createUnknownOperator Boolean attribute of the signOn element.
- When createUnknownOperator=true, and a user successfully logs into your identity provider who is not already a known operator in FlexNet Manager Suite, the operator is automatically created in FlexNet Manager Suite as a time-saving measure. However, the new operator is not assigned to any roles in FlexNet Manager Suite, and is therefore presented with the Sign In Failure page. To permit access, a known administrator must assign the appropriate role(s) for the new operator.
- When createUnknownOperator=false, and a user successfully logs into your identity provider who is not already a known operator in FlexNet Manager Suite, the user is presented with the Sign In Failure page. To permit access, a known administrator must first create an operator account for this user, and then assign the appropriate role(s) for the new operator.
  Tip: The serviceUri, accountUri, and managerUri fields are not required for SAML authentication.
In summary, the user experience is identical in both cases, and both have the same secure outcomes (access is denied); but there is a little less work for the administrator in the first case.

Continue searching through the web.config file, and update the Sustainsys.Saml2 element with the SAML 2.0 details, as follows.

The Sustainsys.Saml2 element stores details about the service provider (FlexNet Manager Suite). It has two child elements that cover the identity provider and the optional identity provider Certificates. Each section is described in turn in the following tables. More details about the attributes described below are available from: http://msdn.microsoft.com/en-us/library/system.security.cryptography.x509certificates.storename.aspx

Configuration information for FlexNet Manager Suite as the Service Provider

Edit these attributes in the Sustainsys.Saml2 element.

Attribute	Description
`entityId`	A mandatory URI that uniquely identifies FlexNet Manager Suite as the service provider. This must remain fixed for the lifetime of the SAML configuration. Tip: If Secure Socket Layer (SSL) is in use, all URLs must use the HTTPS protocol. Because the URI is used only as an identifier, it does not need to be a real URL that resolves to web resources.
`returnUrl`	When the identity provider can initiate a single sign-on (because the operator logs in on the identity provider's web page and invokes FlexNet Manager Suite), this URL is mandatory. It provides the address to which the identity provider redirects a successful operator who selects the appropriate link to FlexNet Manager Suite as service provider. Important: To enable single sign-on initiated by the identity provider, ensure that `allowUnsolicitedAuthnResponse=true` (see next table). Tip: If Secure Socket Layer (SSL) is in use, all URLs must use the HTTPS protocol.
`authenticateRequestSigningBehavior`	An optional field that supports the following values: `Never`: The service provider will never sign any SAML assertions. In this case, a certificate is not required. Ensure that the identity provider is configured to accept unsigned assertions. `Always`: The service provider will always sign all SAML assertions. A certificate is mandatory. If the identity provider is configured to accept only signed assertions, the public key for the certificate must also be uploaded to the identity provider. `IfIdpWantAuthnRequestsSigned`: (default if the attribute is missing): A certificate is required if the identity provider is configured to accept only signed assertions, in which case the public key for the certificate must also be uploaded to the identity provider.

Configuration information about the identity provider

Edit these attributes in the identityProviders > add element. This data identifies the identity provider for the service provider (FlexNet Manager Suite).

Attribute	Description
`entityId`	A mandatory URI that identifies the selected identity provider.
`loadMetadata`	Optional Boolean, with default: `false`. Determines whether FlexNet Manager Suite should use information about the identity provider taken from the metadata XML document. It downloads the document from the URL identified by `metadataLocation` (if specified), and otherwise downloads from the location identified by the `entityId`. The metadata is a XML document that contains information necessary for interaction by FlexNet Manager Suite with the identity provider. It can contain URLs of endpoints, information about supported bindings, identifiers, and public keys. For more information, see the SAML 2.0 metadata schema available at http://docs.oasis‑open.org/security/saml/v2.0/saml-schema-metadata-2.0.xsd. Tip: FlexNet Manager Suite re-reads the metadata file based on the `cacheDuration` setting within the metadata file itself. (If this value is not specified, the metadata is re-read every hour.) If a file read fails, the data is considered still valid for the further period specified by the `validDuration` attribute (again, within the metadata file). If the metadata file cannot be re-read by the expiry of these two periods, SAML authentication is shut down.
`metadataLocation`	An optional URL or file location pointing to the metadata file. If this attribute is not specified, the URL defined by the `entityId` is checked. Tip: If Secure Socket Layer (SSL) is in use, all URLs must use the HTTPS protocol.
`signOnUrl`	Optional when `loadMetadata` is true. URL for the identity provider. If an operator attempts to access FlexNet Manager Suite without existing authorization, they are redirected to this URL to sign in through the identity provider. Tip: If Secure Socket Layer (SSL) is in use, all URLs must use the HTTPS protocol.
`logoutUrl`	Optional when `loadMetadata` is true. An optional URL that the identity provider uses to listen for log out requests, allowing FlexNet Manager Suite to perform a single log out. Tip: If Secure Socket Layer (SSL) is in use, all URLs must use the HTTPS protocol.
`binding`	Optional when `loadMetadata` is true. The binding that the services provider should use when sending requests to the identity provider. Values: `HttpRedirect` or `HttpPost`.
`disableOutboundLogoutRequests`	Optional with values: `True` or `False`. When set to true, it overwrites the single logout configuration set by the identity provider so that single log out is disabled.
`allowUnsolicitedAuthnResponse`	Mandatory Boolean, with default value `false`. Where IdP-initiated single sign-on is to be supported, this attribute must be set to true.
`signingCertificate`	Optional when `loadMetadata` is true. This is a separate element that is a child of the `identityProviders` > `add` element. It identifies the public key certificate supplied by the identity provider for signing and handling encrypted communications. The `signingCertificate` may have all the same attributes as are documented below for the similar certificate from the service provider.

Configuration information for the Signing Certificates for the identity provider and FlexNet Manager Suite as the service provider

A certificate identifying FlexNet Manager Suite is required when Single Logout is used, or whenever the identity provider requires signed or encrypted communication from the service provider (FlexNet Manager Suite). It allows the service provider to sign SAML assertions to the identity provider, validating the identity of the service provider. The requirement for use of certificates is recorded in the authenticateRequestSigningBehavior setting (see above). Use of signed assertions also requires that you have:

Created the certificate (this may be from a well-known Certificate Authority such as DigiCert, or it can conveniently be a self-signed certificate if the identity provider does not require a trusted Certificate Authority)
Uploaded the public key for the certificate to the identity provider.

When a service provider's certificate is required, edit these attributes in the serviceCertificates element, adding them where they do not already exist.

Attribute	Description
`storeLocation`	A mandatory field with values `CurrentUser` or `LocalMachine`. Represents the location of the store to search for the certificate: `CurrentUser` — User store. The user corresponding to IIS `App Pool` user, configured for the FlexNet Manager Suite virtual directory. `LocalMachine` — The machine where the web application server is installed.
`storeName`	A mandatory field containing an alias for the certificate store within the `storeLocation`. Valid values are those from the `System.Security.Cryptography. X509Certificates.StoreName` enumeration (for details, see http://msdn.microsoft.com/en-us/library/system.security.cryptography.x509certificates.storename.aspx).
`fileName`	When you do not wish to store your certificate in the appropriate certificate store, you may save it as a file in a folder beneath the installation folder for FlexNet Manager Suite (represented by the special `~/` path element). Example: `fileName="~/App_Data/okta.cert"`
`x509FindType`	Defines what to search for to find the certificate. Valid values are those from the `System.Security.Cryptography. X509Certificates.X509FindType` enumeration (for details see http://msdn.microsoft.com/en-us/library/system.security.cryptography.x509certificates.x509findtype.aspx.
`findValue`	A mandatory field containing the search term used to find the certificate. For example, if `x509FindType=FindBySubjectName`, then `findValue` must contain the certificate subject name.

Save this web.config file, but keep it open as a source for copying data if you also use Flexera Analytics.
If your implementation uses Flexera Analytics, configure the separate web.config file for your Flexera Analytics server.
Flexera Analytics is visible by navigating to Reports > Analytics. If this is present:
1. Switch to your Cognos server.
  Flexera Analytics (Cognos) is likely to reside on a separate server. For SAML-based single sign-on to work, the Cognos server and web application server must be in the same domain.
2. In your flat text editor, open the local web.config file for the Cognos server.
  The default location (on Windows) is <drive>:\Program Files\ibm\cognos\analytics\cgi-bin.
3. Edit the web.config file using the same values noted in step 2 and 4 above.
4. From the first web.config file for your web application server, copy the machineKey element, and paste it over the same element in the web.config file for your Cognos server.
  This XML element has the format:
```
<machineKey validationKey="…" decryptionKey="…" validation="SHA1" />
```
5. Save your modified web.config for your Cognos server.

Configure IIS:

On your application server (or in a multi-server implementation, the web application server):

There are several sites related to FlexNet Manager Suite, enabling various features. Repeat the following configuration for each of these sites:

Feature	IIS site name	Settings for each site
FlexNet Manager Suite	`Suite`	Windows Authentication is disabled Forms Authentication is enabled Anonymous Authentication is enabled.
Simulations	`ECMBusinessPortal`
FlexNet Manager for SAP Applications	`SAPOptimization`

Tip: If you are applying content compression to your application server (or in a multi-server implementation, the web application server), please also see the note below (after the Cognos server IIS settings).

If you are using Flexera Analytics, on your Cognos server (where the "Gateway service" operates):

Feature	IIS site name	Settings for each site
Flexera Analytics	`ibmcognos`	Windows Authentication is disabled Forms Authentication is enabled Anonymous Authentication is enabled.
Single sign-on for Flexera Analytics	`ibmcognos\sso`
Content compression (see note)	`ibmcognos`	Enable dynamic content compression is checked Enable static content compression is checked.

Note: The web.config files supplied with FlexNet Manager Suite for each of the web application server (or in a smaller implementation your application server) and the Cognos server by default turn on both dynamic and static content compression. Within the respective web.config files, the setting takes this form:

<urlCompression doStaticCompression="true" doDynamicCompression="true" />

Static compression is installed by default for IIS, but dynamic compression requires a standard Microsoft installation to enable it. While you are configuring IIS, you can check whether dynamic compression is available as follows:

In the Connections pane of IIS on your Cognos server, select the ibmcognos site. (To check your web application server, use the Suite site.)
In the siteName Home pane, double-click Compression.
Ensure that the two check boxes are selected.
Tip: If Enable dynamic content compression is not visible, it is not installed on this server. For installation of this standard Windows feature, see https://docs.microsoft.com/en-us/iis/configuration/system.webServer/urlCompression#setup.

Restart IIS.
If you are using Flexera Analytics, run the Flexera Report Designer Package Import Utility to update your SAML authentication configuration:
1. Navigate to the installation folder\Cognos\BusinessReportingAuthenticationService\bin
2. Right-click on the CognosPackageImport.exe application and click Run as Administrator.
  A window appears for the Flexera Report Designer Package Import Utility.
3. From the Windows Authentication drop-down, select SAML/OAuth Authentication
4. Click Install Reports Package.
  Progress is logged in the text window of this dialog as the package is imported into the Flexera Analytics database. When successfully completed, the last line displays Finished publishing the Report Designer package.
5. On your Flexera Analytics server, restart the IBM Cognos service for the changes to take effect.

It is possible to revert back to Windows Integrated Authentication if required. Keep in mind that operators created for use with SAML will no longer have access, and will need to be re-created using Integrated Windows Authentication. To revert, restore the original values to the web.config file(s), and revert the IIS configuration, restarting IIS.

FlexNet Manager Suite (On-Premises)

2023 R1