Troubleshooting Your SAML Single Sign-On Setup
SAML Single Sign-On (SSO) integration with Aphex streamlines access management by allowing your team to use existing identity provider credentials. If you're experiencing issues with your SSO configuration or want to prevent common problems, this guide covers the most frequent issues and their resolutions.
For step-by-step setup instructions, see our Setting up SAML SSO guide.
Common Issues and Questions
Some colleagues are still using email/password authentication while others SSO
Scenario: SSO has been enabled, but some team members continue to log in using email and password instead of being redirected to SSO.
Most likely cause: These colleagues have email addresses from domains that weren't included in your SSO configuration.
Why this happens: Only domains that have been verified as part of the SSO setup process will trigger enforced SSO workflows. Construction teams often use email aliases for joint venture projects or project-specific emails (e.g., [email protected] vs [email protected]). If the joint venture domain wasn't included when SSO was set up, those users won't be subject to SSO enforcement.
Resolution:
For administrators: Review which domains were registered during SSO setup. You can view and modify these settings in the Aphex admin console, or contact [email protected] to add any missing domains that should be subject to SSO.
End users getting "unauthorised" error from Microsoft/IdP after login attempt
Scenario: User attempts to log in, gets redirected to identity provider (e.g., Microsoft), but receives an "unauthorised" error screen.
Most likely cause: The user hasn't been assigned to the Aphex application in your identity provider.
Why this happens: For authentication to succeed, your identity provider needs to confirm both who the user is and that they have permission to access Aphex. This permission is controlled by application assignments within your IdP.
Resolution:
For end users: Contact your internal IT team to request access to the Aphex application
For administrators:
Log into your identity provider (e.g. Microsoft Entra, Okta)
Navigate to the Aphex enterprise application
Assign the user or their group to the application
Refer to step 4 in our Setting up SAML SSO guide for detailed instructions
Logging in with one email but accessing a different account
Scenario: User logs in with [email protected] but gets logged into an account for [email protected], or receives an error about the @company1.com account being unauthorised.
Most likely cause: The primary identifier returned by your identity provider differs from the email address the user is attempting to use for login.
Why this happens: When a user enters any email address from a domain configured for SSO, Aphex routes them to your identity provider. However, the identity provider returns its own primary identifier for that user (which might be their main corporate email), regardless of which alias they used to initiate login.
Resolution:
For End Users:
Check which email address your Aphex invitation was sent to - this indicates the account you should be accessing
Ask your administrator which email address was used when your account was set up
Use that primary email address for login
For administrators:
Review what identifier field is being mapped from your IdP to Aphex (user principal name, primary email, etc.) in the Aphex admin console
Ensure users understand which email address corresponds to their Aphex account
Consider whether the current mapping strategy aligns with how your users expect to access the system
If needed, you can adjust identifier mapping settings in the admin console or contact [email protected] for assistance
Last updated
Was this helpful?