oauth2-resource-server
Use when configuring Spring Boot as an OAuth2 resource server, validating JWTs from an external auth provider (Keycloak, Auth0, Okta, Cognito), extracting claims, or implementing scope-based authorization.
Install / Use
npx skills add rrezartprebreza/spring-boot-skills --skill oauth2-resource-serverInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
SecuritySupported Platforms
Our assessment of oauth2-resource-server
oauth2-resource-server scores 89/100 on our quality scale, 562nd of 1,108 Security skills we index.
Its SKILL.md is 7.4 KB long, well organised into 11 sections with 7 code examples: a thorough specification that gives an agent plenty to work with.
It has 334 GitHub stars, a meaningful sign that others use it.
Maintenance, license and trust
- The repository was last updated 18 days ago, so oauth2-resource-server is actively maintained.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-11-12. Automated pattern scan on 2026-11-12. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
oauth2-resource-server compared with similar skills
All 4 of these similar skills score higher than oauth2-resource-server; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| oauth2-resource-server (this skill)by rrezartprebreza | 89 | 334 | 18d ago | SKILL.md |
| x402by browser-use | 100 | 121.0k | 3d ago | SKILL.md |
| algorithmic-artby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
| pptxby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
| designby nextlevelbuilder | 100 | 149.0k | 6d ago | SKILL.md |
Frequently asked questions
- How do I install oauth2-resource-server?
- Run
npx skills add rrezartprebreza/spring-boot-skills --skill oauth2-resource-server. The install tabs above show the steps for each supported agent. - Which AI agents does oauth2-resource-server work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is oauth2-resource-server safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is oauth2-resource-server still maintained?
- The repository was last updated 18 days ago, so oauth2-resource-server is actively maintained.
Skill content
View source on GitHubname: oauth2-resource-server description: > Use when configuring Spring Boot as an OAuth2 resource server, validating JWTs from an external auth provider (Keycloak, Auth0, Okta, Cognito), extracting claims, or implementing scope-based authorization.
OAuth2 Resource Server
Dependency
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>
Security Configuration
@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class ResourceServerConfig {
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
return http
.csrf(AbstractHttpConfigurer::disable)
.sessionManagement(s -> s.sessionCreationPolicy(STATELESS))
.authorizeHttpRequests(auth -> auth
.requestMatchers("/actuator/health").permitAll()
.requestMatchers("/api/v1/admin/**").hasAuthority("SCOPE_admin")
.anyRequest().authenticated()
)
.oauth2ResourceServer(oauth2 -> oauth2
.jwt(jwt -> jwt.jwtAuthenticationConverter(jwtAuthConverter()))
)
.build();
}
@Bean
public JwtAuthenticationConverter jwtAuthConverter() {
// Keep the defaults: the "scope" OR "scp" claim (Okta/Entra use scp) -> SCOPE_*.
// Calling setAuthoritiesClaimName(...) replaces them — then hasAuthority("SCOPE_admin")
// can never pass. Extend the defaults with Keycloak realm roles instead.
var scopes = new JwtGrantedAuthoritiesConverter();
var converter = new JwtAuthenticationConverter();
converter.setJwtGrantedAuthoritiesConverter(jwt -> {
Collection<GrantedAuthority> authorities = new ArrayList<>(scopes.convert(jwt));
// Keycloak nests realm roles under realm_access.roles -> ROLE_* (for hasRole)
Map<String, Object> realmAccess = jwt.getClaimAsMap("realm_access");
if (realmAccess != null && realmAccess.get("roles") instanceof Collection<?> roles) {
roles.forEach(role -> authorities.add(new SimpleGrantedAuthority("ROLE_" + role)));
}
return authorities;
});
return converter;
}
}
application.yml — Common Providers
Choose the provider configuration matching your issuer; these are alternatives, not duplicate
spring: mappings to paste into one YAML document.
# Keycloak
spring:
security:
oauth2:
resourceserver:
jwt:
issuer-uri: https://keycloak.example.com/realms/my-realm
jwk-set-uri: https://keycloak.example.com/realms/my-realm/protocol/openid-connect/certs
audiences: my-api # without it, tokens minted for ANY client in the realm are accepted
# Auth0
spring:
security:
oauth2:
resourceserver:
jwt:
issuer-uri: https://your-domain.auth0.com/
audiences: https://your-api.example.com # custom claim validation
Custom Claim Extraction
@Component
public class JwtClaimExtractor {
// Provider subjects are opaque strings ("auth0|64f1c2", Okta "00u1abcd..."), not UUIDs.
public String getSubject(JwtAuthenticationToken token) {
return token.getToken().getSubject();
}
public String getEmail(JwtAuthenticationToken token) {
return token.getToken().getClaimAsString("email");
}
public List<String> getRoles(JwtAuthenticationToken token) {
// Keycloak nests roles under realm_access.roles
Map<String, Object> realmAccess = token.getToken().getClaimAsMap("realm_access");
if (realmAccess == null) return List.of();
return (List<String>) realmAccess.getOrDefault("roles", List.of());
}
}
Controller — Accessing Current User
Use the exact (iss, sub) pair as the external identity key, with a database unique
constraint on that pair. Email and username are optional, mutable profile attributes,
not account lookup or automatic account-linking keys, even when email is verified.
The ExternalIdentity template accepts an already
verified access token; signature, issuer, audience and expiry validation must happen first.
Allow only configured issuers; never discover an arbitrary issuer URL from an untrusted token.
For existing subject-only mappings, backfill the known issuer before introducing a second issuer.
Account linking requires an explicit authenticated flow proving control of both accounts.
@RestController
@RequiredArgsConstructor
public class OrderController {
@GetMapping("/api/v1/orders/my")
public ApiResponse<List<OrderResponse>> myOrders(
@AuthenticationPrincipal Jwt jwt // inject JWT directly
) {
ExternalIdentity identity = ExternalIdentity.from(jwt);
return ApiResponse.ok(orderService.findByOwner(identity.issuer(), identity.subject()));
}
// Or with JwtAuthenticationToken for full principal
@GetMapping("/api/v1/profile")
public ApiResponse<ProfileResponse> profile(JwtAuthenticationToken token) {
ExternalIdentity identity = ExternalIdentity.from(token.getToken());
return ApiResponse.ok(userService.findByExternalIdentity(identity.issuer(), identity.subject()));
}
}
Method Security with Scopes
@PreAuthorize("hasAuthority('SCOPE_orders:read')")
public List<Order> findAll() { ... }
@PreAuthorize("hasRole('ADMIN') or @orderSecurity.isOwner(#orderId, authentication)")
public Order findById(UUID orderId) { ... }
// Custom security bean
@Component("orderSecurity")
public class OrderSecurityService {
public boolean isOwner(UUID orderId, Authentication auth) {
Jwt jwt = (Jwt) auth.getPrincipal();
ExternalIdentity identity = ExternalIdentity.from(jwt);
return orderRepository.existsByIdAndOwnerIssuerAndOwnerSubject(
orderId, identity.issuer(), identity.subject());
}
}
Verification scope
The repository fixture targets Boot 3.5.16 with Java 17/21 and checks signed-token validation and issuer/subject mapping; it does not contact a production identity provider. Check the coverage matrix before treating another minor version or an illustrative snippet as verified.
Gotchas
- Agent finds or merges accounts by email - use the verified issuer/subject pair; email changes must not change ownership.
- Agent calls
setAuthoritiesClaimName(...)onJwtGrantedAuthoritiesConverter— it replaces the defaultscope/scplookup, soSCOPE_*authorities vanish (and Okta/Entrascpscopes are dropped); extend the defaults instead - Agent parses
jwt.getSubject()withUUID.fromString— Auth0 (auth0|...) and Okta (00u...) subjects aren't UUIDs; the request fails with 500 - Agent omits
audiences— the resource server then accepts any token the issuer minted for any client - Agent uses
hasRole("ADMIN")for scope check — scopes usehasAuthority("SCOPE_admin") - Agent forgets
issuer-urivalidation — always configure to prevent token forgery - Agent maps roles wrong for Keycloak — roles are nested under
realm_access.roles - Agent uses
getPrincipal()directly — cast toJwtor use@AuthenticationPrincipal Jwt - Agent adds
userDetailsServicebean — not needed for resource servers (stateless JWT)
Related Skills
x402
121.0kSet up Browser Use Cloud payments with x402 — pay per request from a crypto wallet (USDC on Base mainnet), no signup or API key.
algorithmic-art
177.9kCreating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems.
pptx
177.9kUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an em…
design
149.0kComprehensive design skill: brand identity, design tokens, UI styling, logo generation (55 styles, Gemini, Atlas Cloud, or MuAPI AI), corporate identity program (50 deliverables, CIP mockups), HTML presentations (Chart.js), banner design (22 styles, social/ads/web/print), icon design (15 styles, SVG…
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
