001package com.nimbusds.openid.connect.provider.spi.grants;
002
003
004import com.nimbusds.jwt.JWT;
005
006import com.nimbusds.oauth2.sdk.GeneralException;
007import com.nimbusds.oauth2.sdk.Scope;
008import com.nimbusds.oauth2.sdk.id.ClientID;
009import com.nimbusds.openid.connect.sdk.rp.OIDCClientMetadata;
010
011
012/**
013 * Service Provider Interface (SPI) for handling JSON Web Token (JWT) assertion
014 * grants issued by a third-party security token service. Returns the matching
015 * {@link ThirdPartyAssertionAuthorization authorisation} on success. Must
016 * throw a {@link GeneralException} with an
017 * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_GRANT invalid_grant}
018 * error code if the JWT assertion is invalid.
019 *
020 * <p>The handler should not specify access token lifetimes that exceed the
021 * validity period of the JWT assertion by a significant period. The issue of
022 * refresh tokens is not permitted. Clients can refresh an expired access token
023 * by requesting a new one using the same assertion, if it is still valid, or
024 * with a new assertion.
025 *
026 * <p>Implementations must be thread-safe.
027 *
028 * <p>Related specifications:
029 *
030 * <ul>
031 *     <li>Assertion Framework for OAuth 2.0 Client Authentication and
032 *         Authorization Grants (RFC 7521), section 4.1.
033 *     <li>JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and
034 *         Authorization Grants (RFC 7523), sections 2.1, 3 and 3.1.
035 * </ul>
036 */
037public interface ThirdPartyJWTGrantHandler extends JWTGrantHandler {
038
039
040        /**
041         * Handles a JWT assertion grant issued by a third-party security token
042         * service. The grant handler must verify the JWT assertion, using a
043         * previously agreed method to resolve the client's MAC or signature
044         * key.
045         *
046         * <p>The following client authentication / identification cases may be
047         * handled:
048         *
049         * <ol>
050         *     <li><strong>Confidential client: </strong>
051         *         If the client is confidential and has provided valid
052         *         authentication (client_secret_basic, client_secret_post,
053         *         client_secret_jwt or private_key_jwt) the
054         *         {@code confidentialClient} flag will be {@code true}. The
055         *         client_id and metadata arguments will be set.
056         *     <li><strong>Public client: </strong>
057         *         If the client is public and has a provided its registered
058         *         {@code client_id} using the optional token request
059         *         parameter, the {@code confidentialClient} flag will be
060         *         {@code false} and the client metadata will be set.
061         *     <li><strong>Handler must resolve client_id from JWT claims: </strong>
062         *         If no client authentication or {@code client_id} is passed
063         *         with the token request, the client information arguments
064         *         will be {@code null} and the {@code confidentialClient} flag
065         *         will be {@code false}. The grant handler must resolve the
066         *         {@code client_id} for the authorisation result from the
067         *         claims of the JWT assertion. If such a use case is not
068         *         supported or permitted the grant handler should throw a
069         *         {@link GeneralException} with an
070         *         {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_REQUEST
071         *         invalid_request} error.
072         * </ol>
073         *
074         * <p>If the JWT assertion is invalid the handler must throw a
075         * {@link GeneralException} with an
076         * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_GRANT
077         * invalid_grant} error code.
078         *
079         * <p>If the requested scope is invalid, unknown, malformed, or exceeds
080         * the scope granted by the resource owner the handler must throw a
081         * {@link GeneralException} with an
082         * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_SCOPE
083         * invalid_scope} error code.
084         *
085         * @param jwtAssertion       The JWT assertion, to be verified by the
086         *                           handler. Can be signed or signed and
087         *                           encrypted. Not {@code null}.
088         * @param scope              The requested scope, {@code null} if not
089         *                           specified.
090         * @param clientID           The client identifier, {@code null} if not
091         *                           specified or if no client authentication
092         *                           was provided.
093         * @param confidentialClient {@code true} if the client is confidential
094         *                           and has been authenticated, else
095         *                           {@code false}.
096         * @param clientMetadata     The OAuth 2.0 / OpenID Connect client
097         *                           metadata, {@code null} if no
098         *                           {@code client_id} or client authentication
099         *                           was provided.
100         *
101         * @return The authorisation.
102         *
103         * @throws GeneralException If the grant is invalid, or another
104         *                          exception was encountered.
105         */
106        ThirdPartyAssertionAuthorization processThirdPartyGrant(final JWT jwtAssertion,
107                                                                final Scope scope,
108                                                                final ClientID clientID,
109                                                                final boolean confidentialClient,
110                                                                final OIDCClientMetadata clientMetadata)
111                throws GeneralException;
112}