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