Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Provide sample code for handling Handle #2544

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

docs: Provide sample code for handling Handle #2544

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
72e817f
docs: Add sample code & recommendation for handling Handle
paulproteus Sep 13, 2016
b19e805
Explain the unique constraint this relies on
paulproteus Sep 13, 2016
8889dd4
Contextualize the algorithm
paulproteus Sep 14, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 13 additions & 2 deletions docs/developing/auth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,11 +63,22 @@ related to user identity and permissions:
duplicates (such as prompting the user to choose a different one,
or just appending some digits). Apps should strongly consider
using display names (`X-Sandstorm-Username`) instead of handles.
**WARNING: A user can change their preferred handle at any time.
WARNING: A user can change their preferred handle at any time.
Two users can have the same preferred handle. The preferred handle
is just another form of display name. Do not use preferred handles
as primary keys or for security; use `X-Sandstorm-User-Id`
instead.**
instead.

* **Our recommendation on how to use this:** If you need a unique identifier, use the
`X-Sandstorm-User-Id`. If your app requires that handles also be unique, then use the
following algorithm. If there is already an account for the user ID, don't change its
handle. If another account exists with the same handle, then append some numbers to make the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel like this algorithm description is in the uncanny valley between precise and informal. How about:

If your app requires that handles be unique -- for example, because the app is designed to use "usernames" as the primary user identifier -- then you will need to track and store those handles in your app's storage. We suggest implementing the following algorithm, for each request:
1. If there is already a user account in your app's database associated with the request's `X-Sandstorm-User-Id`, use the handle associated with it.
2. Otherwise, if no existing user account is already associated with `X-Sandstorm-Preferred-Handle`, create a new account for this user's ID and handle, and use that.
3. Otherwise, this is a new user but their handle is already in use. Append a number to the handle such that it is unique, create a user account using the user's ID and the modified handle, and use that.

new one unique (this should be rare). This is for example how GitLab works on Sandstorm. See
[sample
code.](https://github.com/dwrensha/gitlabhq/blob/7f2b131c8e632b1a9c261e8ca1b6d46667b99d70/config/initializers/sandstorm_strategy.rb#L12-L21)
In GitLab, the `X-Sandstorm-User-Id` is used as a unique identifier (embedded within the
user's "email address"). This code relies on the fact that GitLab's user schema verifies that
email addresses (therefore, `X-Sandstorm-User-Id` values) are unique.

* `X-Sandstorm-User-Picture`: The URL of the user's profile picture.
The exact resolution of the picture is not specified, but assume
Expand Down