google_apps_oauth2 0.1

Sign up to get free protection for your applications and to get access to all the features.
@@ -0,0 +1,15 @@
1
+ ---
2
+ !binary "U0hBMQ==":
3
+ metadata.gz: !binary |-
4
+ NjBkYjZlMzljYWNlYWQxOGViMDY1OTUxMzRlZDg2ZGY0OGQ1NjYxNQ==
5
+ data.tar.gz: !binary |-
6
+ NWI5NWQzYTRlZGJkNWE2NDdkNjMyZTFkNTAxZDg3NzFiMzMwM2M3Mw==
7
+ !binary "U0hBNTEy":
8
+ metadata.gz: !binary |-
9
+ NTVlYmUzYjA2ZTEyOWE0ZTU2NDdkMGI4MWYxOWFiMmMyNTU1MDI0YTU1Nzkw
10
+ MDVhMmUxYTFhYWJmY2IzY2JlNzgxZGMyYzgyNzM2ZTU2MDBkN2E3M2RiOTUz
11
+ MmU0MWQ2ZTU1MDczMmQ0NjZjMzZhNGYyMmRmY2QzOTM2NmRhNDA=
12
+ data.tar.gz: !binary |-
13
+ MzkzNTk0ZmY1ZmExZDYyNTE4NTYwMTRjOGY1OWY2NzVhM2JjZThmYTNmNWEw
14
+ ODQ2NWU4NDUyZGQwMTE4OWNjMjY3ZDU0ODc4YWUyNzBmN2Q5YmFjMjU4Y2M1
15
+ OTk3N2Q3M2QyZTk2MDE3M2I5MWZkOTdkMjM2MTM1M2JkNmE5Njg=
@@ -0,0 +1,5 @@
1
+ file
2
+ notes.md
3
+ spec/credentials.yaml
4
+ .DS_Store
5
+ .rvmrc
data/Gemfile ADDED
@@ -0,0 +1,4 @@
1
+ source "http://rubygems.org"
2
+
3
+ # Specify your gem's dependencies in license_finder.gemspec
4
+ gemspec
@@ -0,0 +1,40 @@
1
+ PATH
2
+ remote: .
3
+ specs:
4
+ google_apps_oauth2 (0.1)
5
+ httparty
6
+ libxml-ruby (>= 2.2.2)
7
+
8
+ GEM
9
+ remote: http://rubygems.org/
10
+ specs:
11
+ addressable (2.3.2)
12
+ crack (0.3.2)
13
+ diff-lcs (1.1.3)
14
+ httparty (0.10.2)
15
+ multi_json (~> 1.0)
16
+ multi_xml (>= 0.5.2)
17
+ libxml-ruby (2.6.0)
18
+ multi_json (1.6.1)
19
+ multi_xml (0.5.3)
20
+ rake (10.0.3)
21
+ rspec (2.12.0)
22
+ rspec-core (~> 2.12.0)
23
+ rspec-expectations (~> 2.12.0)
24
+ rspec-mocks (~> 2.12.0)
25
+ rspec-core (2.12.2)
26
+ rspec-expectations (2.12.1)
27
+ diff-lcs (~> 1.1.3)
28
+ rspec-mocks (2.12.2)
29
+ webmock (1.9.2)
30
+ addressable (>= 2.2.7)
31
+ crack (>= 0.3.2)
32
+
33
+ PLATFORMS
34
+ ruby
35
+
36
+ DEPENDENCIES
37
+ google_apps_oauth2!
38
+ rake
39
+ rspec
40
+ webmock
data/LICENSE ADDED
@@ -0,0 +1,10 @@
1
+
2
+ Copyright (C) 2013 Will Read
3
+
4
+ MIT LICENSE
5
+
6
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
7
+
8
+ The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
9
+
10
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@@ -0,0 +1,461 @@
1
+ # Google Apps API
2
+
3
+ [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/LeakyBucket/google_apps)
4
+
5
+
6
+ ## What is this?
7
+
8
+ This is another GoogleApps API Library. It is written for Ruby 1.9. I know there is one floating around out there but it is 2 years old and doesn't claim to do more than: users, groups, and calendar.
9
+
10
+ The goal here is a library that supports the entire GoogleApps Domain and Applications APIs.
11
+
12
+
13
+ ## Overview
14
+ * [Status](#currently-supported)
15
+ * [Quick and Dirty](#-short-how)
16
+ * [Details](#-long-how)
17
+ * [License](#-license)
18
+
19
+ ## <a id="Status" /> API Coverage
20
+
21
+ ####Currently Supported:
22
+
23
+ __Domain API__
24
+
25
+ * Provisioning
26
+ * Users
27
+ * User Creation
28
+ * User Deletion
29
+ * User Record Retrieval
30
+ * User Modification
31
+ * Retrieve all users in the domain
32
+ * Groups
33
+ * Group Creation
34
+ * Group Deletion
35
+ * Group Record Retrieval
36
+ * Add Group Member
37
+ * Delete Group Member
38
+ * Modify Group Attributes
39
+ * Member List
40
+ * Group Owner Management
41
+ * Create Owner
42
+ * Nicknames
43
+ * Creation
44
+ * Deletion
45
+ * List Nicknames for a User
46
+ * Public Key Upload
47
+ * Email Audit
48
+ * Mailbox Export Request
49
+ * Mailbox Export Status Check
50
+ * Mailbox Export Download
51
+ * Email Migration
52
+ * Message Upload
53
+ * Set Message Attributes
54
+
55
+
56
+ #### TODO:
57
+
58
+ __Domain__
59
+
60
+ * Admin Audit
61
+ * Admin Settings
62
+ * Calendar Resource
63
+ * Domain Shared Contacts
64
+ * Email Audit
65
+ * Email Monitors
66
+ * Account Information
67
+ * Email Settings
68
+ * Reporting
69
+ * Reporting Visualization
70
+ * User Profiles
71
+
72
+ __Application__
73
+
74
+ * Calendar Data
75
+ * Contacts Data
76
+ * Documents List Data
77
+ * Sites Data
78
+ * Spreadsheets Data
79
+ * Tasks
80
+
81
+ ## <a id="Brief" /> Short How
82
+
83
+ Getting and using the library.
84
+
85
+ ```ruby
86
+ gem install google_apps
87
+
88
+ require 'google_apps'
89
+ ```
90
+
91
+
92
+ Setting up your GoogleApps::Transport object to send requests to Google.
93
+
94
+ ```ruby
95
+ transporter = GoogleApps::Transport.new 'domain', 'TOKEN-FROM-OAUTH2-HANDSHAKE'
96
+ ```
97
+
98
+
99
+ Creating an entity is a matter of creating a matching object and sending it to Google.
100
+
101
+ ```ruby
102
+ # Creating a User
103
+ user = GoogleApps::Atom::User.new
104
+ user = GoogleApps::Atom::User.new <xml string>
105
+
106
+ # or
107
+
108
+ user = GoogleApps::Atom.user
109
+ user = GoogleApps::Atom.user <xml string>
110
+
111
+
112
+ user.set login: 'JWilkens', password: 'uncle J', first_name: 'Johnsen', last_name: 'Wilkens'
113
+
114
+ # or
115
+
116
+ user.login = 'JWilkens'
117
+ user.password = 'uncle J'
118
+ user.first_name = 'Johnsen'
119
+ user.last_name = 'Wilkens'
120
+
121
+ transporter.new_user user
122
+ ```
123
+
124
+
125
+ Modifying an entity is also a simple process.
126
+
127
+ ```ruby
128
+ # Modifying a User
129
+ user.last_name = 'Johnson'
130
+ user.suspended = true
131
+
132
+ transporter.update_user 'bob', user
133
+ ```
134
+
135
+
136
+ Deleting is extremely light weight.
137
+
138
+ ```ruby
139
+ transporter.delete_user 'bob'
140
+ ```
141
+
142
+
143
+ Getting an entity record from Google.
144
+
145
+ ```ruby
146
+ # Retrieving a User
147
+ transporter.get_user 'bob'
148
+ ```
149
+
150
+
151
+ Retrieving a batch of entities from Google.
152
+
153
+ ```ruby
154
+ # Retrieving all Users
155
+ users = transporter.get_users
156
+
157
+
158
+ # Retrieving a range of Users
159
+ users = transporter.get_users start: 'lholcomb2', limit: 320
160
+ # Google actually returns records in batches so you will recieve the lowest multiple of 100 that covers your request.
161
+ ```
162
+
163
+
164
+ Google Apps uses public key encryption for mailbox exports and other audit functionality. Adding a key is fairly simple.
165
+
166
+ ```ruby
167
+ # Uploading Public Key
168
+ pub_key = GoogleApps::Atom::PublicKey.new
169
+ pub_key.new_key File.read('key_file')
170
+
171
+ transporter.add_pubkey pub_key
172
+ ```
173
+
174
+
175
+ Google Apps provides a few mail auditing functions. One of those is grabbing a mailbox export. Below is an example.
176
+
177
+ ```ruby
178
+ # Request Mailbox Export
179
+ export_req = GoogleApps::Atom::Export.new
180
+ export_req.query 'from:Bob'
181
+ export_req.content 'HEADER_ONLY'
182
+
183
+ transporter.request_export 'username', export_req
184
+ ```
185
+
186
+
187
+ Your export request will be placed in a queue and processed eventually. Luckily you can check on the status while you wait.
188
+
189
+ ```ruby
190
+ # Check Export Status
191
+ transporter.export_status 'username', <request_id>
192
+ transporter.export_ready? 'username', <request_id>
193
+ ```
194
+
195
+
196
+ Downloading the requested export is simple.
197
+
198
+ ```ruby
199
+ # Download Export
200
+ transporter.fetch_export 'username', 'req_id', 'filename'
201
+ ```
202
+
203
+
204
+ The Google Apps API provides a direct migration option if you happen to have email in msg (RFC 822) format.
205
+
206
+ ```ruby
207
+ # Migrate Email
208
+ attributes = GoogleApps::Atom::MessageAttributes.new
209
+ attributes.add_label 'Migration'
210
+
211
+ transporter.migrate 'username', attributes, File.read(<message>)
212
+ ```
213
+
214
+ ## <a id="Long" /> Long How
215
+
216
+ #### GoogleApps::Transport
217
+
218
+ This is the main piece of the library. The Transport class does all the heavy lifting and communication between your code and the Google Apps Envrionment.
219
+
220
+ Transport will accept a plethora of configuration options. However most have currently sane defaults. In particular the endpoint values should default to currently valid URIs.
221
+
222
+ The only required option is the name of your domain and a valid OAuth2 token:
223
+
224
+ ```ruby
225
+ GoogleApps::Transport.new 'cnm.edu', 'USERS-OAUTH2-TOKEN'
226
+ ```
227
+
228
+ This domain value is used to set up the URIs
229
+
230
+ GoogleApps::Transport is your interface for any HTTP verb related action. It handles GET, PUT, POST and DELETE requests. Transport also provides methods for checking the status of long running requests and downloading content.
231
+
232
+ ### GoogleApps::Atom::User
233
+
234
+ This class represents a user record in the Google Apps Environment. It is basically a glorified LibXML::XML::Document.
235
+
236
+ ```ruby
237
+ user = GoogleApps::Atom::User.new
238
+ user = GoogleApps::Atom::User.new <xml string>
239
+
240
+ # or
241
+
242
+ user = GoogleApps::Atom.user
243
+ user = GoogleApps::Atom.user <xml string>
244
+ ```
245
+
246
+ User provides a basic accessor interface for common attributes.
247
+
248
+ ```ruby
249
+ user.login = 'lholcomb2'
250
+ # password= will return the plaintext password string but will set a SHA1 encrypted password.
251
+ user.password = 'hobobob'
252
+ user.first_name = 'Glen'
253
+ user.last_name = 'Holcomb'
254
+ user.suspended = false
255
+ user.quota = 1000
256
+
257
+
258
+ user.login
259
+ # => 'lholcomb2'
260
+
261
+ # password returns the SHA1 hash of the password
262
+ user.password
263
+ # => 'b8b32c3e5233b4891ae47bd31e36dc472987a7f4'
264
+
265
+ user.first_name
266
+ # => 'Glen'
267
+
268
+ user.last_name
269
+ # => 'Holcomb'
270
+
271
+ user.suspended
272
+ # => false
273
+
274
+ user.quota
275
+ # => 1000
276
+ ```
277
+
278
+ It also provides methods for setting and updating less common nodes and attributes.
279
+
280
+ ```ruby
281
+ user.update_node 'apps:login', :agreedToTerms, true
282
+
283
+ # if the user specification were to change or expand you could manually set nodes in the following way.
284
+ user.add_node 'apps:property', [['locale', 'Spanish']]
285
+ ```
286
+
287
+ GoogleApps::Atom::User also has a to_s method that will return the underlying LibXML::XML::Document as a string.
288
+
289
+
290
+ ### GoogleApps::Atom::Group
291
+
292
+ This class represents a Google Apps Group. Similarly to GoogleApps::Atom::User this is basically a LibXML::XML::Document.
293
+
294
+ ```ruby
295
+ group = GoogleApps::Atom::Group.new
296
+ group = GoogleApps::Atom::Group.new <xml string>
297
+
298
+ # or
299
+
300
+ group = GoogleApps::Atom.group
301
+ group = GoogleApps::Atom.group <xml string>
302
+ ```
303
+
304
+ The Group class provides getters and setter for the standard group properties.
305
+
306
+ ```ruby
307
+ group.id = 'Group ID'
308
+ group.name = 'Example Group'
309
+ group.permissions = 'Domain'
310
+ group.description = 'A Simple Example'
311
+
312
+ group.id
313
+ # => 'Group ID'
314
+ group.name
315
+ # => 'Example Group'
316
+ group.permissions
317
+ # => 'Domain'
318
+ group.description
319
+ # => 'A Simple Example'
320
+ ```
321
+
322
+ *Note:* Group Membership is actually handled separately in the Google Apps Environment, therefore it is handled separately in this library as well (for now at least). See the next section for Group Membership.
323
+
324
+
325
+ ### GoogleApps::Atom::GroupMember
326
+
327
+ This class is representative of a Google Apps Group Member.
328
+
329
+ ```ruby
330
+ member = GoogleApps::Atom::GroupMember.new
331
+ member = GoogleApps::Atom::GroupMember.new <xml string>
332
+
333
+ # or
334
+
335
+ member = GoogleApps::Atom.group_member
336
+ member = GoogleApps::Atom.gorup_member <xml string>
337
+ ```
338
+
339
+ A GroupMember really only has one attribute. The id of the member.
340
+
341
+ ```ruby
342
+ member.member = 'bogus_account@cnme.edu'
343
+
344
+ member.member
345
+ # => 'bogus_account@cme.edu'
346
+ ```
347
+
348
+ To add a group member you need to make an add_member_to request of your GoogleApps::Transport object. The method requires the id of the group the member is being added to as well as the member doucument.
349
+
350
+ ```ruby
351
+ transporter.add_member_to 'Group ID', member
352
+ ```
353
+
354
+ Id's are unique within the Google Apps environment so it is possible to add a group to another group. You just need to supply the group id as the member value for the GoogleApps::Atom::GroupMember object.
355
+
356
+
357
+ ### GoogleApps::Atom::MessageAttributes
358
+
359
+
360
+ The MessageAttributes class represents a Google Apps Message Attribute XML Document.
361
+
362
+ ```ruby
363
+ attributes = GoogleApps::Atom::MessageAttributes.new
364
+ attributes = GoogleApps::Atom::MessageAttributes.new <xml string>
365
+
366
+ # or
367
+
368
+ attributes = GoogleApps::Atom.message_attributes
369
+ attributes = GoogleApps::Atom.message_attributes <xml string>
370
+ ```
371
+
372
+ This document is sent with an email message that is being migrated. It tells Google how to store the message. A Message Attribute object stores the labels for a message along with the "state" or "location" of the message. Basically along with labels you can specify a message as being in the Inbox, Sent, Drafts, or Trash locations.
373
+
374
+ You can add labels.
375
+
376
+ ```ruby
377
+ attributes.add_label 'Migration'
378
+ ```
379
+
380
+ Check labels.
381
+
382
+ ```ruby
383
+ attributes.labels
384
+ ```
385
+
386
+ And remove labels.
387
+
388
+ ```ruby
389
+ attributes.remove_label 'Migration'
390
+ ```
391
+
392
+ You can also specify the "Type" of message. Basically this means you are identifying where it would reside aside from it's labels. The options are IS_INBOX, IS_SENT, IS_DRAFTS, IS_TRASH, IS_STARRED, IS_UNREAD.
393
+
394
+ ```ruby
395
+ attributes.add_property GoogleApps::Atom::MessageAttributes::INBOX
396
+ attributes.add_property GoogleApps::Atom::MessageAttributes::SENT
397
+ attributes.add_property GoogleApps::Atom::MessageAttributes::DRAFT
398
+ attributes.add_property GoogleApps::Atom::MessageAttributes::STARRED
399
+ attributes.add_property GoogleApps::Atom::MessageAttributes::UNREAD
400
+ attributes.add_property GoogleApps::Atom::MessageAttributes::TRASH
401
+
402
+ # or
403
+
404
+ attributes.add_property 'IS_INBOX'
405
+ ```
406
+
407
+ Pretty self explainatory with the exception of IS_STARRED if you are not familiar with Google. Starring is similar to flagging in Exchange.
408
+
409
+
410
+ ### GoogleApps::Atom::Nickname
411
+
412
+ This class represents a Nickname in the Google Apps Environment.
413
+
414
+ In the Google Apps Environment a Nickname consists of two pieces of information. A username and the actual nickname.
415
+
416
+ ```ruby
417
+ nick.nickname = 'Stretch'
418
+ nick.user = 'sarmstrong'
419
+ ```
420
+
421
+ Creating a new nickname is pretty simple.
422
+
423
+ ```ruby
424
+ transporter.add_nickname nick
425
+ ```
426
+
427
+ Nicknames are unique in the scope of your Google Apps Domain so deleting is pretty simple as well.
428
+
429
+ ```ruby
430
+ transporter.delete_nickname 'Stretch'
431
+ ```
432
+
433
+
434
+ ### GoogleApps::Atom::PublicKey
435
+
436
+ As part of the auditing functionality in Google Apps you can request mailbox exports. Those mailbox exports are encrypted before you can download them. The PublicKey class facilitates the upload of the key used in that process.
437
+
438
+ All you need to do is provide a gpg or other key and upload it.
439
+
440
+ ```ruby
441
+ pub_key.new_key File.read(key_file)
442
+
443
+ transporter.new_pubkey pub_key
444
+ ```
445
+
446
+
447
+ ### GoogleApps::Atom::GroupOwner
448
+
449
+ This is a very lightweight class for the manipulation of group owners in the Google Apps environment.
450
+
451
+ The Group Owner document only has one value, address.
452
+
453
+ ```ruby
454
+ owner.address = 'lholcomb2@root.tld'
455
+
456
+ transporter.add_owner_to 'example_group@root.tld', owner
457
+ ```
458
+
459
+ ## <a id="License" /> License
460
+
461
+ #### MIT