Azure Entra SSO integration with DX UIM SAML

Products

• DX Unified Infrastructure Management (Nimsoft / UIM)

Issue/Introduction

The documentation for SAML/SSO integration with DX UIM provides general information about the integration and also some specific details related to SiteMinder integration but we are looking for information on how to integrate with Azure Entra (Microsoft SSO product).

 

Environment

DX UIM - 23.4.2 (may be applicable to 20.4x also)
Microsoft Azure Entra SSO

Resolution

The following is an outline of the process which includes some steps taken from the documentation and some additional details (highlighted in red).

These steps were followed by a customer who successfully integrated DX UIM 23.4.2 with Microsoft Entra but these steps generally should be applicable to other cloud-based IDPs as well.

This will also generally be applicable for DX UIM 20.4 but the workflow may be slightly different on the DX UIM side.  Refer to the 20.4 documentation for additional details on the differences in the workflow from the UIM side (mostly it is a difference of where files are located and filenames).

 

1. Create a Keystore for use with SAML
   Follow these steps:
   Open an administrator command prompt on the target server (Operator Console or Admin Console).
   The keytool utility is located in the directory where the JRE resides, typically <Operator Console_installation>/jre/<jre_version>/bin/keytool.
   Generate the keystore and key:
   
   

   keytool -genkey -keyalg RSA -alias <EntityId> -keystore keystore.jks -storepass <keystorePassword> -validity <days_cert_is_valid> -keysize 2048

   The alias you use for <EntityID> is a single word identifier that you will use this to identify the integration source.  So for example if you are integrating the Operator Console in your production environment you could use something like "ProductionOC" for the EntityID.  You will need to use this same value in the configuration later so keep it simple.
   
   Make note of the password you use to create the keystore as you will need to use it later.
   
   
2. Copy the resulting keystore.jks file to the folder:  (NIMSOFT HOME)\Nimsoft\probes\service\wasp\conf\samlsso
3. Stop the wasp probe
4. Edit the samlssoConfig.properties file in the same folder and change the top section as described in the documentation with the appropriate values.  Those items which are specific to Azure Entra will be highlighted in red.
   
   saml.configuration.enabled - to enable SAML configuration
   saml.sp.metadata.id - specifies the ID provided by the Service Provider
   - this is just a unique name/identifier transmitted to Azure - best practice would be to set this the same as what you are using for EntityID (for example, "ProductionOC") when you created the keystore in the previous step
   saml.sp.metadata.entityid - specifies the EntityID provided by the Service Provider
   - here again we just need to set a unique name and this one MUST match the name used for EntityID. In the case of Azure Entra it's recommended to set this the metadata.id and metadata.entityid to the same value (which again must match the value used for EntityID when creating the keystore.)
   
   saml.sp.keystore.path - specifies the path for the keystore file
   - set this to the location of the keystore, relative to the wasp folder.  So in this example set the value to "conf/samlsso/keystore.jks"
   
   saml.sp.keystore.password - specifies the password for the keystore file
   
   - this must be set to an encrypted password string.  You can obtain that string by pointing your browser at your Operator Console on the internal network to the folowing page:
   
    https://(operator console IP)/operatorconsole_portlet/encryptText.jsp
   Enter the password you have used to create the keystore and it will return an encrypted string. We will call this "Encrypted String #1"
   
   This encrypted string is the value to paste into the saml.sp.keystore.password field.
   
   saml.sp.keystore.aliasName - specifies the alias name for using keystore file
    - This is an encrypted string of the alias that you used (e.g. "ProductionOC" in our example.  Once again use the "encryptText.jsp" URL above to obtain this string and paste it into the config file here.  We will call this "Encrypted String #2."
   
   saml.sp.keystore.aliasPassword - specifies the password for the alias name for the keystore file
    - This is a bit confusing since we are not using a separate password for the alias itself, just one for the keystore.  So here you just paste the same encrypted string as the one from the saml.sp.keystore.password key - in other words "Encrypted String #1".
   
   saml.idp.metadatafile.path - specifies the path for the metadata file by IDP
   - This value by default points to the default xml file to generate metadata. After the Azure Entra/SAML admins import the metadata, it will generate an XML output that they will provide to you - place this in the samlsso folder and point the relative path to it as follows:
    e.g.:  saml.idp.metadatafile.path=conf/samlsso/<(filename from SAML admins).xml
   
   
   
   
   
   
5. Activate the wasp probe 

 

An example of how the top section of samlssoConfig.properties should look after making the changes (based on the example values above) is as follows:

 

saml.configuration.enabled=true
saml.sp.metadata.id=ProductionOC
saml.sp.metadata.entityid=ProductionOC
saml.sp.keystore.path=conf/samlsso/keystore.jks
saml.sp.keystore.password=(Encrypted String #1)
saml.sp.keystore.aliasName=(Encrypted String #2)
saml.sp.keystore.aliasPassword=(Encrypted String #1)
saml.idp.metadatafile.path=conf/samlsso/federationmetadata_idp.xml