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}