SAML2 authentication (ADFS, Okta, Centrify)

Profile: samlsecurity

SAMLSAML An XML-based standard for exchanging authentication and authorization data between an identity provider and a service provider. Process360 Live supports SAML 2.0 for SSO. (Security Assertion Markup Language) provides single sign-on between service providers (applications that require authentication) and identity providers (applications that provide it). The iGrafx platform is the service provider (SP); your ADFS server, Okta instance, or similar is the identity provider (IdP).

Prerequisites

• HTTPS everywhere. SAMLSAML An XML-based standard for exchanging authentication and authorization data between an identity provider and a service provider. Process360 Live supports SAML 2.0 for SSO. works only if all SPs and IdPs are reachable over https. Set up SSL on your instance and make sure your IdP uses https too.
• Users present in the platform. Every IdP-known user who needs access must already exist in the platform — add them by connecting Active Directory or by importing them (including via the REST API). A user who authenticates via SAMLSAML An XML-based standard for exchanging authentication and authorization data between an identity provider and a service provider. Process360 Live supports SAML 2.0 for SSO. but isn't known to the platform gets a permission-denied error.

Steps

Set up a SAML2 keystore

A samlKeystore.jks file in your base directory signs and verifies IdP and SP metadata and SSL connections. It's loaded once at service startup.

1. Copy openjdk-11.0.x\lib\security\cacerts from your installation directory to igrafxdata\samlKeystore.jks to bootstrap the keystore with the existing Java certificate store. Use changeit for the keystore password when prompted (you can change it later).

2. Then either:

   • Add your production-ready private key with the Java keytool — see the Spring Security SAML key-management docs; or

   • Create a self-signed certificate (keytool is in your Java installation's bin directory):

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

     Replace %KEYALIAS% and %KEYPASS% with an alias and password for your private key. The command sets the key password and then prompts for a store password.

3. Copy samlKeystore.jks into your base directory.

4. In igrafx.properties in the base directory, set (uncomment or add) these, with your keystore password, the private-key alias, and the key password:

   igrafx.usercentral.saml.keystorepass=changeit
   igrafx.usercentral.saml.defaultalias=YOUR_KEY_ALIAS
   igrafx.usercentral.saml.defaultpassword=YOUR_KEY_PASSWORD

5. Restart the platform service. The SP metadata you download later is signed with this private key — if you've already uploaded SP metadata to an IdP, update it.

Set up the identity provider

Pick your IdP. Each procedure assumes you've completed the keystore setup above and activated the samlsecurity profile (see Configuring authentication).

Azure Active Directory

1. Complete the SAML keystore setup, starting from the existing cacerts keystore rather than an empty one.

2. Activate the samlsecurity profile and restart the platform.

3. Sign in to the Azure portal and open App Registration (use More services if it's not shown).

   

4. Select Endpoints in the App registrations header and copy the top URL (the metadata file).

   

5. In the platform, go to Administration → User Management → SAMLSAML An XML-based standard for exchanging authentication and authorization data between an identity provider and a service provider. Process360 Live supports SAML 2.0 for SSO., select Update Identity Provider Metadata, and add the metadata URL. Set the Name ID policy to Email.

6. Back in Azure, close the endpoint blade and select New registration.

   

7. Enter a name, select the account types that can sign in, and enter the HTTPS URL where your installation is available, then Register.

   

8. On the new registration, select Add an Application ID URI.

   

9. Select Set to add a new Application ID URI.

   

10. Copy the autogenerated App ID URI (or set your own) and Save.

    

11. Set the App ID URI in igrafx.properties, then restart the platform:

    igrafx.usercentral.saml.entityId=YOUR_APP_ID_URI

Microsoft ADFS Server

1. Complete the SAML keystore setup.
2. Activate the samlsecurity profile and restart the platform.
3. Sign in over HTTPS and go to Administration → User Management → SAMLSAML An XML-based standard for exchanging authentication and authorization data between an identity provider and a service provider. Process360 Live supports SAML 2.0 for SSO..
4. Click Download Service Provider Metadata and save spring_saml_metadata.xml.
5. In the AD FS 2.0 Management Console, select Add Relying Party Trust (you may need to install Active Directory Federation Services).
6. Select Import data about the relying party from a file and select spring_saml_metadata.xml, then Next. You can ignore a warning that some metadata content isn't supported.
7. Enter a display name and continue. Leave multi-factor authentication unconfigured, and Permit all users to access this relying party.
8. On Ready to Add Trust, confirm the Endpoints tab has multiple endpoints — if not, regenerate your metadata with HTTPS URLs.
9. Leave Open the Edit Claim Rules dialog checked and finish.
10. Select Add Rule → Send LDAP Attributes as Claims → Next. Name the rule NameID, choose Active Directory as the attribute store, E-Mail-Addresses as the LDAP attribute, and Name ID as the outgoing claim type. Finish and confirm.
11. Download your IdP metadata from https://YOUR_ADFS_SERVER/FederationMetadata/2007-06/FederationMetadata.xml.
12. In Administration → User Management → SAMLSAML An XML-based standard for exchanging authentication and authorization data between an identity provider and a service provider. Process360 Live supports SAML 2.0 for SSO., select Update Identity Provider Metadata and upload it.
13. Download the JCE Unlimited policy and place the two JAR files in your JRE/JDK lib/security directory (see JCE Unlimited policy).
14. Restart the platform. You should now be forwarded to the ADFS login page.

To force SHA1 (SHA256 still supports SHA1 trusts unless your devices don't support SHA256), add:

igrafx.usercentral.saml.signatureAlgorithm=SHA1

info

If you see "Bad Request - Request Too Long" opening the platform with ADFS, clear the browser cookie and sign in again.

For automatically creating authenticated users, see ADFS auto-creation of authenticated users.

Okta

1. Complete the SAML keystore setup, activate the samlsecurity profile, and restart the platform.

2. Go to Administration → User Management → SAMLSAML An XML-based standard for exchanging authentication and authorization data between an identity provider and a service provider. Process360 Live supports SAML 2.0 for SSO., click Download Service Provider Metadata, and save spring_saml_metadata.xml.

3. In Okta as an administrator, open Applications → Create New App, select SAMLSAML An XML-based standard for exchanging authentication and authorization data between an identity provider and a service provider. Process360 Live supports SAML 2.0 for SSO. 2.0, and Create.

4. Name the app (for example iGrafx) and continue, then configure SAMLSAML An XML-based standard for exchanging authentication and authorization data between an identity provider and a service provider. Process360 Live supports SAML 2.0 for SSO.:

   Setting	Value
   Single Sign-on URL	https://yourinstance/saml/SSO
   Audience URI (SP Entity ID)	The value from the <md:EntityDescriptor entityID="???"> attribute of the downloaded spring_saml_metadata.xml
   Relay State	Leave blank
   Name ID format	Unspecified
   Application username	Any available option — make sure the usernames map to login names that exist in the platform

5. Finish creating the app. Optionally, configure custom username mappings on the app's People page.

6. On the app's Sign On tab, download (or copy the URL of) the Okta IdP metadata.

7. In Administration → User Management → SAMLSAML An XML-based standard for exchanging authentication and authorization data between an identity provider and a service provider. Process360 Live supports SAML 2.0 for SSO., select Update Identity Provider Metadata and provide the URL or file.

8. Test by going to your application's base URL and selecting Sign-in via SSOSSO An authentication scheme that lets users sign in once with an identity provider and access Process360 Live without re-entering credentials..

9. Restart the platform to disable the login form. You should now be forwarded to the Okta login page.

Centrify

1. Complete the SAML keystore setup and activate the samlsecurity profile.
2. In igrafx.properties, set the entity ID (see Other options) to https://yourinstance/saml/metadata, then restart the platform.
3. Go to Administration → User Management → SAMLSAML An XML-based standard for exchanging authentication and authorization data between an identity provider and a service provider. Process360 Live supports SAML 2.0 for SSO., click Download Service Provider Metadata, and save spring_saml_metadata.xml.
4. In your Centrify web app, select the Custom tab, pick SAMLSAML An XML-based standard for exchanging authentication and authorization data between an identity provider and a service provider. Process360 Live supports SAML 2.0 for SSO., and confirm.
5. In Application Settings, use Upload SP Metadata to upload spring_saml_metadata.xml.
6. In Administration → User Management → SAMLSAML An XML-based standard for exchanging authentication and authorization data between an identity provider and a service provider. Process360 Live supports SAML 2.0 for SSO., select Update Identity Provider Metadata and provide the URL or file.
7. In User Access, map the Centrify roles allowed to access the platform.
8. Restart the platform.

Remote metadata

If your IdP changes its metadata over time (for example, rolling signing keys), point the platform at a metadata URL it downloads periodically:

1. In Administration → User Management → SAMLSAML An XML-based standard for exchanging authentication and authorization data between an identity provider and a service provider. Process360 Live supports SAML 2.0 for SSO., select Update Identity Provider Metadata and add the metadata URL.

2. If the URL is HTTPS (usually), you may need to import its certificate into the keystore:

   keytool -import -alias ALIAS_FOR_IDP -file YOUR_IDP_CERTIFICATE_FILE.cer -keystore samlKeystore.jks

3. Restart the platform if you added a certificate.

The platform downloads the metadata from the URL again every 30 minutes, so an IdP change such as a rotated signing certificate takes effect without a restart. If a scheduled download fails, the platform keeps the metadata it last loaded successfully and logs a warning. Metadata uploaded as a file isn't reloaded — upload the new file to apply a change. To change the interval, set the igrafx.usercentral.saml.metadatarefreshinterval system property — see Advanced configuration.

User mapping

On successful authentication, the IdP forwards a login name with the assertion. Many providers default to the email address — in that case, each user's platform login name must be their email address (it's not enough for the email field to be populated). To use a different login name, configure your IdP to send a different field. The configuration depends on your IdP.

Other options

Set these in igrafx.properties in the base directory and restart the server:

• igrafx.usercentral.saml.locallogin=true — keep the form-based login alongside SAMLSAML An XML-based standard for exchanging authentication and authorization data between an identity provider and a service provider. Process360 Live supports SAML 2.0 for SSO., at https://your-instance/Login. Useful for debugging with a local user. Not recommended in production, since users are sometimes redirected to the login page even after authenticating via SAMLSAML An XML-based standard for exchanging authentication and authorization data between an identity provider and a service provider. Process360 Live supports SAML 2.0 for SSO..
• igrafx.usercentral.saml.entityId=YOUR_ENTITY_ID — use a specific entity ID instead of the autogenerated one. Update your IdP with the new metadata afterward.
• igrafx.usercentral.saml.entityBaseUrl=URL_OF_YOUR_PLATFORM — set the base URL when your server is reachable at multiple URLs or behind a proxy (useful for redirect/POST artifact bindings).
• igrafx.usercentral.saml.nameId — enforce a specific NameID policy. Values: unspecified (default), entity, kerberos, windowsdomain, x509, email, persistent.

JCE Unlimited policy

If the IdP's or your private key's encryption is stronger than the default JRE/JDK allows, decryption of SAMLSAML An XML-based standard for exchanging authentication and authorization data between an identity provider and a service provider. Process360 Live supports SAML 2.0 for SSO. messages or private keys can fail. Install the JCE Unlimited Jurisdiction Policy for your JRE/JDK version, placing the two JAR files in lib/security (back up and overwrite the existing policy files), then restart the server:

• JRE7/JDK7
• JRE8/JDK8

Time skew

Run a time-synchronization service on the platform server so there's no time difference between the IdP and SP. A skew over 60 seconds can fail authentication even with correct configuration.

Debugging

In Administration → Support → Logging Settings, add these classes at DEBUG level to your custom logging configuration:

• org.springframework.security.saml2 — version 20.0.0 and later. On earlier versions, use org.springframework.security.saml instead.
• org.opensaml
• PROTOCOL_MESSAGE

Related

• Update your SAML SSO configuration after upgrading to 20.x
• Configuring authentication
• ADFS auto-creation of authenticated users
• Setting up SSO via an Azure AD enterprise application