Skip to content

Commit 909f56b

Browse files
paul121paul121
committed
Move authentication to docs/authorization.
1 parent 534014c commit 909f56b

File tree

2 files changed

+103
-109
lines changed

2 files changed

+103
-109
lines changed

‎README.md

-109
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,6 @@ For more information on farmOS, visit [farmOS.org](https://farmOS.org).
1313

1414
- [Installation](#installation)
1515
- [Usage](#usage)
16-
- [Authentication](#authentication)
17-
- [OAuth](#OAuth)
18-
- [OAuth Password Credentials](#oauth-password-credentials-most-common)
19-
- [OAuth Authorization Flow](#oauth-authorization-flow-advanced)
20-
- [Saving OAuth Tokens](#saving-oauth-tokens)
2116
- [Server Info](#server-info)
2217
- [Client methods](#client-methods)
2318
- [farmOS 1.x](docs/client_1x.md)
@@ -36,110 +31,6 @@ To install using `conda` see [conda-forge/farmos-feedstock](https://github.com/c
3631

3732
## Usage
3833

39-
### Authentication
40-
41-
The farmOS.py client authenticates with the farmOS server via OAuth `Bearer`
42-
tokens. Before authenticating with the server, a farmOS client must be
43-
created and an OAuth Authorization flow must be completed (unless an optional
44-
`token` was provided when creating the client).
45-
46-
##### Authorizing with Password Credentials (most common)
47-
48-
```python
49-
from farmOS import farmOS
50-
51-
hostname = "myfarm.farmos.net"
52-
username = "username"
53-
password = "password"
54-
55-
# Create the client.
56-
farm_client = farmOS(
57-
hostname=hostname,
58-
client_id = "farm", # Optional. The default oauth client_id "farm" is enabled on all farmOS servers.
59-
scope="farm_manager", # Optional. The default scope is "farm_manager". Only needed if authorizing with a different scope.
60-
version=2 # Optional. The major version of the farmOS server, 1 or 2. Defaults to 2.
61-
)
62-
63-
# Authorize the client, save the token.
64-
# A scope can be specified, but will default to the default scope set when initializing the client.
65-
token = farm_client.authorize(username, password, scope="farm_manager")
66-
```
67-
68-
Running from a Python Console, the `username` and `password` can also be
69-
omitted and entered at runtime. This allows testing without saving
70-
credentials in plaintext:
71-
72-
```python
73-
>>> from farmOS import farmOS
74-
>>> farm_client = farmOS(hostname="myfarm.farmos.net")
75-
>>> farm_client.authorize()
76-
Warning: Password input may be echoed.
77-
Enter username: >? username
78-
Warning: Password input may be echoed.
79-
Enter password: >? password
80-
>>> farm_client.info()
81-
```
82-
83-
##### Authorizing with existing OAuth Token (advanced)
84-
85-
An existing token can be provided when creating the farmOS client. This is
86-
useful for advanced use cases where an OAuth token may be persisted.
87-
88-
```python
89-
from farmOS import farmOS
90-
91-
hostname = "myfarm.farmos.net"
92-
token = {
93-
"access_token": "abcd",
94-
"refresh_token": "abcd",
95-
"expires_at": "timestamp",
96-
}
97-
98-
# Create the client with existing token.
99-
farm_client = farmOS(
100-
hostname=hostname,
101-
token=token,
102-
)
103-
```
104-
105-
##### Saving OAuth Tokens
106-
107-
By default, access tokens expire in 1 hour. This means that requests sent 1
108-
hour after authorization will trigger a `refresh` flow, providing the client
109-
with a new `access_token` to use. A `token_updater` can be provided to save
110-
tokens external of the session when automatic refreshing occurs.
111-
112-
The `token_updater` defaults to an empty lambda function: `lambda new_token: None`.
113-
Alternatively, set `token_updater = None` to allow the [`requests_oauthlib.TokenUpdated`](https://requests-oauthlib.readthedocs.io/en/latest/api.html#requests_oauthlib.TokenUpdated)
114-
exception to be raised and caught by code executing requests from farmOS.py.
115-
116-
```python
117-
from farmOS import farmOS
118-
119-
hostname = "myfarm.farmos.net"
120-
username = "username"
121-
password = "password"
122-
123-
# Maintain an external state of the token.
124-
current_token = None
125-
126-
# Callback function to save new tokens.
127-
def token_updater(new_token):
128-
print(f"Got a new token! {new_token}")
129-
# Update state.
130-
current_token = new_token
131-
132-
# Create the client.
133-
farm_client = farmOS(
134-
hostname=hostname,
135-
token_updater=token_updater, # Provide the token updater callback.
136-
)
137-
138-
# Authorize the client.
139-
# Save the initial token that is created.
140-
current_token = farm_client.authorize(username, password, scope="farm_manager")
141-
```
142-
14334
### Server Info
14435

14536
```python

‎docs/authorization.md

+103
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# Authorization
2+
3+
The farmOS.py client authenticates with the farmOS server via OAuth `Bearer`
4+
tokens. Before authenticating with the server, a farmOS client must be
5+
created and an OAuth Authorization flow must be completed (unless an optional
6+
`token` was provided when creating the client).
7+
8+
## Authorizing with Password Credentials (most common)
9+
10+
```python
11+
from farmOS import farmOS
12+
13+
hostname = "myfarm.farmos.net"
14+
username = "username"
15+
password = "password"
16+
17+
# Create the client.
18+
farm_client = farmOS(
19+
hostname=hostname,
20+
client_id = "farm", # Optional. The default oauth client_id "farm" is enabled on all farmOS servers.
21+
scope="farm_manager", # Optional. The default scope is "farm_manager". Only needed if authorizing with a different scope.
22+
version=2 # Optional. The major version of the farmOS server, 1 or 2. Defaults to 2.
23+
)
24+
25+
# Authorize the client, save the token.
26+
# A scope can be specified, but will default to the default scope set when initializing the client.
27+
token = farm_client.authorize(username, password, scope="farm_manager")
28+
```
29+
30+
Running from a Python Console, the `username` and `password` can also be
31+
omitted and entered at runtime. This allows testing without saving
32+
credentials in plaintext:
33+
34+
```python
35+
>>> from farmOS import farmOS
36+
>>> farm_client = farmOS(hostname="myfarm.farmos.net")
37+
>>> farm_client.authorize()
38+
Warning: Password input may be echoed.
39+
Enter username: >? username
40+
Warning: Password input may be echoed.
41+
Enter password: >? password
42+
>>> farm_client.info()
43+
```
44+
45+
## Authorizing with existing OAuth Token (advanced)
46+
47+
An existing token can be provided when creating the farmOS client. This is
48+
useful for advanced use cases where an OAuth token may be persisted.
49+
50+
```python
51+
from farmOS import farmOS
52+
53+
hostname = "myfarm.farmos.net"
54+
token = {
55+
"access_token": "abcd",
56+
"refresh_token": "abcd",
57+
"expires_at": "timestamp",
58+
}
59+
60+
# Create the client with existing token.
61+
farm_client = farmOS(
62+
hostname=hostname,
63+
token=token,
64+
)
65+
```
66+
67+
## Saving OAuth Tokens
68+
69+
By default, access tokens expire in 1 hour. This means that requests sent 1
70+
hour after authorization will trigger a `refresh` flow, providing the client
71+
with a new `access_token` to use. A `token_updater` can be provided to save
72+
tokens external of the session when automatic refreshing occurs.
73+
74+
The `token_updater` defaults to an empty lambda function: `lambda new_token: None`.
75+
Alternatively, set `token_updater = None` to allow the [`requests_oauthlib.TokenUpdated`](https://requests-oauthlib.readthedocs.io/en/latest/api.html#requests_oauthlib.TokenUpdated)
76+
exception to be raised and caught by code executing requests from farmOS.py.
77+
78+
```python
79+
from farmOS import farmOS
80+
81+
hostname = "myfarm.farmos.net"
82+
username = "username"
83+
password = "password"
84+
85+
# Maintain an external state of the token.
86+
current_token = None
87+
88+
# Callback function to save new tokens.
89+
def token_updater(new_token):
90+
print(f"Got a new token! {new_token}")
91+
# Update state.
92+
current_token = new_token
93+
94+
# Create the client.
95+
farm_client = farmOS(
96+
hostname=hostname,
97+
token_updater=token_updater, # Provide the token updater callback.
98+
)
99+
100+
# Authorize the client.
101+
# Save the initial token that is created.
102+
current_token = farm_client.authorize(username, password, scope="farm_manager")
103+
```

0 commit comments

Comments
 (0)