mirrors/syncstorage-rs
1
0
Fork 0
mirror of https://github.com/mozilla-services/syncstorage-rs.git synced 2026-05-05 04:06:16 +02:00
Code Issues Actions 4 Packages Projects Releases Wiki Activity

docs: add Tokenserver README (#1162)

Browse Source 
Closes #1082
This commit is contained in:
Ethan Donowitz 2021-11-23 09:08:45 -05:00 committed by GitHub
parent 0c05e999d1
commit b5fa8c8a89
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 85 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
config/local.example.toml
View File

@ -13,4 +13,13 @@ human_logs = 1
# enable quota limits
enable_quota = 0
# set the quota limit to 2GB.
# max_quota_limit = 200000000
# max_quota_limit = 200000000
# Example Tokenserver settings:
disable_syncstorage = false
tokenserver.database_url = "mysql://sample_user:sample_password@localhost/tokenserver_rs"
tokenserver.enabled = true
tokenserver.fxa_email_domain = "api-accounts.stage.mozaws.net"
tokenserver.fxa_metrics_hash_secret = "INSERT_SECRET_KEY_HERE"
tokenserver.fxa_oauth_server_url = "https://oauth.stage.mozaws.net"
tokenserver.test_mode_enabled = false

75
src/tokenserver/README.md Normal file
View File

@ -0,0 +1,75 @@
# Tokenserver
Tokenserver is used to:
1. Authenticate Sync clients via an OAuth token that clients receive from FxA
1. Direct Sync clients to the appropriate Sync Storage node
1. Present Sync clients with the encryption key necessary to access their Sync Storage nodes
This functionality was previously provided by a [Python service](https://github.com/mozilla-services/tokenserver/). Originally, the intent was to use Tokenserver as a standalone authentication service for use with various, independent microservices. In practice, it is only used for Firefox Sync, so it was rewritten in Rust to be part of the same code repository as the Sync Storage node.
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
- [Configuration](#configuration)
- [Disabling Syncstorage](#disabling-syncstorage)
- [Test Mode](#test-mode)
- [Connecting to Firefox](#connecting-to-firefox)
- [Database](#database)
- [Running](#running)
- [Testing](#testing)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## Configuration
You can find example settings for Tokenserver in [config/local.example.toml](../../config/local.example.toml). The available settings are:
| Option | Default value | Description |
| --- | --- | --- |
| `disable_syncstorage` | `false` | whether to disable the Sync Storage endpoints (see [Disabling Syncstorage](#disabling-syncstorage) for more information) |
| `tokenserver.database_url` | `"mysql://root@127.0.0.1/tokenserver_rs"` | database DSN |
| `tokenserver.database_pool_max_size` | `None` | the maximum number of connections in the database pool |
| `tokenserver.database_pool_min_idle` | `None` | the minimum number of idle database connections to maintain at all times |
| `tokenserver.database_pool_connection_timeout` | `Some(30)` | the timeout (in seconds) when waiting for an available connection |
| `tokenserver.fxa_metrics_hash_secret` | `"secret"` | the secret used to hash users' FxA UIDs |
| `tokenserver.fxa_email_domain` | `"api.accounts.firefox.com"` | the email domain used to contruct the FxA email address from the user's FxA UID |
| `tokenserver.fxa_oauth_server_url` | `None` | the URL of the FxA OAuth server to be used to verify user's OAuth tokens |
| `tokenserver.test_mode_enabled` | `false` | whether to enable Tokenserver's [test mode](#test-mode) |
### Disabling Syncstorage
Tokenserver can be run as a standalone service by disabling the Sync Storage endpoints. This can be done simply by setting the `disable_syncstorage` setting to `true`. **Note that the Sync Storage settings must still be set even when those endpoints are disabled.**
### Test Mode
When Tokenserver's "test mode" is enabled, OAuth tokens are unpacked without being verified by FxA. Essentially, this allows one to "forge" an OAuth token as though it were created by FxA. This can be useful to test new functionality during development or to run integration tests.
**NOTE:** This should **never** be run in production.
### Connecting to Firefox
1. Visit `about:config` in Firefox
1. Set `identity.sync.tokenserver.uri` to `http://localhost:8000/1.0/sync/1.5`
This will point Firefox to the Tokenserver running alongside your local instance of Sync Storage.
## Database
Prior to using Tokenserver, the migrations must be run. First, install the [diesel](https://diesel.rs/guides/getting-started) CLI tool:
```
cargo install diesel_cli
```
Then, run the migrations:
```
diesel --database-url mysql://sample_user:sample_password@localhost/tokenserver_rs migration --migration-dir src/tokenserver/migrations run
```
You should replace the above database Data Source Name (DSN) with the DSN of the database you are using.
## Running
Tokenserver is run alongside Sync Storage using `make run`.
## Testing
Tokenserver includes unit tests and a comprehensive suite of integration tests. These tests are run alongside the Sync Storage tests and can be run by following the instructions [here](../../README.md#unit-tests) and [here](../../README.md#end-to-end-tests).