You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Oct 2, 2023. It is now read-only.
ToopherPython is a Toopher API library that simplifies the task of interfacing with the Toopher API from Python code. This project wrangles all the required OAuth and JSON functionality so you can focus on just using the API.
4
4
5
5
### Python Version
6
-
\>=2.6.0
6
+
* 2.6
7
+
* 2.7
7
8
8
-
### Learn the Toopher API
9
+
### Documentation
9
10
Make sure you visit [https://dev.toopher.com](https://dev.toopher.com) to get acquainted with the Toopher API fundamentals. The documentation there will tell you the details about the operations this API wrapper library provides.
10
11
11
-
### OAuth Authentication
12
-
First off, to access the Toopher API you'll need to sign up for an account at the [Toopher developers portal](https://dev.toopher.com) and create a "requester". When that process is complete, your requester is issued OAuth 1.0a credentials in the form of a consumer key and secret. Your key is used to identify your requester when Toopher interacts with your customers, and the secret is used to sign each request so that we know it is generated by you. This library properly formats each request with your credentials automatically.
13
-
14
-
### The Toopher Two-Step
15
-
Interacting with the Toopher web service involves two steps: pairing, and authenticating.
16
-
17
-
#### Step 0: Create an API Object
18
-
Using your consumer key and consumer secret, create a ToopherApi object which will be used to generate an authentication or user management url and process the postback data.
19
-
20
-
#### Step 1: Pair
21
-
Before you can enhance your website's actions with Toopher, your customers will need to pair their phone's Toopher app with your website. To do this, they generate a unique, nonsensical "pairing phrase" from within the app on their phone. You will need to prompt them for a pairing phrase as part of the Toopher enrollment process. Once you have a pairing phrase, just send it to the Toopher web service and we'll return a pairing ID that you can use whenever you want to authenticate an action for that user.
12
+
## ToopherApi Workflow
22
13
23
-
#### Step 2: Authenticate
24
-
You have complete control over what actions you want to authenticate using Toopher (for example: logging in, changing account information, making a purchase, etc.). Just send us the user's pairing ID, a name for the terminal they're using, and a description of the action they're trying to perform and we'll make sure they actually want it to happen.
25
-
26
-
### Librarified
27
-
This library makes it super simple to do the Toopher two-step. Check it out:
14
+
### Step 1: Pair
15
+
Before you can enhance your website's actions with Toopher, your customers will need to pair their mobile device's Toopher app with your website. To do this, they generate a unique pairing phrase from within the app on their mobile device. You will need to prompt them for a pairing phrase as part of the Toopher enrollment process. Once you have a pairing phrase, just send it to the Toopher web service and we'll return a pairing ID that you can use whenever you want to authenticate an action for that user.
28
16
29
17
```python
30
-
from toopher import*
18
+
importtoopher
31
19
32
-
#Step 0 - Create an API Object Using Your Credentials
20
+
# Create an API Object Using Your Credentials
33
21
api = toopher.ToopherApi("<your consumer key>", "<your consumer secret>")
34
22
35
-
# Step 1 - Pair with their phone's Toopher app
36
-
# With pairing phrase
23
+
# Step 1 - Pair with their mobile device's Toopher app
You have complete control over what actions you want to authenticate using Toopher (for example: logging in, changing account information, making a purchase, etc.). Just send us the user's pairing ID and a name for the terminal they're using and we'll make sure they actually want it to happen.
42
29
30
+
```python
43
31
# Step 2 - Authenticate a log in
44
-
# With pairing id and terminal name
45
-
authentication_request = api.authenticate(pairing.id, "my computer")
46
-
# With username and terminal name and/or requester_specified_id
# Once they've responded you can then check the status
50
35
authentication_request.refresh_from_server()
51
36
ifnot authentication_request.pending and authentication_request.granted:
52
37
# Success!
53
38
```
54
-
### Zero-Storage Usage Option
55
-
Requesters can choose to integrate the Toopher API in a way does not require storing any per-user data such as Pairing ID and Terminal ID - all of the storage
56
-
is handled by the Toopher API Web Service, allowing your local database to remain unchanged. If the Toopher API needs more data, it will `raise()` a specific
57
-
error that allows your code to respond appropriately.
58
-
59
-
```python
60
-
try:
61
-
# Try to authenticate against Toopher API with username and a requester specified id,
62
-
# which is typically a randomly generated secure browser cookie.
63
-
# It does not need to be human-readable and will not be displayed to the user.
# This user does not have an active pairing (typically because they deleted the pairing).
83
-
# You can prompt the user to re-pair with a new mobile device.
84
-
```
85
39
86
-
### Handling Errors
87
-
If any request runs into an error a `ToopherApiError` will be thrown with more details on what went wrong.
40
+
## ToopherIframe Workflow
41
+
### Step 1: Embed a request in an IFRAME
42
+
1. Generate an authentication URL by providing a username.
43
+
2. Display a webpage to your user that embeds this URL within an `<iframe>` element.
88
44
89
-
### Dependencies
90
-
This library uses the [Requests](http://docs.python-requests.org/en/latest/) library and [OAuthLib](https://oauthlib.readthedocs.org/en/latest/index.html) to handle OAuth signing and make the web requests.
45
+
```python
46
+
import toopher
91
47
92
-
Toopher uses [pip](https://pypi.python.org/pypi/pip) to install Python packages.
Check out `demo.py` for an example program that walks you through the whole process! Just download the contents of this repo, make sure you have the dependencies listed above installed, and then run it like-a-this:
Toopher's IFRAME-based flow is the simplest way for web developers to integrate Toopher Two-Factor Authentication into an application.
58
+
### Step 2: Validate the postback data
113
59
114
-
### Toopher IFRAME Overview
60
+
After the Toopher-IFRAME results are posted back to server, the postback data can be validated one of two ways:
115
61
116
-
The IFRAME-based flow works by inserting an `<iframe>` element into the HTML displayed to the user after a successful username/password validation (but before they are actually logged-in to the service). The IFRAME URL is generated by our library and its content is served from the Toopher API server.
62
+
#### 1. Check the authentication request status
63
+
1. Call `is_authentication_granted` to check if the authentication request was granted.
117
64
118
-
The Authentication IFRAME guides the user through the process of pairing (if the user is not paired already) and authenticating with Toopher. Once complete, the IFRAME will return the result of the authentication to your server by `POST`ing the response via HTML to an endpoint of your choice. Your server validates the cryptographic signature using our library which determines whether or not the user successfully authenticated.
119
-
120
-
The User Management IFRAME is available if you would like to manage users separately from the authentication process. Once complete, the IFRAME will return the result of the pairing to your server by POSTing the response via HTML to an endpoint of your choice. Your server validates the cryptographic signature using our library which determines whether or not the user successfully paired.
121
-
122
-
### HTML Markup
123
-
There is no difference in the markup required for an authentication vs. a user management IFRAME request (the generated URL embeds all relevant information).
124
-
125
-
The IFRAME element must have an id of `toopher_iframe`. Pages that include the Toopher IFRAME must include the accompanying javascript library `toopher-web.js` (located in `/assets/js/` in this repository). Toopher's IFRAME content is designed for a minimum size of 400x300 px. In the example below, `{{IFRAME_REQUEST_URL}}` is the authentication or user management URL generated by the ToopherIframe library. `{{POSTBACK_URL}}` is the path on your server where the Toopher-Iframe will submit the result of the authentication when it is finished.
65
+
```python
66
+
# Returns boolean indicating if user should be granted access
We recommend using some form of primary authentication before initiating a Toopher authentication request. Typical primary authentication methods involve verifying that the user has a valid username and password to access the resource being protected.
137
-
138
-
#### Step 1: Embed a request in an IFRAME
139
-
After verifying the user's primary authentication, but before assuming the user's primary authentication checks out, the next step is to kickoff Toopher authentication.
140
-
141
-
1. Generate an authentication URL by specifying the request parameters to the library as detailed below
142
-
2. Display a webpage to your user that embeds this URL within an `<iframe>` element. The markup requirements for the IFRAME element are described in the "HTML Markup" section above.
73
+
#### 2. Process the postback
74
+
Additional information regarding the AuthenticationRequest is easily obtained by using `process_postback`.
143
75
144
-
#### Step 2: Validate the postback data
145
-
146
-
##### Option 1: Process the postback
147
-
1. Toopher-IFRAME results posted back to server.
148
-
2. Call `process_postback()` to verify that the result is valid. `process_postback()` returns one of the following:
76
+
1. Call `process_postback()` to verify that the result is valid. `process_postback()` returns one of the following:
149
77
* an AuthenticationRequest object if the signature is valid (authentication url)
150
78
* a `UserDisabledError`, `SignatureValidationError` or `ToopherAPIError` if the server encounters an error while processing postback
151
-
3. If no errors were returned, the result of the authentication can be checked by evaluating `not authentication_request.pending and authentication_request.granted`.
152
-
153
-
##### Option 2: Check the authentication request status
154
-
1. Toopher-IFRAME results posted back to server.
155
-
2. Call `ToopherIframe.is_authentication_granted` to check if the authentication request was granted.
156
-
157
-
158
-
#### Examples
159
-
160
-
##### Generating an Authentication IFRAME URL
161
-
Though it is not required, every Toopher Authentication session can include a unique `request_token` - a randomized string that is included in the signed request to the Toopher API and returned in the signed response from the Toopher IFRAME. To guard against potential replay attacks, your code should validate that the returned `request_token` is the same one used to create the request.
162
-
163
-
Here's an example of creating a random request token and storing it in the server-side session using Django:
164
-
165
-
```python
166
-
import random, string
167
-
request_token =''.join(random.choice(string.lowercase + string.digits) for i inrange(15))
The Toopher Authentication API provides the requester a rich set of controls over authentication parameters.
79
+
2. If no errors were returned, the result of the authentication can be checked by evaluating `not authentication_request.pending and authentication_request.granted`.
##### Validating Postback Data from Authentication IFRAME & Parsing Errors
185
-
In this example, `data` is a `dict` of the form data POSTed to your server from the Toopher Authentication IFRAME. You should replace the commented blocks in the `except` with code appropriate for the condition described in the comment.
186
-
187
-
There are two ways to validate postback data from an authentication IFRAME:
188
-
189
-
######Process Postback
190
81
```python
191
82
try:
192
83
# Try to process the postback from the Toopher IFRAME and receive an AuthenticationRequest object.
@@ -206,68 +97,27 @@ except toopher.ToopherApiError as e:
206
97
# The postback resource type was not valid.
207
98
```
208
99
209
-
######Check Authentication Request Status
210
-
```python
211
-
# Returns boolean indicating if user should be granted access
We recommend using some form of primary authentication before initiating a Toopher pairing. Typical primary authentication methods involve verifying that the user has a valid username and password to access the resource being protected.
221
-
222
-
#### Step 1: Embed a request in an IFRAME
223
-
After verifying the user's primary authentication, the next step is to kickoff Toopher pairing.
224
-
225
-
1. Generate a user management URL by specifying the request parameters to the library as detailed below
226
-
2. Display a webpage to your user that embeds this URL within an `<iframe>` element. The markup requirements for the IFRAME element are described in the "HTML Markup" section above.
227
100
228
-
#### Step 2: Validate the postback data
229
-
1. Toopher-IFRAME results posted back to server.
230
-
2. Call `process_postback()` to verify that the result is valid. `process_postback()` returns one of the following:
231
-
* a Pairing or User object if the signature is valid (authentication url)
232
-
* a `UserDisabledError`, `SignatureValidationError` or `ToopherAPIError` if the server encounters an error while processing postback
233
-
3. If no errors were returned and you received a Pairing object, the result of the pairing can be checked by evaluating `pairing.enabled`.
234
-
235
-
#### Examples
236
-
##### Generating a User Management IFRAME URL
237
-
The Toopher Authentication API provides the requester a rich set of controls over user management parameters.
101
+
### Handling Errors
102
+
If any request runs into an error a `ToopherApiError` will be thrown with more details on what went wrong.
Check out `demo.py` for an example program that walks you through the whole process! Just download the contents of this repo, make sure you have the dependencies listed above installed, and then run it like-a-this:
106
+
```shell
107
+
$ python demo.py
242
108
```
243
109
244
-
For the simple case of pairing a user, use `get_user_management_url()` in this simple way:
110
+
## Contributing
111
+
### Dependencies
112
+
This library uses the [Requests](http://docs.python-requests.org/en/latest/) library and [OAuthLib](https://oauthlib.readthedocs.org/en/latest/index.html) to handle OAuth signing and make the web requests.
Toopher uses [pip](https://pypi.python.org/pypi/pip) to install Python packages. To ensure all dependencies are up-to-date run:
115
+
```shell
116
+
$ pip install -r requirements.txt
248
117
```
249
118
250
-
##### Validating Postback Data from User Management IFRAME & Parsing Errors
251
-
In this example, `data` is a `dict` of the form data POSTed to your server from the Toopher Pairing IFRAME. You should replace the commented blocks in the `except` with code appropriate for the condition described in the comment.
252
-
253
-
There is one way to validate postback data from a user management IFRAME:
254
-
255
-
######Process Postback
256
-
```python
257
-
try:
258
-
# Try to process the postback from the Toopher IFRAME and receive a Pairing or User object.
0 commit comments