<!-- Source: https://docs.squirro.com/en/latest/technical/admin/configuration/config-files/user-ini.html -->
# user.ini

The `user.ini` file configures the Squirro user authentication service, which handles authentication, user management, and OAuth2 client credentials.

The file is located at `/etc/squirro/user.ini` and contains only the settings you want to override for your deployment. Any key you omit falls back to its built-in default, so a typical file is short.

Squirro ships a packaged `user.ini` file that lists all supported options, but it is overwritten on every upgrade. Make your changes in `/etc/squirro/user.ini` instead, where they persist across upgrades.

## Example Configuration

The following example shows the settings that most deployments customize:

```ini
[user]
db = mysql+mariadbconnector://user:password@localhost/user?charset=utf8
connection_recycle_interval = 3600
pool_class = queue
pool_size = 10
max_overflow = 3
```

The reference below documents every key that each section supports, along with its default value. Add only the keys you need to change.

## Configuration Reference

### [user]

Controls the database connection, token lifetimes, and notification settings for the user service.

| Key | Description | Default |
| --- | --- | --- |
| `db` | SQLAlchemy connection string for the user database. | `sqlite:///user.db` |
| `connection_recycle_interval` | How often SQLAlchemy recycles database connections, in seconds. | `3600` |
| `db_endpoint_discovery` | When set to `true`, the service discovers the database endpoint through the cluster service instead of using the `db` key directly. | `false` |
| `pool_class` | SQLAlchemy connection pool class. Use `queue` for production deployments. | `queue` |
| `pool_size` | Number of connections to maintain in the pool. | `5` |
| `max_overflow` | Number of connections that can be created beyond `pool_size` when the pool is exhausted. | `5` |
| `pw_salt` | Salt used for password hashing. Set to a unique, randomly generated value in every production deployment. |  |
| `access_token_validity` | How long access tokens remain valid, in minutes. | `10` |
| `refresh_token_validity` | How long refresh tokens remain valid, in minutes. The default is approximately one year. | `525600` |
| `grant_refresh_token_validity_days` | How long grant refresh tokens remain valid, in days. The default is approximately ten years. | `3560` |
| `restrict_token_scope` | When set to `true`, restricts the scope of read-only tokens that would otherwise have too broad access. | `false` |
| `expiring_warn_time_days` | Number of days before a token expires at which to send a warning to the user. | `5` |

### [clients]

Registers the OAuth2 application credentials that services and applications use to authenticate with Squirro. Each client entry has a unique `client_id` and `client_secret`.

A standard Squirro installation includes the following built-in clients:

| Client name | Purpose | Trusted |
| --- | --- | --- |
| `frontend` | Squirro web frontend. | Yes |
| `genai` | GenAI service. | Yes |
| `machinelearning` | Machine learning service. | Yes |
| `plumber` | Plumber service. | Yes |
| `topicproxy` | Topic proxy service. | Yes |
| `dataloader_provider` | Dataloader provider. | Yes |
| `import_export` | Project import and export functionality. | Yes |
| `digestmailer` | Digest mailer service. | No |

> **Notes for administrators**
>
> - All clients that call the grants endpoint must have `trusted = true`. Without it, the server rejects the request with a 403 error.
> - Store `/etc/squirro/user.ini` securely. It contains credentials for all registered OAuth2 clients.

### [server]

Controls the network settings for the user service.

| Key | Description | Default |
| --- | --- | --- |
| `port` | Port the user service listens on. | `20009` |

### [password_policy]

Controls password requirements enforced when users set or change their password.

| Key | Description | Default |
| --- | --- | --- |
| `minimum_password_length` | Minimum number of characters required in a password. Set to `0` to impose no minimum. | `12` |
| `allow_personal_info_in_password` | Whether to allow user personal information (such as name or email address) in passwords. | `false` |
| `personal_info_in_password_threshold` | The fraction of a password that may consist of user personal information before the password is rejected. A value of `0` allows no personal information. A value of `1` imposes no restriction. | `0.20` |

### [jwt]

Controls JWT token support for integrating with external identity providers.

| Key | Description | Default |
| --- | --- | --- |
| `enabled` | When set to `true`, turns on JWT token support. | `false` |
| `token_role` | Which OAuth2 parameter carries the JWT. Set to `access` to use the `access_token` parameter (stateless mode), `refresh` to use the `refresh_token` parameter (stateful mode), or `*` to accept both. | `*` |
| `validate_endpoint` | URL of the JWT validator plugin endpoint. | `http://localhost:81/studio/jwt_validator/validate` |
| `config_endpoint` | URL of the JWT validator configuration endpoint. Optional. | `http://localhost:81/studio/jwt_validator/configs` |
| `cache_enabled` | When set to `true`, caches validation results and plugin configuration. | `true` |
| `config_cache_ttl` | How long to cache plugin configuration, in seconds. | `3600` |
| `access_token_cache_ttl` | How long to cache JWT validation results in access token mode, in seconds. | `3600` |
| `refresh_token_cache_ttl` | How long to cache JWT validation results in refresh token mode, in seconds. | `86400` |
| `jwks_cache_ttl` | How long to cache the JWKS from the identity provider, in seconds. | `3600` |

## Register a New OAuth2 Client

1. Generate a `client_id`.

   ```bash
   python3 -c "import secrets; print(secrets.token_urlsafe(16))"
   ```
2. Generate a `client_secret`.

   ```bash
   python3 -c "import secrets; print(secrets.token_hex(32))"
   ```
3. Add the client to the `[clients]` section of `/etc/squirro/user.ini`. Replace `myapp` with a descriptive name for your application.

   ```ini
   [clients]
   myapp.client_id = <generated_client_id>
   myapp.client_secret = <generated_client_secret>
   myapp.trusted = true
   ```
4. Restart the user service.

   ```bash
   sudo systemctl restart squserd
   ```

Pass the `client_id` and `client_secret` values to the `SquirroClient` constructor. For usage examples, see the [Create a Service Account](../../../api/squirro_client/service-account.md#service-account) page.

## Apply Changes

For changes in `/etc/squirro/user.ini` to take effect, restart the `squserd` service:

```bash
sudo systemctl restart squserd
```