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