Skip to content

Latest commit

 

History

History
422 lines (377 loc) · 9.13 KB

Authentication API.md

File metadata and controls

422 lines (377 loc) · 9.13 KB

Authentication Data Models and REST API

Data models

The data models below are described in the mongoose notation for MongoDB data models.

User

{
  uuid    : {type: String, required: true},
  name    : String,
  gender  : String,
  local            : {
    email        : Email,
    password     : String
  },
  facebook         : {
    id           : String,
    token        : String,
    email        : Email,
    name         : String,
    displayName  : String
  },
  twitter          : {
    id           : String,
    token        : String,
    displayName  : String,
    username     : String
  },
  google           : {
    id           : String,
    token        : String,
    email        : Email,
    name         : String
  },
  github           : {
    id           : String,
    token        : String,
    username     : String,
    displayName  : String
  },
  roles : [String]
}

Data Transfer Objects (DTOs)

In this context a DTOs sole purpose is to define the schema of data transferred in various API methods between client and server. They are not used as database schemas and are not persisted 1:1.

CurrentUser

Information about the current logged in user, used for rendering the UI.

{
  uuid   : {type: String, required: true},  // Optional
  name   : String,                          // Optional
  roles  : [String],                        // Optional
  gender : String,                          // Optional
  local : { email : String }                // Optional added, if it is a local account
}

Signup and Login

User input on signup form

{
  email           : {type: Email, required: true},
  password        : {type: String, required: true}
}

UserInfo

{
  uuid : {type: String, required: true},
  name : String
}

UserSchemaPatch

var UserSchemaPatch = {
  type : Object,
  unknownKeys: 'remove',
  schema : {
    'roles': {
      type: Array,
      required: false,
      schema: {
        type: String
      }
    },
    'name': { type: String, required: false },
    'gender': { type: String, required: false },
    'local' : {
      type : Object,
      schema : {
        'email' : { type: String, required: false },
        'password' : { type: String, required: false }
      }
    }
  }
};

Client REST API

User-related

Description returns information about the currently logged in user, for UI rendering
Request GET /api/v1/auth/currentUser
Response Body CurrentUser
Response Codes 200 OK

Logout

Description logout
Request GET /api/v1/auth/logout
Response Codes 204 OK

Local Login

Description Local login with local credentials (username, password)
Request GET /api/v1/auth/local-login
Response Body CurrentUser
Response Codes 400 Bad Request - if body is malformed
422 Unprocessable Entity - Email address and/or password unknown
200 OK - if successful
500 Internat Server error - if unknown error

Signup process-related

Description Form submission on signup page
Request POST /api/v1/auth/signup
Request Body Signup
Response Body CurrentUser
Response Codes 400 Bad Request - if body is malformed or e.g., passwords do not match
422 Unprocessable Entity - if user with given email already exists
200 OK - if successful
500 Internat Server error - if unknown error

OAuth login / signup

The following methods are available for all currently supported OAuth providers. Replace $PROVIDER with one of [facebook, twitter, google, github].

The actual authentication and signup process is handled using the passport library that abstracts from the actual auth process between the scenario tool and the authentication provider. Here, we only document the most important URLs and methods.

Description Initiate signup / signin with $PROVIDER authentication provider
Request GET /api/v1/auth/$PROVIDER
Description Callback URL to which user is redirected by the OAuth provider after allowing access to his user information. The request will contain the information about the user that the scenario tool requests to read from the authentication provider.
Request GET /api/v1/auth/callback_$PROVIDER

Connecting additional accounts

The following methods are available for all currently supported OAuth providers. Replace $PROVIDER with one of [facebook, twitter, google, github].

The methods allow adding additional accounts to an existing one, i.e. if the user has e.g., a local account he can chose to allow the scenario tool access to his profile data (e.g., email, profile picture, profile name, ...). The backend will then augment the users account data with the additional information retrieved via the authentication provider.

Description Connect additional auth provider account with existing (of logged-in user)
Request POST /api/v1/auth/$PROVIDER

Additionally, if the user signed up with some request provider first, there's the option to additionally connect (i.e. sign up) a local account with:

Description Connect additional local account with existing auth provider account (of logged-in user)
Request Body Signup
Request POST /api/v1/auth/local

Disconnecting additional accounts

Accounts created / added can be removed from the scenario tool by sending requests to one (or more) of the following resources for one of the authentication providers [local, facebook, github, twitter, google]:

Description Disconnect account
Request GET /api/v1/users/:uuid/unlink/$PROVIDER

Retrieve user data / users list

Description Retrieve info about a specific user, used e.g. to display user avatars.
Request GET /api/v1/info/:uuid
Response Body UserInfo
Response Codes 200 OK
Description Lists all user accounts
Request GET /api/v1/users
Response Body [User]
Response Codes 401 Unauthorized - if not logged in
403 Forbidden - if user is logged in but has no administrator rights
200 OK
Description Retrieve detailed account information about one specific user with UUID :uuid
Request GET /api/v1/:uuid
Response Body User
Response Codes 401 Unauthorized - if not logged in
403 Forbidden - if user is logged in but has no administrator rights
200 OK
Description Patch individual fields of a user (allowed if you're administrator or logged in as the user to be patched)
Request PATCH /api/v1/:uuid
Request Body UserSchemaPatch
Response Body User
Response Codes 401 Unauthorized - if not logged in
403 Forbidden - if user is logged in but is not the user to be patched or has no administrator rights
200 OK
Description Remove user model
Request DELETE /api/v1/:uuid
Response Body User (the model of the user that was removed)
Response Codes 401 Unauthorized - if not logged in
403 Forbidden - if user is logged in but is not the user to be patched or has no administrator rights
200 OK