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;
008import org.opensaml.saml2.core.Assertion;
009
010
011/**
012 * Service Provider Interface (SPI) for handling self-issued SAML 2.0 bearer
013 * 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 SAML 2.0 assertion by a significant period. The issue
018 * of refresh tokens is not permitted. Clients can refresh an expired access
019 * token by requesting a new one using the same assertion, if it is still
020 * valid, or 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>Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0
030 *         Client Authentication and Authorization Grants (RFC 7522), sections
031 *         2.1, 3 and 3.1.
032 * </ul>
033 */
034public interface SelfIssuedSAML2GrantHandler extends SAML2GrantHandler {
035        
036
037        /**
038         * Handles a self-issued SAML 2.0 bearer assertion grant by a client
039         * registered with the Connect2id server.
040         *
041         * <p>This method is called for SAML 2.0 assertion grants which fulfil
042         * all of the following conditions:
043         *
044         * <ol>
045         *     <li>Are issued by a client which is registered with the
046         *         Connect2id server, i.e. the assertion issuer matches a
047         *         registered client_id;
048         *     <li>The client is registered for the
049         *         {@code urn:ietf:params:oauth:grant-type:saml2-bearer} grant;
050         *     <li>The client is successfully authenticated, by means of
051         *         separate client authentication included in the token request
052         *         (client_secret_basic, client_secret_post, client_secret_jwt
053         *         or private_key_jwt), and / or with the SAML 2.0 assertion
054         *         grant itself;
055         *     <li>The SAML 2.0 assertion MAC or signature was successfully
056         *         verified using with a registered {@code client_secret} or
057         *         {@code jwks} / {@code jwks_uri};
058         *     <li>The assertion audience, expiration and not-before time are
059         *         verify successfully.
060         * </ol>
061         *
062         * <p>If the requested scope is invalid, unknown, malformed, or exceeds
063         * the scope granted by the resource owner the handler must throw a
064         * {@link GeneralException} with an
065         * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_SCOPE
066         * invalid_scope} error code.
067         *
068         * @param assertion      The SAML 2.0 assertion. The audience,
069         *                       expiration, not-before time and XML signature
070         *                       are verified by the Connect2id server.
071         *                       The issuer will equal the client_id. Not
072         *                       {@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 Assertion assertion,
086                                                                final Scope scope,
087                                                                final ClientID clientID,
088                                                                final OIDCClientMetadata clientMetadata)
089                throws GeneralException;
090}