Scope Note: This documentation covers authentication (via Single Sign-On) for users of the PTV OptiFlow web applications. It does not cover authentication for the PTV OptiFlow API.

Single Sign-On (SSO)

Single Sign-On (SSO) enables your users to authenticate using your organization's existing Identity and Access Management (IAM) solution rather than creating and managing separate credentials in the PTV OptiFlow system. This integration streamlines the user experience and enhances security by centralizing authentication within your own IAM platform while still providing seamless access to PTV OptiFlow.

How SSO for PTV OptiFlow works

When a user attempts to log in to PTV OptiFlow, they are first asked to enter their email address.

This step is necessary for all users, as the system uses the email domain to determine the appropriate authentication method:

• If SSO has been set up for your organization and the user enters an email address with a domain linked to your organization, they will be redirected to your IAM solution to complete authentication.
• If SSO has not been configured for the email domain, the user will be prompted to enter their PTV OptiFlow password.

OpenID Connect (OIDC)

If you want to set up an SSO integration with PTV OptiFlow, please note that we only support the OAuth 2.0 - OpenID Connect protocol. Here's a high-level visual representation of the authentication flow:

Authorization

All users who can successfully authenticate through your OAuth 2.0/OIDC client will have access to PTV OptiFlow.

Spaces

A "space" in PTV OptiFlow represents a logical group of users who can collaborate on the same data (plannings, orders, etc.) while maintaining data isolation from other users.

In multi-tenant architecture terms, a space is typically called a tenant.

Whether your organization is using a single space or multiple spaces, there are some rules that always apply.

Email domains are tied to a single space when using SSO

If acme.com is linked to the ACME space, then users like john@acme.com and jane@acme.com can only access that space.

They can’t use the same email addresses to access other spaces (e.g., ACME_TEST).

Multiple email domains can be linked to the same space when using SSO

You can link multiple email domains (e.g., acme.com and acme.eu) to a single space, so users like john@acme.com and jane@acme.eu can both access the ACME space.

Using SSO when your organization has multiple spaces

One SSO integration per space

If your organization has multiple OptiFlow spaces, each space requires its own SSO integration, mapped to one or more unique email domains.

For example, if you have:

• division-a.acme.com linked to space ACME_DIVISION_A
• division-b.acme.com linked to space ACME_DIVISION_B

Then:

• john@division-a.acme.com logs into space ACME_DIVISION_A
• jane@division-b.acme.com logs into space ACME_DIVISION_B

Users from one division cannot access the other’s space.

⚠️ Your IAM solution must return the correct domain-specific email (e.g., john@division-a.acme.com) in the ID token. If it returns a generic address like john@acme.com, the user won't be able to log in to OptiFlow.

Mixing SSO-enabled spaces and spaces without SSO

If not all spaces can use SSO, users can log in to non-SSO spaces using PTV OptiFlow accounts with credentials managed by the PTV OptiFlow IAM solution.

To avoid triggering SSO login, these accounts must use email addresses with domains not linked to any SSO integration.

You can achieve this by:

• Using an alternative email address with a domain not linked to any SSO integration.
• Using email sub-addressing (if supported by your email provider). Emails with a + in the local part (e.g., john+test@acme.com ) won’t trigger SSO—even if the domain is linked.

For example, if ACME_PRODUCTION uses SSO on acme.com and John needs access to ACME_TEST (non-SSO), he can request an account using john@acme.eu or john+test@acme.com.

ℹ️ Info: Disabling SSO for email sub-addresses is opt-in but can easily be enabled upon request.

Users that need access to multiple spaces

Users that need access to multiple spaces will need a PTV OptiFlow account per space. Whether all those accounts can use SSO depends on how many SSO integrations with PTV OptiFlow your IAM solution supports.

If a user needs to access multiple spaces via SSO, each space must have its own SSO integration linked to a unique domain. Your IAM solution must return an email address that matches the domain of the target space in the ID token.

Example:

• space ACME_PRODUCTION uses SSO on acme.com
• space ACME_TEST uses SSO on test.acme.com

To access ACME_PRODUCTION, John logs in with john@acme.com. To access ACME_TEST, he uses john@test.acme.com. In both cases, the email address in the ID token must match accordingly.

If multiple SSO integrations aren’t possible or desired, users can still access other spaces using non-SSO accounts.

Getting started with SSO

To get started with SSO, contact your PTV Logistics representative to request SSO integration.

If already known, please include the following information as well:

• the space for which to set up the SSO integration
• the email domain(s) to be linked to the SSO integration
• whether SSO needs to be disabled for email addresses with sub-addressing
• whether to enable SSO only for a subset of the "test" users (e.g., when requesting to set up SSO in an existing non-SSO space)
• the default language for users when they first log in

When your request to set up SSO is clear, we'll provide you with the redirect URI needed for your OAuth 2.0/OIDC client.

Note that our IAM system expects the sub, email, and name claims to be present in the ID token. The email address included in the ID token must match one of the domains linked to this SSO integration.

After you have created the necessary OAuth 2.0/OIDC client in your IAM solution, share the client ID and secret with us along with the OpenID Connect Metadata Document endpoint. Please use a secure channel when sharing this information.

Once we have received all the necessary information, we'll activate the SSO integration at the agreed-upon time and date.

Troubleshooting

If users encounter issues with SSO authentication:

1. Check that the user trying to log in to PTV OptiFlow is using an email address whose domain has been configured for SSO.
2. Check that your IAM solution allows the user to log in to PTV OptiFlow via your OAuth 2.0 client.
3. Check that your OAuth 2.0 client configuration matches the settings provided by PTV Logistics.
4. Contact PTV Logistics support for further assistance.