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