Authentication Process RFC

[andrewbranch]

Requesting Access

1. Navigate to directory
2. App sees there’s no token in keychain, or makes a request for directory info with expired token and receives 401
3. Log in with Digits (enter phone number, receive verification code, enter verification code)
4. Send OAuth credentials to server
5. Server verifies with Digits API
6. Look up existing user by Digits user id
7. If user does not exist, create one
8. Generate new JWT*, assign it to user, send it back
9. Confirm that the phone number is correct****
10. Make request for directory info with token
11. If it's a 403, initiate access request\ and optionally wipe any previously downloaded directory data

*

1. To determine scopes for token, look for member with same phone number as user
2. If one exists, grant directory-read scopes

**

1. Send request with token and desired scopes (or some description of intent) to create access request
2. Server looks up user from token, creates and returns access request with endpoints to add Facebook and Twitter accounts and toggle notifications
3. Phone prompts user to expedite the process by logging into a Facebook or Twitter account.*\ Alternatively, go to the front office to be added.
4. Set a key in NSUserDefaults that indicates an access request is open. When this key is set, the app will check the status of the access request whenever the app enters the foreground. If it has been approved, call the refresh token endpoint to receive a new token with updated scopes. Display a message (possibly received from the access request object itself, set by an admin?).

***

1. Log in via social
2. Use endpoint from access request response to send OAuth credentials to server
3. Server verifies OAuth credentials
4. Update access request / user record with social profile
5. Phone tells user (by name) that the request is being reviewed, and gives option to be notified when it’s done.
6. Use endpoint from access request response to toggle notifications

****

1. App says “Hello, ${firstName}!” with buttons for confirming and saying “I’m not ${firstName} ${lastName}!”
2. If user taps “That’s not me,” revoke token and start request process\ with some meta info describing phone number conflict

   Granting Access

3. Internal app is provisioned with symmetric API key.
4. API key and a first name (for record keeping) is exchanged for a JWT
5. Internal app receives notifications for new access requests (5 minute delay to give time to add social profile)
6. Reads and updates access requests from JSON API authenticated with token
7. Scopes cannot be granted directly; they are calculated based on conditions. For directory read access, the condition is defined in (*). Later, we could expand this to a roll-based system, which would map users to roles to scopes, allowing for more custom behavior (and more efficient token creation). So before approving an access request for directory-read scopes, you’d have to add a member to ACS with the phone number and sync it to our API.
8. Because of number 5 above, the server should ensure that the conditions for granting scopes are met before actually approving the request
9. Upon approving or denying, a message can be set for the request. The server may, depending on the user’s settings, send a push notification that the request has been approved or denied.

[andrewbranch]

Big to-dos:

• [ ] Set up push notifications
• [ ] Create internal app for granting access
• [ ] Figure out social login UI