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