001package com.nimbusds.openid.connect.provider.spi.tokens.introspection;
002
003
004import net.jcip.annotations.ThreadSafe;
005
006import com.nimbusds.oauth2.sdk.TokenIntrospectionSuccessResponse;
007import com.nimbusds.openid.connect.provider.spi.tokens.AccessTokenAuthorization;
008
009
010/**
011 * Service Provider Interface (SPI) for composing token introspection (RFC
012 * 7662) responses. Implementations must be thread-safe.
013 *
014 * <p>The SPI may be used to respond differently to different resource servers
015 * making the same request. For instance, an authorisation server may limit
016 * which scopes from a given token are returned for each resource server to
017 * prevent a resource server from learning more about the larger network than
018 * is necessary for its operation.
019 *
020 * <p>See OAuth 2.0 Token Introspection (RFC 7662), section 2.2.
021 */
022@ThreadSafe
023public interface TokenIntrospectionResponseComposer {
024        
025        
026        /**
027         * Composes a token introspection response.
028         *
029         * <p>If the access token was found to be invalid or expired the
030         * method should simply return
031         *
032         * <pre>
033         * if (tokenAuthz == null) {
034         *      return new TokenIntrospectionSuccessResponse.Builder(false)
035         *          .build();
036         * }
037         * </pre>
038         *
039         * @param tokenAuthz The access token authorisation, {@code null} if
040         *                   the token was found to be invalid or expired
041         *                   (implies {@code "active":false}).
042         * @param context    The token introspection context. Not {@code null}.
043         *
044         * @return The token introspection success response (for
045         *         {@code "active":true} as well as {@code "active":false}
046         *         access tokens.
047         */
048        TokenIntrospectionSuccessResponse compose(final AccessTokenAuthorization tokenAuthz,
049                                                  final TokenIntrospectionContext context);
050}