authproto 0.3.0.beta3 → 0.3.0.beta5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +39 -1
- data/README.md +474 -311
- data/examples/basic_webapp/Gemfile +14 -0
- data/examples/{confidential_client → basic_webapp}/Gemfile.lock +1 -1
- data/examples/basic_webapp/README.md +300 -0
- data/examples/basic_webapp/app.rb +351 -0
- data/examples/basic_webapp/config/oauth-client-metadata.localhost.json +11 -0
- data/examples/basic_webapp/public/styles.css +346 -0
- data/examples/basic_webapp/scripts/generate_keys.rb +35 -0
- data/examples/basic_webapp/views/authorized.erb +48 -0
- data/examples/basic_webapp/views/index.erb +48 -0
- data/examples/{confidential_client → basic_webapp}/views/layout.erb +2 -2
- data/examples/bookmarks/Gemfile +16 -0
- data/examples/bookmarks/Gemfile.lock +158 -0
- data/examples/bookmarks/README.md +170 -0
- data/examples/bookmarks/Rakefile +23 -0
- data/examples/bookmarks/app/account.rb +16 -0
- data/examples/bookmarks/app/bookmark.rb +89 -0
- data/examples/bookmarks/app/init.rb +26 -0
- data/examples/bookmarks/app/oauth.rb +43 -0
- data/examples/bookmarks/app/server.rb +184 -0
- data/examples/bookmarks/config/oauth-client-metadata.localhost.json +11 -0
- data/examples/bookmarks/config/oauth-client-metadata.production.json +19 -0
- data/examples/bookmarks/config.ru +5 -0
- data/examples/bookmarks/db/migrate/20261107004141_create_bookmarks.rb +27 -0
- data/examples/bookmarks/db/schema.rb +33 -0
- data/examples/bookmarks/public/styles.css +59 -0
- data/examples/bookmarks/scripts/generate_keys.rb +35 -0
- data/examples/bookmarks/views/bookmarks.erb +86 -0
- data/examples/bookmarks/views/index.erb +17 -0
- data/examples/bookmarks/views/layout.erb +20 -0
- data/examples/minisky_console/Gemfile.lock +2 -2
- data/examples/minisky_console/README.md +29 -25
- data/examples/minisky_console/app.rb +3 -3
- data/examples/minisky_console/localhost.rb +5 -7
- data/examples/minisky_console/production.rb +6 -8
- data/lib/authproto/client.rb +505 -151
- data/lib/authproto/configuration.rb +1 -1
- data/lib/authproto/dpop/client.rb +28 -25
- data/lib/authproto/dpop/key_set.rb +2 -0
- data/lib/authproto/dpop/nonce_manager.rb +24 -25
- data/lib/authproto/dpop/proof_generator.rb +9 -5
- data/lib/authproto/dpop/stored_nonce.rb +7 -5
- data/lib/authproto/dpop.rb +2 -0
- data/lib/authproto/encryption.rb +31 -12
- data/lib/authproto/http_client.rb +13 -12
- data/lib/authproto/http_helpers.rb +6 -0
- data/lib/authproto/metadata/authorization_server.rb +15 -3
- data/lib/authproto/metadata/client_metadata.rb +34 -3
- data/lib/authproto/metadata/resource_server.rb +7 -6
- data/lib/authproto/minisky.rb +120 -33
- data/lib/authproto/par/client.rb +4 -2
- data/lib/authproto/par/client_assertion.rb +4 -1
- data/lib/authproto/par/request.rb +2 -0
- data/lib/authproto/par/response.rb +2 -0
- data/lib/authproto/par.rb +2 -0
- data/lib/authproto/pkce.rb +2 -0
- data/lib/authproto/serialization/session.rb +4 -2
- data/lib/authproto/serialization/stored_nonce.rb +2 -2
- data/lib/authproto/serialization/token_set.rb +5 -2
- data/lib/authproto/state/session.rb +23 -20
- data/lib/authproto/state/session_info.rb +150 -0
- data/lib/authproto/state/session_manager.rb +46 -19
- data/lib/authproto/state/token_set.rb +6 -3
- data/lib/authproto/state.rb +4 -2
- data/lib/authproto/storage/interface.rb +10 -0
- data/lib/authproto/storage/key_builder.rb +3 -3
- data/lib/authproto/storage/memory.rb +24 -18
- data/lib/authproto/storage/sqlite.rb +14 -0
- data/lib/authproto/token/identity.rb +54 -0
- data/lib/authproto/token/refresh.rb +44 -54
- data/lib/authproto/token/response.rb +75 -0
- data/lib/authproto/token/revocation.rb +94 -0
- data/lib/authproto/version.rb +1 -1
- data/lib/authproto.rb +6 -3
- data/sig/authproto/client.rbs +38 -13
- data/sig/authproto/dpop/client.rbs +9 -3
- data/sig/authproto/dpop/nonce_manager.rbs +6 -6
- data/sig/authproto/dpop/proof_generator.rbs +4 -4
- data/sig/authproto/dpop/stored_nonce.rbs +2 -2
- data/sig/authproto/encryption.rbs +4 -2
- data/sig/authproto/http_client.rbs +23 -7
- data/sig/authproto/http_helpers.rbs +1 -0
- data/sig/authproto/metadata/authorization_server.rbs +3 -3
- data/sig/authproto/metadata/client_metadata.rbs +2 -1
- data/sig/authproto/metadata/resource_server.rbs +2 -2
- data/sig/authproto/minisky.rbs +57 -0
- data/sig/authproto/state/session.rbs +13 -4
- data/sig/authproto/state/session_info.rbs +23 -0
- data/sig/authproto/state/session_manager.rbs +10 -3
- data/sig/authproto/storage/interface.rbs +1 -0
- data/sig/authproto/storage/key_builder.rbs +1 -1
- data/sig/authproto/storage/memory.rbs +1 -1
- data/sig/authproto/storage/sqlite.rbs +1 -0
- data/sig/authproto/token/refresh.rbs +2 -1
- data/sig/authproto/token/response.rbs +12 -0
- data/sig/authproto/token/revocation.rbs +15 -0
- data/sig/authproto.rbs +3 -8
- metadata +53 -19
- data/examples/confidential_client/Gemfile +0 -14
- data/examples/confidential_client/README.md +0 -236
- data/examples/confidential_client/app.rb +0 -291
- data/examples/confidential_client/public/styles.css +0 -70
- data/examples/confidential_client/scripts/generate_keys.rb +0 -21
- data/examples/confidential_client/views/authorized.erb +0 -46
- data/examples/confidential_client/views/index.erb +0 -44
- data/sig/authproto/minisky_oauth.rbs +0 -27
- /data/examples/{confidential_client/config/oauth-client-metadata.example.json → basic_webapp/config/oauth-client-metadata.production.json} +0 -0
- /data/examples/{confidential_client → basic_webapp}/config.ru +0 -0
- /data/examples/{confidential_client → basic_webapp}/screenshots/screenshot-1-sign-in.png +0 -0
- /data/examples/{confidential_client → basic_webapp}/screenshots/screenshot-2-success.png +0 -0
data/README.md
CHANGED
|
@@ -1,427 +1,590 @@
|
|
|
1
1
|
# AuthProto
|
|
2
2
|
|
|
3
|
-
[](https://www.rubydoc.info/gems/authproto)
|
|
3
|
+
[](https://rubygems.org/gems/authproto) [](https://rubydoc.info/gems/authproto)
|
|
5
4
|
|
|
6
|
-
A Ruby implementation of
|
|
5
|
+
A Ruby implementation of an OAuth 2.1 client for use in AT Protocol apps.
|
|
7
6
|
|
|
8
|
-
|
|
9
|
-
|
|
7
|
+
Originally released as [atproto_auth](https://github.com/jhuckabee/atproto_auth) by Josh Huckabee in 2024, this is a fork that continues the development.
|
|
8
|
+
|
|
9
|
+
> [!NOTE]
|
|
10
|
+
> Part of ATProto Ruby SDK: [ruby.sdk.blue](https://ruby.sdk.blue)
|
|
10
11
|
|
|
11
12
|
|
|
12
13
|
## Features
|
|
13
14
|
|
|
14
|
-
|
|
15
|
-
- Secure by default with mandatory DPoP and PKCE
|
|
16
|
-
- Support for confidential (backend) and public clients
|
|
17
|
-
- Thread-safe session and token management
|
|
18
|
-
- Comprehensive identity resolution and verification
|
|
19
|
-
- Automatic token refresh and session management
|
|
20
|
-
- Robust error handling and recovery mechanisms
|
|
21
|
-
- Configurable storage backends with built-in SQLite and Redis support
|
|
22
|
-
- Encrypted storage of sensitive data
|
|
15
|
+
The library supports all features of OAuth required by ATProto:
|
|
23
16
|
|
|
24
|
-
|
|
17
|
+
- DPoP (Demonstrating Proof of Possession) and nonce management
|
|
18
|
+
- client, resource server, and authorization server metadata JSON
|
|
19
|
+
- PAR (Pushed Authorization Requests)
|
|
20
|
+
- PKCE (Proof Key for Code Exchange)
|
|
21
|
+
- client assertions for confidential clients
|
|
25
22
|
|
|
26
|
-
|
|
23
|
+
Both public and confidential clients are supported. The main intended use case is backend apps which users authorize to access their ATProto accounts server-side (likely as a confidential client), but it's also possible to use the library in command-line scripts (although in many cases app passwords might still be a better solution for those right now).
|
|
27
24
|
|
|
28
|
-
|
|
29
|
-
gem 'authproto'
|
|
30
|
-
```
|
|
25
|
+
The gem manages the storage of session data and DPoP nonces, and handles at rest encryption of the stored tokens. SQLite, Redis and in-memory storage backends are included.
|
|
31
26
|
|
|
32
|
-
|
|
27
|
+
There is also an (a bit experimental) adapter for using AuthProto with the [Minisky gem](https://tangled.org/mackuba.eu/minisky) to make XRPC requests with OAuth login support.
|
|
33
28
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
29
|
+
> [!NOTE]
|
|
30
|
+
> This gem deliberately does not support any features, profiles and configurations of OAuth that are not currently
|
|
31
|
+
used in ATProto, and it does not support turning off any additional requirements and restrictions that ATProto
|
|
32
|
+
introduces on top of standard OAuth specifications. For example, DPoP with server nonces, PAR, and PKCE are always required, and the client ID must be a URL from which the client metadata is fetched.
|
|
33
|
+
>
|
|
34
|
+
> It will likely not be of much use in non-ATProto contexts. This is intentional, in order to not make the project more complicated than it already is.
|
|
37
35
|
|
|
38
|
-
Or install it yourself as:
|
|
39
36
|
|
|
40
|
-
|
|
41
|
-
gem install authproto
|
|
42
|
-
```
|
|
37
|
+
## Status
|
|
43
38
|
|
|
44
|
-
|
|
39
|
+
The project was originally written in 2024. I have forked it, reviewed the code, refactored a lot of it, and made a lot of bug fixes to make everything more up to date and compliant with current ATProto OAuth. It has a pretty complete test coverage (converted from Minitest to RSpec), and it has been reviewed by a few AI agents, with no major outstanding issues left at the moment.
|
|
45
40
|
|
|
46
|
-
|
|
47
|
-
- OpenSSL support
|
|
48
|
-
- For confidential clients: HTTPS-capable domain for client metadata hosting
|
|
49
|
-
- Optional: SQLite or Redis storage adapter gems for production use
|
|
41
|
+
I'm not currently using it in production at all yet, so consider this still alpha quality. Might kill your cat, steal your girlfriend, and so on…
|
|
50
42
|
|
|
51
|
-
|
|
43
|
+
The public API will likely be changing in some initial releases. The `AuthProto::Client` entry point will likely be the most stable part, but treat most of the rest of the library as private API / implementation detail for now.
|
|
52
44
|
|
|
53
|
-
### Configuration
|
|
54
45
|
|
|
55
|
-
|
|
56
|
-
require 'authproto'
|
|
46
|
+
## Installation & requirements
|
|
57
47
|
|
|
58
|
-
AuthProto.
|
|
59
|
-
# Configure HTTP client settings
|
|
60
|
-
config.http_client = AuthProto::HTTPClient.new(
|
|
61
|
-
timeout: 10,
|
|
62
|
-
verify_ssl: true
|
|
63
|
-
)
|
|
64
|
-
|
|
65
|
-
# Set the default nonce cache lifetime (seconds), used by newly created clients.
|
|
66
|
-
config.dpop_nonce_lifetime = 300 # 5 minutes
|
|
48
|
+
AuthProto requires Ruby version 3.3 or newer (versions 3.2 and older no longer receive maintenance updates). Tested on versions up to 4.0.
|
|
67
49
|
|
|
68
|
-
|
|
69
|
-
config.client_assertion_lifetime = 300 # 5 minutes
|
|
50
|
+
To use it in your app, add this to your `Gemfile`:
|
|
70
51
|
|
|
71
|
-
|
|
72
|
-
config.storage = AuthProto::Storage::Memory.new
|
|
73
|
-
end
|
|
74
|
-
|
|
75
|
-
# Storage adapter gems are optional dependencies. Add one of these:
|
|
76
|
-
gem 'sqlite3', '~> 2.9'
|
|
77
|
-
gem 'redis', '~> 5.4'
|
|
78
|
-
```
|
|
52
|
+
gem 'authproto'
|
|
79
53
|
|
|
80
|
-
|
|
81
|
-
managers. Its default is 300 seconds. An explicit `NonceManager.new(ttl: ...)` or
|
|
82
|
-
`DPoP::Client.new(nonce_ttl: ...)` overrides it. Existing managers retain the
|
|
83
|
-
lifetime chosen at initialization.
|
|
54
|
+
Depending on the configured storage, you will also need to add either the `sqlite3` gem or the `redis` gem, and `minisky` if you want to use the Minisky XRPC client. These are not explicit dependencies so they're not forced on you if you don't need them.
|
|
84
55
|
|
|
85
|
-
`client_assertion_lifetime` must also be a positive integer and defaults to 300
|
|
86
|
-
seconds. It is read for each assertion, including by existing clients and signers.
|
|
87
|
-
An explicit `ClientAssertion#generate_jwt(lifetime: ...)` overrides the configured
|
|
88
|
-
default. This controls assertion validity, not access-token or session lifetime.
|
|
89
56
|
|
|
90
|
-
|
|
57
|
+
## Initial configuration
|
|
91
58
|
|
|
92
|
-
|
|
93
|
-
resolution, metadata discovery and OAuth requests), explicitly select:
|
|
59
|
+
The first thing you need to do is to set up a few required things in the global configuration:
|
|
94
60
|
|
|
95
|
-
```
|
|
61
|
+
```rb
|
|
96
62
|
AuthProto.configure do |config|
|
|
97
|
-
|
|
63
|
+
...
|
|
98
64
|
end
|
|
99
65
|
```
|
|
100
66
|
|
|
101
|
-
|
|
102
|
-
destinations, and permits redirects between them. It disables the regular client's
|
|
103
|
-
scheme/IP restrictions for development; HTTPS certificate verification stays enabled
|
|
104
|
-
by default. Timeouts, response size limits and request headers are inherited.
|
|
105
|
-
|
|
106
|
-
The regular `HTTPClient` accepts HTTPS and rejects loopback/private addresses.
|
|
107
|
-
Use it for remote OAuth servers, including when your application's callback is
|
|
108
|
-
local: the browser, rather than this HTTP client, follows the callback redirect.
|
|
67
|
+
There are two required settings to be configured:
|
|
109
68
|
|
|
110
|
-
|
|
111
|
-
200 with an `application/json` response. Custom HTTP clients must support this
|
|
112
|
-
keyword and return the initial response without following redirects when it is false.
|
|
69
|
+
### <u>http_client:</u>
|
|
113
70
|
|
|
114
|
-
|
|
115
|
-
public clients or `private_key_jwt` for confidential clients. Omitting it defaults
|
|
116
|
-
to `client_secret_basic` in OAuth metadata, which this library does not support.
|
|
71
|
+
This configures a HTTP client for making requests to the authorization server and to metadata endpoints during the initial authorization process and later token refreshing (**not** for later authorized data requests to the PDS). Set it either to an instance of the default `AuthProto::HTTPClient`, or a compatible custom implementation/adapter.
|
|
117
72
|
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
The client ID query can specify one `scope` parameter and multiple `redirect_uri`
|
|
122
|
-
parameters, encoded using `URI.encode_www_form`. These values are decoded and
|
|
123
|
-
validated; the original client ID is preserved exactly.
|
|
73
|
+
```rb
|
|
74
|
+
config.http_client = AuthProto::HTTPClient.new
|
|
75
|
+
```
|
|
124
76
|
|
|
125
|
-
###
|
|
77
|
+
### <u>storage:</u>
|
|
126
78
|
|
|
127
|
-
|
|
79
|
+
This configures the storage adapter for storing session data and DPoP nonces.
|
|
128
80
|
|
|
129
|
-
|
|
130
|
-
Configure the lifetime in seconds with a positive integer:
|
|
81
|
+
The available options are:
|
|
131
82
|
|
|
132
|
-
|
|
133
|
-
AuthProto
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
```
|
|
83
|
+
* an SQLite database (`AuthProto::Storage::SQLite`, requires additionally the `sqlite3` gem)
|
|
84
|
+
* a Redis database (`AuthProto::Storage::Redis`, requires additionally the `redis` gem)
|
|
85
|
+
* an in-memory storage for testing (`AuthProto::Storage::Memory`)
|
|
86
|
+
* it's also possible to implement a custom storage adapter, providing the same interface (see `AuthProto::Storage::Interface`)
|
|
137
87
|
|
|
138
|
-
|
|
139
|
-
the pending deadline and state-token lookup. Authenticated sessions without refresh tokens
|
|
140
|
-
expire with their access token; sessions with refresh tokens have no automatic storage expiry.
|
|
88
|
+
A basic configuration may look like this:
|
|
141
89
|
|
|
142
|
-
|
|
90
|
+
```rb
|
|
91
|
+
require 'authproto'
|
|
143
92
|
|
|
144
|
-
```ruby
|
|
145
|
-
# Default configuration - good for development
|
|
146
93
|
AuthProto.configure do |config|
|
|
147
|
-
config.
|
|
148
|
-
end
|
|
149
|
-
```
|
|
150
|
-
|
|
151
|
-
#### SQLite Storage
|
|
152
|
-
|
|
153
|
-
SQLite can be used for persistent storage in development or in production setups with
|
|
154
|
-
low-to-moderate write concurrency:
|
|
94
|
+
config.http_client = AuthProto::HTTPClient.new(timeout: 10)
|
|
155
95
|
|
|
156
|
-
```ruby
|
|
157
|
-
AuthProto.configure do |config|
|
|
158
96
|
config.storage = AuthProto::Storage::SQLite.new(
|
|
159
|
-
path:
|
|
97
|
+
path: File.join(__dir__, "db", "localhost_auth.sqlite3")
|
|
160
98
|
)
|
|
161
99
|
end
|
|
162
100
|
```
|
|
163
101
|
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
```ruby
|
|
167
|
-
gem 'sqlite3', '~> 2.9'
|
|
168
|
-
```
|
|
169
|
-
|
|
170
|
-
#### Redis Storage
|
|
171
|
-
|
|
172
|
-
Use Redis for production deployments with multiple hosts or write-heavy scenarios:
|
|
102
|
+
For more complex production setups you may want to use Redis instead, which is configured like this:
|
|
173
103
|
|
|
174
104
|
```ruby
|
|
175
105
|
require 'redis'
|
|
176
106
|
|
|
177
107
|
AuthProto.configure do |config|
|
|
178
108
|
redis_client = Redis.new(
|
|
179
|
-
url: ENV
|
|
109
|
+
url: ENV.fetch('REDIS_URL'),
|
|
180
110
|
ssl_params: { verify_mode: OpenSSL::SSL::VERIFY_PEER }
|
|
181
111
|
)
|
|
182
|
-
|
|
112
|
+
|
|
183
113
|
config.storage = AuthProto::Storage::Redis.new(
|
|
184
114
|
redis_client: redis_client
|
|
185
115
|
)
|
|
186
116
|
end
|
|
187
117
|
```
|
|
188
118
|
|
|
189
|
-
|
|
119
|
+
The `AuthProto::Storage::Memory` adapter is configured by default, so you can skip the `storage` part if you want to use it.
|
|
190
120
|
|
|
191
|
-
|
|
192
|
-
|
|
121
|
+
For the `SQLite` adapter, you might call `AuthProto.storage.cleanup_expired_records` periodically to remove expired sessions and locks if you want. `Memory` and `Redis` handle this automatically.
|
|
122
|
+
|
|
123
|
+
It's not recommended to use AuthProto's storage for other purposes beyond what the library reads & writes to it internally.
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
### ATPROTO_MASTER_KEY:
|
|
127
|
+
|
|
128
|
+
This is technically not required, but you'll want to set it for anything more than brief testing. In the session storage, things like state token and access tokens are encrypted at rest using a key read from an ENV var `ATPROTO_MASTER_KEY`. The var needs to be Base64-encoded, and 32 bytes long when decoded.
|
|
129
|
+
|
|
130
|
+
You can generate it e.g. like this:
|
|
131
|
+
|
|
132
|
+
```
|
|
133
|
+
openssl rand -base64 32
|
|
193
134
|
```
|
|
194
135
|
|
|
195
|
-
|
|
196
|
-
```ruby
|
|
197
|
-
# Implement your own storage backend
|
|
198
|
-
class CustomStorage < AuthProto::Storage::Interface
|
|
199
|
-
def set(key, value, ttl: nil)
|
|
200
|
-
# Implementation
|
|
201
|
-
end
|
|
136
|
+
And then set it e.g. by adding `ATPROTO_MASTER_KEY=...` on the command line, or with `export`, or with something like [dotenv](https://github.com/bkeepers/dotenv).
|
|
202
137
|
|
|
203
|
-
|
|
204
|
-
# Implementation
|
|
205
|
-
end
|
|
138
|
+
If you don't set it, you will see a warning like this:
|
|
206
139
|
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
140
|
+
```
|
|
141
|
+
WARNING: Using randomly generated encryption key - tokens will not persist across restarts
|
|
142
|
+
```
|
|
210
143
|
|
|
211
|
-
def exists?(key)
|
|
212
|
-
# Implementation
|
|
213
|
-
end
|
|
214
144
|
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
145
|
+
## Usage
|
|
146
|
+
|
|
147
|
+
The main class and the entry point to the library is the `AuthProto::Client` class. You will likely only need to create and use this one directly.
|
|
148
|
+
|
|
149
|
+
The initializer looks like this:
|
|
150
|
+
|
|
151
|
+
```rb
|
|
152
|
+
client = AuthProto::Client.new(
|
|
153
|
+
client_id: "https://...",
|
|
154
|
+
redirect_uri: "https://...",
|
|
155
|
+
metadata: { ... },
|
|
156
|
+
signing_key: signing_key
|
|
157
|
+
)
|
|
219
158
|
```
|
|
220
159
|
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
Each new OAuth session generates its own DPoP key before PAR. The session serializer
|
|
224
|
-
stores its private JWK with the session and encrypts the private `d` component.
|
|
225
|
-
Restoring the session restores that same key for code exchange, refresh and API
|
|
226
|
-
requests. Configure persistent storage and a stable `ATPROTO_MASTER_KEY` to retain
|
|
227
|
-
sessions across application restarts.
|
|
228
|
-
|
|
229
|
-
`Client` and the Minisky integration no longer accept `dpop_key:`. Restore sessions
|
|
230
|
-
by their session ID; no separate key export or constructor argument is needed.
|
|
231
|
-
`Client#dpop_client` remains shared and accepts `session:` when generating proofs.
|
|
232
|
-
Its `ProofGenerator` accepts `key_set:` per call. Nonces are stored separately with
|
|
233
|
-
TTLs, indexed by session ID and server origin. URLs on the same origin share a
|
|
234
|
-
nonce within that session; other sessions and origins have independent nonces.
|
|
235
|
-
`DPoP::Client#with_nonce_handling(session, url) { ... }` runs a request block,
|
|
236
|
-
processes its response, and runs it once more if the server sends a nonce challenge.
|
|
237
|
-
The block must generate a fresh proof and send the request on each invocation.
|
|
238
|
-
The helper returns the final response; other errors and exceptions are left to
|
|
239
|
-
its caller. PAR, code exchange, and refresh use this helper.
|
|
240
|
-
|
|
241
|
-
`DPoP::Client#process_response` accepts the whole HTTP response hash and requires
|
|
242
|
-
`server_url:` and `session_id:` to update the requesting
|
|
243
|
-
session's nonce. When sending requests without `with_nonce_handling`, call it
|
|
244
|
-
for every DPoP response, including successes, failures, and retry responses; missing or empty `DPoP-Nonce` headers raise an error. Nonces must use RFC 9449's
|
|
245
|
-
`NQCHAR` syntax; malformed values and duplicate nonce headers are rejected.
|
|
246
|
-
`has_nonce_error?` recognizes HTTP 400 JSON nonce errors and HTTP 401 DPoP
|
|
247
|
-
authentication challenges. It does not update the nonce or send a retry.
|
|
248
|
-
Direct nonce manager calls to `get`, `update`, and `clear` also
|
|
249
|
-
require `server_url:` and `session_id:` keywords. Old per-server cache entries are
|
|
250
|
-
ignored and expire normally; a missing nonce can be obtained through a server challenge.
|
|
251
|
-
|
|
252
|
-
Serialized sessions from older versions that lack a private DPoP key cannot be
|
|
253
|
-
restored: start authorization again. Loading never generates a replacement key for
|
|
254
|
-
an existing session. Client-authentication signing keys remain separate from these
|
|
255
|
-
per-session DPoP keys.
|
|
256
|
-
|
|
257
|
-
### Confidential Client Example
|
|
258
|
-
|
|
259
|
-
Here's a basic example of using the library in a confidential client application:
|
|
260
|
-
|
|
261
|
-
Supply the private EC P-256 client-authentication JWK through `signing_key:`,
|
|
262
|
-
separately from metadata. It must have a nonempty `kid` and permit ES256 signing.
|
|
263
|
-
Metadata's `jwks` contains only public keys; the client checks that the matching
|
|
264
|
-
public key and `kid` are advertised and active. A public key may declare
|
|
265
|
-
`use: "sig"` or `key_ops: ["verify"]`.
|
|
266
|
-
Each key in an inline `jwks` must have a distinct, case-sensitive `kid`.
|
|
267
|
-
Other advertised public keys may serve other purposes, such as encryption;
|
|
268
|
-
the matching authentication key must permit signature verification.
|
|
269
|
-
|
|
270
|
-
With `jwks_uri`, the client still uses your separate private signing key. It does
|
|
271
|
-
not fetch that URL or check the advertised key locally; the authorization server
|
|
272
|
-
fetches it to verify assertions.
|
|
273
|
-
|
|
274
|
-
New confidential-client sessions record the signing key's `kid` as `signing_key_id`
|
|
275
|
-
and its RFC 7638 SHA-256 thumbprint as `signing_key_thumbprint` before PAR. Both
|
|
276
|
-
values persist through callbacks and refreshes without including the private
|
|
277
|
-
client-authentication key. The session manager returns `nil` if the key ID is
|
|
278
|
-
unsupported or its thumbprint no longer matches, leaving stored data intact.
|
|
279
|
-
`Client` supplies a key-ID-to-thumbprint mapping derived from its configured
|
|
280
|
-
private signing key, rather than the public keys advertised in metadata.
|
|
281
|
-
Sessions with a recorded key ID but no thumbprint must authorize again.
|
|
282
|
-
Clients still accept one `signing_key:`; automatic key selection and rotation
|
|
283
|
-
are not implemented.
|
|
284
|
-
|
|
285
|
-
Public-client sessions have no signing key ID. Older serialized sessions without
|
|
286
|
-
this field remain readable and use the configured signing key without an ID check;
|
|
287
|
-
their original key ID cannot be inferred from the stored session.
|
|
160
|
+
The first two arguments are required, the other two are optional. What you put into these will depend on how you're running the app: on a publicly accessible server or on localhost, and as a public or a confidential client.
|
|
288
161
|
|
|
289
|
-
|
|
290
|
-
|
|
162
|
+
|
|
163
|
+
### <u>On a production server</u>
|
|
164
|
+
|
|
165
|
+
The normal, expected way to run an OAuth app is that you have a publicly accessible server (with HTTPS) on which you can at least host the client metadata JSON file – even if you're building e.g. a native iOS app. This can be a completely static site hosting just the JSON file, if you don't need anything else, but it needs to be there (though in case of a Ruby app, you will also need some kind of callback endpoint to receive authorization codes).
|
|
166
|
+
|
|
167
|
+
The metadata can technically be located at any path you want, but it's strongly recommended to put it at `/oauth-client-metadata.json`: this will make the PDS display your app as just a hostname, like "_**foobar.com** wants to access your account_", otherwise the full URL with the path will be shown, which looks less friendly.
|
|
168
|
+
|
|
169
|
+
Client metadata is a JSON file that includes information about your app like the name and requested permissions, and the enabled security features. What exactly goes into it is a bit beyond the scope of this readme, you can see the details in the [ATProto OAuth spec](https://atproto.com/specs/oauth#client-id-metadata-document).
|
|
170
|
+
|
|
171
|
+
Once you have the file readable on the server, you can create the `Client` passing it the `client_id` – which is the full URL to the metadata JSON file – and a `redirect_uri` to which the user's browser will be redirected after authorization:
|
|
172
|
+
|
|
173
|
+
```rb
|
|
291
174
|
client = AuthProto::Client.new(
|
|
292
|
-
client_id: "https://
|
|
293
|
-
redirect_uri: "https://
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
175
|
+
client_id: "https://site.example.com/oauth-client-metadata.json",
|
|
176
|
+
redirect_uri: "https://site.example.com/callback"
|
|
177
|
+
)
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
If you host the metadata file from the same codebase, you can also include the `metadata` here inline as a Hash. It's not required – it will be fetched from the live URL here otherwise – but if you do, it saves you one request whenever `Client` is created. (Note, this is a fetch on the *client* side so the library can get more info about the app and validate it – the *authorization server* will still need to fetch this JSON file even if you provide the `metadata` here.)
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
### <u>Confidential clients</u>
|
|
184
|
+
|
|
185
|
+
The example above is for a **public client**; this has nothing to do with it running on a public server – a "public client" is one that doesn't have a set of secret signing keys kept server-side, and those get shorter access & refresh token lifetimes.
|
|
186
|
+
|
|
187
|
+
The other type is a **confidential client**; to run one, you need a set of keys to sign *client assertions*. The key is a JSON representation of an elliptic curve key in the form of a [JWK (JSON Web Key)](https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-key-sets), like this:
|
|
188
|
+
|
|
189
|
+
```json
|
|
190
|
+
{
|
|
191
|
+
"kty": "EC",
|
|
192
|
+
"crv": "P-256",
|
|
193
|
+
"kid": "key-1",
|
|
194
|
+
"x": "1vhfr8lFBg0jhXMNoXn-XWtpxR9nu8Ja1JGFrWqDIV8",
|
|
195
|
+
"y": "sBgQICMTA8MBeD_TgdJduJmmhEQ9pA5l4EPUBtBeZOg",
|
|
196
|
+
"d": "rqnhaaobMsqhWAnCWJGzioXbrqBFQ_59I2dhF_cw1dA",
|
|
197
|
+
"use": "sig"
|
|
198
|
+
}
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
This is a private key, a public key lacks the `d` field. You can generate those e.g. using this [generate_keys.rb script](https://tangled.org/mackuba.eu/authproto/blob/main/examples/basic_webapp/scripts/generate_keys.rb) from the example app in [examples folder](https://tangled.org/mackuba.eu/authproto/tree/main/examples/) here.
|
|
202
|
+
|
|
203
|
+
Once you have the keys, put the public one under `jwks.keys` in the metadata JSON:
|
|
204
|
+
|
|
205
|
+
```json
|
|
206
|
+
{
|
|
207
|
+
...
|
|
208
|
+
"jwks": {
|
|
209
|
+
"keys": [{ "x": ... }]
|
|
297
210
|
}
|
|
211
|
+
}
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
And pass the private one as `signing_key` to the `Client`:
|
|
215
|
+
|
|
216
|
+
```rb
|
|
217
|
+
client = AuthProto::Client.new(
|
|
218
|
+
client_id: "https://site.example.com/oauth-client-metadata.json",
|
|
219
|
+
redirect_uri: "https://site.example.com/callback",
|
|
220
|
+
signing_key: { x: ... }
|
|
298
221
|
)
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
You also need these fields set in the metadata JSON like this:
|
|
225
|
+
|
|
226
|
+
```json
|
|
227
|
+
"token_endpoint_auth_method": "private_key_jwt",
|
|
228
|
+
"token_endpoint_auth_signing_alg": "ES256",
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
With a setup like this, you get much longer potential session length, assuming correctly implemented token refresh.
|
|
232
|
+
|
|
233
|
+
|
|
234
|
+
### <u>Testing on localhost</u>
|
|
235
|
+
|
|
236
|
+
Running OAuth on localhost is a bit of a special exception, it doesn't work the way it works normally:
|
|
237
|
+
|
|
238
|
+
* the `client_id` URL needs to be `http://localhost/`, **without a port**, and with this literal hostname, **not as a loopback IP**
|
|
239
|
+
* the metadata JSON file isn't fetched from the URL, but it's instead generated from preset values and from URL query parameters (`Client` will reject a `metadata` parameter here)
|
|
240
|
+
* you can configure `redirect_uri` and `scope` by appending them as query params (with encoded values) to the `client_id`
|
|
241
|
+
* the `redirect_uri` needs to be on `127.0.0.1` or `[::1]` IP (likely with a port), **not** on `localhost`, confusingly
|
|
242
|
+
* the app will always be a "public" client, not a "confidential" one
|
|
243
|
+
|
|
244
|
+
The client ID will then look something like this:
|
|
299
245
|
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
246
|
+
```
|
|
247
|
+
http://localhost/?redirect_uri=http%3A%2F%2F127.0.0.1%3A8000%2Fcallback&scope=atproto+repo%3Aapp.bsky.feed.post
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
`AuthProto::Client` includes a special helper `Client.for_localhost` which generates this `client_id` with encoded query params for you:
|
|
251
|
+
|
|
252
|
+
```rb
|
|
253
|
+
client = AuthProto::Client.for_localhost(
|
|
254
|
+
redirect_uri: "http://127.0.0.1:8000/callback",
|
|
255
|
+
scope: "atproto repo:app.bsky.feed.post"
|
|
304
256
|
)
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
|
|
260
|
+
## Using the Client
|
|
261
|
+
|
|
262
|
+
Regardless of the configuration, the rest of the API is the same. The expected steps are:
|
|
263
|
+
|
|
264
|
+
|
|
265
|
+
### Create an authorization URL
|
|
266
|
+
|
|
267
|
+
You can start the authorization process either with a specific user handle/DID – then their PDS will be looked up and they will be redirected there and asked to log in with this specific account – or from a PDS URL, in which case they will go to the PDS's site, but presented with a login form or account selection:
|
|
268
|
+
|
|
269
|
+
```rb
|
|
270
|
+
client.authorize(handle: 'user.handle', scope: 'atproto ...')
|
|
271
|
+
client.authorize(pds: 'https://pds.example.com', scope: 'atproto ...')
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
This returns a hash like:
|
|
275
|
+
|
|
276
|
+
```rb
|
|
277
|
+
{
|
|
278
|
+
url: "https://lab.martianbase.net/oauth/authorize?request_uri=.....",
|
|
279
|
+
session_id: "20044fc4-1131-47f9-90f8-99c26fe82a00"
|
|
280
|
+
}
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
Depending on your app, either redirect the user to this URL, or present it to the user and ask them to open it and log in there. Write down this session ID too – you'll need it in a moment (for a web app, store it e.g. in a session variable).
|
|
284
|
+
|
|
285
|
+
|
|
286
|
+
### Handle the callback request
|
|
305
287
|
|
|
306
|
-
|
|
307
|
-
session[:pending_oauth_session_id] = auth.fetch(:session_id)
|
|
288
|
+
After the user approves or rejects the request, they will be redirected to your configured `redirect_uri`. Check the received params for an `error` key – if it's set, handle the error in some appropriate way.
|
|
308
289
|
|
|
309
|
-
#
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
expected_session_id: session[:
|
|
290
|
+
If there's no error, pass the received query parameters to `Client#handle_callback`. Note: you will need to also pass the ID of the session from which the login was initiated. This is to make sure that we don't log in a user completing authorization into *another user's* account:
|
|
291
|
+
|
|
292
|
+
```rb
|
|
293
|
+
client.handle_callback(
|
|
294
|
+
params,
|
|
295
|
+
expected_session_id: session[:session_id]
|
|
315
296
|
)
|
|
316
|
-
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
You can also skip checking for `error` and just pass the params to `handle_callback`, in which case you will get a `CallbackError` raised with the error details if the params included an error.
|
|
300
|
+
|
|
301
|
+
For localhost clients, there is also a helper class included called `LocalhostServer`, which starts a temporary localhost HTTP server inline just to receive the callback request, and returns the received codes to the block you pass to it:
|
|
302
|
+
|
|
303
|
+
```rb
|
|
304
|
+
AuthProto::LocalhostServer.start(client.client_metadata) do |json|
|
|
305
|
+
client.handle_callback(json, expected_session_id: session_id)
|
|
306
|
+
end
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
### Load session data
|
|
310
|
+
|
|
311
|
+
When coming back later to a previously saved session, you will need to look it up in the storage using the session ID and see if's still usable and check its state:
|
|
312
|
+
|
|
313
|
+
```rb
|
|
314
|
+
info = client.get_session(session_id)
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
`get_session` returns a `SessionInfo` object with these methods:
|
|
318
|
+
|
|
319
|
+
- `session_id` - the session's unique identifier
|
|
320
|
+
- `access_token` - the current access token, or `nil` before authorization
|
|
321
|
+
- `refresh_token` - the current refresh token, or `nil` if none was issued
|
|
322
|
+
- `expires_at` - the access token's expiry time, or `nil` before authorization
|
|
323
|
+
- `expires_in` - seconds remaining until the access token expires
|
|
324
|
+
- `requested_scope` - list of requested permissions
|
|
325
|
+
- `granted_scope` - list of actually granted permissions
|
|
326
|
+
- `did` - the account's DID, if known
|
|
327
|
+
- `pds` - the URL of the account's PDS, if known
|
|
328
|
+
- `pending?` - if authorization is still pending
|
|
329
|
+
- `tokens_valid?` or `authorized?` - if an access token was issued and is valid (not expired)
|
|
330
|
+
- `renewable?` - if the session has a refresh token
|
|
331
|
+
- `has_limited_scope?` - if any requested permissions are missing from the current grant
|
|
332
|
+
- `can_be_revoked?` - if the authorization server supports token revocation
|
|
333
|
+
|
|
334
|
+
|
|
335
|
+
### Refresh the tokens
|
|
336
|
+
|
|
337
|
+
The access tokens usually have a lifetime of around 15-30 minutes, and after that time, you will get a 401 error (or `Client` can raise `Client::TokenError` if it detects an expired token earlier). In that case, call `refresh_token` to use the other token you got (the refresh token) to get a new access token:
|
|
338
|
+
|
|
339
|
+
```rb
|
|
340
|
+
client.refresh_token(session_id)
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
It might also be a good idea to check the token's expiration date before making the request and refreshing it in advance if needed:
|
|
344
|
+
|
|
345
|
+
```rb
|
|
346
|
+
if !session.tokens_valid?
|
|
347
|
+
session = client.refresh_token(session_id)
|
|
348
|
+
end
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
Replace the previously returned value with the return value from `refresh_token` – the method looks up a new session object, and the previous object is not updated in place.
|
|
352
|
+
|
|
353
|
+
|
|
354
|
+
### Make authenticated data requests
|
|
355
|
+
|
|
356
|
+
This part is a bit more complicated, because this API is designed to allow working with any HTTP client library you're using. `AuthProto::Client` by itself doesn't implement a full XRPC client for making requests and handling responses. What it gives you is a way to get a set of authentication headers generated for a specific request (method + URL) that you can then pass to e.g. `Net::HTTP` or [Faraday](https://github.com/lostisland/faraday):
|
|
357
|
+
|
|
358
|
+
```rb
|
|
359
|
+
endpoint = "https://#{pds_host}/xrpc/com.atproto.repo.createRecord"
|
|
360
|
+
session = client.get_session(session_id)
|
|
361
|
+
|
|
362
|
+
if !session.tokens_valid?
|
|
363
|
+
session = client.refresh_token(session_id)
|
|
364
|
+
end
|
|
317
365
|
|
|
318
|
-
# Make authenticated requests
|
|
319
366
|
headers = client.auth_headers(
|
|
320
|
-
session_id:
|
|
321
|
-
method:
|
|
322
|
-
url:
|
|
367
|
+
session_id: session_id,
|
|
368
|
+
method: 'POST',
|
|
369
|
+
url: endpoint
|
|
323
370
|
)
|
|
371
|
+
|
|
372
|
+
connection = Faraday.new do |f|
|
|
373
|
+
f.request :json
|
|
374
|
+
end
|
|
375
|
+
|
|
376
|
+
post_record = {
|
|
377
|
+
repo: session.did,
|
|
378
|
+
collection: "app.bsky.feed.post",
|
|
379
|
+
record: {
|
|
380
|
+
text: "Hello world!",
|
|
381
|
+
langs: ["en"],
|
|
382
|
+
createdAt: Time.now.utc.iso8601(3)
|
|
383
|
+
}
|
|
384
|
+
}
|
|
385
|
+
|
|
386
|
+
res = connection.post(endpoint) do |req|
|
|
387
|
+
req.headers.merge!(headers)
|
|
388
|
+
req.body = post_record
|
|
389
|
+
end
|
|
324
390
|
```
|
|
325
391
|
|
|
326
|
-
|
|
327
|
-
- Complete OAuth flow implementation
|
|
328
|
-
- Session management
|
|
329
|
-
- DPoP token binding
|
|
330
|
-
- Making authenticated API requests
|
|
331
|
-
- Proper error handling
|
|
332
|
-
- Key generation and management
|
|
392
|
+
One additional complication is **DPoP** and its changing *nonces*. The server gives you a "nonce" that you need to use to generate the "proof" header, which changes after at most 5 minutes, so the requests will often fail with a header indicating a new nonce to use.
|
|
333
393
|
|
|
334
|
-
|
|
394
|
+
You handle this by passing the response to `client.process_dpop` like this to let it update the nonce. The method expects the response as a hash of `{ headers, body, status }` (since different HTTP libraries will return it in a different format):
|
|
335
395
|
|
|
336
|
-
|
|
396
|
+
```rb
|
|
397
|
+
response = { headers: res.headers, body: res.body, status: res.status }
|
|
337
398
|
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
redirect_uri: "https://app.example.com/callback"
|
|
399
|
+
client.process_dpop(response,
|
|
400
|
+
url: endpoint,
|
|
401
|
+
session_id: session_id
|
|
342
402
|
)
|
|
403
|
+
```
|
|
343
404
|
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
)
|
|
405
|
+
Then, ask the client to check if the response contains a nonce error, and if so, you'll need to retry the whole request once again (with new headers):
|
|
406
|
+
|
|
407
|
+
```rb
|
|
408
|
+
if client.has_nonce_error?(response)
|
|
409
|
+
make_request(...)
|
|
410
|
+
end
|
|
411
|
+
```
|
|
412
|
+
|
|
413
|
+
You can also use the `with_nonce_handling` helper, passing it a block which makes a request (remember to call `auth_headers` *inside* the block, since on the repeated call the headers will be different) and returns the response in the hash format:
|
|
349
414
|
|
|
350
|
-
|
|
351
|
-
|
|
415
|
+
```rb
|
|
416
|
+
endpoint = "https://#{pds_host}/xrpc/com.atproto.repo.createRecord"
|
|
417
|
+
session = client.get_session(session_id)
|
|
352
418
|
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
419
|
+
connection = Faraday.new do |f|
|
|
420
|
+
f.request :json
|
|
421
|
+
end
|
|
422
|
+
|
|
423
|
+
post_record = {
|
|
424
|
+
repo: session.did,
|
|
425
|
+
collection: "app.bsky.feed.post",
|
|
426
|
+
record: {
|
|
427
|
+
text: "Hello world!",
|
|
428
|
+
langs: ["en"],
|
|
429
|
+
createdAt: Time.now.utc.iso8601(3)
|
|
430
|
+
}
|
|
431
|
+
}
|
|
432
|
+
|
|
433
|
+
response = client.with_nonce_handling(session_id, endpoint) do
|
|
434
|
+
headers = client.auth_headers(
|
|
435
|
+
session_id: session_id,
|
|
436
|
+
method: 'POST',
|
|
437
|
+
url: endpoint
|
|
438
|
+
)
|
|
439
|
+
|
|
440
|
+
res = connection.post(endpoint) do |req|
|
|
441
|
+
req.headers.merge!(headers)
|
|
442
|
+
req.body = post_record
|
|
443
|
+
end
|
|
444
|
+
|
|
445
|
+
{ headers: res.headers, body: res.body, status: res.status }
|
|
446
|
+
end
|
|
447
|
+
```
|
|
448
|
+
|
|
449
|
+
Here's an example using `Net::HTTP`:
|
|
450
|
+
|
|
451
|
+
```rb
|
|
452
|
+
endpoint = "https://#{pds_host}/xrpc/app.bsky.feed.getTimeline"
|
|
453
|
+
|
|
454
|
+
response = client.with_nonce_handling(session_id, endpoint) do
|
|
455
|
+
headers = client.auth_headers(
|
|
456
|
+
session_id: session_id,
|
|
457
|
+
method: 'GET',
|
|
458
|
+
url: endpoint
|
|
459
|
+
)
|
|
460
|
+
|
|
461
|
+
res = Net::HTTP.get_response(URI(endpoint), headers)
|
|
462
|
+
|
|
463
|
+
{ headers: res.to_hash, body: res.body, status: res.code }
|
|
464
|
+
end
|
|
465
|
+
```
|
|
466
|
+
|
|
467
|
+
And you can also use the `#http` method to access the global AuthProto HTTP client you've configured earlier:
|
|
468
|
+
|
|
469
|
+
```rb
|
|
470
|
+
endpoint = "https://#{pds_host}/xrpc/app.bsky.feed.getTimeline"
|
|
471
|
+
|
|
472
|
+
response = client.with_nonce_handling(session_id, endpoint) do
|
|
473
|
+
headers = client.auth_headers(
|
|
474
|
+
session_id: session_id,
|
|
475
|
+
method: 'GET',
|
|
476
|
+
url: endpoint
|
|
477
|
+
)
|
|
478
|
+
|
|
479
|
+
client.http.get(endpoint, headers)
|
|
480
|
+
end
|
|
481
|
+
```
|
|
482
|
+
|
|
483
|
+
For a more batteries-included client API, see [Minisky](#minisky-adapter) below.
|
|
484
|
+
|
|
485
|
+
|
|
486
|
+
### Log the user out
|
|
487
|
+
|
|
488
|
+
Finally, if you want to log the user out, call `delete_session` to clear the session from the configured storage:
|
|
489
|
+
|
|
490
|
+
```rb
|
|
491
|
+
client.delete_session(session_id)
|
|
492
|
+
```
|
|
493
|
+
|
|
494
|
+
You can also pass `revoke: true` to additionally revoke the tokens on the PDS:
|
|
495
|
+
|
|
496
|
+
```rb
|
|
497
|
+
client.delete_session(session_id, revoke: true)
|
|
498
|
+
```
|
|
499
|
+
|
|
500
|
+
|
|
501
|
+
## Minisky adapter
|
|
502
|
+
|
|
503
|
+
AuthProto also includes an adapter for the [Minisky gem](https://tangled.org/mackuba.eu/minisky) for making XRPC requests, which gives you a client with a slightly more high-level API that handles the authenticated requests for you.
|
|
504
|
+
|
|
505
|
+
The API is a bit of a mix of a standard password-auth Minisky client and the `AuthProto::Client` for the initial authentication:
|
|
506
|
+
|
|
507
|
+
```rb
|
|
508
|
+
# needs to be required separately
|
|
509
|
+
# and requires `gem 'minisky'` in the Gemfile
|
|
510
|
+
require 'authproto/minisky'
|
|
511
|
+
|
|
512
|
+
sky = Minisky::OAuth.new(
|
|
513
|
+
client_id: "https://#{server_hostname}/oauth-client-metadata.json",
|
|
514
|
+
redirect_uri: "https://#{server_hostname}/callback",
|
|
515
|
+
metadata: metadata, # or nil/skip
|
|
516
|
+
session_id: session_id, # or nil/skip
|
|
517
|
+
signing_key: signing_key # or nil/skip
|
|
359
518
|
)
|
|
360
|
-
|
|
519
|
+
|
|
520
|
+
auth = sky.authorize(handle: 'user.handle', scope: "atproto ...")
|
|
521
|
+
p auth[:url]
|
|
522
|
+
# ...
|
|
523
|
+
|
|
524
|
+
sky.handle_callback(params, expected_session_id: auth[:session_id])
|
|
525
|
+
```
|
|
526
|
+
|
|
527
|
+
and then e.g.:
|
|
528
|
+
|
|
529
|
+
```rb
|
|
530
|
+
sky.get_request('app.bsky.feed.getTimeline', { limit: 100 })
|
|
531
|
+
|
|
532
|
+
sky.post_request('com.atproto.repo.createRecord', { repo: ..., ... })
|
|
533
|
+
|
|
534
|
+
posts = sky.fetch_all('app.bsky.graph.getFollows', { actor: did }, field: 'follows')
|
|
361
535
|
```
|
|
362
536
|
|
|
363
|
-
|
|
537
|
+
It also handles automatically the nonce updates and token refresh. Unlike `AuthProto::Client`, `Minisky::OAuth` handles a single session at a time.
|
|
538
|
+
|
|
539
|
+
For localhost development, use this convenience initializer to generate a localhost client ID with the callback URL and scope encoded as query params:
|
|
364
540
|
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
541
|
+
```rb
|
|
542
|
+
sky = Minisky::OAuth.for_localhost(
|
|
543
|
+
redirect_uri: 'http://127.0.0.1:3000/callback',
|
|
544
|
+
scope: 'atproto repo:app.bsky.feed.post',
|
|
545
|
+
session_id: session_id # optional, to resume a stored session
|
|
546
|
+
)
|
|
547
|
+
```
|
|
369
548
|
|
|
370
|
-
|
|
371
|
-
`state`: that would not establish which browser started the login. A shared web
|
|
372
|
-
client's `session_id` is not a substitute for per-browser session storage. Remove
|
|
373
|
-
the pending association after successful completion. For concurrent login attempts,
|
|
374
|
-
retain each expected ID separately and verify membership in that browser's pending attempts.
|
|
549
|
+
You can also use the `with_oauth_client` helper to reuse an existing instance of `AuthProto::Client` (normally `Minisky::OAuth` creates one internally):
|
|
375
550
|
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
add this required keyword using the retained authorization result.
|
|
551
|
+
```rb
|
|
552
|
+
sky = Minisky::OAuth.with_oauth_client(client, session_id: session_id)
|
|
553
|
+
```
|
|
380
554
|
|
|
381
|
-
|
|
555
|
+
This class is a bit more experimental and likely to change in future versions (pending a redesign of the Minisky internal architecture).
|
|
382
556
|
|
|
383
|
-
### Identity Resolution
|
|
384
557
|
|
|
385
|
-
|
|
558
|
+
## Additional configuration
|
|
386
559
|
|
|
387
|
-
|
|
388
|
-
- DID document fetching and validation
|
|
389
|
-
- PDS (Personal Data Server) location verification
|
|
390
|
-
- Bidirectional handle verification
|
|
391
|
-
- Authorization server binding verification
|
|
560
|
+
Some other things you can configure through `AuthProto.configure`:
|
|
392
561
|
|
|
393
|
-
|
|
562
|
+
* `client_assertion_lifetime` – how long a client assertion is valid for a confidential client (default: 5 min)
|
|
563
|
+
* `dpop_nonce_lifetime` – how long a DPoP nonce is valid (default: 5 min)
|
|
564
|
+
* `pending_session_ttl` – how long a session that hasn't completed authentication with a callback is valid (default: 15 min)
|
|
394
565
|
|
|
395
|
-
|
|
566
|
+
You shouldn't generally need to change those defaults.
|
|
396
567
|
|
|
397
|
-
- Secure token storage with encryption
|
|
398
|
-
- Automatic token refresh
|
|
399
|
-
- DPoP proof generation and binding
|
|
400
|
-
- Session state tracking
|
|
401
|
-
- Cleanup of expired sessions
|
|
402
568
|
|
|
403
|
-
|
|
569
|
+
## Further examples
|
|
404
570
|
|
|
405
|
-
|
|
571
|
+
There are 3 example apps included in the [examples folder](https://tangled.org/mackuba.eu/authproto/tree/main/examples/) in the repo:
|
|
406
572
|
|
|
407
|
-
-
|
|
408
|
-
-
|
|
409
|
-
-
|
|
410
|
-
- Thread-safe state management
|
|
411
|
-
- Protection against SSRF attacks
|
|
412
|
-
- Secure encrypted token storage
|
|
413
|
-
- Atomic storage operations with locking
|
|
573
|
+
- [minisky_console](https://tangled.org/mackuba.eu/authproto/tree/main/examples/minisky_console/) – shows how to use AuthProto & `Minisky::OAuth` from a console script or IRB
|
|
574
|
+
- [basic_webapp](https://tangled.org/mackuba.eu/authproto/tree/main/examples/basic_webapp/) – demonstrates how to build a simple webapp where the user can log in and access some of their ATProto account data
|
|
575
|
+
- [bookmarks](https://tangled.org/mackuba.eu/authproto/tree/main/examples/bookmarks/) – another webapp, which imports and stores your Bluesky bookmarks, which demonstrates how to use AuthProto both in server endpoints and in Rake tasks to import data, how to integrate it with ActiveRecord, and how to make proxied calls to the AppView through the PDS
|
|
414
576
|
|
|
415
|
-
## Development
|
|
416
577
|
|
|
417
|
-
|
|
578
|
+
## Other resources
|
|
418
579
|
|
|
419
|
-
|
|
580
|
+
- [YARD API documentation](https://rubydoc.info/gems/authproto) at rubydoc.info
|
|
581
|
+
- [ruby.sdk.blue](https://ruby.sdk.blue)
|
|
582
|
+
- [ATProto OAuth specification](https://atproto.com/specs/oauth)
|
|
420
583
|
|
|
421
|
-
##
|
|
584
|
+
## Credits
|
|
422
585
|
|
|
423
|
-
|
|
586
|
+
Copyright © 2026 Kuba Suder ([@mackuba.eu](https://bsky.app/profile/did:plc:oio4hkxaop4ao4wz2pp3f4cr)).
|
|
424
587
|
|
|
425
|
-
|
|
588
|
+
Original AtprotoAuth copyright © 2024 Josh Huckabee.
|
|
426
589
|
|
|
427
|
-
The
|
|
590
|
+
The code is available under the terms of the [MIT license](https://tangled.org/mackuba.eu/authproto/blob/main/MIT-LICENSE.txt). Bug reports and pull requests are welcome 😎
|