001package com.nimbusds.openid.connect.provider.spi.grants;
002
003
004import net.jcip.annotations.ThreadSafe;
005
006import com.nimbusds.jwt.JWTClaimsSet;
007import com.nimbusds.oauth2.sdk.GeneralException;
008import com.nimbusds.oauth2.sdk.Scope;
009import com.nimbusds.oauth2.sdk.id.ClientID;
010import com.nimbusds.openid.connect.sdk.rp.OIDCClientMetadata;
011
012
013/**
014 * Service Provider Interface (SPI) for handling self-issued JSON Web Token
015 * (JWT) bearer assertion grants. Returns the matching
016 * {@link SelfIssuedAssertionAuthorization authorisation} on success.
017 *
018 * <p>The handler should not specify access token lifetimes that exceed the
019 * validity period of the JWT assertion by a significant period. The issue of
020 * refresh tokens is not permitted. Clients can refresh an expired access token
021 * by requesting a new one using the same assertion, if it is still valid, or
022 * with a new assertion.
023 *
024 * <p>Implementations must be thread-safe.
025 *
026 * <p>Related specifications:
027 *
028 * <ul>
029 *     <li>Assertion Framework for OAuth 2.0 Client Authentication and
030 *         Authorization Grants (RFC 7521), section 4.1.
031 *     <li>JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and
032 *         Authorization Grants (RFC 7523), sections 2.1, 3 and 3.1.
033 * </ul>
034 */
035@ThreadSafe
036public interface SelfIssuedJWTGrantHandler extends JWTGrantHandler {
037
038
039        /**
040         * Handles a self-issued JWT bearer assertion grant by a client
041         * registered with the Connect2id server.
042         *
043         * <p>This method is called for JWT assertion grants which fulfil all
044         * of the following conditions:
045         *
046         * <ol>
047         *     <li>Are issued by a client which is registered with the
048         *         Connect2id server, i.e. the JWT issuer (iss) assertion
049         *         matches a registered client_id;
050         *     <li>The client is registered for the
051         *         {@code urn:ietf:params:oauth:grant-type:jwt-bearer} grant;
052         *     <li>The client is successfully authenticated, by means of
053         *         separate client authentication included in the token request
054         *         (client_secret_basic, client_secret_post, client_secret_jwt
055         *         or private_key_jwt), and / or with the JWT assertion grant
056         *         itself;
057         *     <li>The JWT MAC or signature was successfully verified using
058         *         with a registered {@code client_secret} or {@code jwks} /
059         *         {@code jwks_uri};
060         *     <li>The JWT audience (aud), expiration (exp) and not-before
061         *         time (nbf) claims verify successfully.
062         * </ol>
063         *
064         * <p>If the requested scope is invalid, unknown, malformed, or exceeds
065         * the scope granted by the resource owner the handler must throw a
066         * {@link GeneralException} with an
067         * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_SCOPE
068         * invalid_scope} error code.
069         *
070         * @param jwtClaimsSet   The claims set included in the verified JWT
071         *                       assertion grant. The audience (aud),
072         *                       expiration (exp) and not-before time (nbf)
073         *                       claims are verified by the Connect2id server.
074         *                       The issuer (iss) claims will equal the
075         *                       client_id. Not {@code null}.
076         * @param scope          The requested scope, {@code null} if not
077         *                       specified.
078         * @param clientID       The identifier of the authenticated client.
079         *                       Not {@code null}.
080         * @param clientMetadata The OAuth 2.0 / OpenID Connect metadata for
081         *                       the client. Not {@code null}.
082         *
083         * @return The authorisation.
084         *
085         * @throws GeneralException If the grant is invalid, or another
086         *                          exception was encountered.
087         */
088        SelfIssuedAssertionAuthorization processSelfIssuedGrant(final JWTClaimsSet jwtClaimsSet,
089                                                                final Scope scope,
090                                                                final ClientID clientID,
091                                                                final OIDCClientMetadata clientMetadata)
092                throws GeneralException;
093}