001/* 002 * The contents of this file are subject to the terms of the Common Development and 003 * Distribution License (the License). You may not use this file except in compliance with the 004 * License. 005 * 006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the 007 * specific language governing permission and limitations under the License. 008 * 009 * When distributing Covered Software, include this CDDL Header Notice in each file and include 010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL 011 * Header, with the fields enclosed by brackets [] replaced by your own identifying 012 * information: "Portions copyright [year] [name of copyright owner]". 013 * 014 * Copyright 2014-2015 ForgeRock AS. 015 * Portions Copyrighted 2015 Nomura Research Institute, Ltd. 016 */ 017 018package org.forgerock.oauth2.core; 019 020import org.forgerock.oauth2.core.exceptions.InvalidClientException; 021import org.forgerock.oauth2.core.exceptions.InvalidScopeException; 022import org.forgerock.oauth2.core.exceptions.NotFoundException; 023import org.forgerock.oauth2.core.exceptions.ServerException; 024import org.forgerock.oauth2.core.exceptions.UnauthorizedClientException; 025 026import java.util.Map; 027import java.util.Set; 028 029/** 030 * Provided as extension points to allow the OAuth2 provider to customise the requested scope of authorize, 031 * access token and refresh token requests and to allow the OAuth2 provider to return additional data from these 032 * endpoints as well. 033 * 034 * @since 12.0.0 035 * @supported.all.api 036 */ 037public interface ScopeValidator { 038 039 /** 040 * Provided as an extension point to allow the OAuth2 provider to customise the scope requested when authorization 041 * is requested. 042 * 043 * @param clientRegistration The client registration. 044 * @param scope The requested scope. 045 * @param request The OAuth2 request. 046 * @return The updated scope used in the remaining OAuth2 process. 047 * @throws InvalidScopeException If the requested scope is invalid, unknown, or malformed. 048 * @throws ServerException If any internal server error occurs. 049 */ 050 Set<String> validateAuthorizationScope(ClientRegistration clientRegistration, Set<String> scope, 051 OAuth2Request request) throws InvalidScopeException, ServerException; 052 053 /** 054 * Provided as an extension point to allow the OAuth2 provider to customise the scope requested when an access token 055 * is requested. 056 * 057 * @param clientRegistration The client registration. 058 * @param scope The requested scope. 059 * @param request The OAuth2 request. 060 * @return The updated scope used in the remaining OAuth2 process. 061 * @throws InvalidScopeException If the requested scope is invalid, unknown, or malformed. 062 * @throws ServerException If any internal server error occurs. 063 */ 064 Set<String> validateAccessTokenScope(ClientRegistration clientRegistration, Set<String> scope, 065 OAuth2Request request) throws InvalidScopeException, ServerException; 066 067 /** 068 * Provided as an extension point to allow the OAuth2 provider to customise the scope requested when a refresh token 069 * is requested. 070 * 071 * @param clientRegistration The client registration. 072 * @param requestedScope The requested scope. 073 * @param tokenScope The scope from the access token. 074 * @param request The OAuth2 request. 075 * @return The updated scope used in the remaining OAuth2 process. 076 * @throws InvalidScopeException If the requested scope is invalid, unknown, or malformed. 077 * @throws ServerException If any internal server error occurs. 078 */ 079 Set<String> validateRefreshTokenScope(ClientRegistration clientRegistration, Set<String> requestedScope, 080 Set<String> tokenScope, OAuth2Request request) throws ServerException, InvalidScopeException; 081 082 /** 083 * Gets the resource owners information based on an issued access token. 084 * 085 * @param token The access token. 086 * @param request The OAuth2 request. 087 * @return A {@code Map<String, Object>} of the resource owner's information. 088 * @throws UnauthorizedClientException If the client's authorization fails. 089 * @throws NotFoundException If the realm does not have an OAuth 2.0 provider service. 090 */ 091 UserInfoClaims getUserInfo(AccessToken token, OAuth2Request request) throws UnauthorizedClientException, NotFoundException; 092 093 /** 094 * Gets the specified access token's information. 095 * 096 * @param accessToken The access token. 097 * @return A {@code Map<String, Object>} of the access token's information. 098 */ 099 Map<String, Object> evaluateScope(AccessToken accessToken); 100 101 /** 102 * Provided as an extension point to allow the OAuth2 provider to return additional data from an authorization 103 * request. 104 * 105 * @param tokens The tokens that will be returned from the authorization call. 106 * @param request The OAuth2 request. 107 * @return A {@code Map<String, String>} of the additional data to return. 108 */ 109 Map<String, String> additionalDataToReturnFromAuthorizeEndpoint(Map<String, Token> tokens, OAuth2Request request); 110 111 /** 112 * Provided as an extension point to allow the OAuth2 provider to return additional data from an access token 113 * request. 114 * <br/> 115 * Any additional data to be returned should be added to the access token by invoking, 116 * AccessToken#addExtraData(String, String). 117 * 118 * @param accessToken The access token. 119 * @param request The OAuth2 request. 120 * @throws ServerException If any internal server error occurs. 121 * @throws InvalidClientException If either the request does not contain the client's id or the client fails to be 122 * authenticated. 123 * @throws NotFoundException If the realm does not have an OAuth 2.0 provider service. 124 */ 125 void additionalDataToReturnFromTokenEndpoint(AccessToken accessToken, OAuth2Request request) throws ServerException, 126 InvalidClientException, NotFoundException; 127}