001/*
002 * DO NOT REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003 *
004 * Copyright (c) 2012-2013 ForgeRock AS. All rights reserved.
005 *
006 * The contents of this file are subject to the terms
007 * of the Common Development and Distribution License
008 * (the License). You may not use this file except in
009 * compliance with the License.
010 *
011 * You can obtain a copy of the License at
012 * http://forgerock.org/license/CDDLv1.0.html
013 * See the License for the specific language governing
014 * permission and limitations under the License.
015 *
016 * When distributing Covered Code, include this CDDL
017 * Header Notice in each file and include the License file
018 * at http://forgerock.org/license/CDDLv1.0.html
019 * If applicable, add the following below the CDDL Header,
020 * with the fields enclosed by brackets [] replaced by
021 * your own identifying information:
022 * "Portions Copyrighted [year] [name of company]"
023 */
024
025package org.forgerock.openam.oauth2.provider;
026
027import org.forgerock.openam.oauth2.model.CoreToken;
028
029import java.util.Map;
030import java.util.Set;
031
032/**
033 * This interface needs to be implemented to take advantage of OAuth2's scope feature.
034 * Each method of Scope is called with a new instance of the Scope implementation class. Any data that needs to
035 * persist between scope method calls should be declared static.
036 *
037 * @supported.all.api
038 */
039public interface Scope {
040    /**
041     * scopeToPresentOnAuthorizationPage is called to decide what scopes will appear on the authorization page.
042     *
043     * @param requestedScopes The set of scopes requested
044     * @param availableScopes The set of scopes available for the client requesting the access token
045     * @param defaultScopes   The set of scopes set in the client registration as default
046     * @return The set of scopes to grant the token
047     */
048    public Set<String> scopeToPresentOnAuthorizationPage(Set<String> requestedScopes,
049                                                         Set<String> availableScopes,
050                                                         Set<String> defaultScopes);
051
052    /**
053     * ScopeRequestedForAccessToken is called when a token is created and the token scope is requested.
054     *
055     * @param requestedScopes The set of scopes requested
056     * @param availableScopes The set of scopes available for the client requesting the access token
057     * @param defaultScopes   The set of scopes set in the client registration as default
058     * @return The set of scopes to grant the token
059     */
060    public Set<String> scopeRequestedForAccessToken(Set<String> requestedScopes,
061                                                    Set<String> availableScopes,
062                                                    Set<String> defaultScopes);
063
064    /**
065     * ScopeRequestedForRefreshToken is called when the client tries to refresh an Access Token. The scope returned MUST
066     * not contain a scope not originally granted to the original Access Token.
067     *
068     * @param requestedScopes The set of scopes requested
069     * @param availableScopes The set of scopes given to the original Access Token
070     * @param allScopes       All the available scopes for the client
071     * @param defaultScopes   The set of scopes set in the client registration as default
072     * @return The set of scopes to grant the new Access Token
073     */
074    public Set<String> scopeRequestedForRefreshToken(Set<String> requestedScopes,
075                                                     Set<String> availableScopes,
076                                                     Set<String> allScopes,
077                                                     Set<String> defaultScopes);
078
079    /**
080     * This method is called on the /tokeninfo endpoint. The purpose of this function is to evaluate scope and return
081     * to the client some information on the scope evaluation if necessary.
082     *
083     * @param token An AccessToken that contains all the information about the token
084     * @return returns a map of data to be added to the token json object that will be returned to the client,
085     *         can be null if no information needs to be returned.
086     */
087    public Map<String, Object> evaluateScope(CoreToken token);
088
089    /**
090     * This method is called before the access_token end point returns an access token. Whatever is returned by this
091     * method will be added to the json object returned by the access_token endpoint.
092     *
093     * @param parameters set of extra data to pass into the method
094     * @param token      the token created that will be returned with the extra data from this method
095     * @return
096     */
097    public Map<String, Object> extraDataToReturnForTokenEndpoint(Map<String, String> parameters,
098                                                                 CoreToken token);
099
100    /**
101     * This method is called before the authorize end point returns an response. Whatever is returned by this
102     * method will be added to the json object returned by the authorize endpoint.
103     *
104     * @param parameters map of extra data to pass into the method
105     * @param tokens     a map of token return names to the token objects. For example "code"=>tokenObject
106     * @return the return map should include the key value pair returnType=>Value where value is either FRAGMENT or QUERY
107     */
108    public Map<String, String> extraDataToReturnForAuthorizeEndpoint(Map<String, String> parameters,
109                                                                     Map<String, CoreToken> tokens);
110
111    /**
112     * This method takes the scope values in the token and gets those user profile attributes for the owner of
113     * the token.
114     *
115     * @param token The OAuth2 bearer token containing the user to get the info about
116     * @return
117     */
118    public Map<String, Object> getUserInfo(CoreToken token);
119
120}