User repeatedly pastes his private key rather than his public key into the SSH key field (https://gitlab.com/profile/keys). He doesn't understand why he is receiving an error message.
This problem was identified as part of the following research study:
ux-research#53 (closed)
To do
Recognise when a user has accidentally copied and pasted their private SSH key instead of their public SSH key. Inform them with a clear input field validation error message.
Update current copy via following changes/additions on the SSH keys settings page
New wording for labels, descriptions, placeholders
Block description
Is
Suggestion
Before you can add an SSH key you need to generate one or use an existing key.
To add an SSH key you need to generate one or use an existing key.
New "Key" description
Is
Suggestion
n/a
Paste your public SSH key, which is usually contained in the file '~/.ssh/id_rsa.pub' and begins with 'ssh-rsa'. Don't use your private SSH key.
"Key" placeholder
Is
Suggestion
Don't paste the private part of the SSH key. Paste the public part, which is usually contained in the file '~/.ssh/id_rsa.pub' and begins with 'ssh-rsa'.
Typically starts with "ssh-rsa …" (?)
New "Title" description
Is
Suggestion
n/a
Name your individual key via a title
"Title" placeholder
Is
Suggestion
empty
e.g. My MacBook key
Proposed design
Add key form
Form alert
User flow when private key is entered
User pastes the key
User fills in the Title input field ('Add key' button becomes enabled)
User clicks on 'Add key'
Alert shows up
User checks the key, deletes it from 'Key' text area and pastes in the correct public key
User clicks on 'Yes, it's not private'
The key is added
Changes introduced
Moved long placeholder text from 'Key' text area outside of it, below the 'Key' label as paragraph text.
Changed the 'Key' text area placeholder to a shorter and helpful one
Added an example placeholder text to the 'Title' input field
Added a warning alert that shows up when we think the key might be private.
@jramsay We should definitely do this on the frontend so that the private key never makes it onto the network or our systems. We can also make the error message a bit clearer in case someone accidentally adds a private key using the API.
Ideally, we can also improve the label an placeholder texts on the SSH keys settings page.
Block description Is Before you can add an SSH key you need to generate one or use an existing key.. Suggestion To add an SSH key you need to generate one or use an existing key.
"Key" placeholder Is Don't paste the private part of the SSH key. Paste the public part, which is usually contained in the file '~/.ssh/id_rsa.pub' and begins with 'ssh-rsa'.. Suggestion Paste your public SSH key, which is usually contained in the file '~/.ssh/id_rsa.pub' and begins with 'ssh-rsa'. Don't use your private SSH key.
"Title" placeholder Is
empty Suggestion Name your individual key via a title
@timzallmann, I would suggest to check against a leading -----BEGIN RSA PRIVATE KEY-----, but I would see that as part of actual validation implementation. I'm happy to work on this together with the assigned engineer during development.
@matejlatin Being aware that you are going to work on Forms for our Design System in 11.1 as well, do you know if we have an existing UI pattern for input form validation? Bootstrap Vue only references Bootstrap right now. Thank you!
@akaemmerle we do, we show red text messages below the input fields. I'll mock up an example.
Some feedback on other form design things:
"Key" placeholder Is Don't paste the private part of the SSH key. Paste the public part, which is usually contained in the file '~/.ssh/id_rsa.pub' and begins with 'ssh-rsa'.. Suggestion Paste your public SSH key, which is usually contained in the file '~/.ssh/id_rsa.pub' and begins with 'ssh-rsa'. Don't use your private SSH key.
Suggested copy is good but we should place this outside of the text area as help text instead. Then the placeholder can be an example or a 'Starts with -----BEGIN RSA PRIVATE KEY-----' or something that is short but helpful.
"Title" placeholder Is
empty Suggestion Name your individual key via a title
Again, if that long and descriptive, it should be outside as help text. Then the placeholder can either remain empty or give an example 'e.g. My public key'
@akaemmerle that's exactly what I was just working on I only have a generic 'Not a valid key' error for now but we should write more helpful and contextual validation error messages.
Awesome, @matejlatin . Please also feel free to question the text blocks, as the original copy was focused on being as short as possible via placeholders. I think we can be a bit more elaborate inside a description.
@lbennett The issue description is up to date in terms of copy. @matejlatin Could you please update the description and confirm that this is final? Thank you!
@akaemmerle Doesn't look too promising. It seems there might not be a definitive way to distinguish between public and private keys using a regular expression. I believe there is a way we can use a binary on the BE to test it, but this would require to BE efforts and I'm not even certain it's actually a possibility.
@winh made a good suggestion to warn the user that it doesn't look like a typical public key, but they can continue if they're certain. We can then test for -----BEGIN .* PRIVATE KEY----- and show a warning if it's matched.
@nick.thomas: personally, i'd just test for !~ /^ssh-/
it's fairly rare, but you do get some PEM-encoded public keys that would match -----BEGIN
(we don't support them, so they'd be rejected anyway, but saying "these are private keys" would be wrong and confusing)
These are great points that are going to save a lot of time but it doesn't change that we should warn instead of reject. Hope this helps!
If we can't find a placeholder for the 'Key' text area, maybe let's just leave it blank? We have a full paragraph above it that should be quite helpful.
What would be a good way to tell them that the key they entered is a private one but they should enter a public one?
We need to change the form validation so it always shows up below the input field that has an error and move away from the general "The form contains the following errors". Are we doing this as part of this issue?
2. What would be a good way to tell them that the key they entered is a private one but they should enter a public one?
We shouldn't be certain of this. This means we shouldn't use "This is a private key", because we're never 100% sure. We need to warn them but let them continue if they know what they're doing and I think this needs to be reflected in the UI. Maybe not red? Or just the copy can explain that they can continue if they want.
I'd agree, optional text see description. Does not block progress.
I expected this FE validation pattern to be already in place. The error message you reference comes from BE after saving invalid forms. If this UI pattern for input validation feedback is available, we sure should add this to the input.
We shouldn't be certain of this. This means we shouldn't use "This is a private key", because we're never 100% sure. We need to warn them but let them continue if they know what they're doing and I think this needs to be reflected in the UI. Maybe not red? Or just the copy can explain that they can continue if they want.
@lbennett in this case, I think we should look to do something like this:
I think that trying to do that through an error message (even if it's not red) will be confusing. Besides, as you said, we need to allow them to continue and I wouldn't just keep the 'Add key' button and expect them to click on it again—that alone wouldn't be clear and I'm afraid it would confuse users.
We just need something softer than "Warning" but I can't think of anything... Any ideas?
@matejlatin I think Luke any myself had a similar idea here, I thought about a warning alert, see Bootstrap Vue component. But I am not aware that we have this pattern adapted.
@lbennett thinking about it again, I'm not even sure if we need the Cancel button. The users should still be able to change the key even after the "oops, are you sure?" part shows up and they can submit the form from there on.
What do you think?
@akaemmerle no, it seems we don't have such alerts. If we want to consider adding one, it could be like this
@akaemmerle@lbennett I updated the description with the latest designs and a user flow in case when the key entered is private. I also prototyped the flow (up until the alert shows up) to see if it feels right and to me it does. Check out the gif below.
Unless we missed something, I think this is ~"UX ready" WDYT?