Merge branch '2979-personal-access-tokens' into 'master'

Allow creating Personal Access Tokens through the website

Related to #2979 

- Allow a user to create personal access tokens, and use them to authenticate
- Refactor `API::Helpers` into `API::Helpers::Core` and `API::Helpers::Authentication`

# Tasks

- [ ]  #2979 (!3749)  - Personal Access Tokens
    - [x]  Basic Implementation
        - [x]  Add UI to add "Personal Access Tokens"
        - [x]  Reload `lib/api` on every request
        - [x]  Respect these tokens for API requests
        - [x]  Just a param or a header too?
        - [x]  Allow revoking tokens
        - [x]  Expire tokens
        - [x]  Left bar should have a "PAT" icon
        - [x]  Scopes?
        - [x]  Copy to Clipboard
        - [x]  Show active/inactive tokens separately
            - [x]  No need to check for expired/revoked in the appropriate places
        - [x]  Why does regular ApplicationController check for private token?
        - [x]  Support non-API requests
        - [x]  Revert (or work on) `lib/api` eager loading
    - [x]  Create MR
    - [x]  Refactoring
    - [x]  Fix tests
    - [x]  Write more tests
    - [x]  Add screenshots to MR
    - [x]  Add description of query performance to MR
    - [x]  Limit the number of queries in the `personal_access_tokens` page
    - [x]  Wait for CI to pass
    - [x]  Fix merge issues in schema.rb
    - [x]  Assign MR to endboss
    - [x]  Wait for feedback
    - [x]  Fix feedback
        - [x]  Wait for CI to pass
    - [x]  Assign to @rspeicher
    - [x]  Fix @rspeicher's comments
    - [x]  Wait for CI to pass
    - [x]  Assign back to @rspeicher
    - [x]  Write documentation and ping @axil
    - [x]  Wait for Axil to respond
    - [x]  Assign to endboss
    - [x]  Address Douwe's feedback
        - [x]  Use the `private_token` or `authentication_token` param instead of `personal_access_token`
        - [x]  Ditto for the header
    - [x]  Assign to endboss
    - [x]  Make sure CI is green
    - [x]  Address Douwe's feedback
        - [x]  Don't go through the `authenticate_user_from_private_token!` method, if a private token is supplied (or combine them)
        - [x]  In `authenticate_user_from_personal_access_token!` don't hit DB if `token_string` is `nil`
        - [x]  Use `current_user.personal_access_tokens.build` in the controller
        - [x]  Remove the "We aren't using `personal_access_token` as the root param" comment
        - [x]  `No need for = "...", we can just have the Inactive ... #{...} on the next line` in the view
        - [x]  Render dates in a (more) human format
        - [x]  CSS issue with table
        - [x]  Don't show the tokens in the UI indefinitely
        - [x]  How to implement scopes? Add-on to current impl? Doorkeeper?
    - [x]  Wait for @DouweM's comments about scopes
    - [x]  Address @DouweM's second review 
        - [x]  Try not using `native['innerHTML']`
        - [x]  use contexts for all "when ..."
        - [x]  Ensure consistency (styling) with other pages for "You don't have any tokens" message
        - [x]  "Actions" table column doesn't need a label
        - [x]  %td can be moved outside of the if/else statement
        - [x]  The header title should be "Profile Settings"
        - [x]  Can this be a `before_create`, so we don't need to use `generate`?
        - [x]  If it couldn't be revoked, will we show an error?
        - [x]  If it couldn't be saved, will we show an error?
    - [x]  Merge master
    - [x]  Update CHANGELOG entry
    - [x]  Add tests for form errors?
    - [x]  Post screenshots
    - [x]  Tag @jschatz1 for review
    - [x]  Wait for [build](https://gitlab.com/gitlab-org/gitlab-ce/commit/0dff6fd/builds) to pass
    - [x]  Respond to @jschatz1's comments
        - [x]  Hardcoded colors should be variables
        - [x]  Should not be allowed to chose a date in the past
        - [x]  Use the same table as in the Applications tab
        - [x]  button should say "Create Personal Access Token"
        - [x]  Float the revoke to the right on the `a`
        - [x]  Change revocation message. "Are you sure you want to revoke this certificate? This action cannot be undone."
        - [x]  Date stays selected and looks selected even though date is set as "never".
        - [x]  ~~hover on the calendar button shifts~~ (not caused by this MR - happens on `milestones#new` as well)
        - [x]  Don't use the panel for the created token
            - [x]  Use a normal flash for "Your new personal access token has been created"
            - [x]  Show the input (with the token) below it full width.
            - [x]  Put the "Make sure you save it - you won't be able to access it again." message near the input
        - [x]  Have the input highlight all on single click
    - [x]  Update screenshots
    - [x]  Merge master in + conflicts
    - [x]  Assign to @jschatz1 again
    - [x]  Respond to @jschatz1's comments
        - [x]  No button for clipboard, only link
        - [x]  text-danger
        - [x]  highlight fade on that area where the token was created
    - [x]  Make sure [build](https://gitlab.com/gitlab-org/gitlab-ce/commit/d754d99179f1ffe846fcc1d8e858163b39efc5dc/builds) is green
    - [x]  Assign to @jschatz1
    - [x]  Wait for [build](https://gitlab.com/gitlab-org/gitlab-ce/commit/faa0e3f7580bc38d4d12916b4589c64d6c2678a7/builds) to pass
    - [x]  Respond to @DouweM's feedback
        - [x]  move the redirect_to out of the if/else
        - [x]  certificate -> token
        - [x]  datepicker back to text field
        - [x]  combine the get_user_from_private_token and get_user_from_personal_access_token methods in ApplicationController
        - [x]  combine the get_user_from_private_token and get_user_from_personal_access_token methods in `lib/api/helpers`
        - [x]  don't need the new constants
    - [x]  Wait for [build](https://gitlab.com/gitlab-org/gitlab-ce/commit/9d7cda3ddce52baad9618466a5d00319b333be57/builds) to pass
    - [ ]  Wait for merge

# Screenshots
![Screen_Shot_2016-06-16_at_8.30.33_AM](/uploads/30a168964b7c5e0eb322705747829fb6/Screen_Shot_2016-06-16_at_8.30.33_AM.png)
![Screen_Shot_2016-06-16_at_8.30.44_AM](/uploads/7a8202885df6120071bbe81b215aaead/Screen_Shot_2016-06-16_at_8.30.44_AM.png)
![Screen_Shot_2016-06-16_at_8.31.02_AM](/uploads/6905c0848864e390138b771389c7a1b2/Screen_Shot_2016-06-16_at_8.31.02_AM.png)
![Screen_Shot_2016-06-16_at_8.31.29_AM](/uploads/0bc92369fb2f9bc335773f6abec421c3/Screen_Shot_2016-06-16_at_8.31.29_AM.png)

See merge request !3749

19 files changed, 533 insertions, 56 deletions

diff --git a/CHANGELOG b/CHANGELOG
index f3ac35be81f..440ae348c31 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -65,6 +65,7 @@ v 8.9.0 (unreleased)
   - Remove 'main language' feature
   - Toggle whitespace button now available for compare branches diffs #17881
   - Pipelines can be canceled only when there are running builds
+  - Allow authentication using personal access tokens
   - Use downcased path to container repository as this is expected path by Docker
   - Projects pending deletion will render a 404 page
   - Measure queue duration between gitlab-workhorse and Rails
diff --git a/app/assets/stylesheets/framework/variables.scss b/app/assets/stylesheets/framework/variables.scss
index 148b00ac853..c37574ca7a1 100644
--- a/app/assets/stylesheets/framework/variables.scss
+++ b/app/assets/stylesheets/framework/variables.scss
@@ -268,5 +268,10 @@ $calendar-hover-bg: #ecf3fe;
 $calendar-border-color: rgba(#000, .1);
 $calendar-unselectable-bg: #faf9f9;
 
+/*
+ * Personal Access Tokens
+ */
+$personal-access-tokens-disabled-label-color: #bbb;
+
 $ci-output-bg: #1d1f21;
 $ci-text-color: #c5c8c6;
diff --git a/app/assets/stylesheets/pages/profile.scss b/app/assets/stylesheets/pages/profile.scss
index 167ab40d881..46371ec6871 100644
--- a/app/assets/stylesheets/pages/profile.scss
+++ b/app/assets/stylesheets/pages/profile.scss
@@ -192,6 +192,25 @@
   }
 }
 
+.personal-access-tokens-never-expires-label {
+  color: $personal-access-tokens-disabled-label-color;
+}
+
+.datepicker.personal-access-tokens-expires-at .ui-state-disabled span {
+  text-align: center;
+}
+
+.created-personal-access-token-container {
+  #created-personal-access-token {
+    width: 90%;
+    display: inline;
+  }
+
+  .btn-clipboard {
+    margin-left: 5px;
+  }
+}
+
 .user-profile {
   @media (max-width: $screen-xs-max) {
     .cover-block {
diff --git a/app/controllers/application_controller.rb b/app/controllers/application_controller.rb
index cd6ae507cf1..72d1b97bf56 100644
--- a/app/controllers/application_controller.rb
+++ b/app/controllers/application_controller.rb
@@ -8,7 +8,7 @@ class ApplicationController < ActionController::Base
   include PageLayoutHelper
   include WorkhorseHelper
 
-  before_action :authenticate_user_from_token!
+  before_action :authenticate_user_from_private_token!
   before_action :authenticate_user!
   before_action :validate_user_service_ticket!
   before_action :reject_blocked!
@@ -64,17 +64,10 @@ class ApplicationController < ActionController::Base
     end
   end
 
-  # From https://github.com/plataformatec/devise/wiki/How-To:-Simple-Token-Authentication-Example
-  # https://gist.github.com/josevalim/fb706b1e933ef01e4fb6
-  def authenticate_user_from_token!
-    user_token = if params[:authenticity_token].presence
-                   params[:authenticity_token].presence
-                 elsif params[:private_token].presence
-                   params[:private_token].presence
-                 elsif request.headers['PRIVATE-TOKEN'].present?
-                   request.headers['PRIVATE-TOKEN']
-                 end
-    user = user_token && User.find_by_authentication_token(user_token.to_s)
+  # This filter handles both private tokens and personal access tokens
+  def authenticate_user_from_private_token!
+    token_string = params[:private_token].presence || request.headers['PRIVATE-TOKEN'].presence
+    user = User.find_by_authentication_token(token_string) || User.find_by_personal_access_token(token_string)
 
     if user
       # Notice we are passing store false, so the user is not
diff --git a/app/controllers/profiles/personal_access_tokens_controller.rb b/app/controllers/profiles/personal_access_tokens_controller.rb
new file mode 100644
index 00000000000..508b82a9a6c
--- /dev/null
+++ b/app/controllers/profiles/personal_access_tokens_controller.rb
@@ -0,0 +1,42 @@
+class Profiles::PersonalAccessTokensController < Profiles::ApplicationController
+  before_action :load_personal_access_tokens, only: :index
+
+  def index
+    @personal_access_token = current_user.personal_access_tokens.build
+  end
+
+  def create
+    @personal_access_token = current_user.personal_access_tokens.generate(personal_access_token_params)
+
+    if @personal_access_token.save
+      flash[:personal_access_token] = @personal_access_token.token
+      redirect_to profile_personal_access_tokens_path, notice: "Your new personal access token has been created."
+    else
+      load_personal_access_tokens
+      render :index
+    end
+  end
+
+  def revoke
+    @personal_access_token = current_user.personal_access_tokens.find(params[:id])
+
+    if @personal_access_token.revoke!
+      flash[:notice] = "Revoked personal access token #{@personal_access_token.name}!"
+    else
+      flash[:alert] = "Could not revoke personal access token #{@personal_access_token.name}."
+    end
+
+    redirect_to profile_personal_access_tokens_path
+  end
+
+  private
+
+  def personal_access_token_params
+    params.require(:personal_access_token).permit(:name, :expires_at)
+  end
+
+  def load_personal_access_tokens
+    @active_personal_access_tokens = current_user.personal_access_tokens.active.order(:expires_at)
+    @inactive_personal_access_tokens = current_user.personal_access_tokens.inactive
+  end
+end
diff --git a/app/models/personal_access_token.rb b/app/models/personal_access_token.rb
new file mode 100644
index 00000000000..c4b095e0c04
--- /dev/null
+++ b/app/models/personal_access_token.rb
@@ -0,0 +1,20 @@
+class PersonalAccessToken < ActiveRecord::Base
+  include TokenAuthenticatable
+  add_authentication_token_field :token
+
+  belongs_to :user
+
+  scope :active, -> { where(revoked: false).where("expires_at >= NOW() OR expires_at IS NULL") }
+  scope :inactive, -> { where("revoked = true OR expires_at < NOW()") }
+
+  def self.generate(params)
+    personal_access_token = self.new(params)
+    personal_access_token.ensure_token
+    personal_access_token
+  end
+
+  def revoke!
+    self.revoked = true
+    self.save
+  end
+end
diff --git a/app/models/user.rb b/app/models/user.rb
index 8d0427da5ab..051745fe252 100644
--- a/app/models/user.rb
+++ b/app/models/user.rb
@@ -51,6 +51,7 @@ class User < ActiveRecord::Base
   # Profile
   has_many :keys, dependent: :destroy
   has_many :emails, dependent: :destroy
+  has_many :personal_access_tokens, dependent: :destroy
   has_many :identities, dependent: :destroy, autosave: true
   has_many :u2f_registrations, dependent: :destroy
 
@@ -267,6 +268,11 @@ class User < ActiveRecord::Base
       find_by!('lower(username) = ?', username.downcase)
     end
 
+    def find_by_personal_access_token(token_string)
+      personal_access_token = PersonalAccessToken.active.find_by_token(token_string) if token_string
+      personal_access_token.user if personal_access_token
+    end
+
     def by_username_or_id(name_or_id)
       find_by('users.username = ? OR users.id = ?', name_or_id.to_s, name_or_id.to_i)
     end
diff --git a/app/views/layouts/nav/_profile.html.haml b/app/views/layouts/nav/_profile.html.haml
index d4b1f477f3f..bb6f14a6225 100644
--- a/app/views/layouts/nav/_profile.html.haml
+++ b/app/views/layouts/nav/_profile.html.haml
@@ -13,6 +13,10 @@
       = link_to applications_profile_path, title: 'Applications' do
         %span
           Applications
+  = nav_link(controller: :personal_access_tokens) do
+    = link_to profile_personal_access_tokens_path, title: 'Personal Access Tokens' do
+      %span
+        Personal Access Tokens
   = nav_link(controller: :emails) do
     = link_to profile_emails_path, title: 'Emails' do
       %span
diff --git a/app/views/profiles/personal_access_tokens/index.html.haml b/app/views/profiles/personal_access_tokens/index.html.haml
new file mode 100644
index 00000000000..1b45548bd02
--- /dev/null
+++ b/app/views/profiles/personal_access_tokens/index.html.haml
@@ -0,0 +1,105 @@
+- page_title "Personal Access Tokens"
+
+.row.prepend-top-default
+  .col-lg-3.profile-settings-sidebar
+    %h4.prepend-top-0
+      = page_title
+    %p
+      You can generate a personal access token for each application you use that needs access to the GitLab API.
+  .col-lg-9
+
+    - if flash[:personal_access_token]
+      .created-personal-access-token-container
+        %h5.prepend-top-0
+          Your New Personal Access Token
+        .form-group
+          = text_field_tag 'created-personal-access-token', flash[:personal_access_token], readonly: true, class: "form-control", 'aria-describedby' => "created-personal-access-token-help-block"
+          = clipboard_button(clipboard_text: flash[:personal_access_token])
+          %span#created-personal-access-token-help-block.help-block.text-danger Make sure you save it - you won't be able to access it again.
+
+      %hr
+
+    %h5.prepend-top-0
+      Add a Personal Access Token
+    %p.profile-settings-content
+      Pick a name for the application, and we'll give you a unique token.
+    = form_for [:profile, @personal_access_token],
+                method: :post, html: { class: 'js-requires-input' } do |f|
+
+      = form_errors(@personal_access_token)
+
+      .form-group
+        = f.label :name, class: 'label-light'
+        = f.text_field :name, class: "form-control", required: true
+
+      .form-group
+        = f.label :expires_at, class: 'label-light'
+        = f.text_field :expires_at, class: "datepicker form-control", required: false
+
+      .prepend-top-default
+        = f.submit 'Create Personal Access Token', class: "btn btn-create"
+
+    %hr
+
+    %h5 Active Personal Access Tokens (#{@active_personal_access_tokens.length})
+
+    - if @active_personal_access_tokens.present?
+      .table-responsive
+        %table.table.active-personal-access-tokens
+          %thead
+            %tr
+              %th Name
+              %th Created
+              %th Expires
+              %th
+          %tbody
+            - @active_personal_access_tokens.each do |token|
+              %tr
+                %td= token.name
+                %td= token.created_at.to_date.to_s(:medium)
+                %td
+                  - if token.expires_at.present?
+                    = token.expires_at.to_date.to_s(:medium)
+                  - else
+                    %span.personal-access-tokens-never-expires-label Never
+                %td= link_to "Revoke", revoke_profile_personal_access_token_path(token), method: :put, class: "btn btn-danger pull-right", data: { confirm: "Are you sure you want to revoke this token? This action cannot be undone." }
+
+    - else
+      .settings-message.text-center
+        You don't have any active tokens yet.
+
+    %hr
+
+    %h5 Inactive Personal Access Tokens (#{@inactive_personal_access_tokens.length})
+
+    - if @inactive_personal_access_tokens.present?
+      .table-responsive
+        %table.table.inactive-personal-access-tokens
+          %thead
+            %tr
+              %th Name
+              %th Created
+          %tbody
+            - @inactive_personal_access_tokens.each do |token|
+              %tr
+                %td= token.name
+                %td= token.created_at.to_date.to_s(:medium)
+
+    - else
+      .settings-message.text-center
+        There are no inactive tokens.
+
+
+:javascript
+  var date = $('#personal_access_token_expires_at').val();
+
+  var datepicker = $(".datepicker").datepicker({
+    dateFormat: "yy-mm-dd",
+    minDate: 0
+  });
+
+  $("#created-personal-access-token").click(function() {
+    this.select();
+  });
+
+  $("#created-personal-access-token").effect('highlight', { color: '#ffff99' }, 2000);
diff --git a/config/routes.rb b/config/routes.rb
index d52cbb22428..25c1f41dac4 100644
--- a/config/routes.rb
+++ b/config/routes.rb
@@ -348,6 +348,13 @@ Rails.application.routes.draw do
       resources :keys
       resources :emails, only: [:index, :create, :destroy]
       resource :avatar, only: [:destroy]
+
+      resources :personal_access_tokens, only: [:index, :create] do
+        member do
+          put :revoke
+        end
+      end
+
       resource :two_factor_auth, only: [:show, :create, :destroy] do
         member do
           post :create_u2f
diff --git a/db/migrate/20160415062917_create_personal_access_tokens.rb b/db/migrate/20160415062917_create_personal_access_tokens.rb
new file mode 100644
index 00000000000..ce0b33f32bd
--- /dev/null
+++ b/db/migrate/20160415062917_create_personal_access_tokens.rb
@@ -0,0 +1,13 @@
+class CreatePersonalAccessTokens < ActiveRecord::Migration
+  def change
+    create_table :personal_access_tokens do |t|
+      t.references :user, index: true, foreign_key: true, null: false
+      t.string :token, index: { unique: true }, null: false
+      t.string :name, null: false
+      t.boolean :revoked, default: false
+      t.datetime :expires_at
+
+      t.timestamps null: false
+    end
+  end
+end
diff --git a/db/schema.rb b/db/schema.rb
index d6a542a89fd..5a27e9d5cdc 100644
--- a/db/schema.rb
+++ b/db/schema.rb
@@ -756,6 +756,19 @@ ActiveRecord::Schema.define(version: 20160616084004) do
   add_index "oauth_applications", ["owner_id", "owner_type"], name: "index_oauth_applications_on_owner_id_and_owner_type", using: :btree
   add_index "oauth_applications", ["uid"], name: "index_oauth_applications_on_uid", unique: true, using: :btree
 
+  create_table "personal_access_tokens", force: :cascade do |t|
+    t.integer  "user_id",                    null: false
+    t.string   "token",                      null: false
+    t.string   "name",                       null: false
+    t.datetime "created_at",                 null: false
+    t.datetime "updated_at",                 null: false
+    t.boolean  "revoked",    default: false
+    t.datetime "expires_at"
+  end
+
+  add_index "personal_access_tokens", ["token"], name: "index_personal_access_tokens_on_token", unique: true, using: :btree
+  add_index "personal_access_tokens", ["user_id"], name: "index_personal_access_tokens_on_user_id", using: :btree
+
   create_table "project_group_links", force: :cascade do |t|
     t.integer  "project_id",                null: false
     t.integer  "group_id",                  null: false
@@ -1095,5 +1108,6 @@ ActiveRecord::Schema.define(version: 20160616084004) do
   add_index "web_hooks", ["created_at", "id"], name: "index_web_hooks_on_created_at_and_id", using: :btree
   add_index "web_hooks", ["project_id"], name: "index_web_hooks_on_project_id", using: :btree
 
+  add_foreign_key "personal_access_tokens", "users"
   add_foreign_key "u2f_registrations", "users"
 end
diff --git a/doc/api/README.md b/doc/api/README.md
index e3fc5a09f21..71bb01e0d51 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -44,13 +44,11 @@ The following documentation is for the [internal CI API](ci/README.md):
 
 ## Authentication
 
-All API requests require authentication. You need to pass a `private_token`
-parameter via query string or header. If passed as a header, the header name
-must be `PRIVATE-TOKEN` (uppercase and with a dash instead of an underscore).
-You can find or reset your private token in your account page (`/profile/account`).
+All API requests require authentication via a token. There are three types of tokens 
+available: private tokens, OAuth 2 tokens, and personal access tokens.
 
-If `private_token` is invalid or omitted, then an error message will be
-returned with status code `401`:
+If a token is invalid or omitted, an error message will be returned with 
+status code `401`:
 
 ```json
 {
@@ -58,42 +56,56 @@ returned with status code `401`:
 }
 ```
 
-API requests should be prefixed with `api` and the API version. The API version
-is defined in [`lib/api.rb`][lib-api-url].
+### Private Tokens
 
-Example of a valid API request:
+You need to pass a `private_token` parameter via query string or header. If passed as a 
+header, the header name must be `PRIVATE-TOKEN` (uppercase and with a dash instead of 
+an underscore). You can find or reset your private token in your account page
+(`/profile/account`).
 
-```shell
-GET https://gitlab.example.com/api/v3/projects?private_token=9koXpg98eAheJpvBs5tK
-```
+### OAuth 2 Tokens
 
-Example of a valid API request using cURL and authentication via header:
+You can use an OAuth 2 token to authenticate with the API by passing it either in the
+`access_token` parameter or in the `Authorization` header.
+
+Example of using the OAuth2 token in the header:
 
 ```shell
-curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects"
+curl -H "Authorization: Bearer OAUTH-TOKEN" https://gitlab.example.com/api/v3/projects
 ```
 
-The API uses JSON to serialize data. You don't need to specify `.json` at the
-end of an API URL.
+Read more about [GitLab as an OAuth2 client](oauth2.md).
+
+### Personal Access Tokens
 
-## Authentication with OAuth2 token
+> **Note:** This feature was [introduced][ce-3749] in GitLab 8.8
 
-Instead of the `private_token` you can transmit the OAuth2 access token as a
-header or as a parameter.
+You can create as many personal access tokens as you like from your GitLab 
+profile (`/profile/personal_access_tokens`); perhaps one for each application
+that needs access to the GitLab API.
 
-Example of OAuth2 token as a parameter:
+Once you have your token, pass it to the API using either the `private_token`
+parameter or the `PRIVATE-TOKEN` header.
+
+## Basic Usage
+
+API requests should be prefixed with `api` and the API version. The API version
+is defined in [`lib/api.rb`][lib-api-url].
+
+Example of a valid API request:
 
 ```shell
-curl https://gitlab.example.com/api/v3/user?access_token=OAUTH-TOKEN
+GET https://gitlab.example.com/api/v3/projects?private_token=9koXpg98eAheJpvBs5tK
 ```
 
-Example of OAuth2 token as a header:
+Example of a valid API request using cURL and authentication via header:
 
 ```shell
-curl -H "Authorization: Bearer OAUTH-TOKEN" https://example.com/api/v3/user
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects"
 ```
 
-Read more about [GitLab as an OAuth2 client](oauth2.md).
+The API uses JSON to serialize data. You don't need to specify `.json` at the
+end of an API URL.
 
 ## Status codes
 
@@ -330,3 +342,4 @@ programming languages. Visit the [GitLab website] for a complete list.
 
 [GitLab website]: https://about.gitlab.com/applications/#api-clients "Clients using the GitLab API"
 [lib-api-url]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/api/api.rb
+[ce-3749]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3749
diff --git a/lib/api/helpers.rb b/lib/api/helpers.rb
index de5959e3aae..77e407b54c5 100644
--- a/lib/api/helpers.rb
+++ b/lib/api/helpers.rb
@@ -9,9 +9,13 @@ module API
       [ true, 1, '1', 't', 'T', 'true', 'TRUE', 'on', 'ON' ].include?(value)
     end
 
+    def find_user_by_private_token
+      token_string = (params[PRIVATE_TOKEN_PARAM] || env[PRIVATE_TOKEN_HEADER]).to_s
+      User.find_by_authentication_token(token_string) || User.find_by_personal_access_token(token_string)
+    end
+
     def current_user
-      private_token = (params[PRIVATE_TOKEN_PARAM] || env[PRIVATE_TOKEN_HEADER]).to_s
-      @current_user ||= (User.find_by(authentication_token: private_token) || doorkeeper_guard)
+      @current_user ||= (find_user_by_private_token || doorkeeper_guard)
 
       unless @current_user && Gitlab::UserAccess.allowed?(@current_user)
         return nil
@@ -33,7 +37,7 @@ module API
       identifier ||= params[SUDO_PARAM] || env[SUDO_HEADER]
 
       # Regex for integers
-      if !!(identifier =~ /^[0-9]+$/)
+      if !!(identifier =~ /\A[0-9]+\z/)
         identifier.to_i
       else
         identifier
diff --git a/spec/controllers/application_controller_spec.rb b/spec/controllers/application_controller_spec.rb
index 186239d3096..ff5b3916273 100644
--- a/spec/controllers/application_controller_spec.rb
+++ b/spec/controllers/application_controller_spec.rb
@@ -30,4 +30,75 @@ describe ApplicationController do
       controller.send(:check_password_expiration)
     end
   end
+
+  describe "#authenticate_user_from_token!" do
+    describe "authenticating a user from a private token" do
+      controller(ApplicationController) do
+        def index
+          render text: "authenticated"
+        end
+      end
+
+      let(:user) { create(:user) }
+
+      context "when the 'private_token' param is populated with the private token" do
+        it "logs the user in" do
+          get :index, private_token: user.private_token
+          expect(response.status).to eq(200)
+          expect(response.body).to eq("authenticated")
+        end
+      end
+
+
+      context "when the 'PRIVATE-TOKEN' header is populated with the private token" do
+        it "logs the user in" do
+          @request.headers['PRIVATE-TOKEN'] = user.private_token
+          get :index
+          expect(response.status).to eq(200)
+          expect(response.body).to eq("authenticated")
+        end
+      end
+
+      it "doesn't log the user in otherwise" do
+        @request.headers['PRIVATE-TOKEN'] = "token"
+        get :index, private_token: "token", authenticity_token: "token"
+        expect(response.status).not_to eq(200)
+        expect(response.body).not_to eq("authenticated")
+      end
+    end
+
+    describe "authenticating a user from a personal access token" do
+      controller(ApplicationController) do
+        def index
+          render text: 'authenticated'
+        end
+      end
+
+      let(:user) { create(:user) }
+      let(:personal_access_token) { create(:personal_access_token, user: user) }
+
+      context "when the 'personal_access_token' param is populated with the personal access token" do
+        it "logs the user in" do
+          get :index, private_token: personal_access_token.token
+          expect(response.status).to eq(200)
+          expect(response.body).to eq('authenticated')
+        end
+      end
+
+      context "when the 'PERSONAL_ACCESS_TOKEN' header is populated with the personal access token" do
+        it "logs the user in" do
+          @request.headers["PRIVATE-TOKEN"] = personal_access_token.token
+          get :index
+          expect(response.status).to eq(200)
+          expect(response.body).to eq('authenticated')
+        end
+      end
+
+      it "doesn't log the user in otherwise" do
+        get :index, private_token: "token"
+        expect(response.status).not_to eq(200)
+        expect(response.body).not_to eq('authenticated')
+      end
+    end
+  end
 end
diff --git a/spec/factories/personal_access_tokens.rb b/spec/factories/personal_access_tokens.rb
new file mode 100644
index 00000000000..da4c72bcb5b
--- /dev/null
+++ b/spec/factories/personal_access_tokens.rb
@@ -0,0 +1,9 @@
+FactoryGirl.define do
+  factory :personal_access_token do
+    user
+    token { SecureRandom.hex(50) }
+    name { FFaker::Product.brand }
+    revoked false
+    expires_at { 5.days.from_now }
+  end
+end
diff --git a/spec/features/profiles/personal_access_tokens_spec.rb b/spec/features/profiles/personal_access_tokens_spec.rb
new file mode 100644
index 00000000000..a85930c7543
--- /dev/null
+++ b/spec/features/profiles/personal_access_tokens_spec.rb
@@ -0,0 +1,94 @@
+require 'spec_helper'
+
+describe 'Profile > Personal Access Tokens', feature: true, js: true do
+  let(:user) { create(:user) }
+
+  def active_personal_access_tokens
+    find(".table.active-personal-access-tokens")
+  end
+
+  def inactive_personal_access_tokens
+    find(".table.inactive-personal-access-tokens")
+  end
+
+  def created_personal_access_token
+    find("#created-personal-access-token").value
+  end
+
+  def disallow_personal_access_token_saves!
+    allow_any_instance_of(PersonalAccessToken).to receive(:save).and_return(false)
+    errors = ActiveModel::Errors.new(PersonalAccessToken.new).tap { |e| e.add(:name, "cannot be nil") }
+    allow_any_instance_of(PersonalAccessToken).to receive(:errors).and_return(errors)
+  end
+
+  before do
+    login_as(user)
+  end
+
+  describe "token creation" do
+    it "allows creation of a token" do
+      visit profile_personal_access_tokens_path
+      fill_in "Name", with: FFaker::Product.brand
+
+      expect {click_on "Create Personal Access Token"}.to change { PersonalAccessToken.count }.by(1)
+      expect(created_personal_access_token).to eq(PersonalAccessToken.last.token)
+      expect(active_personal_access_tokens).to have_text(PersonalAccessToken.last.name)
+      expect(active_personal_access_tokens).to have_text("Never")
+    end
+
+    it "allows creation of a token with an expiry date" do
+      visit profile_personal_access_tokens_path
+      fill_in "Name", with: FFaker::Product.brand
+
+      # Set date to 1st of next month
+      find_field("Expires at").trigger('focus')
+      find("a[title='Next']").click
+      click_on "1"
+
+      expect {click_on "Create Personal Access Token"}.to change { PersonalAccessToken.count }.by(1)
+      expect(created_personal_access_token).to eq(PersonalAccessToken.last.token)
+      expect(active_personal_access_tokens).to have_text(PersonalAccessToken.last.name)
+      expect(active_personal_access_tokens).to have_text(Date.today.next_month.at_beginning_of_month.to_s(:medium))
+    end
+
+    context "when creation fails" do
+      it "displays an error message" do
+        disallow_personal_access_token_saves!
+        visit profile_personal_access_tokens_path
+        fill_in "Name", with: FFaker::Product.brand
+
+        expect { click_on "Create Personal Access Token" }.not_to change { PersonalAccessToken.count }
+        expect(page).to have_content("Name cannot be nil")
+      end
+    end
+  end
+
+  describe "inactive tokens" do
+    let!(:personal_access_token) { create(:personal_access_token, user: user) }
+
+    it "allows revocation of an active token" do
+      visit profile_personal_access_tokens_path
+      click_on "Revoke"
+
+      expect(inactive_personal_access_tokens).to have_text(personal_access_token.name)
+    end
+
+    it "moves expired tokens to the 'inactive' section" do
+      personal_access_token.update(expires_at: 5.days.ago)
+      visit profile_personal_access_tokens_path
+
+      expect(inactive_personal_access_tokens).to have_text(personal_access_token.name)
+    end
+
+    context "when revocation fails" do
+      it "displays an error message" do
+        disallow_personal_access_token_saves!
+        visit profile_personal_access_tokens_path
+
+        expect { click_on "Revoke" }.not_to change { PersonalAccessToken.inactive.count }
+        expect(active_personal_access_tokens).to have_text(personal_access_token.name)
+        expect(page).to have_content("Could not revoke")
+      end
+    end
+  end
+end
diff --git a/spec/models/personal_access_token_spec.rb b/spec/models/personal_access_token_spec.rb
new file mode 100644
index 00000000000..46eb71cef14
--- /dev/null
+++ b/spec/models/personal_access_token_spec.rb
@@ -0,0 +1,15 @@
+require 'spec_helper'
+
+describe PersonalAccessToken, models: true do
+  describe ".generate" do
+    it "generates a random token" do
+      personal_access_token = PersonalAccessToken.generate({})
+      expect(personal_access_token.token).to be_present
+    end
+
+    it "doesn't save the record" do
+      personal_access_token = PersonalAccessToken.generate({})
+      expect(personal_access_token).not_to be_persisted
+    end
+  end
+end
diff --git a/spec/requests/api/api_helpers_spec.rb b/spec/requests/api/api_helpers_spec.rb
index 0c19094ec54..f22db61e744 100644
--- a/spec/requests/api/api_helpers_spec.rb
+++ b/spec/requests/api/api_helpers_spec.rb
@@ -1,8 +1,10 @@
 require 'spec_helper'
 
-describe API, api: true do
+describe API::Helpers, api: true do
+
   include API::Helpers
   include ApiHelpers
+
   let(:user) { create(:user) }
   let(:admin) { create(:admin) }
   let(:key) { create(:key, user: user) }
@@ -39,24 +41,64 @@ describe API, api: true do
   end
 
   describe ".current_user" do
-    it "should return nil for an invalid token" do
-      env[API::Helpers::PRIVATE_TOKEN_HEADER] = 'invalid token'
-      allow_any_instance_of(self.class).to receive(:doorkeeper_guard){ false }
-      expect(current_user).to be_nil
-    end
-
-    it "should return nil for a user without access" do
-      env[API::Helpers::PRIVATE_TOKEN_HEADER] = user.private_token
-      allow(Gitlab::UserAccess).to receive(:allowed?).and_return(false)
-      expect(current_user).to be_nil
+    describe "when authenticating using a user's private token" do
+      it "should return nil for an invalid token" do
+        env[API::Helpers::PRIVATE_TOKEN_HEADER] = 'invalid token'
+        allow_any_instance_of(self.class).to receive(:doorkeeper_guard){ false }
+        expect(current_user).to be_nil
+      end
+
+      it "should return nil for a user without access" do
+        env[API::Helpers::PRIVATE_TOKEN_HEADER] = user.private_token
+        allow(Gitlab::UserAccess).to receive(:allowed?).and_return(false)
+        expect(current_user).to be_nil
+      end
+
+      it "should leave user as is when sudo not specified" do
+        env[API::Helpers::PRIVATE_TOKEN_HEADER] = user.private_token
+        expect(current_user).to eq(user)
+        clear_env
+        params[API::Helpers::PRIVATE_TOKEN_PARAM] = user.private_token
+        expect(current_user).to eq(user)
+      end
     end
 
-    it "should leave user as is when sudo not specified" do
-      env[API::Helpers::PRIVATE_TOKEN_HEADER] = user.private_token
-      expect(current_user).to eq(user)
-      clear_env
-      params[API::Helpers::PRIVATE_TOKEN_PARAM] = user.private_token
-      expect(current_user).to eq(user)
+    describe "when authenticating using a user's personal access tokens" do
+      let(:personal_access_token) { create(:personal_access_token, user: user) }
+
+      it "should return nil for an invalid token" do
+        env[API::Helpers::PRIVATE_TOKEN_HEADER] = 'invalid token'
+        allow_any_instance_of(self.class).to receive(:doorkeeper_guard){ false }
+        expect(current_user).to be_nil
+      end
+
+      it "should return nil for a user without access" do
+        env[API::Helpers::PRIVATE_TOKEN_HEADER] = personal_access_token.token
+        allow(Gitlab::UserAccess).to receive(:allowed?).and_return(false)
+        expect(current_user).to be_nil
+      end
+
+      it "should leave user as is when sudo not specified" do
+        env[API::Helpers::PRIVATE_TOKEN_HEADER] = personal_access_token.token
+        expect(current_user).to eq(user)
+        clear_env
+        params[API::Helpers::PRIVATE_TOKEN_PARAM] = personal_access_token.token
+        expect(current_user).to eq(user)
+      end
+
+      it 'does not allow revoked tokens' do
+        personal_access_token.revoke!
+        env[API::Helpers::PRIVATE_TOKEN_HEADER] = personal_access_token.token
+        allow_any_instance_of(self.class).to receive(:doorkeeper_guard){ false }
+        expect(current_user).to be_nil
+      end
+
+      it 'does not allow expired tokens' do
+        personal_access_token.update_attributes!(expires_at: 1.day.ago)
+        env[API::Helpers::PRIVATE_TOKEN_HEADER] = personal_access_token.token
+        allow_any_instance_of(self.class).to receive(:doorkeeper_guard){ false }
+        expect(current_user).to be_nil
+      end
     end
 
     it "should change current user to sudo when admin" do