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, 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

# pubspec.yaml
dependencies:
  spring_boot_starter_security: ^0.9.0
  spring_boot_starter_supabase: ^0.9.0
# lib/resources/application.yml
spring:
  supabase:
    url: https://abcd.supabase.co
    anon-key: ${SUPABASE_ANON_KEY}
@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), 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

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). user_metadata is never read: a user can write it.

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:

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:

# 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=

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