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 User Format: Login was successful, but <username> is not set up as a user within Flywheel. Contact an administrator to get registered to the platform.
-
Institution Not Enabled: IdP <address> 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: The site administrators responsibility to ensure the adding of users that authenticate to their Flywheel site by way of external Identity Providers complies with their 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 login.flywheel.io 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 below will appear:
- Use the email in the message as the username when Creating a New User to 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.
1. Determine Username Format
If the error message, Login was successful, but <username> is not set up as a user within Flywheel. Contact an administrator to get registered to the platform appears, then one will need to add the user to Flywheel. 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 one will find the ePPN for a user by following the steps below:
-
The user should now 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 is not able to logon to Flywheel, then open a Flywheel support ticket and attach the User Attributes screenshot.
2. 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 <address> is not whitelisted. Contact an administrator to add your login provider.
To address this, follow Step 1: Contact Flywheel to Add the New Identity Provider