= SSH OAuth Authentication =

'''Rather than creating and uploading an SSH key, you can authenticate your bzr client using the web ui.'''  When you first try to use Bazaar against Launchpad, it'll launch a browser where you log in and give permission for this machine to access Launchpad.  No other user configuration is needed.

'''Contact:''' Martin Pool<<BR>>
'''On Launchpad:''' '''[[https://bugs.launchpad.net/launchpad/+bugs?field.tag=ssh-oauth|bug tag ssh-oauth]]''' and '''Bug:297398''' (the original request for something like this)

== Rationale ==

 * Creating and managing SSH keys is a noticeable (not overwhelming) source of friction for users especially for those on Windows or new to Unix development.  It also creates [[https://answers.launchpad.net/launchpad/+questions?field.search_text=ssh&field.sort=RELEVANCY&field.sort-empty-marker=1&field.actions.search=Search&field.language=en&field.language-empty-marker=1&field.status=OPEN&field.status=NEEDSINFO&field.status=ANSWERED&field.status=SOLVED&field.status-empty-marker=1|some support burden]] for Launchpad staff.

   * Bug:297398: overall bug saying that ssh keys are confusing (basically, this bug)

   * Bug:705050 users with different local and Launchpad user names can use the wrong one and get a confusing situation; this could be avoided by bzr automatically getting the Launchpad identity through an authenticated browser (presumably the user knows how to log in with their email address.)

   * Bug:60601, Bug:128167, Bug:230144, Bug:416910, various usability problems with uploading keys; these could be mitigated by not making the user manually upload a key (though they could still exist for people who do want to use their own keys)

   * Bug:568982: people want to add keys over the api (though that could possibly be part of a solution to this)

   * Bug:246783, Bug:484827: insufficient documentation for creating and using ssh keys

   * [[https://answers.launchpad.net/bzr/+question/174098|question 174098]], access to private branches over http is confusing

 * People would like to make semi-trusted robots that have access to private branches, or that can write to branches, but that don't get full access to the user's account.

== Stakeholders ==

''Who really cares about this feature? When did you last talk to them?''

 * mwh (setting up robots) 
 * could benefit from user testing
 * Canonical developers new to Unix?
 * [[developer.ubuntu.com]] representatives?
 * Quickly developers?
 * Ubuntu/Canonical security teams?
 * ground-control developers?
 * LOSAs?
 * users who previously had trouble with ssh -- see [[https://answers.launchpad.net/launchpad/+questions?field.search_text=ssh|questions]], [[https://bugs.launchpad.net/launchpad/+bugs?field.searchtext=ssh&orderby=-importance&search=Search&field.status%3Alist=NEW&field.status%3Alist=INCOMPLETE_WITH_RESPONSE&field.status%3Alist=INCOMPLETE_WITHOUT_RESPONSE&field.status%3Alist=CONFIRMED&field.status%3Alist=TRIAGED&field.status%3Alist=INPROGRESS&field.status%3Alist=FIXCOMMITTED&field.assignee=&field.bug_reporter=&field.omit_dupes=on&field.has_patch=&field.has_no_package=|bugs]]
 * ...?

== User stories ==

<<Anchor(story-name>)>>

=== New developer without a key ===

''As a'' developer new to working on Ubuntu<<BR>>
''I want to'' just get a checkout of a Launchpad branch without futzing with ssh and key files<<BR>>
''so that I can'' branch the code and contribute changes

=== Delegated to robot ===

''As a'' person managing an external auto-build service<<BR>>
''I want to'' give it access to branch and push back changes, without giving it my real private key<<BR>>
''So that I can'' get the robot going, with less risk if the build machine is compromised.

I may want the token given to the robot to expire after a certain period of time (say 24h).

=== Launchpad developer ===

''As a'' Launchpad developer<<BR>>
''I want to'' start an ec2 instance that can pull from Launchpad over ssh, without giving it my real key<<BR>>
''So that'' I can land my changes without trusting my key to a random external machine
''Have as many as you like. Group user stories together into meaningfully deliverable units. They'll be used as the driving elements of exploratory testing QA.''

See also bug:577118.

== Constraints and Requirements ==

=== Must ===

 * Allow logins without manually configuring a key.

 * Continue using encrypted SSH as the transport.

 * Continue to support ssh key authentication using a user-provided key.

 * Continue to work on a text-mode server, preferably one without a web browser

=== Nice to have ===
 
 * Running lp-login should automatically take you into generating a token or perhaps even registering an account.

 * Tokens auto expire after a period of time, as they can with OAuth tokens at the moment.

 * Consistent or integrated with existing OAuth ui.

 * A reasonably easy way to generate a token on one machine and then install it on another.  (Good for headless servers, or machines which you do not trust enough to type your real Launchpad/SSO credentials.)

 * Use an asymmetric key that cannot so easily be leaked to machines that shouldn't have it?  (Seems in tension with not being an SSH key and not requiring SSH changes.)

=== Must not ===

 * Require code changes to the SSH client, which would be infeasible to put into OpenSSH and Putty; requiring everyone to use bzr paramiko might be hard.
 
 * Open security vulnerabilities.

 * Reimplement crypto code that belongs in SSH.

=== Out of scope ===

 * Anonymous-SSH access?

 * General delegated-token or impersonation enhancements (though they would be nice):

   * Audit trail showing when and why tokens were issued and when they were used.

   * A means to limit access of a particular token to particular projects or actions.

== Subfeatures ==

''Other LaunchpadEnhancementProposal``s that form a part of this one.''

== Success ==

=== How will we know when we are done? ===

 * Running ``bzr lp-login`` (or perhaps even just branching from lp:), when you already have a Launchpad account, will authenticate you to Launchpad without requiring any manual setup of keys.

=== How will we measure how well we have done? ===

 * This works reliably on all platforms.
 * User questions about the topic decrease.
 * The user experience for setup has a small number of steps and it is hard to have them go wrong.

== Thoughts? ==

''Put everything else here. Better out than in.''

== Implementation ideas ==

 1. Generate a symmetric OAuth token; send that as a cleartext password; store it in bazaar's authentication.conf or in the keyring.
   * If using an external SSH, how will it be passed across?
   * Should it be stored just unencrypted, or in the system keyring, or elsewhere?
   * Server should accept this only if you authenticate as eg mbp+auth@bazaar.launchpad.net?

 1. Add a new auth_oauth authentication mechanism in SSH (requires client and server side modifications)

 1. Generate an SSH key automatically when logging in and add it to Launchpad.