001package com.nimbusds.openid.connect.provider.spi.clientauth;
002
003
004import java.util.Optional;
005
006import net.jcip.annotations.ThreadSafe;
007
008import com.nimbusds.oauth2.sdk.auth.verifier.InvalidClientException;
009import com.nimbusds.openid.connect.provider.spi.Lifecycle;
010
011
012/**
013 * Service Provider Interface (SPI) for verifying an X.509 certificate (x5c) in
014 * {@link com.nimbusds.oauth2.sdk.auth.ClientAuthenticationMethod#PRIVATE_KEY_JWT
015 * private_key_jwt} client authentications. This can be used to enable
016 * {@code private_key_jwt} authentication based on qualified certificates and
017 * without a prior client JWK set registration (via the "jwks" or "jwks_uri"
018 * client metadata parameters).
019 *
020 * <p>The SPI enables implementation of policies where only selected
021 * clients are allowed or required to include a certificate for the
022 * {@code private_key_jwt}, based on the client's registered metadata or other
023 * criteria.
024 *
025 * <p>A client can {@linkplain CertificateLocation place} the certificate in
026 * the {@code private_key_jwt} "x5c" header. Alternatively, the certificate
027 * can be put in the "x5c" parameter of a matching public JWK and have the key
028 * pre-registered via the "jwks" or "jwks_uri" client metadata parameter.
029 *
030 * <p>Implementations must be thread-safe.
031 */
032@ThreadSafe
033public interface PrivateKeyJWTCertificateVerifier extends Lifecycle {
034        
035        
036        /**
037         * Checks the X.509 certificate requirement for the specified
038         * {@code private_key_jwt} client authentication. If the client must
039         * use a certificate as part of the {@code private_key_jwt}
040         * authentication, included by value in the JWS "x5c" header parameter,
041         * or included in a registered client JWK in the client's "jwks" or
042         * "jwks_uri", the method returns a certificate verification callback.
043         *
044         * @param context The {@code private_key_jwt} client authentication
045         *                context. Not {@code null}.
046         *
047         * @return A certificate verification callback if a certificate is
048         *         required for the {@code private_key_jwt} client
049         *         authentication. If a certificate isn't required none is
050         *         returned.
051         *
052         * @throws InvalidClientException To reject the authentication with an
053         * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_CLIENT
054         * invalid_client} error, due to an unmet authentication requirement.
055         * Throwing an {@link ExposedInvalidClientException} will override the
056         * default Connect2id server {@code error_description} and
057         * {@code error_uri} in the HTTP 401 Unauthorized error response.
058         */
059        Optional<CertificateVerification> checkCertificateRequirement(final PrivateKeyJWTContext context)
060                throws InvalidClientException;
061}