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 self-issued SAML 2.0 bearer
015 * assertion grants. Returns the matching
016 * {@link SelfIssuedAssertionAuthorization authorisation} on success.
017 *
018 * <p>The handler should not specify access token lifetimes that exceed the
019 * validity period of the SAML 2.0 assertion by a significant period. The issue
020 * of refresh tokens is not permitted. Clients can refresh an expired access
021 * token by requesting a new one using the same assertion, if it is still
022 * valid, or with a new assertion.
023 *
024 * <p>Implementations must be thread-safe.
025 *
026 * <p>Related specifications:
027 *
028 * <ul>
029 *     <li>Assertion Framework for OAuth 2.0 Client Authentication and
030 *         Authorization Grants (RFC 7521), section 4.1.
031 *     <li>Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0
032 *         Client Authentication and Authorization Grants (RFC 7522), sections
033 *         2.1, 3 and 3.1.
034 * </ul>
035 */
036@ThreadSafe
037public interface SelfIssuedSAML2GrantHandler extends SAML2GrantHandler {
038        
039
040        /**
041         * Handles a self-issued SAML 2.0 bearer assertion grant by a client
042         * registered with the Connect2id server.
043         *
044         * <p>This method is called for SAML 2.0 assertion grants which fulfil
045         * all of the following conditions:
046         *
047         * <ol>
048         *     <li>Are issued by a client which is registered with the
049         *         Connect2id server, i.e. the assertion issuer matches a
050         *         registered client_id;
051         *     <li>The client is registered for the
052         *         {@code urn:ietf:params:oauth:grant-type:saml2-bearer} grant;
053         *     <li>The client is successfully authenticated, by means of
054         *         separate client authentication included in the token request
055         *         (client_secret_basic, client_secret_post, client_secret_jwt
056         *         or private_key_jwt), and / or with the SAML 2.0 assertion
057         *         grant itself;
058         *     <li>The SAML 2.0 assertion MAC or signature was successfully
059         *         verified using with a registered {@code client_secret} or
060         *         {@code jwks} / {@code jwks_uri};
061         *     <li>The assertion audience, expiration and not-before time are
062         *         verify successfully.
063         * </ol>
064         *
065         * <p>If the requested scope is invalid, unknown, malformed, or exceeds
066         * the scope granted by the resource owner the handler must throw a
067         * {@link GeneralException} with an
068         * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_SCOPE
069         * invalid_scope} error code.
070         *
071         * @param assertion      The SAML 2.0 assertion. The audience,
072         *                       expiration, not-before time and XML signature
073         *                       are verified by the Connect2id server.
074         *                       The issuer will equal the client_id. Not
075         *                       {@code null}.
076         * @param scope          The requested scope, {@code null} if not
077         *                       specified.
078         * @param clientID       The identifier of the authenticated client.
079         *                       Not {@code null}.
080         * @param clientMetadata The OAuth 2.0 / OpenID Connect metadata for
081         *                       the client. Not {@code null}.
082         *
083         * @return The authorisation.
084         *
085         * @throws GeneralException If the grant is invalid, or another
086         *                          exception was encountered.
087         */
088        SelfIssuedAssertionAuthorization processSelfIssuedGrant(final Assertion assertion,
089                                                                final Scope scope,
090                                                                final ClientID clientID,
091                                                                final OIDCClientMetadata clientMetadata)
092                throws GeneralException;
093}