View source for Spring REST API Quick Start

=Introduction=
This is meant to just be a quickstart for me. I use many technologies so this reminds me how to get going.
=Setup Spring=
Go to start.spring.io and select JPA, Rest Repositories and H2 Database.<br>
[[File:Spring RESTAPI.png]]
<br>
<br>
Import the resulting project as a maven project
=Create Classes=
==Beer Class (Entity)==
<syntaxhighlight lang="java"> 
@Entity
public class Beer {

	@Id
	@GeneratedValue(strategy = GenerationType.IDENTITY)
	private Long id;
	public Long getId() {
		return id;
	}
	public void setId(Long id) {
		this.id = id;
	}
	public String getName() {
		return name;
	}
	public void setName(String name) {
		this.name = name;
	}
	public Double getApv() {
		return apv;
	}
	public void setApv(Double apv) {
		this.apv = apv;
	}
	private String name;
	private Double apv;
}
</syntaxhighlight> 
==Beer Repository==
<syntaxhighlight lang="java"> 
package nz.co.bibble.restapi11;

import org.springframework.data.repository.CrudRepository;
import org.springframework.data.rest.core.annotation.RepositoryRestResource;

@RepositoryRestResource
public interface RestRepository extends CrudRepository<Beer,Long> {

}
</syntaxhighlight> 
==Resources==
Set the application properties for H2
<syntaxhighlight lang="java"> 
spring.datasource.url=jdbc:h2:mem:beers
</syntaxhighlight> 
Create the Data.sql in the resources directory
<syntaxhighlight lang="sql"> 
INSERT INTO beer(name, apv) VALUES('Jai Alai', 7.5);
INSERT INTO beer(name, apv) VALUES('Stella Artois', 5.0);
INSERT INTO beer(name, apv) VALUES('Lagunitas', 6.2);
COMMIT;
</syntaxhighlight> 
==Run==
Goto http://localhost:8080/beers
=Add Spring Security=
==Add Dependencies==
We can add security to a new project with 
<syntaxhighlight lang="xml">

        <dependencies>
...
                <dependency>
                        <groupId>org.springframework.boot</groupId>
                        <artifactId>spring-boot-starter-security</artifactId>
                </dependency>

                <dependency>
                        <groupId>org.springframework.security</groupId>
                        <artifactId>spring-security-test</artifactId>
                        <scope>test</scope>
                </dependency>

        </dependencies>
</syntaxhighlight>
==Add Web Security to App==
<syntaxhighlight lang="java">
@SpringBootApplication
public class Restapi11Application extends SpringBootServletInitializer {
    
	public static void main(String[] args) {
		SpringApplication.run(Restapi11Application.class, args);
	}
}
</syntaxhighlight>
===Amend WebSecurityConfigurerAdapter===
<syntaxhighlight lang="java">
@Configuration
@EnableWebSecurity
@EnableGlobalMethodSecurity (
   prePostEnabled = true,
   securedEnabled = true,
   jsr250Enabled = true
)
public class Restapi11SecurityConfigurerAdapter extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(final AuthenticationManagerBuilder auth) throws Exception {
        auth.inMemoryAuthentication()
                .withUser("iwiseman").password(passwordEncoder().encode("pass")).roles("USER");
    }
    
    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }
}
</syntaxhighlight>
=Add Oauth2 Security Jwt=
==Setup Application==
I set up a Keycloak Server to do this. Assuming this all works these are the changes to make my /beer work
===Application Properties===
Starting to see why yaml is nice given the alternative.
<syntaxhighlight lang="bash">
# H2 definition
spring.datasource.url=jdbc:h2:mem:beers

# Server Port
server.port=8081

# Path
server.servlet.context-path=/resource-server-jwt

# Keycloak Server with Realm
spring.security.oauth2.resourceserver.jwt.issuer-uri=http://192.168.1.70:9999/auth/realms/bibble

# Debug
logging.level.root=debug
logging.level.org.springframework.security=DEBUG
</syntaxhighlight>

===Add Dependencies===
<syntaxhighlight lang="xml">
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>
<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
</dependency>
</syntaxhighlight>
===Define location of Keycloak Server===
Add some debug for good measure
<syntaxhighlight>
# Keycloak Server with Realm
spring.security.oauth2.resourceserver.jwt.issuer-uri=http://192.168.1.70:9999/auth/realms/bibble

# Debug
logging.level.root=debug
logging.level.org.springframework.security=DEBUG
</syntaxhighlight>

==Setup MVC==
This section sets up the data to be used with the keycloak server. The important part is the owner. We read the user_id from the Jwt to provide filtering on owner
===Create Entity===
<syntaxhighlight lang="java">
@Entity
public class TestItem {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    public Long getId() {
        return id;
    }
	
    public void setId(Long id) {
 	this.id = id;
    }

    @Column
    private String description;

    public String getDescription() {
        return description;
    }

    public void setDescription(String description) {
        this.description = description;
    }
	
    @Column
    private UUID owner;

    public UUID getOwner() {
        return owner;
    }

    public void setOwner(UUID owner) {
        this.owner = owner;
    }
}
</syntaxhighlight>
===Create Repository===
<syntaxhighlight lang="java">
@RepositoryRestResource
public interface TestItemsRepository extends CrudRepository<TestItem,Long> {

    List<TestItem> findByOwner(UUID owner);
}
</syntaxhighlight>
===Create Initializer===
<syntaxhighlight lang="java">
@Component
public class TestItemsInitializer implements SmartInitializingSingleton {

	private final TestItemsRepository testItems;

	public TestItemsInitializer(TestItemsRepository testItems) {
		this.testItems = testItems;
	}

	@Override
	public void afterSingletonsInstantiated() {

		UUID iwiseman = UUID.fromString("cae12e7d-9c1c-4c26-a146-15b9f97f2cca");
		UUID bwiseman = UUID.fromString("e5991839-9e2f-41c9-b188-02cc112eedf3");

		this.testItems.save(create("Iain Read War and Peace", iwiseman));
		this.testItems.save(create("Iain Free Solo the Eiffel Tower", iwiseman));
		this.testItems.save(create("Iain Hang Christmas Lights", iwiseman));

		this.testItems.save(create("Run for President", bwiseman));
		this.testItems.save(create("Run a Marathon", bwiseman));
		this.testItems.save(create("Run an Errand", bwiseman));
	}

	public TestItem create(String description, UUID owner) {
		TestItem testItem = new TestItem();
		testItem.setDescription(description);
		testItem.setOwner(owner);
		return testItem;
	}

}
</syntaxhighlight>
===Create Controller===
<syntaxhighlight lang="java">
@RestController
public class TestItemController {

	private final TestItemsRepository testItems;

	public TestItemController(TestItemsRepository testItems) {
		this.testItems = testItems;
	}

	@GetMapping("/testItems")
	public List<TestItem> read(@AuthenticationPrincipal Jwt jwt) {
		UUID owner = jwt.getClaim("user_id");
		return this.testItems.findByOwner(owner);
	}

}
</syntaxhighlight>

==Configure Spring Security WebSecurityConfigurerAdapter==
===http configure===
Restrict the requests to be authenticated and add the oauth2ResourceServer where we define the jwtAuthenticationConverter
<syntaxhighlight lang="java">
@Configuration
@EnableWebSecurity(debug = true)
public class Restapi11SecurityConfigurerAdapter extends WebSecurityConfigurerAdapter {

    private static final Logger logger = LoggerFactory.getLogger(FooController.class);

	@Override
	protected void configure(HttpSecurity http) throws Exception {
        http
        .authorizeRequests(a -> a
                .anyRequest().authenticated())
        .oauth2ResourceServer(o -> o
                .jwt(j -> j.jwtAuthenticationConverter(jwtAuthenticationConverter()))
        );
	}
...
</syntaxhighlight>
===Auto Wire the JwtDecoder===
Define the custom ClaimSetConverter and JwtValidator to use
<syntaxhighlight lang="java">
    @Autowired
    void jwtDecoder(JwtDecoder jwtDecoder) {
            ((NimbusJwtDecoder) jwtDecoder).setClaimSetConverter(claimSetConverter());
            ((NimbusJwtDecoder) jwtDecoder).setJwtValidator(jwtValidator());
    }
</syntaxhighlight>

===Jwt Validator===
For this example we are just looking at the Audience
<syntaxhighlight lang="java">
    private OAuth2TokenValidator<Jwt> jwtValidator() {
        OAuth2TokenValidator<Jwt> audience = jwt ->
                        Optional.ofNullable(jwt.getAudience())
                                .filter(aud -> aud.contains("account"))
                                .map(aud -> success())
                                .orElse(failure(new OAuth2Error(INVALID_TOKEN, "Bad audience", "url")));
        OAuth2TokenValidator<Jwt> defaults = JwtValidators.createDefault();
        return new DelegatingOAuth2TokenValidator<>(defaults, audience);
}
</syntaxhighlight>
===Claim Set Converter===
For this in the Keycloak server I modified the client and the user. For Client I added an attribute.
<syntaxhighlight lang="json">
      "id": "cf2a3f05-d29c-44bb-b08d-96a1b1c7b178",
      "name": "user_id",
      "protocol": "openid-connect",
      "attributes": {
        "include.in.token.scope": "true",
        "display.on.consent.screen": "true"
      },
      "protocolMappers": [
        {
          "id": "88e630bf-10e6-470e-9592-981392a906ab",
          "name": "user_id",
          "protocol": "openid-connect",
          "protocolMapper": "oidc-usermodel-attribute-mapper",
          "consentRequired": false,
          "config": {
            "userinfo.token.claim": "true",
            "user.attribute": "user_id",
            "id.token.claim": "true",
            "access.token.claim": "true",
            "claim.name": "user_id",
            "jsonType.label": "String"
          }
        }
      ]
</syntaxhighlight>
This is then mapped to the user as an attribute.<br>
<br>
From there we simply extract it from the Jwt.
<syntaxhighlight lang="java">
    private MappedJwtClaimSetConverter claimSetConverter() {
        
    	Converter<Object, UUID> converter = value -> {
            if(value == null) {
            	return UUID.fromString("");
            }
    		return UUID.fromString(value.toString());
    	};
                        
        return MappedJwtClaimSetConverter.withDefaults
                        (Collections.singletonMap("user_id", converter));
    }
</syntaxhighlight>

===PreAuthorize===
We can use this annotation in combination with Scope when we get a token
*The Optional scope must exist in the keycloak server 
*The Scope must be passed when generation the token.
*Must specify the @EnableGlobalMethodSecurity(prePostEnabled = true) on the application
*Controller uses the @PreAuthorize
Generating the token we
<syntaxhighlight lang="bash" highlight="8">
   export TOKEN=`curl -X POST 'http://192.168.1.70:8086/auth/realms/one/protocol/openid-connect/token' \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data-urlencode 'grant_type=password' \
 --data-urlencode 'client_id=app' \
 --data-urlencode 'client_secret=bfbd9f62-02ce-4638-a370-80d45514bd0a' \
 --data-urlencode 'username=carol' \
 --data-urlencode 'password=carol' \
 --data-urlencode scope="resolution:read" | jq -r .access_token`
</syntaxhighlight>
In the controller 
<syntaxhighlight lang="java">
	@GetMapping("/resolutions")
	@PreAuthorize("hasAuthority('SCOPE_resolution:read')")
	public List<Resolution> read(@AuthenticationPrincipal Jwt jwt) {
		UUID owner = jwt.getClaim("user_id");
		return this.resolutions.findByOwner(owner);
	}

</syntaxhighlight>
===Testing===
I really liked how easy it was to write the unit tests. Wouldn't normally put the whole thing up.
<syntaxhighlight lang="bash">
@WebMvcTest(controllers = ResolutionController.class)
@Import({ ResolutionsApplication.class, ResolutionsApplicationTests.JwtDecoderConfig.class })
@AutoConfigureMockMvc
class ResolutionsApplicationTests {
	UUID joshId = UUID.fromString("219168d2-1da4-4f8a-85d8-95b4377af3c1");
	UUID carolId = UUID.fromString("328167d1-2da3-5f7a-86d7-96b4376af2c0");

	@Autowired
	MockMvc mvc;

	@MockBean
	ResolutionRepository resolutions;

	@Test
	public void resolutionsWhenNoTokenThenUnauthorized() throws Exception {
		this.mvc.perform(get("/resolutions"))
				.andExpect(status().isUnauthorized());
	}

	@Test
	public void resolutionsWhenNoScopesThenForbidden() throws Exception {
		this.mvc.perform(get("/resolutions")
				.with(jwt()))
				.andExpect(status().isForbidden());
	}

	@Test
	public void resolutionsWhenWrongScopeThenForbidden() throws Exception {
		this.mvc.perform(get("/resolutions")
				.with(jwt().authorities(new SimpleGrantedAuthority("SCOPE_resolution:write"))))
				.andExpect(status().isForbidden());
	}

	@Test
	public void resolutionsWhenReadScopeThenAuthorized() throws Exception {
		this.mvc.perform(get("/resolutions")
				.with(jwt().jwt(j -> j
						.claim("user_id", this.carolId)
						.claim("scope", "resolution:read")
				)))
				.andExpect(status().isOk());
	}

	@Test
	public void resolutionByIdWhenAdminThenAuthorized() throws Exception {
		Resolution josh = new Resolution("Mow the lawn", this.joshId);
		Resolution carol = new Resolution("Sing Christmas Carols", this.carolId);
		when(this.resolutions.findById(josh.getId())).thenReturn(Optional.of(josh));
		when(this.resolutions.findById(carol.getId())).thenReturn(Optional.of(carol));

		String joshToken = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiMjE5MTY4ZDItMWRhNC00ZjhhLTg1ZDgtOTViNDM3N2FmM2MxIiwic2NvcGUiOiJyZXNvbHV0aW9uOnJlYWQiLCJhdWQiOiJyZXNvbHV0aW9uIn0.";
		String carolToken = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiMzI4MTY3ZDEtMmRhMy01ZjdhLTg2ZDctOTZiNDM3NmFmMmMwIiwic2NvcGUiOiJyZXNvbHV0aW9uOnJlYWQiLCJhdWQiOiJyZXNvbHV0aW9uIn0.";

		this.mvc.perform(get("/resolution/" + josh.getId())
				.header("Authorization", "Bearer " + carolToken))
				.andExpect(status().isOk());
		this.mvc.perform(get("/resolution/" + carol.getId())
				.header("Authorization", "Bearer " + joshToken))
				.andExpect(status().isForbidden());
	}

	@Test
	public void resolutionsWhenNoAudienceThenUnauthorized() throws Exception {
		String audience = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiMjE5MTY4ZDItMWRhNC00ZjhhLTg1ZDgtOTViNDM3N2FmM2MxIiwic2NvcGUiOiJyZXNvbHV0aW9uOnJlYWQiLCJhdWQiOiJyZXNvbHV0aW9uIn0.";
		String noAudience = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiMjE5MTY4ZDItMWRhNC00ZjhhLTg1ZDgtOTViNDM3N2FmM2MxIiwic2NvcGUiOiJyZXNvbHV0aW9uOnJlYWQifQ.";

		this.mvc.perform(get("/resolutions")
				.header("Authorization", "Bearer " + audience))
				.andExpect(status().isOk());
		this.mvc.perform(get("/resolutions")
				.header("Authorization", "Bearer " + noAudience))
				.andExpect(status().isUnauthorized());
	}

	@Configuration
	static class JwtDecoderConfig {
		@Bean
		JwtDecoder jwtDecoder() {
			return new NimbusJwtDecoder(new MockJWTProcessor());
		}

		private static class MockJWTProcessor extends DefaultJWTProcessor<SecurityContext> {
			@Override
			public JWTClaimsSet process(SignedJWT signedJwt, SecurityContext context) {
				try {
					return signedJwt.getJWTClaimsSet();
				} catch (ParseException e) {
					throw new IllegalArgumentException(e);
				}
			}
		}
	}
}
</syntaxhighlight>

==Issues==
*The iss claim is not valid
This is caused by the wrong address in the issuer-uri where I put localhost and it wanted 192.168.x.x. You see iss in the Jwt Debugger which is what let me to fix this.
=Add Oauth2 Security Opaque Tokens=
===Application Properties===
For the Opaque tokens we do not have a user in them so we need to provide enough information to validate in the application properties. We also need to provide the end point to hit
<syntaxhighlight lang="yaml">
spring:
  security:
    oauth2:
      resourceserver:
        opaque-token:
          introspection-uri: http://localhost:9999/auth/realms/one/protocol/openid-connect/token/introspect
          client-id: app
          client-secret: bfbd9f62-02ce-4638-a370-80d45514bd0a
logging:
  level:
    root: debug  
</syntaxhighlight>
===Add Dependencies===
<syntaxhighlight lang="xml">

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
		</dependency>

		<dependency>
			<groupId>com.nimbusds</groupId>
			<artifactId>oauth2-oidc-sdk</artifactId>
			<version>6.0</version>
		</dependency>

</syntaxhighlight>
==Configure Spring Security WebSecurityConfigurerAdapter==
===http configure===
We need to set the scope and to tell the resource server to authenticate. Restrict the requests to be authenticated and add the opaque oauth2ResourceServer customizer. The 
<br>
OpaqueTokenIntrospector is a Bean that which decodes String tokens into validated instances of OAuth2AuthenticatedPrincipal. For me this approach to framework is quite poor if you are looking at it for the first time.
<syntaxhighlight lang="java">
@Configuration
@EnableWebSecurity(debug = true)
@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {

@Override
protected void configure(HttpSecurity http) throws Exception {
		http
		.authorizeRequests(a -> a
		.mvcMatchers("/resolutions").hasAuthority("SCOPE_resolution:read")
		.mvcMatchers("/resolution/{id}/share").hasAuthority("resolution:share")
		.anyRequest().authenticated())
		.oauth2ResourceServer(o -> o.opaqueToken());
	}

@Bean
public OpaqueTokenIntrospector tokenIntrospector(
	OAuth2ResourceServerProperties properties, UserRepository users) {

                // Get Properties
		String url = properties.getOpaquetoken().getIntrospectionUri();
		String clientId = properties.getOpaquetoken().getClientId();
		String clientSecret = properties.getOpaquetoken().getClientSecret();

		OpaqueTokenIntrospector delegate = 
                       new NimbusOpaqueTokenIntrospector
                         (url, 
                          clientId,
                          clientSecret);

			return new ResolutionOpaqueTokenIntrospector(delegate, users);
       }
}
</syntaxhighlight>
===Translating the OAuth2AuthenticatedPrincipal===
====Bridge User====
This basically translates the properties from the OAuth2AuthenticatedPrincipal
</syntaxhighlight>
	private static class BridgeUser extends User implements OAuth2AuthenticatedPrincipal {
		private final OAuth2AuthenticatedPrincipal delegate;

		public BridgeUser(User user, OAuth2AuthenticatedPrincipal delegate) {
			super(user);
			this.delegate = delegate;
		}

		@Override
		@Nullable
		public <A> A getAttribute(String name) {
			return delegate.getAttribute(name);
		}

		@Override
		public Map<String, Object> getAttributes() {
			return delegate.getAttributes();
		}

		@Override
		public Collection<? extends GrantedAuthority> getAuthorities() {
			return delegate.getAuthorities();
		}

		@Override
		public String getName() {
			return delegate.getName();
		}
	}

</syntaxhighlight>
====Introspector Implementation====
This is the class responsible for translating the OAuth2AuthenticatedPrincipal
<syntaxhighlight lang="java">
public class ResolutionOpaqueTokenIntrospector implements OpaqueTokenIntrospector {
	private final OpaqueTokenIntrospector delegate;
	private final UserRepository users;

	public ResolutionOpaqueTokenIntrospector(
			OpaqueTokenIntrospector delegate, UserRepository users) {
		this.delegate = delegate;
		this.users = users;
	}

	@Override
	public OAuth2AuthenticatedPrincipal introspect(String token) {
		OAuth2AuthenticatedPrincipal principal = this.delegate.introspect(token);

		String name = principal.getName();
		Map<String, Object> attributes =
				new HashMap<>(principal.getAttributes());
		Collection<GrantedAuthority> authorities =
				new ArrayList<>(principal.getAuthorities());

		UUID userId = UUID.fromString(principal.getAttribute("user_id"));
		attributes.put("user_id", userId);

		User user = users.findById(userId)
				.orElseThrow(() -> new UsernameNotFoundException("no user"));
		if ("premium".equals(user.getSubscription())) {
			if (authorities.stream().map(GrantedAuthority::getAuthority)
					.anyMatch(authority -> "SCOPE_resolution:write".equals(authority))) {
				authorities.add(new SimpleGrantedAuthority("resolution:share"));
			}
		}

		OAuth2AuthenticatedPrincipal delegate =
				new DefaultOAuth2AuthenticatedPrincipal(name, attributes, authorities);

		return new BridgeUser(user, delegate);
	}

	private static class BridgeUser extends User implements OAuth2AuthenticatedPrincipal {
		private final OAuth2AuthenticatedPrincipal delegate;

		public BridgeUser(User user, OAuth2AuthenticatedPrincipal delegate) {
			super(user);
			this.delegate = delegate;
		}

		@Override
		@Nullable
		public <A> A getAttribute(String name) {
			return delegate.getAttribute(name);
		}

		@Override
		public Map<String, Object> getAttributes() {
			return delegate.getAttributes();
		}

		@Override
		public Collection<? extends GrantedAuthority> getAuthorities() {
			return delegate.getAuthorities();
		}

		@Override
		public String getName() {
			return delegate.getName();
		}
	}
}

</syntaxhighlight>