# Google Analytics

SAML Authentication (ADFS, Okta, Centrify, Azure AD)


Profile: samlsecurity

What is SAML2?

SAML stands for Security Assertion Markup Language and is used to provide Single-Sign-On (SSO) services to end users. It is used as a data exchange format between Service Providers (web applications that require their users to be authenticated) and Identity Providers (web applications that provide the required authentication). The iGrafx Platform acts as a Service Provider (SP) in this scenario, while your ADFS server or Okta instance acts as an Identity Provider (IDP).

Prerequisites

SAML2 authentication will only work if all involved SPs and IDPs are available via https. Follow the article about setting up SSL for your iGrafx Platform instance and make sure your IDP also uses https. All the users that are known to your IDP that require access to iGrafx Platform must be present in the iGrafx platform. Users can be added to iGrafx Platform either by connecting to an Active Directory or by manual or automated import of your users (the latter can be achieved through our REST API). If a user authenticates via SAML2 that is not known in the iGrafx Platform, the user will receive a permission denied error upon login.

Set up a SAML2 keystore

A keystore file samlKeystore.jks has to be placed in your iGrafx Base directory that is used to sign, verify IDP and SP metadata as well as SSL connections. The file is loaded once on iGrafx Platform service startup. For the iGrafx Platform to be able to sign SAML messages with a key, follow these steps:

  1. Create a new keystore file samlKeystore.jks with the private key you want to use by either
    1. Add your production-ready private key to the keystore by using the java keytool. Refer to http://docs.spring.io/spring-security-saml/docs/current/reference/html/security.html#configuration-key-management-private-keys on how to create, import and modify keys in the samlKeystore.jks file via the command line.

    2. Create a new keystore file with a new self-signed certificate with the following command (the keytool command is located in the bin directory of your Java installation:

      keytool -genkey -keyalg RSA -alias %KEYALIAS% -keystore samlKeystore.jks -storepass %KEYSTOREPASS% -validity 360 -keysize 2048

      Replace %KEYALIAS% and %KEYSTOREPASS% with an alias for your private key and the password for the newly created keystore, respectively. Follow the on-screen instructions and set a password for the private key at the end of the process

  2. Copy the samlKeystore.jks file into your base directory
  3. Open the igrafx.properties file in your base directory
  4. Uncomment (or add if not already present) the line igrafx.usercentral.saml.keystorepass= and append your keystore password
  5. Uncomment (or add if not already present) the line igrafx.usercentral.saml.defaultalias= and append the alias you used for the private key that you want to use to sign your metadata
  6. Uncomment (or add if not already present) the line igrafx.usercentral.saml.defaultpassword= and append the password you have used for the private key that you added to they keystore
  7. Restart the iGrafx Platform service.
  8. The Service Provider metadata file you download later in these instructions will now be signed with this private key. You might need to update the metadata in your respective Identity Provider if you have already uploaded your metadata file to an ADFS or other SAML IDP in the past.

How to set up SAML2 authentication

The configuration of 3rd party software i.e. Operating Systems, Databases, Application Server, etc., in the context of this documentation is for illustration purposes only. iGrafx doesn't imply that the provided examples are the best or only way of configuration for the described scenario. Nor can we guarantee that it is the best option for performance and security. You apply the instructions at your own risk, please consult an expert of the 3rd party software if you are not sure.

Microsoft ADFS Server

  1. Perform the SAML Keystore setup
  2. Change the authentication scheme to "samlsecurity" according to this article about changing the authentication schema.
  3. If you did not do so in Step 2 above, restart the iGrafx Platform service
  4. Log in to your iGrafx Platform via https (NOT HTTP!) and go to Administration -> User Management -> SAML
  5. Click DOWNLOAD SERVICE PROVIDER METADATA and save the spring_saml_metadata.xml file to your hard drive
  6. In AD FS 2.0 Management Console (in Control Panel - Administrative Tools) select "Add Relying Party Trust". Note: you may need to install Active Directory Federation Services.

  7. Select "Import data about the relying party from a file" and select the spring_saml_metadata.xml file you just downloaded. Click Next

  8. The wizard may complain that some content of the metadata is not supported. You can safely ignore this warning

  9. Enter a Display name and click Next
  10. Leave "I do not want to configure multi-factor authentication settings for this relying party trust at this time" checked and click Next
  11. Leave "Permit all users to access this relying party" checked and click Next
  12. On the "Ready to Add Trust" make sure that the tab "endpoints" contains multiple endpoint values. If not, verify that your metadata was generated with HTTPS protocol URLs

  13. Leave "Open the Edit Claim Rules dialog" checkbox checked and finish the wizard

  14. Select "Add Rule", choose "Send LDAP Attributes as Claims" and press Next

  15. Add NameID as "Claim rule name", choose "Active Directory" as Attribute store, choose "SAM-Account-Name" as LDAP Attribute and "Name ID" as "Outgoing claim type", finish the wizard and confirm the claim rules windowDownload your Identity Provider metadata from https://YOUR_ADFS_SERVER/FederationMetadata/2007-06/FederationMetadata.xml.

  16. Upload the IDP metadata FedeterationMetadata.xml file by going to Administration -> User Management -> SAML, and click UPLOAD IDENTITY PROVIDER METADATA.  Alternatively you can perform steps 1-3 of the below section "Remote Metadata"
  17. Download JCE Unlimited Policy and place the 2 jar files in your lib/security directory of your JDK or JRE. (see JCE Unlimited Policy section below)
  18. Restart the iGrafx Platform service
  19. You should now be forwarded to the ADFS login page when trying to access the iGrafx Platform

Support for SHA1 configuration can be forced if needed using the following settings in your igrafx.properties file (SHA256 configuration should still support SHA1 party trust configuration unless your devices do not support SHA256)

igrafx.usercentral.saml.signatureAlgorithm=SHA1


See also: ADFS Auto Creation of Authenticated Users

Okta

  1. Perform the SAML Keystore setup
  2. Change the authentication scheme to "samlsecurity" according to this article about changing the authentication schema.
  3. Restart the iGrafx Platform service
  4. Log in and go to Administration -> User Management -> SAML
  5. Click DOWNLOAD SERVICE PROVIDER METADATA and save the spring_saml_metadata.xml file to your hard drive
  6. Login to Okta as an administrator, select Admin, select Applications and click Create New App

  7. From the list of supported protocols select SAML 2.0 and press Create

  8. Define app name (e.g. iGrafx) and optionally define app image and press Next

  9. Configure SAML with the following settings:

    SettingValue
    Single Sign on URLhttps://yourinstance/saml/SSO
    Audience URI (SP Entity ID)Enter the value from the <md:EntityDescriptor entityID="???"> attribute of the spring_saml_metadata.xml file downloaded above
    Relay StateLeave blank
    Name ID formatUnspecified
    Application usernameSelect any of the available options, depending on your requirements.
    IMPORTANT: Make sure that the selected usernames will map to login names that exist in your iGrafx Platform
  10. Finish your Okta application creation
  11. Optional: Open your application configuration and go to the people page to configure custom username mappings
  12. Go to the Sign On tab in your Okta application configuration page and download the Okta Identity Provider metadata by clicking on the Identity Provider metadata link.
  13. Store the downloaded spring_saml_metadata.xml file as FederationMetadata.xml in your iGrafx Base directory or perform steps 1-3 of the below section "Remote Metadata".
  14. Restart the iGrafx Platform service
  15. You should now be forwarded to the Okta login page when trying to access the iGrafx Platform

Azure Active Directory

  1. Perform the SAML Keystore setup - make sure to start from the existing default Java Keystore "cacerts" in your JRE/lib/security folder, instead of creating a new, empty one
  2. Log in to your Azure account at https://portal.azure.com
  3. Search for the App Registration service in the left-hand panel. If it doesn't appear, use the More services button to look for it (and possibly favorite it by clicking the star)



  4. Click on Endpoints in the App registrations header




  5. Looking at the endpoint list, add the top URL (of the Metadata file) to your igrafx.properties file using the following line

    igrafx.usercentral.saml.metadataurl=YOUR_FEDERATION_METADATA_ENDPOINT_URL
  6. Close the endpoint Azure blade and click New registration



  7. Enter a name for your application registration that allows you to identify it (1), select the account types that can log in (2) and enter the HTTPS URL under which your installation will be available (3). Then press Register at the bottom



  8. On your new App registration click Add an Application ID URI  on the right side


  9. On the blade that now opens, click Set  to add a new Application ID URI



  10. Copy the autogenerated App ID URI from the properties panel (or set your own) (1) and click Save  (2)

  11. Paste the Application ID URI  you copied in the previous step into your igrafx.properties as described below

    igrafx.usercentral.saml.entityId=YOUR_APP_ID_URI
  12. To make sure that your email address will be used as your username, also add this line to the igrafx.properties file

    igrafx.usercentral.saml.nameId=EMAIL
  13. Change the authentication scheme to "samlsecurity" according to this article about changing the authentication schema.

  14. Restart your iGrafx Platform service

Centrify

  1. Perform the SAML Keystore setup
  2. Change the authentication scheme to "samlsecurity" according to this article about changing the authentication schema.
  3. Edit the igrafx.properties file to set your entity ID as described below in "Other options" to https://yourinstance/saml/metadata
  4. Restart the iGrafx Platform service
  5. Log in and go to Administration -> User Management -> SAML
  6. Click DOWNLOAD SERVICE PROVIDER METADATA and save the spring_saml_metadata.xml file to your hard drive
  7. Select the Custom tab and pick SAML, then confirm
  8. Go to the Application Settings area in your Centrify Web App and use Upload SP Metadata to upload the spring_saml_metadata.xml file generated by the iGrafx Platform
  9. Download the IDP metadata via the link Download Identity Provider SAML Meta data on the Centrify page and store it as FederationMetadata.xml in your base directory or perform steps 1-3 of the below section "Remote Metadata"
  10. Map the Centrify roles that are allowed to access the iGrafx Platform in the User Access area
  11. Restart your iGrafx Platform service

Remote Metadata

If you are using an IDP that changes its metadata from time to time (for example for rolling over signing keys), you can also point the iGrafx Platform to a metadata file in the web and have the platform download it automatically. To do that, follow these steps:

  1. Determine the URL your IDPs Metadata is stored at
  2. Edit the igrafx.properties file and add the line

    igrafx.usercentral.saml.metadataurl=YOUR_METADATA_URL
  3. If the metadata URL is HTTPS, which it usually is, you have to download the certificate for the respective website and import it into your SAML Keystore using the following command

    keytool -import -alias ALIAS_FOR_IDP -file YOUR_IDP_CERTIFICATE_FILE.cer -keystore samlKeystore.jks
  4. Restart the iGrafx Platform service (unless you are doing this as part of your initial setup - in this case simply ignore this step)

User Mapping

When the IDP authentication is successful, the IDP will forward the user to the iGrafx Platform and send a login name along with the authentication assertion. The user name depends on the IDP setup, but many online providers default to using the e-mail address. In that case, the login name of your users within the iGrafx Platform must be their e-mail address. It is not sufficient for the e-mail address field to be populated. If you want the platform login names to be something other than the e-mail address, you can set up your IDP to send a different user info field as the login name when performing a SAML authentication. The configuration depends on your IDP.

Other options

If you want to use the form-based login in parallel with SAML authentication, you can uncomment or add the property igrafx.usercentral.saml.locallogin=true in your igrafx.properties file in your base directory and restart your server. You can now use the login form at https://your-instance/Login to login using local authentication. This is also useful for debugging SAML authentication issues with a local user. We do NOT recommend this setup for production systems as users will be redirected to the login page at times, even if they authenticated via SAML before.

If you want to use a specific entity ID for your instance instead of the autogenerated one, uncomment or add the property igrafx.usercentral.saml.entityId=YOUR_ENTITY_ID to your igrafx.properties file and restart your server. Make sure to update your Identity Provider with the new metadata from your application afterwards.

If you server is available at multiple URLs or behind a proxy, it is sometimes useful to be able to determine the base URL for your entity. You can set the base URL (useful for redirect/POST artifact bindings) by adding the property igrafx.usercentral.saml.entityBaseUrl=URL_OF_YOUR_PLATFORM to your igrafx.properties file.

Should you want to enforce a specific NameID policy for the IDP, you can use the property igrafx.usercentral.saml.nameId. Possible values are:

  • unspecified (default)
  • entity
  • kerberos
  • windowsdomain
  • x509
  • email
  • persistent

JCE Unlimited Policy

In some cases, the encryption used by the Identity Provider or your private key might be stronger than the default JRE/JDK allows. If this is the case, issues with decrypting SAML messages or private keys might be resolved by installing the JCE Unlimited Jurisdiction Policy that is appropriate for your JRE/JDK version:

Download the files and place the two included JAR files in the lib/security directory of your JRE or JDK. Overwrite (and possibly back up) the existing policy files to allow stronger encryption mechanisms. A server restart is required after installing the new policy files.

Time Skew

Make sure that the server you are running the iGrafx Platform on has a time synchronization service running, so that there is no time difference between your IDP and your SP. If there is a time skew of more than 60 seconds between the two servers, authentication might fail even if the configuration is correct.

Debugging

To properly debug SAML authentication issues, go to Administration -> Support -> Logging Settings and set the Log level to DEBUG. Then uncheck Log All Classes and check Custom. Now enter the following into the custom logging class field:

org.springframework.security.saml;org.opensaml;PROTOCOL_MESSAGE

There could be a case where users may encounter a "Bad Request - Request Too Long" error appearing when opening their iGrafx Platform in the browser when using ADFS. Simply clear the browser cookie and login with ADFS credentials again.


This article contains