Adding Institutional Collaborators to Flywheel

Introduction

This document provides instructional steps to add a new identity provider, verify username format, and add users to the site. Site administrators can use Flywheel's CILogon integration to allow users from other institutions to sign in to the Flywheel site using their institution's credentials.

This document also includes additional Troubleshooting CILogon Issue Steps for the following errors:

• Determine Username Format: Login was successful, but \ is not set up as a user within Flywheel. Contact an administrator to get registered to the platform.
• Institution Not Enabled: IdP \
  is not whitelisted. Contact an administrator to add your login provider.

Flywheel Identity Management

The image below displays the relationship of the external Identity Providers (IdPs) that Flywheel uses for authentication.

Disclaimer: It is the site administrator's responsibility to ensure that users who authenticate by way of External Identity Providers comply with the institution’s security policies and procedures.

Instruction Steps

Step 1: Contact Flywheel to Add the Identity Provider

CILogon has over 4000 Identity Providers (IdPs) that are supported by CILogon; however, none are enabled on the site until they are manually added. This is single step per IdP, so an IdP should never have to be added twice. A list can be provided to Flywheel to add multiple IdPs.

To add a IdP:

• Verify that the institution is included in this list of supported Identity Providers. If it is not listed in the dropdown, one can seek other options such as provisioning a user account on the hosting institution or using an ORCID account. ORCID would also need to be added as an IdP in Flywheel. For ORCID guidance, follow the instructions in ORCID Accounts Configuring for Flywheel. In general, the list includes all the identity providers registered with InCommon, plus all the identity providers InCommon imports from eduGAIN.
• To add an Identity Provider to your site, create a ticket through the Zendesk Dashboard.

Step 2: Verify Username Format and Add the User to the Site

Once the new identity provider has been added, verify the expected format for the username:

• Instruct a user from the institution that was added to go to your site's URL and click CILogon. The user will be redirected to CILogon.
• Users should select their institution from the dropdown menu and click Log On.

• In order for the site admin to add an Institution, the user should provide an email for the record.
• ORCID users will need to follow ORCID Account Configuration for Flywheel.
• The user will be redirected to their institution's sign-in page. Once successfully signed in, the user will be redirected back to Flywheel. The following message will appear:

• Use the email in the message as the username when Creating a New User in Flywheel. The username is case-sensitive.
• The user should now be able to log onto Flywheel.

Tip: This username may differ from the user's email address because Flywheel uses the ePPN (eduPersonPrincipalName) field. If the email in the error message did not work properly, see the Troubleshooting CILogon section of this document.

Troubleshooting CILogon

The following steps provide assistance to a user if they experience an error logging into their Flywheel site after adding the user as described above.

Determine Username Format

If you see the following error message, then the user needs to be added to Flywheel.

Login was successful, but \ is not set up as a user within Flywheel. Contact an administrator to get registered to the platform.

If the user has already been added to Flywheel using their email address, then the username should be updated to use the username in the error. This is the user's eduPersonPrincipalName (ePPN). This name can be different from the users email address.

If the error is still present after adding the username from the error, then follow the steps below to find the ePPN for the user:

• Have the user navigate to https://authtest.flywheel.io.

• Click University Credentials via CILogon.
• Select the Institution from the dropdown list. The user will be redirected to the institution's sign in page.

Note: If the institution does not appear in the dropdown, contact Flywheel to enable it.

• After signing in successfully, the user will be redirected to the Flywheel Token Debugger page.

• Look for "https://flywheel.io/eppn". The value after is what should be entered for the username in Flywheel. All users added from the institution will follow this same format.
• The Site Administrator should confirm that the value matches the User ID for the added Flywheel user. If different than the user that was added, disable that user and add a new one with email matching ePPN value.
• If the user is still not able to logon to Flywheel, then open a Flywheel support ticket and attach the User Attributes screenshot.

Institution Not Enabled

The following error appears if an Institution is selected from the dropdown list that has not yet been enabled on your Flywheel site:

IdP \