SMART-SPACES OAUTH PROPOSAL

gistfile1.txt

INTRODUCTION

Workflow for OAuth2 with Citrix Octoblu SmartSpaces should follow the 
"Authorization Code Grant" process as described in section 4.1 of RFC6749.
(see https://tools.ietf.org/html/rfc6749.html#section-4.1)

In summary, the following steps will occur:
   (A)  The user is directed to an authorization endpoint.

   (B)  The authorization server authenticates the user and verifies or
        requests permission to grant tokens.

   (C)  Assuming the user grants access, the authorization server 
        redirects to a provided redirection URI with an auth code.

   (D)  The client requests an access token be generated from the 
        authorization server using the provided auth code.

   (E)  The authorization server authenticates the request and responds 
        back with an access token.

The resulting access token may then be used on behalf of a user to trigger
actions.


DETAILS

The Authorization server will run with meshblu credentials 'Server Device', capable of retrieving 
'OAuth Devices' which contain information needed to process requests. Information contained 
by the OAuth Device should include the following:

   (*)  Name of the service requesting OAuth, eg 'Open Spaces', for displaying to the user.
   (*)  Secret for use in a Bearer token and authenticating requests, NOT an actual token.
   (*)  Redirect URI to be used after an authentication code has been obtained.
   (?)  Possibly information for referer validation.

The authorization code grant process can then be described in further detail:

   (A)  The user is directed to an authorization endpoint, 'https://oauth.ctxs.octo.space/authorize',
        with the following data:
         1. A POST body or GET parameters containing response_type=code, client_id=athena, 
            and an optional state.
         2. A Header containing a Bearer Token for authorization. (?)

   (B)  The authorization server authenticates the user using a Smart Spaces authenticator:
        1. The Bearer token is translated into a uuid and secret. The 'Server Device' fetches
           the 'OAuth Device', as given by the uuid, and verifies the secret.
        2. The user is redirected to 'athena.ctxs.octo.space' to login (given client_id=athena).
        3. On login the user is redirected to back to 'oauth.ctxs.octo.space/athena' with a 
           uuid & token (* Note: smart spaces authenticators need callbacks whitelisted).
        4. The authentication server checks the user device if permission has already been granted,
           if not permission is requested and successful grants recorded.

   (C)  Assuming the user grants access, the authorization server redirects to a redirection URI 
        as defined in the 'OAuth Device' with an auth code and optionally a provided state.
        (eg redirects to https://openspaces.azure.com/oauthed?code=xyz&state=abc)
        The auth code and user credentials will be stored in Redis for a short period of time,
        until a token request is made or the auth code expires (5 minutes).

   (D)  The client requests an access token be generated from the 
        authorization server using the provided auth code.
        (eg POST request to https://oauth.ctxs.octo.space/token, with body of
         grant_type=authorization_code and code=xyz)

   (E)  The authorization server authenticates the request and responds 
        back with an access token.
        The user credentials are returned in an encoded base64 token format, suitable for using 
        directly with Meshblu. eg:
           {
             "access_token":"0C2BrYotnFZFEjr1zCsicMWpAA==",
             "token_type":"Bearer"
           }
        The access token will never expire and refresh tokens are not provided. 
        Immediately after token retrieval the access code and associated user credentials
        will be purged from Redis.


EXAMPLE WORKFLOW

The following is an example of how the user redirection process might look when logging in using the Athena authenticator:

  https://openspaces.azure.com/
  `-> 
    https://oauth-uuid:oauth-secret@oauth.ctxs.octo.space/authorize?response_type=code&client_id=athena&state=random-state
    `->
      https://athena.ctxs.octo.space/login?callbackUrl=https:%2f%2foauth.ctxs.octo.space%2fauthed%2fathena%dfshortcode&domain=ctxs
    <-' 
    https://oauth.ctxs.octo.space/authed/athena/shortcode?uuid=user-uuid&token=user-token
  <-'
  https://openspaces.azure.com/authed/smartspaces?code=random-code&state=random-state
  `->
    POST https://client-id:client-secret@oauth.ctxs.octo.space/token 
    BODY grant_type=authorization_code&code=random-code&client_id=athena&client_secret=???
  <-'
  { access_token, token_type }
  

UNKNOWNS / POTENTIAL ISSUES

The Authorization header seems to be required as a Bearer token by node-oauth2-server in the authorize endpoint,
is this appropriate?

Authorization in the form of a client_id and client_secret is required by the token endpoint. How do those
values relate to the OAuth Devices and are they being used correctly? The client_secret seems to not be required
per spec but is required in token requests by node-oauth2-server.

Should an underlying library like node-oauth2-server be used or should we simply provide the end-points to spec?
(Note: use of node-oauth2-server by octoblu/oauth-provider is non-standard)

Even though some libraries make decisions that may deviate slightly from spec, I think it is preferable to use a library when possible. This one looked promising oauth2orize