Introduction

Pathwright integrates with external authentication systems via the SAML 2.0 and OpenID Connect protocols. In practice, this allows your school members to sign in with their credentials for other authentication services such as Google Suite, Microsoft Active Directory, Auth0, or other custom integrations.

When logging in via a single sign-on implementation, the user will be redirected to your organization's login pages to authenticate their Pathwright session. In addition, Pathwright maintains links to your external database and automatically updates user profile information when it changes on the identity server.

Prerequisites

• Your organization must have an authentication system in place that has support for one of the following standard web-based SSO protocols:
  • SAML 2.0
  • OpenID Connect
• At the very least, your user database must store a unique email address, as well as a first and last name for each user.

Considerations

• Standard login via Pathwright authentication servers can remain enabled by default, or can be disabled upon request.
• REST API endpoints for updating user information for SSO-linked users on demand are in beta. Contact Pathwright support if you have any interest in using these APIs as part of your SSO integration.
• Pathwright uniquely identifies users in an SSO integration by the unique ID the SSO server sends us. For some identity providers, this may be an email address, which has the potential to change for a given user. As a result, we recommend configuring your SSO integrations to use another means of uniquely identifying the user within the SSO authentication process.
  • In SAML2, this unique ID is called a "name ID". In OpenID Connect, the unique ID is reported as the "sub" claim of the token.

How SSO works

When a user begins to sign into Pathwright via an external identity provider, they will be redirected to your authentication service to sign in. Pathwright receives a response from the authentication server either allowing or denying the authentication request based on user permissions.

All Pathwright users are uniquely identified by an email address, however for SSO, this email address can be updated by your SSO integration automatically, so long as the unique ID provided by the SSO integration is not the email address. This means that for SSO integrations, Pathwright's platform uses the unique identifier from your identity provider to complete the authentication process.

When the authentication process is complete, Pathwright uses the unique identifier for the user that is provided by your authentication server to locate the correct user to sign into. At this time, any user profile information such as name and email will be updated on Pathwright if the attributes reported by the identity provider are different from those stored in Pathwright. If a user does not exist on Pathwright for the external user in your database, a new Pathwright user is created with the email address reported by the identity provider.

Afterward, the user authentication process is complete, and the user will receive access to your school.

Implementation outline

• SSO implementation is a two-way process, requiring configuration on both Pathwright and your organization's servers.
• A technical contact will be asked to provide links to configuration and/or SSO protocol metadata to aid in the setup process. These documents are usually generated automatically by software supporting our supported protocols.
• We can map other attributes from users in your database to profile attributes in Pathwright. Let us know if this is something you may be interested in.
• After configuration is complete with your organization's authentication servers and Pathwright's servers, we will test our SSO integration.
  • Generally, this process will go faster if we have a test account in your database that we can sign into your authentication server with.