Need design for how GitHub user and org will get configured via Global Settings

[chirino]

Eventually the git hub oauth info should be configurable via the global settings page. We could leverage the oauth settings for the client id/secret.. but I think we need a place in the global settings to configure the access tokens via an oauth flow and and the organization that the git projects will be created under.

[chirino]

@rhuss @jimmidyson what do you guys think? Is this some thing we want somewhere in global settings?

[sjcox-rh]

Is this something that will be done as part of the first time user experience? Or something they can do on their own time as they use the product?

On Wed, Aug 2, 2017 at 2:46 PM, Hiram Chirino notifications@github.com wrote:

@rhuss https://github.com/rhuss @jimmidyson https://github.com/jimmidyson what do you guys think? Is this some thing we want somewhere in global settings?

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/syndesisio/syndesis-ux/issues/29#issuecomment-319762839, or mute the thread https://github.com/notifications/unsubscribe-auth/APgSBPH0E_EdxwCeDwZwViowBt1kFmzaks5sUMQSgaJpZM4Orfb5 .

-- Sarah Jane Cox User Interaction Designer User Experience Design Team

Red Hat, Inc. http://www.redhat.com/about/whoisredhat/redhatstories.html?intcmp=70160000000TB9vAAG&

[chirino]

It should be part of the first time user experience. But I think its something that should be editable later.

[rhuss]

I agree that we should have some global configuration section for GitHub related configuration like the target GitHub organization (with a default on the currently connected GitHub user as authenticated in the initial flow) so that its clearer where integration projects are created.

Whether we want to expose the GitHub OAuth application which is used to access the GitHub API should be exposed in the UI, I'm not sure about. For the hosted version we probably don't want to expose it, as it is part of the Syndesis setup which should not be changed (it's a single GitHub application that we use for all Syndesis Installations on OSO, right ?). I would be perfectly fine if the GitHub setup is only part of the template instantiation.

[dongniwang]

@chirino @rhuss So do we still need design for GitHub config. in global settings?

If we do, here are a few questions:

• Is the current design (with the expandable list view) sufficient? Or we need a whole different tab for handling GitHub configuration?
• For the configurable fields, what should be included?
  • Team/Org account, user account
  • Project location/address
  • Access token (are we just storing this? or pointing users to GitHub to obtain access token?)

[dongniwang]

@kcbabo @chirino @rhuss @gashcrumb @sjcox-rh

FYI. We actually have this issue for creating GitHub config in global setting page. Please check and let me know if anything changes. Thanks!

[kcbabo]

This looks right to me. I won't bother filing a duplicate issue then.

[dongniwang]

Just wanted get some initial feedback on the designs, now they live in InVision: GitHub Settings

I'll put up a PR tomorrow (having issues with SourceTree right now).

[kcbabo]

Looks good to me. I'm not sure how much of step 1 is technically possible, but I'm sure Roland et al. can provide insight there.

[rhuss]

@dongniwang thanks for the design, looks really good.

Some remarks (and possibly answers to your questions):

• Authentication is already done via OpenShift (so when already connected to the user's OpenShift account which he got during registration, then the initial login page is not there). On the first login, however, he gets pushed through the GitHub OAuth flow to connect the users GitHub account to the OpenShift account (via Keycloak but that's a technical detail).
• After this authentication flow (which we already have) the user is redirected to the starting page that you are designing.
• The next two steps (creating OAuth app and entering IDs) are currently a manual process: We can redirect the user to the GitHub page, possibly in a new window or tab to not lose the user as there will be no redirect back to our pages at the end. The user then has to create the GitHub app either in his/her personal account or in an organization account (or maybe even in a different than authenticated GitHub account). actually, the GitHub app can be created everywhere. At the point, we would need for sure some help document. So the button is more or less only a link to an external page to its personal settings
• When a GitHub OAuth app has been created the client id and secret needs to be copied manually. There is currently no way via UI or any kind of API to do this automatically.
• Step 3 is perfectly fine, as we can obtain the organisations to which a user has write access via the GitHub API.

This solution is not the best one as we theoretically could automate step 1 & 2, and then insert the client id and secret already into the user's settings.

However, GitHub doesn't offer a programmatic way for creating the GitHub app. If it would, we could create the GitHub app in a Syndesis specific account with the onboarding script when we install Syndesis. We are currently exploring some automatic way to do it via the HTML UI (via some scripting), but this is currently not of high priority. @kcbabo if this is something you think it's crucial we can invest more efforts to automate step 1 & 2.

// @jimmidyson, I hope I have accurately described the auth flow, please correct me if wrong.

[dongniwang]

Thanks @kcbabo and @rhuss for the feedback!

Authentication is already done via OpenShift (so when already connected to the user's OpenShift account which he got during registration, then the initial login page is not there). On the first login, however, he gets pushed through the GitHub OAuth flow to connect the users GitHub account to the OpenShift account (via Keycloak but that's a technical detail).

I'm not sure I fully understand this part. Do you mean user would always come in to ipaas via OpenShift? What happen before a user sees the starting page? Is the user in OpenShift environment already, any action required to trigger the starting page?

[kcbabo]

I think linking to docs on how to create the GitHub app would be sufficient for TP1.

[rhuss]

@dongniwang the flow normally goes like this (but some steps might be skipped because this already has been done elsewhere):

• When accessing the app URL you first have to login with the OpenShift account:

• Then you get redirected to our single sign-on server, keycloak, to complete user information:

• Then normally next is the GitHub OAuth flow, where the user has to authenticated with GitHub and grant permissions:

However, this last step is only possible if we already have the GitHub client id / secret (which is currently installed when we apply the template).

So I suggest that we after the initial OpenShift / Keycloak round we detect that there is github config missing, we redirect to this setup page which queries for this information. And then redirects to the GitHub OAuth part. Tbh, I don't know how to do this technically as the GitHub auth is directly configured into Keycloak (afaik).

@jimmidyson can shed some light of how we can configure this to make it a two step process.

[dongniwang]

@rhuss Thank you so much for the detailed explanation! It makes a lot more sense now. :)

When accessing the app URL you first have to login with the OpenShift account

Are we saying having OpenShift accounts is required before users start using Syndesis? Or as part of the first time user experience of Syndesis, users would need to sign up for OpenShift (RH account?)as well?

[rhuss]

@dongniwang yes, this is part of the registration process. Every user gets an OpenShift account, so this can be taken for granted. That's my understanding, but please correct me @kcbabo if I'm wrong ;-)

[kcbabo]

It depends on how wide we make the aperture for first time user experience. Let's break down the first experience into two stages: Stage 1 : signing up to evaluate Syndesis Stage 2 : using Syndesis for the first time

A precondition of Stage 2 is that you have an OpenShift Online account with Syndesis installed already. This is taken care of in Stage 1. I think we're just talking about Stage 2 in this issue, right?

[dongniwang]

Thanks for clarifying this! @kcbabo And to answer your question, yes, the design in this issue is only for Stage 2.

So my question is - does the current designs address what we need for stage 2? I just put up a PR yesterday, please feel free to comment.

[kcbabo]

I'm good with the UX, but engineering will have to answer whether some of those steps are possible. For example, can you just link to https://github.com/settings/applications/new in a new tab from that UI flow to setup the OAuth app?

[kahboom]

I think Stage 2 that @kcbabo describes "using Syndesis for the first time" entails the on boarding/guided tour here as well, correct? https://github.com/syndesisio/syndesis-ui/issues/57 Would be nice to see the transition between the two for first time users after authenticating, but we can carry on that discussion here (https://github.com/syndesisio/syndesis-project/issues/68) or in the UI issue.

[rhuss]

I'm closing this now that we don't have GitHub anymore.

Thanks for all the work on this ...