From 61ba0952602692d9ff088aa4e45893298b3cb8fa Mon Sep 17 00:00:00 2001 From: soartec-lab Date: Mon, 11 Nov 2019 23:40:48 +0900 Subject: [PATCH] Add `HTTP Token authentication` section to guide [skip ci] --- guides/source/action_controller_overview.md | 27 ++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/guides/source/action_controller_overview.md b/guides/source/action_controller_overview.md index a5d097637e..b3c9ddf8ee 100644 --- a/guides/source/action_controller_overview.md +++ b/guides/source/action_controller_overview.md @@ -860,10 +860,11 @@ NOTE: In the above case it would make more sense to use the `content_type` sette HTTP Authentications -------------------- -Rails comes with two built-in HTTP authentication mechanisms: +Rails comes with three built-in HTTP authentication mechanisms: * Basic Authentication * Digest Authentication +* Token Authentication ### HTTP Basic Authentication @@ -899,6 +900,30 @@ end As seen in the example above, the `authenticate_or_request_with_http_digest` block takes only one argument - the username. And the block returns the password. Returning `false` or `nil` from the `authenticate_or_request_with_http_digest` will cause authentication failure. +### Token authentication + +HTTP token authentication is a scheme to enable the usage of Bearer tokens in the HTTP `Authorization` header. There are many token formats available and describing them is outside the scope of this document. + +As an example, suppose you want to use an authentication token that has been issued in advance to perform authentication and access. Implementing token authentication with Rails is quite easy and only requires using one method, `authenticate_or_request_with_http_token`. + +```ruby +class PostsController < ApplicationController + TOKEN = "secret" + + before_action :authenticate + + private + + def authenticate + authenticate_or_request_with_http_token do |token, options| + ActiveSupport::SecurityUtils.secure_compare(token, TOKEN) + end + end +end +``` + +As seen in the example above, the `authenticate_or_request_with_http_token` block takes two arguments - the token and a `Hash` containing the options that were parsed from the HTTP `Authorization` header. The block should return `true` if the authentication is successful. Returning `false` or `nil` on it will cause an authentication failure. + Streaming and File Downloads ----------------------------