digix_devise_token_auth 0.1.44

Sign up to get free protection for your applications and to get access to all the features.
Files changed (149) hide show
  1. checksums.yaml +7 -0
  2. data/LICENSE +13 -0
  3. data/README.md +952 -0
  4. data/Rakefile +35 -0
  5. data/app/controllers/devise_token_auth/application_controller.rb +76 -0
  6. data/app/controllers/devise_token_auth/concerns/resource_finder.rb +43 -0
  7. data/app/controllers/devise_token_auth/concerns/set_user_by_token.rb +165 -0
  8. data/app/controllers/devise_token_auth/confirmations_controller.rb +30 -0
  9. data/app/controllers/devise_token_auth/omniauth_callbacks_controller.rb +243 -0
  10. data/app/controllers/devise_token_auth/passwords_controller.rb +202 -0
  11. data/app/controllers/devise_token_auth/registrations_controller.rb +205 -0
  12. data/app/controllers/devise_token_auth/sessions_controller.rb +133 -0
  13. data/app/controllers/devise_token_auth/token_validations_controller.rb +29 -0
  14. data/app/controllers/devise_token_auth/unlocks_controller.rb +89 -0
  15. data/app/models/devise_token_auth/concerns/user.rb +260 -0
  16. data/app/models/devise_token_auth/concerns/user_omniauth_callbacks.rb +26 -0
  17. data/app/validators/email_validator.rb +21 -0
  18. data/app/views/devise/mailer/confirmation_instructions.html.erb +5 -0
  19. data/app/views/devise/mailer/reset_password_instructions.html.erb +8 -0
  20. data/app/views/devise/mailer/unlock_instructions.html.erb +7 -0
  21. data/app/views/devise_token_auth/omniauth_external_window.html.erb +38 -0
  22. data/config/initializers/devise.rb +196 -0
  23. data/config/locales/da-DK.yml +50 -0
  24. data/config/locales/de.yml +49 -0
  25. data/config/locales/en.yml +50 -0
  26. data/config/locales/es.yml +49 -0
  27. data/config/locales/fr.yml +49 -0
  28. data/config/locales/it.yml +46 -0
  29. data/config/locales/ja.yml +46 -0
  30. data/config/locales/nl.yml +30 -0
  31. data/config/locales/pl.yml +48 -0
  32. data/config/locales/pt-BR.yml +46 -0
  33. data/config/locales/pt.yml +48 -0
  34. data/config/locales/ro.yml +46 -0
  35. data/config/locales/ru.yml +50 -0
  36. data/config/locales/sq.yml +46 -0
  37. data/config/locales/uk.yml +59 -0
  38. data/config/locales/vi.yml +50 -0
  39. data/config/locales/zh-CN.yml +46 -0
  40. data/config/locales/zh-HK.yml +48 -0
  41. data/config/locales/zh-TW.yml +48 -0
  42. data/lib/devise_token_auth.rb +8 -0
  43. data/lib/devise_token_auth/controllers/helpers.rb +149 -0
  44. data/lib/devise_token_auth/controllers/url_helpers.rb +8 -0
  45. data/lib/devise_token_auth/engine.rb +90 -0
  46. data/lib/devise_token_auth/rails/routes.rb +114 -0
  47. data/lib/devise_token_auth/url.rb +37 -0
  48. data/lib/devise_token_auth/version.rb +3 -0
  49. data/lib/generators/devise_token_auth/USAGE +31 -0
  50. data/lib/generators/devise_token_auth/install_generator.rb +160 -0
  51. data/lib/generators/devise_token_auth/install_views_generator.rb +16 -0
  52. data/lib/generators/devise_token_auth/templates/devise_token_auth.rb +48 -0
  53. data/lib/generators/devise_token_auth/templates/devise_token_auth_create_users.rb.erb +55 -0
  54. data/lib/generators/devise_token_auth/templates/user.rb +7 -0
  55. data/lib/tasks/devise_token_auth_tasks.rake +4 -0
  56. data/test/controllers/custom/custom_confirmations_controller_test.rb +21 -0
  57. data/test/controllers/custom/custom_omniauth_callbacks_controller_test.rb +29 -0
  58. data/test/controllers/custom/custom_passwords_controller_test.rb +75 -0
  59. data/test/controllers/custom/custom_registrations_controller_test.rb +54 -0
  60. data/test/controllers/custom/custom_sessions_controller_test.rb +37 -0
  61. data/test/controllers/custom/custom_token_validations_controller_test.rb +40 -0
  62. data/test/controllers/demo_group_controller_test.rb +153 -0
  63. data/test/controllers/demo_mang_controller_test.rb +284 -0
  64. data/test/controllers/demo_user_controller_test.rb +601 -0
  65. data/test/controllers/devise_token_auth/confirmations_controller_test.rb +129 -0
  66. data/test/controllers/devise_token_auth/omniauth_callbacks_controller_test.rb +371 -0
  67. data/test/controllers/devise_token_auth/passwords_controller_test.rb +649 -0
  68. data/test/controllers/devise_token_auth/registrations_controller_test.rb +878 -0
  69. data/test/controllers/devise_token_auth/sessions_controller_test.rb +500 -0
  70. data/test/controllers/devise_token_auth/token_validations_controller_test.rb +90 -0
  71. data/test/controllers/devise_token_auth/unlocks_controller_test.rb +194 -0
  72. data/test/controllers/overrides/confirmations_controller_test.rb +43 -0
  73. data/test/controllers/overrides/omniauth_callbacks_controller_test.rb +49 -0
  74. data/test/controllers/overrides/passwords_controller_test.rb +66 -0
  75. data/test/controllers/overrides/registrations_controller_test.rb +40 -0
  76. data/test/controllers/overrides/sessions_controller_test.rb +33 -0
  77. data/test/controllers/overrides/token_validations_controller_test.rb +41 -0
  78. data/test/dummy/README.rdoc +28 -0
  79. data/test/dummy/app/controllers/application_controller.rb +16 -0
  80. data/test/dummy/app/controllers/auth_origin_controller.rb +5 -0
  81. data/test/dummy/app/controllers/custom/confirmations_controller.rb +13 -0
  82. data/test/dummy/app/controllers/custom/omniauth_callbacks_controller.rb +11 -0
  83. data/test/dummy/app/controllers/custom/passwords_controller.rb +40 -0
  84. data/test/dummy/app/controllers/custom/registrations_controller.rb +39 -0
  85. data/test/dummy/app/controllers/custom/sessions_controller.rb +29 -0
  86. data/test/dummy/app/controllers/custom/token_validations_controller.rb +19 -0
  87. data/test/dummy/app/controllers/demo_group_controller.rb +13 -0
  88. data/test/dummy/app/controllers/demo_mang_controller.rb +12 -0
  89. data/test/dummy/app/controllers/demo_user_controller.rb +25 -0
  90. data/test/dummy/app/controllers/overrides/confirmations_controller.rb +26 -0
  91. data/test/dummy/app/controllers/overrides/omniauth_callbacks_controller.rb +14 -0
  92. data/test/dummy/app/controllers/overrides/passwords_controller.rb +33 -0
  93. data/test/dummy/app/controllers/overrides/registrations_controller.rb +27 -0
  94. data/test/dummy/app/controllers/overrides/sessions_controller.rb +36 -0
  95. data/test/dummy/app/controllers/overrides/token_validations_controller.rb +23 -0
  96. data/test/dummy/app/helpers/application_helper.rb +1065 -0
  97. data/test/dummy/app/models/evil_user.rb +3 -0
  98. data/test/dummy/app/models/lockable_user.rb +5 -0
  99. data/test/dummy/app/models/mang.rb +3 -0
  100. data/test/dummy/app/models/nice_user.rb +7 -0
  101. data/test/dummy/app/models/only_email_user.rb +5 -0
  102. data/test/dummy/app/models/scoped_user.rb +7 -0
  103. data/test/dummy/app/models/unconfirmable_user.rb +8 -0
  104. data/test/dummy/app/models/unregisterable_user.rb +7 -0
  105. data/test/dummy/app/models/user.rb +18 -0
  106. data/test/dummy/app/views/layouts/application.html.erb +14 -0
  107. data/test/dummy/config.ru +16 -0
  108. data/test/dummy/config/application.rb +24 -0
  109. data/test/dummy/config/application.yml.bk +0 -0
  110. data/test/dummy/config/boot.rb +5 -0
  111. data/test/dummy/config/environment.rb +5 -0
  112. data/test/dummy/config/environments/development.rb +44 -0
  113. data/test/dummy/config/environments/production.rb +82 -0
  114. data/test/dummy/config/environments/test.rb +48 -0
  115. data/test/dummy/config/initializers/assets.rb +8 -0
  116. data/test/dummy/config/initializers/backtrace_silencers.rb +7 -0
  117. data/test/dummy/config/initializers/cookies_serializer.rb +3 -0
  118. data/test/dummy/config/initializers/devise.rb +3 -0
  119. data/test/dummy/config/initializers/devise_token_auth.rb +22 -0
  120. data/test/dummy/config/initializers/figaro.rb +1 -0
  121. data/test/dummy/config/initializers/filter_parameter_logging.rb +4 -0
  122. data/test/dummy/config/initializers/inflections.rb +16 -0
  123. data/test/dummy/config/initializers/mime_types.rb +4 -0
  124. data/test/dummy/config/initializers/omniauth.rb +8 -0
  125. data/test/dummy/config/initializers/session_store.rb +3 -0
  126. data/test/dummy/config/initializers/wrap_parameters.rb +14 -0
  127. data/test/dummy/config/routes.rb +72 -0
  128. data/test/dummy/config/spring.rb +1 -0
  129. data/test/dummy/db/migrate/20140715061447_devise_token_auth_create_users.rb +63 -0
  130. data/test/dummy/db/migrate/20140715061805_devise_token_auth_create_mangs.rb +62 -0
  131. data/test/dummy/db/migrate/20140829044006_add_operating_thetan_to_user.rb +6 -0
  132. data/test/dummy/db/migrate/20140916224624_add_favorite_color_to_mangs.rb +5 -0
  133. data/test/dummy/db/migrate/20140928231203_devise_token_auth_create_evil_users.rb +64 -0
  134. data/test/dummy/db/migrate/20141222035835_devise_token_auth_create_only_email_users.rb +60 -0
  135. data/test/dummy/db/migrate/20141222053502_devise_token_auth_create_unregisterable_users.rb +61 -0
  136. data/test/dummy/db/migrate/20150409095712_devise_token_auth_create_nice_users.rb +61 -0
  137. data/test/dummy/db/migrate/20150708104536_devise_token_auth_create_unconfirmable_users.rb +61 -0
  138. data/test/dummy/db/migrate/20160103235141_devise_token_auth_create_scoped_users.rb +61 -0
  139. data/test/dummy/db/migrate/20160629184441_devise_token_auth_create_lockable_users.rb +61 -0
  140. data/test/dummy/db/schema.rb +258 -0
  141. data/test/dummy/lib/migration_database_helper.rb +29 -0
  142. data/test/integration/navigation_test.rb +10 -0
  143. data/test/lib/devise_token_auth/url_test.rb +24 -0
  144. data/test/lib/generators/devise_token_auth/install_generator_test.rb +187 -0
  145. data/test/lib/generators/devise_token_auth/install_views_generator_test.rb +23 -0
  146. data/test/models/only_email_user_test.rb +35 -0
  147. data/test/models/user_test.rb +169 -0
  148. data/test/test_helper.rb +77 -0
  149. metadata +342 -0
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: b55ff90a091e5670fb0a623b897bf1cffff375085012969f82b72ab539aa6fb8
4
+ data.tar.gz: 3199f7d7dc44082f8a97e53f7b1121d1236402ce8a3ea71029324e838e49841d
5
+ SHA512:
6
+ metadata.gz: cb14ed6bd87764a5ceb173f672a613f4cdf6cf01c746244e6d8e3c8796ee4e6111793fc39253173ebe86b99778e05a48f4f5fc4335072598983a0314ff3d5408
7
+ data.tar.gz: 203a9ddf9012b7381ff1997e2480670377e0d33754f19ef9239952897df6513881581edf6e6fa5273b502407c1b4762ad4e45525286e797aff912b702ed0f1a8
data/LICENSE ADDED
@@ -0,0 +1,13 @@
1
+ DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
2
+ Version 2, December 2004
3
+
4
+ Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>
5
+
6
+ Everyone is permitted to copy and distribute verbatim or modified
7
+ copies of this license document, and changing it is allowed as long
8
+ as the name is changed.
9
+
10
+ DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
11
+ TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
12
+
13
+ 0. You just DO WHAT THE FUCK YOU WANT TO.
@@ -0,0 +1,952 @@
1
+ # Contributors wanted!
2
+
3
+ See our [Contribution Guidelines](https://github.com/lynndylanhurley/devise_token_auth/blob/master/.github/CONTRIBUTING.md). We're making an effort to bring back this gem and fix everything open! Feel free to submit pull requests, review pull requests, or review open issues. If you'd like to get in contact, [Zach Feldman](https://github.com/zachfeldman) has been wrangling this effort, you can reach him with his name @gmail. Further discussion of this in [this issue](https://github.com/lynndylanhurley/devise_token_auth/issues/969).
4
+
5
+ <hr>
6
+
7
+ ![Serious Trust](https://github.com/lynndylanhurley/devise_token_auth/raw/master/test/dummy/app/assets/images/logo.jpg "Serious Trust")
8
+
9
+ [![Gem Version](https://badge.fury.io/rb/devise_token_auth.svg)](http://badge.fury.io/rb/devise_token_auth)
10
+ [![Build Status](https://travis-ci.org/lynndylanhurley/devise_token_auth.svg?branch=master)](https://travis-ci.org/lynndylanhurley/devise_token_auth)
11
+ [![Code Climate](http://img.shields.io/codeclimate/github/lynndylanhurley/devise_token_auth.svg)](https://codeclimate.com/github/lynndylanhurley/devise_token_auth)
12
+ [![Test Coverage](http://img.shields.io/codeclimate/coverage/github/lynndylanhurley/devise_token_auth.svg)](https://codeclimate.com/github/lynndylanhurley/devise_token_auth)
13
+ [![Dependency Status](https://gemnasium.com/lynndylanhurley/devise_token_auth.svg)](https://gemnasium.com/lynndylanhurley/devise_token_auth)
14
+ [![Downloads](https://img.shields.io/gem/dt/devise_token_auth.svg)](https://rubygems.org/gems/devise_token_auth)
15
+
16
+ ## Simple, secure token based authentication for Rails.
17
+
18
+ [![Join the chat at https://gitter.im/lynndylanhurley/devise_token_auth](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/lynndylanhurley/devise_token_auth?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
19
+
20
+ This gem provides the following features:
21
+
22
+ * Seamless integration with:
23
+ * [ng-token-auth](https://github.com/lynndylanhurley/ng-token-auth) for [AngularJS](https://github.com/angular/angular.js)
24
+ * [Angular2-Token](https://github.com/neroniaky/angular2-token) for [Angular2](https://github.com/angular/angular)
25
+ * [redux-token-auth](https://github.com/kylecorbelli/redux-token-auth) for [React with Redux](https://github.com/reactjs/react-redux)
26
+ * [jToker](https://github.com/lynndylanhurley/j-toker) for [jQuery](https://jquery.com/)
27
+ * Oauth2 authentication using [OmniAuth](https://github.com/intridea/omniauth).
28
+ * Email authentication using [Devise](https://github.com/plataformatec/devise), including:
29
+ * User registration
30
+ * Password reset
31
+ * Account updates
32
+ * Account deletion
33
+ * Support for [multiple user models](https://github.com/lynndylanhurley/devise_token_auth#using-multiple-models).
34
+ * It is [secure](#security).
35
+
36
+ # Live Demos
37
+
38
+ [Here is a demo](http://ng-token-auth-demo.herokuapp.com/) of this app running with the [ng-token-auth](https://github.com/lynndylanhurley/ng-token-auth) module and [AngularJS](https://github.com/angular/angular.js).
39
+
40
+ [Here is a demo](https://angular2-token.herokuapp.com) of this app running with the [Angular2-Token](https://github.com/neroniaky/angular2-token) service and [Angular2](https://github.com/angular/angular).
41
+
42
+ [Here is a demo](https://j-toker-demo.herokuapp.com/) of this app using the [jToker](https://github.com/lynndylanhurley/j-toker) plugin and [React](http://facebook.github.io/react/).
43
+
44
+ The fully configured api used in these demos can be found [here](https://github.com/lynndylanhurley/devise_token_auth_demo).
45
+
46
+ # Troubleshooting
47
+
48
+ Please read the [issue reporting guidelines](#issue-reporting) before posting issues.
49
+
50
+ # Table of Contents
51
+
52
+ * [Dependencies](#dependencies)
53
+ * [Configuration TL;DR](#configuration-tldr)
54
+ * [Usage TL;DR](#usage-tldr)
55
+ * [Configuration Continued](#configuration-cont)
56
+ * [Initializer Settings](#initializer-settings)
57
+ * [OmniAuth Authentication](#omniauth-authentication)
58
+ * [OmniAuth Provider Settings](#omniauth-provider-settings)
59
+ * [Email Authentication](#email-authentication)
60
+ * [Customizing Devise Verbiage](#customizing-devise-verbiage)
61
+ * [Cross Origin Requests (CORS)](#cors)
62
+ * [Usage Continued](#usage-cont)
63
+ * [Mounting Routes](#mounting-routes)
64
+ * [Controller Integration](#controller-methods)
65
+ * [Model Integration](#model-concerns)
66
+ * [Using Multiple User Classes](#using-multiple-models)
67
+ * [Excluding Modules](#excluding-modules)
68
+ * [Custom Controller Overrides](#custom-controller-overrides)
69
+ * [Passing blocks to Controllers](#passing-blocks-controllers)
70
+ * [Email Template Overrides](#email-template-overrides)
71
+ * [Testing](#testing)
72
+ * [Issue Reporting Guidelines](#issue-reporting)
73
+ * [FAQ](#faq)
74
+ * [Can I use this gem alongside standard Devise?](#can-i-use-this-gem-alongside-standard-devise)
75
+ * [Conceptual Diagrams](#conceptual)
76
+ * [Token Management](#about-token-management)
77
+ * [Batch Requests](#about-batch-requests)
78
+ * [Security](#security)
79
+ * [Callouts](#callouts)
80
+ * [Contribution Guidelines](#contributing)
81
+
82
+ # Dependencies
83
+ This project leverages the following gems:
84
+
85
+ * [Devise](https://github.com/plataformatec/devise)
86
+ * [OmniAuth](https://github.com/intridea/omniauth)
87
+
88
+ # Installation
89
+ Add the following to your `Gemfile`:
90
+
91
+ ~~~ruby
92
+ gem 'devise_token_auth'
93
+ ~~~
94
+
95
+ Then install the gem using bundle:
96
+
97
+ ~~~bash
98
+ bundle install
99
+ ~~~
100
+
101
+ # Configuration TL;DR
102
+
103
+ You will need to create a [user model](#model-concerns), [define routes](#mounting-routes), [include concerns](#controller-methods), and you may want to alter some of the [default settings](#initializer-settings) for this gem. Run the following command for an easy one-step installation:
104
+
105
+ ~~~bash
106
+ rails g devise_token_auth:install [USER_CLASS] [MOUNT_PATH]
107
+ ~~~
108
+
109
+ **Example**:
110
+
111
+ ~~~bash
112
+ rails g devise_token_auth:install User auth
113
+ ~~~
114
+
115
+ This generator accepts the following optional arguments:
116
+
117
+ | Argument | Default | Description |
118
+ |---|---|---|
119
+ | USER_CLASS | `User` | The name of the class to use for user authentication. |
120
+ | MOUNT_PATH | `auth` | The path at which to mount the authentication routes. [Read more](#usage-tldr). |
121
+
122
+ The following events will take place when using the install generator:
123
+
124
+ * An initializer will be created at `config/initializers/devise_token_auth.rb`. [Read more](#initializer-settings).
125
+
126
+ * A model will be created in the `app/models` directory. If the model already exists, a concern will be included at the top of the file. [Read more](#model-concerns).
127
+
128
+ * Routes will be appended to file at `config/routes.rb`. [Read more](#mounting-routes).
129
+
130
+ * A concern will be included by your application controller at `app/controllers/application_controller.rb`. [Read more](#controller-methods).
131
+
132
+ * A migration file will be created in the `db/migrate` directory. Inspect the migrations file, add additional columns if necessary, and then run the migration:
133
+
134
+ ~~~bash
135
+ rake db:migrate
136
+ ~~~
137
+
138
+ You may also need to configure the following items:
139
+
140
+ * **OmniAuth providers** when using 3rd party oauth2 authentication. [Read more](#omniauth-authentication).
141
+ * **Cross Origin Request Settings** when using cross-domain clients. [Read more](#cors).
142
+ * **Email** when using email registration. [Read more](#email-authentication).
143
+ * **Multiple model support** may require additional steps. [Read more](#using-multiple-models).
144
+
145
+ [Jump here](#configuration-cont) for more configuration information.
146
+
147
+ # Usage TL;DR
148
+
149
+ The following routes are available for use by your client. These routes live relative to the path at which this engine is mounted (`auth` by default). These routes correspond to the defaults used by the [ng-token-auth](https://github.com/lynndylanhurley/ng-token-auth) module for [AngularJS](https://angularjs.org/) and the [jToker](https://github.com/lynndylanhurley/j-toker) plugin for [jQuery](https://jquery.com/).
150
+
151
+ | path | method | purpose |
152
+ |:-----|:-------|:--------|
153
+ | / | POST | Email registration. Requires **`email`**, **`password`**, **`password_confirmation`**, and **`confirm_success_url`** params (this last one can be omitted if you have set `config.default_confirm_success_url` in `config/initializers/devise_token_auth.rb`). A verification email will be sent to the email address provided. Upon clicking the link in the confirmation email, the API will redirect to the URL specified in **`confirm_success_url`**. Accepted params can be customized using the [`devise_parameter_sanitizer`](https://github.com/plataformatec/devise#strong-parameters) system. |
154
+ | / | DELETE | Account deletion. This route will destroy users identified by their **`uid`**, **`access-token`** and **`client`** headers. |
155
+ | / | PUT | Account updates. This route will update an existing user's account settings. The default accepted params are **`password`** and **`password_confirmation`**, but this can be customized using the [`devise_parameter_sanitizer`](https://github.com/plataformatec/devise#strong-parameters) system. If **`config.check_current_password_before_update`** is set to `:attributes` the **`current_password`** param is checked before any update, if it is set to `:password` the **`current_password`** param is checked only if the request updates user password. |
156
+ | /sign_in | POST | Email authentication. Requires **`email`** and **`password`** as params. This route will return a JSON representation of the `User` model on successful login along with the `access-token` and `client` in the header of the response. |
157
+ | /sign_out | DELETE | Use this route to end the user's current session. This route will invalidate the user's authentication token. You must pass in **`uid`**, **`client`**, and **`access-token`** in the request headers. |
158
+ | /:provider | GET | Set this route as the destination for client authentication. Ideally this will happen in an external window or popup. [Read more](#omniauth-authentication). |
159
+ | /:provider/callback | GET/POST | Destination for the oauth2 provider's callback uri. `postMessage` events containing the authenticated user's data will be sent back to the main client window from this page. [Read more](#omniauth-authentication). |
160
+ | /validate_token | GET | Use this route to validate tokens on return visits to the client. Requires **`uid`**, **`client`**, and **`access-token`** as params. These values should correspond to the columns in your `User` table of the same names. |
161
+ | /password | POST | Use this route to send a password reset confirmation email to users that registered by email. Accepts **`email`** and **`redirect_url`** as params. The user matching the `email` param will be sent instructions on how to reset their password. `redirect_url` is the url to which the user will be redirected after visiting the link contained in the email. |
162
+ | /password | PUT | Use this route to change users' passwords. Requires **`password`** and **`password_confirmation`** as params. This route is only valid for users that registered by email (OAuth2 users will receive an error). It also checks **`current_password`** if **`config.check_current_password_before_update`** is not set `false` (disabled by default). |
163
+ | /password/edit | GET | Verify user by password reset token. This route is the destination URL for password reset confirmation. This route must contain **`reset_password_token`** and **`redirect_url`** params. These values will be set automatically by the confirmation email that is generated by the password reset request. |
164
+
165
+ [Jump here](#usage-cont) for more usage information.
166
+
167
+ # Configuration cont.
168
+
169
+ ## Initializer settings
170
+
171
+ The following settings are available for configuration in `config/initializers/devise_token_auth.rb`:
172
+
173
+ | Name | Default | Description|
174
+ |---|---|---|
175
+ | **`change_headers_on_each_request`** | `true` | By default the access-token header will change after each request. The client is responsible for keeping track of the changing tokens. Both [ng-token-auth](https://github.com/lynndylanhurley/ng-token-auth) and [jToker](https://github.com/lynndylanhurley/j-toker) do this out of the box. While this implementation is more secure, it can be difficult to manage. Set this to false to prevent the `access-token` header from changing after each request. [Read more](#about-token-management). |
176
+ | **`token_lifespan`** | `2.weeks` | Set the length of your tokens' lifespans. Users will need to re-authenticate after this duration of time has passed since their last login. |
177
+ | **`batch_request_buffer_throttle`** | `5.seconds` | Sometimes it's necessary to make several requests to the API at the same time. In this case, each request in the batch will need to share the same auth token. This setting determines how far apart the requests can be while still using the same auth token. [Read more](#about-batch-requests). |
178
+ | **`omniauth_prefix`** | `"/omniauth"` | This route will be the prefix for all oauth2 redirect callbacks. For example, using the default '/omniauth' setting, the github oauth2 provider will redirect successful authentications to '/omniauth/github/callback'. [Read more](#omniauth-provider-settings). |
179
+ | **`default_confirm_success_url`** | `nil` | By default this value is expected to be sent by the client so that the API knows where to redirect users after successful email confirmation. If this param is set, the API will redirect to this value when no value is provided by the client. |
180
+ | **`default_password_reset_url`** | `nil` | By default this value is expected to be sent by the client so that the API knows where to redirect users after successful password resets. If this param is set, the API will redirect to this value when no value is provided by the client. |
181
+ | **`redirect_whitelist`** | `nil` | As an added security measure, you can limit the URLs to which the API will redirect after email token validation (password reset, email confirmation, etc.). This value should be an array containing matches to the client URLs to be visited after validation. Wildcards are supported. |
182
+ | **`enable_standard_devise_support`** | `false` | By default, only Bearer Token authentication is implemented out of the box. If, however, you wish to integrate with legacy Devise authentication, you can do so by enabling this flag. NOTE: This feature is highly experimental! |
183
+ | **`remove_tokens_after_password_reset`** | `false` | By default, old tokens are not invalidated when password is changed. Enable this option if you want to make passwords updates to logout other devices. |
184
+ | **`default_callbacks`** | `true` | By default User model will include the `DeviseTokenAuth::Concerns::UserOmniauthCallbacks` concern, which has `email`, `uid` validations & `uid` synchronization callbacks. |
185
+ | **`bypass_sign_in`** | `true` | By default DeviseTokenAuth will not check user's `#active_for_authentication?` which includes confirmation check on each call (it will do it only on sign in). If you want it to be validated on each request (for example, to be able to deactivate logged in users on the fly), set it to false. |
186
+
187
+
188
+ Additionally, you can configure other aspects of devise by manually creating the traditional devise.rb file at `config/initializers/devise.rb`. Here are some examples of what you can do in this file:
189
+
190
+ ~~~ruby
191
+ Devise.setup do |config|
192
+ # The e-mail address that mail will appear to be sent from
193
+ # If absent, mail is sent from "please-change-me-at-config-initializers-devise@example.com"
194
+ config.mailer_sender = "support@myapp.com"
195
+
196
+ # If using rails-api, you may want to tell devise to not use ActionDispatch::Flash
197
+ # middleware b/c rails-api does not include it.
198
+ # See: http://stackoverflow.com/q/19600905/806956
199
+ config.navigational_formats = [:json]
200
+ end
201
+ ~~~
202
+
203
+ ## OmniAuth authentication
204
+
205
+ If you wish to use omniauth authentication, add all of your desired authentication provider gems to your `Gemfile`.
206
+
207
+ **OmniAuth example using github, facebook, and google**:
208
+ ~~~ruby
209
+ gem 'omniauth-github'
210
+ gem 'omniauth-facebook'
211
+ gem 'omniauth-google-oauth2'
212
+ ~~~
213
+
214
+ Then run `bundle install`.
215
+
216
+ [List of oauth2 providers](https://github.com/intridea/omniauth/wiki/List-of-Strategies)
217
+
218
+ ## OmniAuth provider settings
219
+
220
+ In `config/initializers/omniauth.rb`, add the settings for each of your providers.
221
+
222
+ These settings must be obtained from the providers themselves.
223
+
224
+ **Example using github, facebook, and google**:
225
+ ~~~ruby
226
+ # config/initializers/omniauth.rb
227
+ Rails.application.config.middleware.use OmniAuth::Builder do
228
+ provider :github, ENV['GITHUB_KEY'], ENV['GITHUB_SECRET'], scope: 'email,profile'
229
+ provider :facebook, ENV['FACEBOOK_KEY'], ENV['FACEBOOK_SECRET']
230
+ provider :google_oauth2, ENV['GOOGLE_KEY'], ENV['GOOGLE_SECRET']
231
+ end
232
+ ~~~
233
+
234
+ The above example assumes that your provider keys and secrets are stored in environmental variables. Use the [figaro](https://github.com/laserlemon/figaro) gem (or [dotenv](https://github.com/bkeepers/dotenv) or [secrets.yml](https://github.com/rails/rails/blob/v4.1.0/railties/lib/rails/generators/rails/app/templates/config/secrets.yml) or equivalent) to accomplish this.
235
+
236
+ #### OmniAuth callback settings
237
+
238
+ The "Callback URL" setting that you set with your provider must correspond to the [omniauth prefix](#initializer-settings) setting defined by this app. **This will be different than the omniauth route that is used by your client application**.
239
+
240
+ For example, the demo app uses the default `omniauth_prefix` setting `/omniauth`, so the "Authorization callback URL" for github must be set to "http://devise-token-auth-demo.herokuapp.com**/omniauth**/github/callback".
241
+
242
+ **Github example for the demo site**:
243
+ ![password reset flow](https://github.com/lynndylanhurley/devise_token_auth/raw/master/test/dummy/app/assets/images/omniauth-provider-settings.png)
244
+
245
+ The url for github authentication will be different for the client. The client should visit the API at `/[MOUNT_PATH]/:provider` for omniauth authentication.
246
+
247
+ For example, given that the app is mounted using the following settings:
248
+
249
+ ~~~ruby
250
+ # config/routes.rb
251
+ mount_devise_token_auth_for 'User', at: 'auth'
252
+ ~~~
253
+
254
+ The client configuration for github should look like this:
255
+
256
+ **Angular.js setting for authenticating using github**:
257
+ ~~~javascript
258
+ angular.module('myApp', ['ng-token-auth'])
259
+ .config(function($authProvider) {
260
+ $authProvider.configure({
261
+ apiUrl: 'http://api.example.com'
262
+ authProviderPaths: {
263
+ github: '/auth/github' // <-- note that this is different than what was set with github
264
+ }
265
+ });
266
+ });
267
+ ~~~
268
+
269
+ **jToker settings for github should look like this:
270
+
271
+ ~~~javascript
272
+ $.auth.configure({
273
+ apiUrl: 'http://api.example.com',
274
+ authProviderPaths: {
275
+ github: '/auth/github' // <-- note that this is different than what was set with github
276
+ }
277
+ });
278
+ ~~~
279
+
280
+ This incongruence is necessary to support multiple user classes and mounting points.
281
+
282
+ #### Note for [pow](http://pow.cx/) and [xip.io](http://xip.io) users
283
+
284
+ If you receive `redirect-uri-mismatch` errors from your provider when using pow or xip.io urls, set the following in your development config:
285
+
286
+ ~~~ruby
287
+ # config/environments/development.rb
288
+
289
+ # when using pow
290
+ OmniAuth.config.full_host = "http://app-name.dev"
291
+
292
+ # when using xip.io
293
+ OmniAuth.config.full_host = "http://xxx.xxx.xxx.app-name.xip.io"
294
+ ~~~
295
+
296
+ ## Email authentication
297
+ If you wish to use email authentication, you must configure your Rails application to send email. [Read here](http://guides.rubyonrails.org/action_mailer_basics.html) for more information.
298
+
299
+ I recommend using [mailcatcher](http://mailcatcher.me/) for development.
300
+
301
+ ##### mailcatcher development example configuration:
302
+ ~~~ruby
303
+ # config/environments/development.rb
304
+ Rails.application.configure do
305
+ config.action_mailer.default_url_options = { :host => 'your-dev-host.dev' }
306
+ config.action_mailer.delivery_method = :smtp
307
+ config.action_mailer.smtp_settings = { :address => 'your-dev-host.dev', :port => 1025 }
308
+ end
309
+ ~~~
310
+
311
+ If you wish to send custom e-mails instead of using the default devise templates, you can [do that too](#email-template-overrides).
312
+
313
+ ## Customizing Devise Verbiage
314
+ Devise Token Auth ships with intelligent default wording for everything you need. But that doesn't mean you can't make it more awesome. You can override the [devise defaults](https://github.com/plataformatec/devise/blob/master/config/locales/en.yml) by creating a YAML file at `config/locales/devise.en.yml` and assigning whatever custom values you want. For example, to customize the subject line of your devise e-mails, you could do this:
315
+
316
+ ~~~yaml
317
+ en:
318
+ devise:
319
+ mailer:
320
+ confirmation_instructions:
321
+ subject: "Please confirm your e-mail address"
322
+ reset_password_instructions:
323
+ subject: "Reset password request"
324
+ ~~~
325
+
326
+ ## CORS
327
+
328
+ If your API and client live on different domains, you will need to configure your Rails API to allow [cross origin requests](http://en.wikipedia.org/wiki/Cross-origin_resource_sharing). The [rack-cors](https://github.com/cyu/rack-cors) gem can be used to accomplish this.
329
+
330
+ The following **dangerous** example will allow cross domain requests from **any** domain. Make sure to whitelist only the needed domains.
331
+
332
+ ##### Example rack-cors configuration:
333
+ ~~~ruby
334
+ # gemfile
335
+ gem 'rack-cors', :require => 'rack/cors'
336
+
337
+ # config/application.rb
338
+ module YourApp
339
+ class Application < Rails::Application
340
+ config.middleware.use Rack::Cors do
341
+ allow do
342
+ origins '*'
343
+ resource '*',
344
+ :headers => :any,
345
+ :expose => ['access-token', 'expiry', 'token-type', 'uid', 'client'],
346
+ :methods => [:get, :post, :options, :delete, :put]
347
+ end
348
+ end
349
+ end
350
+ end
351
+ ~~~
352
+
353
+ Make extra sure that the `Access-Control-Expose-Headers` includes `access-token`, `expiry`, `token-type`, `uid`, and `client` (as is set in the example above by the`:expose` param). If your client experiences erroneous 401 responses, this is likely the cause.
354
+
355
+ CORS may not be possible with older browsers (IE8, IE9). I usually set up a proxy for those browsers. See the [ng-token-auth readme](https://github.com/lynndylanhurley/ng-token-auth) or the [jToker readme](https://github.com/lynndylanhurley/j-toker) for more information.
356
+
357
+ # Usage cont.
358
+
359
+ ## Mounting Routes
360
+
361
+ The authentication routes must be mounted to your project. This gem includes a route helper for this purpose:
362
+
363
+ **`mount_devise_token_auth_for`** - similar to `devise_for`, this method is used to append the routes necessary for user authentication. This method accepts the following arguments:
364
+
365
+ | Argument | Type | Default | Description |
366
+ |---|---|---|---|
367
+ |`class_name`| string | 'User' | The name of the class to use for authentication. This class must include the [model concern described here](#model-concerns). |
368
+ | `options` | object | {at: 'auth'} | The [routes to be used for authentication](#usage) will be prefixed by the path specified in the `at` param of this object. |
369
+
370
+ **Example**:
371
+ ~~~ruby
372
+ # config/routes.rb
373
+ mount_devise_token_auth_for 'User', at: 'auth'
374
+ ~~~
375
+
376
+ Any model class can be used, but the class will need to include [`DeviseTokenAuth::Concerns::User`](#model-concerns) for authentication to work properly.
377
+
378
+ You can mount this engine to any route that you like. `/auth` is used by default to conform with the defaults of the [ng-token-auth](https://github.com/lynndylanhurley/ng-token-auth) module and the [jToker](https://github.com/lynndylanhurley/j-toker) plugin.
379
+
380
+
381
+ ## Controller Methods
382
+
383
+ ### Concerns
384
+
385
+ This gem includes a [Rails concern](http://api.rubyonrails.org/classes/ActiveSupport/Concern.html) called `DeviseTokenAuth::Concerns::SetUserByToken`. Include this concern to provide access to [controller methods](#controller-methods) such as [`authenticate_user!`](#authenticate-user), [`user_signed_in?`](#user-signed-in), etc.
386
+
387
+ The concern also runs an [after_action](http://guides.rubyonrails.org/action_controller_overview.html#filters) that changes the auth token after each request.
388
+
389
+ It is recommended to include the concern in your base `ApplicationController` so that all children of that controller include the concern as well.
390
+
391
+ ##### Concern example:
392
+
393
+ ~~~ruby
394
+ # app/controllers/application_controller.rb
395
+ class ApplicationController < ActionController::Base
396
+ include DeviseTokenAuth::Concerns::SetUserByToken
397
+ end
398
+ ~~~
399
+
400
+ ### Methods
401
+
402
+ This gem provides access to all of the following [devise helpers](https://github.com/plataformatec/devise#controller-filters-and-helpers):
403
+
404
+ | Method | Description |
405
+ |---|---|
406
+ | **`before_action :authenticate_user!`** | Returns a 401 error unless a `User` is signed-in. |
407
+ | **`current_user`** | Returns the currently signed-in `User`, or `nil` if unavailable. |
408
+ | **`user_signed_in?`** | Returns `true` if a `User` is signed in, otherwise `false`. |
409
+ | **`devise_token_auth_group`** | Operate on multiple user classes as a group. [Read more](#group-access) |
410
+
411
+ Note that if the model that you're trying to access isn't called `User`, the helper method names will change. For example, if the user model is called `Admin`, the methods would look like this:
412
+
413
+ * `before_action :authenticate_admin!`
414
+ * `admin_signed_in?`
415
+ * `current_admin`
416
+
417
+
418
+ ##### Example: limit access to authenticated users
419
+ ~~~ruby
420
+ # app/controllers/test_controller.rb
421
+ class TestController < ApplicationController
422
+ before_action :authenticate_user!
423
+
424
+ def members_only
425
+ render json: {
426
+ data: {
427
+ message: "Welcome #{current_user.name}",
428
+ user: current_user
429
+ }
430
+ }, status: 200
431
+ end
432
+ end
433
+ ~~~
434
+
435
+ ### Token Header Format
436
+
437
+ The authentication information should be included by the client in the headers of each request. The headers follow the [RFC 6750 Bearer Token](http://tools.ietf.org/html/rfc6750) format:
438
+
439
+ ##### Authentication headers example:
440
+ ~~~
441
+ "access-token": "wwwww",
442
+ "token-type": "Bearer",
443
+ "client": "xxxxx",
444
+ "expiry": "yyyyy",
445
+ "uid": "zzzzz"
446
+ ~~~
447
+
448
+ The authentication headers (each one is a seperate header) consists of the following params:
449
+
450
+ | param | description |
451
+ |---|---|
452
+ | **`access-token`** | This serves as the user's password for each request. A hashed version of this value is stored in the database for later comparison. This value should be changed on each request. |
453
+ | **`client`** | This enables the use of multiple simultaneous sessions on different clients. (For example, a user may want to be authenticated on both their phone and their laptop at the same time.) |
454
+ | **`expiry`** | The date at which the current session will expire. This can be used by clients to invalidate expired tokens without the need for an API request. |
455
+ | **`uid`** | A unique value that is used to identify the user. This is necessary because searching the DB for users by their access token will make the API susceptible to [timing attacks](http://codahale.com/a-lesson-in-timing-attacks/). |
456
+
457
+ The authentication headers required for each request will be available in the response from the previous request. If you are using the [ng-token-auth](https://github.com/lynndylanhurley/ng-token-auth) AngularJS module or the [jToker](https://github.com/lynndylanhurley/j-toker) jQuery plugin, this functionality is already provided.
458
+
459
+ ## Model Concerns
460
+
461
+ ##### DeviseTokenAuth::Concerns::User
462
+
463
+ Typical use of this gem will not require the use of any of the following model methods. All authentication should be handled invisibly by the [controller concerns](#controller-methods) described above.
464
+
465
+ Models that include the `DeviseTokenAuth::Concerns::User` concern will have access to the following public methods (read the above section for context on `token` and `client`):
466
+
467
+ * **`valid_token?`**: check if an authentication token is valid. Accepts a `token` and `client` as arguments. Returns a boolean.
468
+
469
+ **Example**:
470
+ ~~~ruby
471
+ # extract token + client_id from auth header
472
+ client_id = request.headers['client']
473
+ token = request.headers['access-token']
474
+
475
+ @resource.valid_token?(token, client_id)
476
+ ~~~
477
+
478
+ * **`create_new_auth_token`**: creates a new auth token with all of the necessary metadata. Accepts `client` as an optional argument. Will generate a new `client` if none is provided. Returns the authentication headers that should be sent by the client as an object.
479
+
480
+ **Example**:
481
+ ~~~ruby
482
+ # extract client_id from auth header
483
+ client_id = request.headers['client']
484
+
485
+ # update token, generate updated auth headers for response
486
+ new_auth_header = @resource.create_new_auth_token(client_id)
487
+
488
+ # update response with the header that will be required by the next request
489
+ response.headers.merge!(new_auth_header)
490
+ ~~~
491
+
492
+ * **`build_auth_header`**: generates the auth header that should be sent to the client with the next request. Accepts `token` and `client` as arguments. Returns a string.
493
+
494
+ **Example**:
495
+ ~~~ruby
496
+ # create client id and token
497
+ client_id = SecureRandom.urlsafe_base64(nil, false)
498
+ token = SecureRandom.urlsafe_base64(nil, false)
499
+
500
+ # store client + token in user's token hash
501
+ @resource.tokens[client_id] = {
502
+ token: BCrypt::Password.create(token),
503
+ expiry: (Time.now + @resource.token_lifespan).to_i
504
+ }
505
+
506
+ # generate auth headers for response
507
+ new_auth_header = @resource.build_auth_header(token, client_id)
508
+
509
+ # update response with the header that will be required by the next request
510
+ response.headers.merge!(new_auth_header)
511
+ ~~~
512
+
513
+ ## Using multiple models
514
+
515
+ ### View Live Multi-User Demos
516
+
517
+ * [AngularJS](http://ng-token-auth-demo.herokuapp.com/multi-user)
518
+ * [Angular2](https://angular2-token.herokuapp.com)
519
+ * [React + jToker](http://j-toker-demo.herokuapp.com/#/alt-user)
520
+
521
+ This gem supports the use of multiple user models. One possible use case is to authenticate visitors using a model called `User`, and to authenticate administrators with a model called `Admin`. Take the following steps to add another authentication model to your app:
522
+
523
+ 1. Run the install generator for the new model.
524
+ ~~~
525
+ rails g devise_token_auth:install Admin admin_auth
526
+ ~~~
527
+
528
+ This will create the `Admin` model and define the model's authentication routes with the base path `/admin_auth`.
529
+
530
+ 1. Define the routes to be used by the `Admin` user within a [`devise_scope`](https://github.com/plataformatec/devise#configuring-routes).
531
+
532
+ **Example**:
533
+
534
+ ~~~ruby
535
+ Rails.application.routes.draw do
536
+ # when using multiple models, controllers will default to the first available
537
+ # devise mapping. routes for subsequent devise mappings will need to defined
538
+ # within a `devise_scope` block
539
+
540
+ # define :users as the first devise mapping:
541
+ mount_devise_token_auth_for 'User', at: 'auth'
542
+
543
+ # define :admins as the second devise mapping. routes using this class will
544
+ # need to be defined within a devise_scope as shown below
545
+ mount_devise_token_auth_for "Admin", at: 'admin_auth'
546
+
547
+ # this route will authorize requests using the User class
548
+ get 'demo/members_only', to: 'demo#members_only'
549
+
550
+ # routes within this block will authorize requests using the Admin class
551
+ devise_scope :admin do
552
+ get 'demo/admins_only', to: 'demo#admins_only'
553
+ end
554
+ end
555
+ ~~~
556
+
557
+ 1. Configure any `Admin` restricted controllers. Controllers will now have access to the methods [described here](#methods):
558
+ * `before_action :authenticate_admin!`
559
+ * `current_admin`
560
+ * `admin_signed_in?`
561
+
562
+
563
+ ### Group access
564
+
565
+ It is also possible to control access to multiple user types at the same time using groups. The following example shows how to limit controller access to both `User` and `Admin` users.
566
+
567
+ ##### Example: group authentication
568
+
569
+ ~~~ruby
570
+ class DemoGroupController < ApplicationController
571
+ devise_token_auth_group :member, contains: [:user, :admin]
572
+ before_action :authenticate_member!
573
+
574
+ def members_only
575
+ render json: {
576
+ data: {
577
+ message: "Welcome #{current_member.name}",
578
+ user: current_member
579
+ }
580
+ }, status: 200
581
+ end
582
+ end
583
+ ~~~
584
+
585
+ In the above example, the following methods will be available (in addition to `current_user`, `current_admin`, etc.):
586
+
587
+ * `before_action: :authenticate_member!`
588
+ * `current_member`
589
+ * `member_signed_in?`
590
+
591
+ ## Excluding Modules
592
+
593
+ By default, almost all of the Devise modules are included:
594
+ * [`database_authenticatable`](https://github.com/plataformatec/devise/blob/master/lib/devise/models/database_authenticatable.rb)
595
+ * [`registerable`](https://github.com/plataformatec/devise/blob/master/lib/devise/models/registerable.rb)
596
+ * [`recoverable`](https://github.com/plataformatec/devise/blob/master/lib/devise/models/recoverable.rb)
597
+ * [`trackable`](https://github.com/plataformatec/devise/blob/master/lib/devise/models/trackable.rb)
598
+ * [`validatable`](https://github.com/plataformatec/devise/blob/master/lib/devise/models/validatable.rb)
599
+ * [`confirmable`](https://github.com/plataformatec/devise/blob/master/lib/devise/models/confirmable.rb)
600
+ * [`omniauthable`](https://github.com/plataformatec/devise/blob/master/lib/devise/models/omniauthable.rb)
601
+
602
+ You may not want all of these features enabled in your app. That's OK! You can mix and match to suit your own unique style.
603
+
604
+ The following example shows how to disable email confirmation.
605
+
606
+ ##### Example: disable email confirmation
607
+
608
+ Just list the devise modules that you want to include **before** including the `DeviseTokenAuth::Concerns::User` model concern.
609
+
610
+ ~~~ruby
611
+ # app/models/user.rb
612
+ class User < ActiveRecord::Base
613
+
614
+ # notice this comes BEFORE the include statement below
615
+ # also notice that :confirmable is not included in this block
616
+ devise :database_authenticatable, :recoverable,
617
+ :trackable, :validatable, :registerable,
618
+ :omniauthable
619
+
620
+ # note that this include statement comes AFTER the devise block above
621
+ include DeviseTokenAuth::Concerns::User
622
+ end
623
+ ~~~
624
+
625
+ Some features include routes that you may not want mounted to your app. The following example shows how to disable OAuth and its routes.
626
+
627
+ ##### Example: disable OAuth authentication
628
+
629
+ First instruct the model not to include the `omniauthable` module.
630
+
631
+ ~~~ruby
632
+ # app/models/user.rb
633
+ class User < ActiveRecord::Base
634
+
635
+ # notice that :omniauthable is not included in this block
636
+ devise :database_authenticatable, :confirmable,
637
+ :recoverable, :trackable, :validatable,
638
+ :registerable
639
+
640
+ include DeviseTokenAuth::Concerns::User
641
+ end
642
+ ~~~
643
+
644
+ Now tell the route helper to `skip` mounting the `omniauth_callbacks` controller:
645
+
646
+ ~~~ruby
647
+ Rails.application.routes.draw do
648
+ # config/routes.rb
649
+ mount_devise_token_auth_for 'User', at: 'auth', skip: [:omniauth_callbacks]
650
+ end
651
+ ~~~
652
+
653
+ ## Custom Controller Overrides
654
+
655
+ The built-in controllers can be overridden with your own custom controllers.
656
+
657
+ For example, the default behavior of the [`validate_token`](https://github.com/lynndylanhurley/devise_token_auth/blob/8a33d25deaedb4809b219e557e82ec7ec61bf940/app/controllers/devise_token_auth/token_validations_controller.rb#L6) method of the [`TokenValidationController`](https://github.com/lynndylanhurley/devise_token_auth/blob/8a33d25deaedb4809b219e557e82ec7ec61bf940/app/controllers/devise_token_auth/token_validations_controller.rb) is to return the `User` object as json (sans password and token data). The following example shows how to override the `validate_token` action to include a model method as well.
658
+
659
+ ##### Example: controller overrides
660
+
661
+ ~~~ruby
662
+ # config/routes.rb
663
+ Rails.application.routes.draw do
664
+ ...
665
+ mount_devise_token_auth_for 'User', at: 'auth', controllers: {
666
+ token_validations: 'overrides/token_validations'
667
+ }
668
+ end
669
+
670
+ # app/controllers/overrides/token_validations_controller.rb
671
+ module Overrides
672
+ class TokenValidationsController < DeviseTokenAuth::TokenValidationsController
673
+
674
+ def validate_token
675
+ # @resource will have been set by set_user_by_token concern
676
+ if @resource
677
+ render json: {
678
+ data: @resource.as_json(methods: :calculate_operating_thetan)
679
+ }
680
+ else
681
+ render json: {
682
+ success: false,
683
+ errors: ["Invalid login credentials"]
684
+ }, status: 401
685
+ end
686
+ end
687
+ end
688
+ end
689
+ ~~~
690
+
691
+ ## Overriding rendering methods
692
+ To customize json rendering, implement the following protected controller methods, for success methods, assume that the @resource object is available:
693
+
694
+ ### Registrations Controller
695
+ * render_create_error_missing_confirm_success_url
696
+ * render_create_error_redirect_url_not_allowed
697
+ * render_create_success
698
+ * render_create_error
699
+ * render_create_error_email_already_exists
700
+ * render_update_success
701
+ * render_update_error
702
+ * render_update_error_user_not_found
703
+
704
+
705
+ ### Sessions Controller
706
+ * render_new_error
707
+ * render_create_success
708
+ * render_create_error_not_confirmed
709
+ * render_create_error_bad_credentials
710
+ * render_destroy_success
711
+ * render_destroy_error
712
+
713
+
714
+ ### Passwords Controller
715
+ * render_create_error_missing_email
716
+ * render_create_error_missing_redirect_url
717
+ * render_create_error_not_allowed_redirect_url
718
+ * render_create_success
719
+ * render_create_error
720
+ * render_update_error_unauthorized
721
+ * render_update_error_password_not_required
722
+ * render_update_error_missing_password
723
+ * render_update_success
724
+ * render_update_error
725
+
726
+ ### Token Validations Controller
727
+ * render_validate_token_success
728
+ * render_validate_token_error
729
+
730
+ ##### Example: all :controller options with default settings:
731
+
732
+ ~~~ruby
733
+ mount_devise_token_auth_for 'User', at: 'auth', controllers: {
734
+ confirmations: 'devise_token_auth/confirmations',
735
+ passwords: 'devise_token_auth/passwords',
736
+ omniauth_callbacks: 'devise_token_auth/omniauth_callbacks',
737
+ registrations: 'devise_token_auth/registrations',
738
+ sessions: 'devise_token_auth/sessions',
739
+ token_validations: 'devise_token_auth/token_validations'
740
+ }
741
+ ~~~
742
+
743
+ **Note:** Controller overrides must implement the expected actions of the controllers that they replace.
744
+
745
+ ## Passing blocks to Controllers
746
+
747
+ It may be that you simply want to _add_ behavior to existing controllers without having to re-implement their behavior completely. In this case, you can do so by creating a new controller that inherits from any of DeviseTokenAuth's controllers, overriding whichever methods you'd like to add behavior to by passing a block to `super`:
748
+
749
+ ```ruby
750
+ class Custom::RegistrationsController < DeviseTokenAuth::RegistrationsController
751
+
752
+ def create
753
+ super do |resource|
754
+ resource.do_something(extra)
755
+ end
756
+ end
757
+
758
+ end
759
+ ```
760
+
761
+ Your block will be performed just before the controller would usually render a successful response.
762
+
763
+ ## Email Template Overrides
764
+
765
+ You will probably want to override the default email templates for email sign-up and password-reset confirmation. Run the following command to copy the email templates into your app:
766
+
767
+ ~~~bash
768
+ rails generate devise_token_auth:install_views
769
+ ~~~
770
+
771
+ This will create two new files:
772
+
773
+ * `app/views/devise/mailer/reset_password_instructions.html.erb`
774
+ * `app/views/devise/mailer/confirmation_instructions.html.erb`
775
+
776
+ These files may be edited to suit your taste. You can customize the e-mail subjects like [this](#customizing-devise-verbiage).
777
+
778
+ **Note:** if you choose to modify these templates, do not modify the `link_to` blocks unless you absolutely know what you are doing.
779
+
780
+ ## Testing
781
+
782
+ In order to authorise a request when testing your API you will need to pass the four headers through with your request, the easiest way to gain appropriate values for those headers is to use `resource.create_new_auth_token` e.g.
783
+
784
+ ```Ruby
785
+ request.headers.merge! resource.create_new_auth_token
786
+ get '/api/authenticated_resource'
787
+ # success
788
+ ```
789
+
790
+ # Issue Reporting
791
+
792
+ When posting issues, please include the information mentioned in the [ISSUE_TEMPLATE.md].
793
+
794
+ [ISSUE_TEMPLATE.md]: https://github.com/lynndylanhurley/devise_token_auth/blob/master/.github/ISSUE_TEMPLATE.md
795
+
796
+ # FAQ
797
+
798
+ ### Can I use this gem alongside standard Devise?
799
+
800
+ Yes! But you will need to enable the support of separate routes for standard Devise. So do something like this:
801
+
802
+ #### config/initializers/devise_token_auth.rb
803
+ ~~~ruby
804
+ DeviseTokenAuth.setup do |config|
805
+ # config.enable_standard_devise_support = false
806
+ end
807
+ ~~~
808
+
809
+ #### config/routes.rb
810
+ ~~~ruby
811
+ Rails.application.routes.draw do
812
+
813
+ # standard devise routes available at /users
814
+ # NOTE: make sure this comes first!!!
815
+ devise_for :users
816
+
817
+ # token auth routes available at /api/v1/auth
818
+ namespace :api do
819
+ scope :v1 do
820
+ mount_devise_token_auth_for 'User', at: 'auth'
821
+ end
822
+ end
823
+
824
+ end
825
+ ~~~
826
+
827
+ ### Why are the `new` routes included if this gem doesn't use them?
828
+
829
+ Removing the `new` routes will require significant modifications to devise. If the inclusion of the `new` routes is causing your app any problems, post an issue in the issue tracker and it will be addressed ASAP.
830
+
831
+ ### I'm having trouble using this gem alongside [ActiveAdmin](http://activeadmin.info/)...
832
+
833
+ For some odd reason, [ActiveAdmin](http://activeadmin.info/) extends from your own app's `ApplicationController`. This becomes a problem if you include the `DeviseTokenAuth::Concerns::SetUserByToken` concern in your app's `ApplicationController`.
834
+
835
+ The solution is to use two separate `ApplicationController` classes - one for your API, and one for ActiveAdmin. Something like this:
836
+
837
+ ~~~ruby
838
+ # app/controllers/api_controller.rb
839
+ # API routes extend from this controller
840
+ class ApiController < ActionController::Base
841
+ include DeviseTokenAuth::Concerns::SetUserByToken
842
+ end
843
+
844
+ # app/controllers/application_controller.rb
845
+ # leave this for ActiveAdmin, and any other non-api routes
846
+ class ApplicationController < ActionController::Base
847
+ end
848
+ ~~~
849
+
850
+ ### How can I use this gem with Grape?
851
+
852
+ You may be interested in [GrapeTokenAuth](https://github.com/mcordell/grape_token_auth) or [GrapeDeviseTokenAuth](https://github.com/mcordell/grape_devise_token_auth).
853
+
854
+ ### I already have an user, how can I add the new fields?
855
+
856
+ Check [Setup migrations for an existing User table](https://github.com/lynndylanhurley/devise_token_auth/wiki/Setup-migrations-for-an-existing-User-table)
857
+
858
+
859
+ # Conceptual
860
+
861
+ None of the following information is required to use this gem, but read on if you're curious.
862
+
863
+ ## About token management
864
+
865
+ Tokens should be invalidated after each request to the API. The following diagram illustrates this concept:
866
+
867
+ ![password reset flow](https://github.com/lynndylanhurley/ng-token-auth/raw/master/test/app/images/flow/token-update-detail.jpg)
868
+
869
+ During each request, a new token is generated. The `access-token` header that should be used in the next request is returned in the `access-token` header of the response to the previous request. The last request in the diagram fails because it tries to use a token that was invalidated by the previous request.
870
+
871
+ The only case where an expired token is allowed is during [batch requests](#about-batch-requests).
872
+
873
+ These measures are taken by default when using this gem.
874
+
875
+ ## About batch requests
876
+
877
+ By default, the API should update the auth token for each request ([read more](#about-token-management)). But sometimes it's necessary to make several concurrent requests to the API, for example:
878
+
879
+ ##### Batch request example
880
+
881
+ ~~~javascript
882
+ $scope.getResourceData = function() {
883
+
884
+ $http.get('/api/restricted_resource_1').success(function(resp) {
885
+ // handle response
886
+ $scope.resource1 = resp.data;
887
+ });
888
+
889
+ $http.get('/api/restricted_resource_2').success(function(resp) {
890
+ // handle response
891
+ $scope.resource2 = resp.data;
892
+ });
893
+ };
894
+ ~~~
895
+
896
+ In this case, it's impossible to update the `access-token` header for the second request with the `access-token` header of the first response because the second request will begin before the first one is complete. The server must allow these batches of concurrent requests to share the same auth token. This diagram illustrates how batch requests are identified by the server:
897
+
898
+ ![batch request overview](https://github.com/lynndylanhurley/ng-token-auth/raw/master/test/app/images/flow/batch-request-overview.jpg)
899
+
900
+ The "5 second" buffer in the diagram is the default used this gem.
901
+
902
+ The following diagram details the relationship between the client, server, and access tokens used over time when dealing with batch requests:
903
+
904
+ ![batch request detail](https://github.com/lynndylanhurley/ng-token-auth/raw/master/test/app/images/flow/batch-request-detail.jpg)
905
+
906
+ Note that when the server identifies that a request is part of a batch request, the user's auth token is not updated. The auth token will be updated and returned with the first request in the batch, and the subsequent requests in the batch will not return a token. This is necessary because the order of the responses cannot be guaranteed to the client, and we need to be sure that the client does not receive an outdated token *after* the the last valid token is returned.
907
+
908
+ This gem automatically manages batch requests. You can change the time buffer for what is considered a batch request using the `batch_request_buffer_throttle` parameter in `config/initializers/devise_token_auth.rb`.
909
+
910
+
911
+ # Security
912
+
913
+ This gem takes the following steps to ensure security.
914
+
915
+ This gem uses auth tokens that are:
916
+ * [changed after every request](#about-token-management) (can be [turned off](https://github.com/lynndylanhurley/devise_token_auth/#initializer-settings)),
917
+ * [of cryptographic strength](http://ruby-doc.org/stdlib-2.1.0/libdoc/securerandom/rdoc/SecureRandom.html),
918
+ * hashed using [BCrypt](https://github.com/codahale/bcrypt-ruby) (not stored in plain-text),
919
+ * securely compared (to protect against timing attacks),
920
+ * invalidated after 2 weeks (thus requiring users to login again)
921
+
922
+ These measures were inspired by [this stackoverflow post](http://stackoverflow.com/questions/18605294/is-devises-token-authenticatable-secure).
923
+
924
+ This gem further mitigates timing attacks by using [this technique](https://gist.github.com/josevalim/fb706b1e933ef01e4fb6).
925
+
926
+ But the most important step is to use HTTPS. You are on the hook for that.
927
+
928
+ # Callouts
929
+
930
+ Thanks to the following contributors:
931
+
932
+ * [@booleanbetrayal](https://github.com/booleanbetrayal)
933
+ * [@zachfeldman](https://github.com/zachfeldman)
934
+ * [@MaicolBen](https://github.com/MaicolBen)
935
+ * [@guilhermesimoes](https://github.com/guilhermesimoes)
936
+ * [@jasonswett](https://github.com/jasonswett)
937
+ * [@m2omou](https://github.com/m2omou)
938
+ * [@smarquez1](https://github.com/smarquez1)
939
+ * [@jartek](https://github.com/jartek)
940
+ * [@nicolas-besnard](https://github.com/nicolas-besnard)
941
+ * [@tbloncar](https://github.com/tbloncar)
942
+ * [@nickL](https://github.com/nickL)
943
+ * [@mchavarriagam](https://github.com/mchavarriagam)
944
+
945
+ # Contributing
946
+
947
+ See the [CONTRIBUTING.md] document.
948
+
949
+ [CONTRIBUTING.md]: https://github.com/lynndylanhurley/devise_token_auth/blob/master/.github/CONTRIBUTING.md
950
+
951
+ # License
952
+ This project uses the WTFPL