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}