package org.springframework.security.oauth2.provider.approval;

import java.util.Map;

import org.springframework.security.core.Authentication;
import org.springframework.security.oauth2.provider.AuthorizationRequest;

/**
 * Basic interface for determining whether a given client authentication request has been approved by the current user.
 * 
 * @author Ryan Heaton
 * @author Dave Syer
 * @author Amanda Anganes
 */
public interface UserApprovalHandler {

	/**
	 * <p>
	 * Tests whether the specified authorization request has been approved by the current user (if there is one).
	 * </p>
	 * 
	 * @param authorizationRequest the authorization request.
	 * @param userAuthentication the user authentication for the current user.
	 * @return true if the request has been approved, false otherwise
	 */
	boolean isApproved(AuthorizationRequest authorizationRequest, Authentication userAuthentication);

	/**
	 * <p>
	 * Provides a hook for allowing requests to be pre-approved (skipping the User Approval Page). Some implementations
	 * may allow users to store approval decisions so that they only have to approve a site once. This method is called
	 * in the AuthorizationEndpoint before sending the user to the Approval page. If this method sets
	 * oAuth2Request.approved to true, the Approval page will be skipped.
	 * </p>
	 * 
	 * @param authorizationRequest the authorization request.
	 * @param userAuthentication the user authentication
	 * @return the AuthorizationRequest, modified if necessary
	 */
	AuthorizationRequest checkForPreApproval(AuthorizationRequest authorizationRequest,
			Authentication userAuthentication);

	/**
	 * <p>
	 * Provides an opportunity to update the authorization request before it is checked for approval in cases where the
	 * incoming approval parameters contain richer information than just true/false (e.g. some scopes are approved, and
	 * others are rejected), implementations may need to be able to modify the {@link AuthorizationRequest} before a
	 * token is generated from it.
	 * </p>
	 * 
	 * @param authorizationRequest the authorization request.
	 * @param userAuthentication the user authentication
	 * @return the AuthorizationRequest, modified if necessary
	 */
	AuthorizationRequest updateAfterApproval(AuthorizationRequest authorizationRequest,
			Authentication userAuthentication);

	/**
	 * Generate a request for the authorization server to ask for the user's approval. Typically this will be rendered
	 * into a view (HTML etc.) to prompt for the approval, so it needs to contain information about the grant (scopes
	 * and client id for instance).
	 * 
	 * @param authorizationRequest the authorization request
	 * @param userAuthentication the user authentication
	 * @return a model map for rendering to the user to ask for approval
	 */
	Map<String, Object> getUserApprovalRequest(AuthorizationRequest authorizationRequest,
			Authentication userAuthentication);

}

@@ -297,32 +297,35 @@
 request has been
+%0A *
  approved by the
@@ -552,24 +552,28 @@
  the current
+%0A%09 *
  user (if th
@@ -868,17 +868,20 @@
 Request,
- 
+%0A%09%09%09
 Authenti
@@ -1001,16 +1001,20 @@
 the User
+%0A%09 *
  Approva
@@ -1042,20 +1042,16 @@
 ntations
-%0A%09 *
  may all
@@ -1089,16 +1089,20 @@
 sions so
+%0A%09 *
  that th
@@ -1163,19 +1163,19 @@
 lled
-%0A%09 *
  in the
+%0A%09 *
  Aut
@@ -1257,17 +1257,17 @@
 thod
+%0A%09 *
  sets
-%0A%09 *
  oAu
@@ -1724,16 +1724,122 @@
 request 
+after the%0A%09 * %7B@link AuthorizationRequest#setApprovalParameters(Map) approval parameters%7D are set%0A%09 * but 
 before i
@@ -1863,16 +1863,24 @@
 approval
+. Useful
  in case
@@ -1890,20 +1890,16 @@
 here the
-%0A%09 *
  incomin
@@ -1900,32 +1900,36 @@
 ncoming approval
+%0A%09 *
  parameters cont
@@ -1993,16 +1993,20 @@
 opes are
+%0A%09 *
  approve
@@ -2011,20 +2011,16 @@
 ved, and
-%0A%09 *
  others 
@@ -2079,16 +2079,20 @@
 o modify
+%0A%09 *
  the %7B@l
@@ -2125,20 +2125,16 @@
 before a
-%0A%09 *
  token i
@@ -2559,16 +2559,20 @@
 pproval.
+%0A%09 *
  Typical
@@ -2595,20 +2595,16 @@
 rendered
-%0A%09 *
  into a 
@@ -2647,16 +2647,20 @@
 pproval,
+%0A%09 *
  so it n
@@ -2710,20 +2710,16 @@
  (scopes
-%0A%09 *
  and cli
@@ -2728,16 +2728,20 @@
 t id for
+%0A%09 *
  instanc

Update UserApprovalHandler documentation.