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