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}