Update your SAML SSO configuration after upgrading to 20.x
Release 20.x modernizes how the platform processes 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. sign-ins, and the new framework validates 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 more strictly than before. Most identity provider (IdP) configurations keep working unchanged, but a small number of setups that worked on 19.x need an update on the IdP side. Review your IdP configuration against this page when you upgrade, and keep the page available to your identity team in case sign-in issues appear afterward.
Prerequisites
- Your users sign in to the platform 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. 2.0 (the
samlsecurityprofile, set up as described in SAML2 authentication). Installations using form-based login are not affected. - You can change the iGrafx application's configuration at your IdP.
Steps
Re-import the service provider metadata
After the upgrade, the platform publishes updated service provider (SP) metadata at https://<your-server>/saml/metadata (also available via 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. → Download Service Provider Metadata). Everything endpoint-related — URLs and bindings — is contained in that document, so this is the fastest first step:
- Download the SP metadata from the upgraded platform.
- If your IdP supports importing SP metadata, re-import it. Otherwise, update the IdP's configured URLs and bindings to match the metadata exactly.
The metadata continues to declare the signing requirements and the supported NameID formats, so IdPs that derive those settings from metadata keep their previous behavior. Some IdP settings are never derived from metadata — verify those manually, as described in the remaining steps.
Verify the response binding is HTTP-POST
The platform now supports only the HTTP-POST and HTTP-Redirect bindings; the HTTP-Artifact binding is no longer supported and no longer appears in the SP metadata.
If your IdP delivers the 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. response with the Artifact binding, SSOSSO An authentication scheme that lets users sign in once with an identity provider and access Process360 Live without re-entering credentials. fails immediately after authentication at the IdP and no session is established. Change the binding for the iGrafx application at your IdP to HTTP-POST — some IdPs treat the binding as a manual setting rather than deriving it from the imported metadata.
Verify the endpoint URLs match the metadata exactly
Make sure the SSOSSO An authentication scheme that lets users sign in once with an identity provider and access Process360 Live without re-entering credentials. / Recipient / Destination URLs configured at your IdP match the values in the SP metadata character for character. In particular, don't write default ports explicitly — the metadata publishes the URLs without :443.
You need to make changes only when the URLs configured at your IdP differ from the metadata — typically a hand-typed URL with an explicit :443. IdPs that validate the URL in the platform's sign-in request as an exact string then reject the request: the IdP shows an error such as HTTP 400 — Bad 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. Request before the sign-in page appears, and nothing appears in the platform's logs.
Either correct the URLs at the IdP, or set the igrafx.usercentral.saml.entityBaseUrl property so the platform's request matches the IdP's configured value (for example, https://your-server:443). If the failure persists after aligning the URLs, capture a 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. traceTrace The ordered sequence of activities executed for a single case. Grouping cases by identical traces produces variants. or HAR recording of the failed sign-in and contact iGrafx support.
Update the Single Logout URL
The Single Logout (SLO) endpoint moved from /saml/SingleLogout to /logout/saml2/slo, and only the HTTP-POST binding is supported for it (the Redirect binding for SLO was dropped). SLO is active only when a signing keystore is configured, since logout requests must be signed.
If you use 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. Single Logout, update the SLO URL for the iGrafx application at your IdP to https://<your-server>/logout/saml2/slo with the HTTP-POST binding. The current value is published in the SP metadata.
Verify the NameID format
The NameID is the identifier in the assertion — typically the user's email address — that the platform uses to match the sign-in to a platform user account. If user matching changes after an IdP-side reconfiguration, verify the NameID format configured for the iGrafx application at the IdP. The platform can also request a specific format explicitly via the igrafx.usercentral.saml.nameId property; see Other options. The default, unspecified, leaves the choice to the IdP.
Verify
Sign in to the platform via SSOSSO An authentication scheme that lets users sign in once with an identity provider and access Process360 Live without re-entering credentials. with a test user, then sign out. If sign-in fails, work through the Troubleshooting section below.
What hasn't changed
- The platform signs its sign-in requests whenever a signing keystore is configured, regardless of what your IdP's metadata requests.
- The IdP must sign the 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. response, the assertion, or both. A completely unsigned response is rejected, exactly as before.
Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| The IdP shows an error such as "400 Bad 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. Request" before sign-in | The IdP validates the platform's request URL as an exact string and it doesn't match | Align the endpoint URLs |
| Sign-in fails immediately after authenticating at the IdP; the IdP uses the Artifact binding | The Artifact binding is removed | Re-import the metadata and switch the binding to HTTP-POST |
| Sign-in loops back to the IdP or the login screen | Endpoint URL mismatch between the IdP and the platform | Re-import the metadata and align the endpoint URLs |
| Users are no longer matched, or matched to the wrong account, after IdP-side changes | The NameID format changed at the IdP | Verify the NameID format |
| Single logout stopped working | The SLO endpoint moved | Update the Single Logout URL |
For any failing sign-in, the most useful artifacts to attach to a support ticket are a browser HAR recording of the failed sign-in, a 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.-tracer capture, and the decoded 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. response from the 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. debug loggers — see Debugging. Remove the loggers afterward — the output contains user identity data.
Emergency access if SSO is broken
If SSOSSO An authentication scheme that lets users sign in once with an identity provider and access Process360 Live without re-entering credentials. fails after upgrading and no immediate resolution is available:
- Restore access for your users in one of two ways:
- Recommended: collect the diagnostics from step 2 first, then roll back to the previous version using your backups, as outlined in the upgrade guide.
- Alternatively, keep running 20.x and enable local form login as a fallback: set
igrafx.usercentral.saml.locallogin=trueinigrafx.propertiesand restart the platform service. 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. stays the default sign-in method, but the login form athttps://<your-server>/Loginstays reachable so administrators and local users can sign in while you resolve the SSOSSO An authentication scheme that lets users sign in once with an identity provider and access Process360 Live without re-entering credentials. issue.
- Collect diagnostics: enable the SAML debug loggers and capture a HAR recording of a failed sign-in.
- Contact iGrafx support with the diagnostics, your IdP product and version, and the SP metadata your IdP currently has configured.