There are several areas of the document labeled "[FIRST TIME]" to indicate what will happen the first time a user logs in via Globus and explains how to link an account. It would be clearer if there was a section on how to link a user's XSEDE identity to their Globus account.
On page 6 where a "custom skin" is described, the image shows "Login to use Jetstream Web App", however the previous examples use "Login to use XSEDE JIRA" which may lead to confusion as to whether or not the "Jetstream Web App" is part of the custom skin. We should use the same string where possible.
I think it would be useful to link a "First Time Login" document section from the main "XSEDE Single Sign-On" interface as well. Will this documentation live in the user portal?
Maybe revising the text above the button to be:
"You will be redirected to globus.org for XSEDE Web Single Sign-On when you click the button below. If this is your first time logging in, you may need to link your XSEDE identity to your Globus account."
This is probably a good idea in general. The last bit of text you suggest about linking isn't right, though. Specifically, the words "may need to" and "to your Globus account."
The only thing that the user needs in order to login to an app configured as described in this design is an XSEDE identity. In fact, they can start the login process *without having* an XSEDE identity and they'll be guided to the XSEDE registration page where they can sign up. Linking is never required.
There are two different linking scenarios:
1) If the user chooses to authenticate using a non-XSEDE identity (like their campus system or Google or ORCID or NIH), and they haven't previously linked their XSEDE identity to it, then Globus will tell the user that they have to authenticate to XSEDE and will take them to the XSEDE login page. At the XSEDE login page, the user can either login using an XSEDE ID/password, or register a new XSEDE account. Either way, they don't get back to the login flow until they have their XSEDE identity and have authenticated to it. When they get back to the login flow, Globus will offer to link the XSEDE identity to the one they originally authenticated as so they don't have to do that again.
2) If the user chooses to authenticate using XSEDE and it's the first time they've done that with Globus--bear in mind that logging into the XUP since January 2017 counts as authenticating to XSEDE using Globus!--then, once they've authenticated, Globus will ask if they want to link the XSEDE identity to one they've used before in Globus, or use the XSEDE identity on its own. If they choose not to link, then they're immediately logged in to the app.
In either scenario, if the user is given the option of linking and they choose to do it, Globus will ask them to authenticate to the identity they've used in Globus before. That could be a campus ID, ORCID, Google, DOE or NIH, or whatever. It *might* be a GlobusID, especially if they're a long-time Globus user. Once they've proven they can authenticate to that identity, the XSEDE identity will be linked to it.
Either way, the linking question never appears in the login flow until AFTER the user authenticates to XSEDE. At that point, unless they stop dead in their tracks and close their browser, they're effectively logged in and their XSEDE identity information will be returned to the application. They might be offered to link and they may or may not choose to, but either way, they're in.
Ok, turns out there is one scenario where the user ends up linking their accounts without being explicitly given an option. It begins in Scenario 1 above, where the user begins the whole process by using a non-XSEDE identity to login. If the user authenticates to, let's say, their campus authentication service, and they've never linked that identity to XSEDE before, then Globus will tell them they need to link their XSEDE identity before they can login to the application. It will take them to XSEDE to authenticate. (At this point, they can either authenticate to XSEDE or register a new XSEDE account.) Once they've authenticated to XSEDE, the XSEDE identity is linked to whatever identity they authenticated to first.
In the scenario you have presented here, if the non-XSEDE identity is NOT even present in a globus account currently, I have found that Globus will give the option of linking to an account that might already exist in Globus (say GlobusID). [THE FLOW DIAGRAM CURRENTLY DOESN'T REFLECT THIS.] After this is done (which is optional), then XSEDE linkup happens as you mentioned. v1.1 of the doc presents this scenario of 3 independent identities (Campus, GlobusID and XSEDE) coming together as this is the most common scenario for a researcher operating from a home campus and that has been active in XSEDE and Globus transfer services. v1.1 does list the simplistic case of just an XSEDE account as well. Thanks.
Perhaps a flow chart image at the beginning of the user guide that represents the login flow, and has links to appropriate user guide sections, would simplify what a user reads before using XSEDE Web Single Sign-On. That way they can follow steps based on whether or not it's their first login, they are authenticating with an XSEDE or non-XSEDE identity, etc. Even if it doesn't make sense to link an image to specific user guide sections, I think a visual representation of the login flow would be helpful (for me anyway!)
Lee, kindly put together a flow chart, that's now included in the design doc v1.1. Thanks, Lee.