
# Security on a server

A server whose users sign in with Supabase Auth receives their access token in `Authorization: Bearer`. The starter sets the properties of Spring Security's [JWT resource server](../spring-boot-starter-security/jwt.md), so `spring_boot_starter_security` accepts those tokens with nothing else to configure.

## Why

Checking a token of Supabase has traps of its own. The anon key and the service role key are signed tokens too, with the same issuer and the same keys: a server that only checks the signature would take the anon key for a user. Roles written in `user_metadata` can be changed by the user. The defaults close these: a user's token only, and roles from where a user cannot write.

There is no token check in the starter itself. The filter chain is not changed; the starter only gives the security starter's own properties their values.

## Example

```yaml
# pubspec.yaml
dependencies:
  spring_boot_starter_security: ^0.9.0
  spring_boot_starter_supabase: ^0.9.0
```

```yaml
# lib/resources/application.yml
spring:
  supabase:
    url: https://abcd.supabase.co
    anon-key: ${SUPABASE_ANON_KEY}
```

```dart
@RestController()
class PostController {
  PostController(this.posts);

  final Posts posts;

  @PreAuthorize("hasRole('editor')")
  @PostMapping('/api/posts')
  Future<Post> publish(@RequestBody() Post post) => posts.save(post);
}
```

The default chain then needs a valid bearer token on every request. On the REST API `posts.save` is made with the same token (see [Who a call is made as](credentials.md)), so the database applies the user's row-level security too.

## The defaults

They apply when `spring.supabase.url` is set and `spring.supabase.auth.enabled` is not `false`, on a server only: the module is of the `server` platform (the Dart VM or an AOT executable), so neither a browser build nor a Flutter app has it.

| `spring.security.oauth2.resourceserver.jwt.` | Value with this starter |
|---|---|
| `jwk-set-uri` | `<spring.supabase.url>/auth/v1/.well-known/jwks.json` |
| `jws-algorithms` | `ES256,RS256` |
| `issuer-uri` | `spring.supabase.auth.issuer`, else `<spring.supabase.url>/auth/v1` |
| `audiences` | `authenticated` |
| `required-claims.role` | `authenticated` |
| `require-expiry` | `true` |
| `authorities-claim-name` | `app_metadata.roles` |
| `authority-prefix` | `ROLE_` |

## What a token must carry

| Check | Refuses |
|---|---|
| Signed by a key of the project's key set, with ES256 or RS256 | a token signed by anyone else, `alg: none`, an HMAC token made from a public key |
| `iss` is exactly the project's issuer | a token of another project or provider |
| `aud` has `authenticated` | tokens for another audience |
| `role` is exactly `authenticated` | the anon key (`role: anon`) and the service role key (`role: service_role`) used as bearer tokens |
| `exp` is there | a token without an expiry (`require-expiry`) |
| `exp`, `nbf`, the type | expired tokens, and everything else the [resource server checks](../spring-boot-starter-security/jwt.md) |

A refused token is a `401` with `WWW-Authenticate: Bearer error="invalid_token"`.

## Roles

The authorities are `ROLE_<role>` for each string of `app_metadata.roles`, so a rule reads `hasRole('editor')`. `app_metadata` is written by the project only (its service role, through the [admin API](auth.md)). `user_metadata` is never read: a user can write it.

- **Anonymous sign-ins** (`is_anonymous`) are users with the role `authenticated` and no roles: they pass the token checks and get no `ROLE_…`, so a rule such as `hasRole('editor')` refuses them. A rule that must keep them out has to say so.
- **A top-level claim literally named `app_metadata.roles`** would be read before the nested `app_metadata.roles`. Only the project's own access token hook can write top-level claims; a user cannot, and `user_metadata` is never read.

```dart
await admin.updateUser(user.id, appMetadata: {'roles': ['editor']});
```

The roles of an access token change at its next refresh. A client application reads the same claim, so both sides see the same roles.

## A legacy secret

A project that still signs its tokens with HS256 has a JWT secret instead of signing keys. Set it, and the defaults change:

```yaml
spring:
  supabase:
    auth:
      jwt-secret: ${SUPABASE_JWT_SECRET}
```

| `spring.security.oauth2.resourceserver.jwt.` | Value with `jwt-secret` |
|---|---|
| `secret-key` | the secret |
| `jws-algorithms` | `HS256` |
| `jwk-set-uri` | not set |

The claim checks are the same. Whoever has the secret can sign a token for any user: it belongs on a server only, taken from the environment. In a Flutter app it is warned about at startup.

## Overriding

The defaults are a property source of the lowest precedence: below the application's files, above its `defaultProperties`. Whatever the application sets itself under `spring.security.oauth2.resourceserver.jwt.*` wins, key by key:

```properties
# Roles from another claim of the project's tokens.
spring.security.oauth2.resourceserver.jwt.authorities-claim-name=app_metadata.permissions
spring.security.oauth2.resourceserver.jwt.authority-prefix=
```

- `spring.supabase.auth.enabled=false` sets none of them.
- A `SecurityFilterChain` or a `JwtDecoder` bean of your own works as with any resource server.
- A token accepted through settings of your own is passed on to Supabase only when it is a user's token of this project.

## The database protects the data

A server's rules (`@PreAuthorize`, request rules) decide who may call an endpoint. What a user may read and write is decided by the database: row-level security, column privileges, constraints. The starter makes sure the database knows who calls; write the policies there.

## In Spring (Java)

The properties are Spring Boot's (`spring.security.oauth2.resourceserver.jwt.*`), with four of this project's own that the starter uses: `required-claims`, `require-expiry`, `secret-key`, and a path in `authorities-claim-name`. In Spring a starter would declare a `JwtDecoder` bean; here it sets properties, so the application overrides them one by one.

## See also

- [JWT resource servers](../spring-boot-starter-security/jwt.md)
- [Method security](../spring-security-core/method-security.md)
- [Who a call is made as](credentials.md)
- [Sign-in in a client application](auth.md)
