Skip to content
Newer
Older
100644 138 lines (73 sloc) 3.59 KB
325a4a3 @joshk first lot of readme updates
authored
1 Devise - Imapable
2 =================
3
687432d @joshk fixed a few typos
authored
4 Devise-Imapable is a imap based authentication strategy for the [Devise](http://github.com/plataformatec/devise) authentication framework.
325a4a3 @joshk first lot of readme updates
authored
5
6 If you are building applications for use within your organisation which require authentication and don't have access to a LDAP server, using imap can be a great alternative.
7
8 Installation
695e4c4 @joshk some readme love
authored
9 ------------
325a4a3 @joshk first lot of readme updates
authored
10
aafc233 @joshk updated readme re 1.0.6 issue
authored
11 **Please note that Devise-Imapable only works with Devise 1.0.5 at the moment, changes for 1.0.6 will be made soon**
12
325a4a3 @joshk first lot of readme updates
authored
13 Currently this can only be installed as a plugin.
14
695e4c4 @joshk some readme love
authored
15 script/plugin install git@github.com:joshk/devise_imapable.git
325a4a3 @joshk first lot of readme updates
authored
16
687432d @joshk fixed a few typos
authored
17 *Now in gem form, install notes coming soon*
325a4a3 @joshk first lot of readme updates
authored
18
19
687432d @joshk fixed a few typos
authored
20 **And don't forget to add [Devise](http://github.com/plataformatec/devise)!**
325a4a3 @joshk first lot of readme updates
authored
21
695e4c4 @joshk some readme love
authored
22 either in config/environment.rb:
325a4a3 @joshk first lot of readme updates
authored
23
695e4c4 @joshk some readme love
authored
24 config.gem 'devise'
325a4a3 @joshk first lot of readme updates
authored
25
695e4c4 @joshk some readme love
authored
26 or in bundler
325a4a3 @joshk first lot of readme updates
authored
27
695e4c4 @joshk some readme love
authored
28 gem 'devise'
325a4a3 @joshk first lot of readme updates
authored
29
30
695e4c4 @joshk some readme love
authored
31 Setup
32 -----
33
34 Once devise-imapable is installed, all you need to do is setup the user model which includes a small addition to the model itself and to the schema.
35
36 First the schema :
37
38 create_table :users do |t|
39
687432d @joshk fixed a few typos
authored
40 t.imapable
695e4c4 @joshk some readme love
authored
41
42 end
43
44 and indexes (optional) :
45
46 add_index :users, :email, :unique => true
47
48 and don’t forget to migrate :
49
50 rake db:migrate.
51
52 then finally the model :
53
54 class User < ActiveRecord::Base
55
56 devise :rememberable, :trackable, :timeoutable, :imapable
57
58 # Setup accessible (or protected) attributes for your model
59 attr_accessible :email, :password, :remember_me
60
61 ...
62 end
63
64 I recommend using :rememberable, :trackable, :timeoutable along with :imapable as it gives a full feature set for logins.
65
66
67 Usage
68 -----
69
70 Devise-Imapable works in replacement of Authenticatable, allowing for user name (or email) and password authentication. The standard sign\_in routes and views work out of the box as these are just reused from devise. I recommend you run :
71
72 script/generate devise_views
73
74 so you can customize your login pages.
75
76 ------------------------------------------------------------
77
78 **please note**
79
80 This devise plugin has not been tested with Authenticatable enabled at the same time. This is meant as a drop in replacement for Authenticatable allowing for a semi single sign on approach.
81
82
83 Advanced Configuration
84 ----------------------
85
86 In initializer `config/initializers/devise.rb` :
87
88 Devise.setup do |config|
89 # ...
90 config.imap_server = 'bigcorporation.com'
91 config.default_email_suffix = 'friendly-corporation.com'
92 # ...
93 end
94
95 Imap servers usually allow a user to login using their full email address or just the identifier part, eg: josh.kalderimis and josh.kalderimis@gmail.com will both work. It is recommend that you set the default\_email\_suffix so the login is kept consistent and the users email is correctly stored in the User model.
96
97 So remember ...
98 ---------------
99
100 - don't use Authenticatable
101
102 - add imap\_server and default\_email\_suffix settings in the devise initializer
103
104 - generate the devise views and make them pretty
105
106
107 References
108 ----------
109
687432d @joshk fixed a few typos
authored
110 * [Devise](http://github.com/plataformatec/devise)
111 * [Warden](http://github.com/hassox/warden)
695e4c4 @joshk some readme love
authored
112
113
114 TODO
115 ----
116
687432d @joshk fixed a few typos
authored
117 - add notes about gem
118
695e4c4 @joshk some readme love
authored
119 - email validation
120
d99d3ea @joshk more doc love
authored
121 - add update\_with\_password to the model, similar to Authenticatable
122
123 - assert Authenticatable is not being used
124
695e4c4 @joshk some readme love
authored
125 - assert imap\_server is present, and warn if default\_email\_suffix isn't present
126
127 - tests, tests, tests
128
129 - allow for setups which require profile information before creating a user
130
131 - investigate how well this works with other devise modules like http\_authenticatable, token\_authenticatable lockable, confirmable, and activatable
132
133
dde2a79 @joshk more url issues, oops
authored
134
695e4c4 @joshk some readme love
authored
135 Released under the MIT license
dde2a79 @joshk more url issues, oops
authored
136
695e4c4 @joshk some readme love
authored
137 Copyright (c) 2010 Josh Kalderimis,
Something went wrong with that request. Please try again.