106 lines
4.2 KiB
Markdown
106 lines
4.2 KiB
Markdown
# Authentication
|
|
|
|
> Source: `src/content/docs/actors/authentication.mdx`
|
|
> Canonical URL: https://rivet.dev/docs/actors/authentication
|
|
> Description: Secure your actors with authentication and authorization.
|
|
|
|
---
|
|
## Do You Need Authentication?
|
|
|
|
### Rivet Cloud
|
|
|
|
Actors are private by default on Rivet Cloud. Only requests with the publishable token can interact with actors.
|
|
|
|
- **Backend-only actors**: If your publishable token is only included in your backend, then authentication is not necessary.
|
|
- **Frontend-accessible actors**: If your publishable token is included in your frontend, then implementing authentication is recommended.
|
|
|
|
### Self-Hosted
|
|
|
|
Actors are public by default on self-hosted Rivet. Anyone can access them without a token.
|
|
|
|
- **Only accessible within private network**: If Rivet is only accessible within your private network, then authentication is not necessary.
|
|
- **Rivet exposed to the public internet**: If Rivet is configured to accept traffic from the public internet, then implementing authentication is recommended.
|
|
|
|
## Authentication Connections
|
|
|
|
Authentication is configured through either:
|
|
|
|
- `onBeforeConnect` for simple pass/fail validation
|
|
- `createConnState` when you need to access user data in your actions via `c.conn.state`
|
|
|
|
## Access Control
|
|
|
|
After a connection is authenticated, use [Access Control](/docs/actors/access-control) to enforce authorization:
|
|
|
|
- Check permissions in action handlers.
|
|
- Use `queues.<name>.canPublish` to gate inbound queue publishes.
|
|
- Use `events.<name>.canSubscribe` to gate event subscriptions.
|
|
|
|
### `onBeforeConnect`
|
|
|
|
The `onBeforeConnect` hook validates credentials before allowing a connection. Throw an error to reject the connection.
|
|
|
|
### `createConnState`
|
|
|
|
Use `createConnState` to extract user data from credentials and store it in connection state. This data is accessible in actions via `c.conn.state`. Like `onBeforeConnect`, throwing an error will reject the connection. See [connections](/docs/actors/connections) for more details.
|
|
|
|
## Available Auth Data
|
|
|
|
Authentication hooks have access to several properties:
|
|
|
|
| Property | Description |
|
|
|----------|-------------|
|
|
| `params` | Custom data passed by the client when connecting (see [connection params](/docs/actors/connections#extracting-data-from-connection-params)) |
|
|
| `c.request` | The underlying HTTP request object |
|
|
| `c.request.headers` | Request headers for tokens, API keys (does not work for `.connect()`) |
|
|
| `c.state` | Actor state for authorization decisions (see [state](/docs/actors/state)) |
|
|
| `c.key` | The actor's key (see [keys](/docs/actors/keys)) |
|
|
|
|
It's recommended to use `params` instead of `c.request.headers` whenever possible since it works for both HTTP & WebSocket connections.
|
|
|
|
## Client Usage
|
|
|
|
### Passing Credentials
|
|
|
|
Pass authentication data when connecting. Use `getParams` when you need a fresh JWT for every connection or reconnect:
|
|
|
|
### Handling Errors
|
|
|
|
Authentication errors use the same system as regular errors. See [errors](/docs/actors/errors) for more details.
|
|
|
|
## Examples
|
|
|
|
### JWT
|
|
|
|
Validate JSON Web Tokens and extract user claims:
|
|
|
|
### External Auth Provider
|
|
|
|
Validate credentials against an external authentication service:
|
|
|
|
### Using `c.state` In Authorization
|
|
|
|
Access actor state via `c.state` and the actor's key via `c.key` to make authorization decisions:
|
|
|
|
### Role-Based Access Control
|
|
|
|
Create helper functions for common authorization patterns:
|
|
|
|
### Rate Limiting
|
|
|
|
Use `c.vars` to track connection attempts and rate limit by user:
|
|
|
|
The limits in this example are [ephemeral](/docs/actors/state#ephemeral-variables). If you wish to persist rate limits, you can optionally replace `vars` with `state`.
|
|
|
|
### Caching Tokens
|
|
|
|
Cache validated tokens in `c.vars` to avoid redundant validation on repeated connections. See [ephemeral variables](/docs/actors/state#ephemeral-variables) for more details.
|
|
|
|
## API Reference
|
|
|
|
- [`AuthIntent`](/typedoc/types/rivetkit.mod.AuthIntent.html) - Authentication intent type
|
|
- [`OnBeforeConnectContext`](/typedoc/interfaces/rivetkit.mod.OnBeforeConnectContext.html) - Context for auth checks
|
|
- [`OnConnectContext`](/typedoc/interfaces/rivetkit.mod.OnConnectContext.html) - Context after connection
|
|
|
|
_Source doc path: /docs/actors/authentication_
|