Identity Federation Integration Guide
Overview on how to configure an identity federation integration with Roundtrip.
This article lays out an implementation guide for onboarding your organization to Roundtrip’s Single Sign On capabilities. Below, you’ll find an overview of the functionality afforded by Roundtrip’s Single Sign On capability, as well as a high level overview of technical requirements for each of the identity providers that Roundtrip supports.
If you have specific questions about your organization’s identity provider, we recommend contacting the support team of that identity provider directly for assistance.
How Does an Identity Federation Integration Work?
Roundtrip uses Auth0 as our identity platform to facilitate Single Sign On. When Single Sign On is active, the workflow is as follows:
- The user opens the Roundtrip home page at https://app.rideroundtrip.com.
- On the login screen, the user enters their email address.
- After entering their email address, Roundtrip recognizes the domain as one where federation is active, and redirects the user to the organization’s identity provider login sequence.
- The user completes the login sequence.
- The user is redirected to the Roundtrip dashboard page.
Authorization Management
Access to Roundtrip is governed by your organization’s identity manager. You will need to plan to create one or more access groups in your identity manager to limit access to appropriate users.
Users will be created in Roundtrip upon their first login. There are two approaches to handling control of Roundtrip application permissions:
Basic FIM
By default, all users will be given the same role (i.e. a Care Coordinator role for Health System and Health Plan organizations, a Dispatcher role for Transportation Partners). When a new user is provisioned, that account will by default be authorized for all groups within the organization.
An Admin Care Coordinator can make the following permissions changes to user accounts within the Roundtrip application:
- Restrict a Care Coordinator user’s access to only certain groups within the organization
- Turn on the Limited Access feature, which restricts the user’s ability to book rides.
Need assistance with granting Admin access to a user? Please reach out to the Client Services Team at Roundtrip if a new user needs to be elevated to the Admin Care Coordinator role.
Advanced FIM
Your organization will work closely with Roundtrip to define how access will be granted. In general, Roundtrip will expect your organization to define the following:
- A claim in the identity record that corresponds to the Roundtrip roles:
- Care Coordinator
- Admin Care Coordinator
- Dispatcher (applicable only for Transportation Partners or Health System/Health Plan organizations with internal fleets)
- A claim in the identity record that will correspond to Roundtrip’s Limited Access permission
- Access group membership(s) that correspond to the organization structure that is setup in Roundtrip for your organization.
An example of this mapping follows below - in this example, St. Active of Directory Hospital has three departments underneath it - Oncology, Emergency Department, and Neurology:
Roundtrip Structure | Identity Manager |
St. Active of Directory (cascades access to all groups underneath) | RT_FULL |
Oncology | RT_ONCOLOGY |
Emergency Department | RT_ED |
Neurology | RT_NEURO |
Let’s say that we’ve just hired a new case manager for the Oncology department, who just needs to book rides for patients. In the identity manager, they’ll need to be provisioned with the role of Care Coordinator, and membership in the RT_ONCOLOGY access group. When this is done, when the new case manager logs into Roundtrip, the Roundtrip application will refer to the data sent in the SSO transaction to authorize this new case manager with permissions appropriately.
Alternatively, let’s say that we have a new director of case management. This new director will want to see everything that’s going on with transportation at St. Active of Directory Hospital. In the identity manager, they’ll need to be provisioned with the role of Admin Care Coordinator, and membership into the RT_FULL group. This group will give the new director cascaded permissions to see all three departments at St. Active of Directory Hospital.
.png?table=block&id=b5585317-a317-4bd5-acc3-80c298c9215b&cache=v2)
Supported Identity Providers and How to Configure
Roundtrip’s Single Sign On capability supports the following identity providers:
- Auth0
- Okta
- Microsoft Entra ID (formerly known as Azure Active Directory)
- Microsoft Active Directory (ADFS/LDAP)
- Google Workspace
- Ping Federate
- Any identity provider that can generate SAML
- Any identity provider that supports OpenID Connect
For each identity provider, Roundtrip will need to exchange certain pieces of data. These data points are provided below.
SAML
In order to onboard a SAML integration, Roundtrip will need the following data:
- The organization’s sign in URL
- A signing certificate
- If Single Logout functionality is desired, the Sign Out URL
- The user ID attribute
Roundtrip will return a URL where the Roundtrip SSO metadata can be accessed, as well as the endpoint URL that SAML tokens should be sent to.
When implementing SAML, we will need the following claims:
- First Name (given_name)
- Last Name (family_name)
- Email address (email) - this is the unique identifier
SAML Optional Rider Context
If the source identity provider is capable of including an identifier for a rider (e.g. a Medical Record Number), Roundtrip offers the capability of single sign on including patient context. In this flow, the source identity provider would initiate the SSO. The patient identifier should be included in the attribute statements of the SAML Payload.
The Attribute name should be produced as follows:
<saml:AttributeStatement xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <saml:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/patientidentifier" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"> <saml:AttributeValue xsi:type="xs:string"> {Rider Identifier goes here} </saml:AttributeValue> </saml:Attribute>
OpenID Connect/Auth0/Okta
In order to onboard an OpenID Connect integration, Roundtrip will need the following:
- Issuer URL
Roundtrip can be reached at this URL:
https://login.rideroundtrip.com/login/callback
Microsoft Entra ID / Azure Active Directory
In order to onboard an Entra ID integration, Roundtrip will need the following data:
- The organization’s Entra ID domain
- Client ID
- Client Secret
Please ensure that the following settings are active:
- Extended Profile
- Users > User.Read
- Directory > Directory.Read.All
Roundtrip can be reached at this URL:
https://login.rideroundtrip.com/login/callback
Active Directory ADFS
Roundtrip will need the domains that correspond to the organization, and the ADFS URL.
Roundtrip’s Realm Identifier is:
urn:auth0:roundtrip
Roundtrip’s endpoint URL is:
https://login.rideroundtrip.com/login/callback
Active Directory LDAP
In order to set up LDAP, an organization must install the Auth0 LDAP connector. More information can be found at Auth0’s support site here:
Google Workspace
In order to set up a Google Workspace Connection, the following will need to be provided from the organization:
- The Google Workspace Domain
- Client ID
- Client Secret
Roundtrip’s authorized JavaScript origin is:
https://login.rideroundtrip.com
Roundtrip’s endpoint URL is:
https://login.rideroundtrip.com/login/callback
Ping Federate
In order to set up a Ping Federate connection, the following will need to be provided from the organization:
- The PingFederate Server URL
- An X509 Signing Certificate
Roundtrip’s endpoint URL is:
https://login.rideroundtrip.com/login/callback