001package com.nimbusds.oauth2.sdk.auth.verifier;
002
003
004import java.security.PublicKey;
005import java.util.List;
006
007import com.nimbusds.jose.JWSHeader;
008import com.nimbusds.oauth2.sdk.auth.ClientAuthenticationMethod;
009import com.nimbusds.oauth2.sdk.auth.Secret;
010import com.nimbusds.oauth2.sdk.id.ClientID;
011
012
013/**
014 * Selector of client credential candidates for client authentication
015 * verification. The select methods should typically return a single candidate,
016 * but may also return multiple in case of client credentials key rotation.
017 * Implementations should be tread-safe.
018 *
019 * <p>Selection of {@link com.nimbusds.oauth2.sdk.auth.ClientSecretBasic
020 * client_secret_basic}, {@link com.nimbusds.oauth2.sdk.auth.ClientSecretPost
021 * client_secret_post} and {@link com.nimbusds.oauth2.sdk.auth.ClientSecretJWT
022 * client_secret_jwt} secrets is handled by the {@link #selectClientSecrets}
023 * method.
024 *
025 * <p>Selection of {@link com.nimbusds.oauth2.sdk.auth.PrivateKeyJWT
026 * private_key_jwt} keys is handled by the {@link #selectPublicKeys} method.
027 *
028 * <p>The generic {@link Context context object} may be used to return
029 * {@link com.nimbusds.oauth2.sdk.client.ClientMetadata client metadata} or
030 * other information to the caller.
031 */
032public interface ClientCredentialsSelector<T> {
033
034
035        /**
036         * Selects one or more client secret candidates for
037         * {@link com.nimbusds.oauth2.sdk.auth.ClientSecretBasic client_secret_basic},
038         * {@link com.nimbusds.oauth2.sdk.auth.ClientSecretPost client_secret_post} and
039         * {@link com.nimbusds.oauth2.sdk.auth.ClientSecretJWT client_secret_jwt}
040         * authentication.
041         *
042         * @param claimedClientID The client identifier (to be verified). Not
043         *                        {@code null}.
044         * @param authMethod      The client authentication method. Not
045         *                        {@code null}.
046         * @param context         Additional context. May be {@code null}.
047         *
048         * @return The selected client secret candidates, empty list if none.
049         *
050         * @throws InvalidClientException If the client is invalid.
051         */
052        List<Secret> selectClientSecrets(final ClientID claimedClientID,
053                                         final ClientAuthenticationMethod authMethod,
054                                         final Context<T> context)
055                throws InvalidClientException;
056
057
058        /**
059         * Selects one or more public key candidates (e.g. RSA or EC) for
060         * {@link com.nimbusds.oauth2.sdk.auth.PrivateKeyJWT private_key_jwt}
061         * authentication.
062         *
063         * @param claimedClientID The client identifier (to be verified). Not
064         *                        {@code null}.
065         * @param authMethod      The client authentication method. Not
066         *                        {@code null}.
067         * @param jwsHeader       The JWS header, which may contain parameters
068         *                        such as key ID to facilitate the key
069         *                        selection. Not {@code null}.
070         * @param forceRefresh    {@code true} to force refresh of the JWK set
071         *                        (for a remote JWK set referenced by URL).
072         * @param context         Additional context. May be {@code null}.
073         *
074         * @return The selected public key candidates, empty list if none.
075         *
076         * @throws InvalidClientException If the client is invalid.
077         */
078        List<? extends PublicKey> selectPublicKeys(final ClientID claimedClientID,
079                                                   final ClientAuthenticationMethod authMethod,
080                                                   final JWSHeader jwsHeader,
081                                                   final boolean forceRefresh,
082                                                   final Context<T> context)
083                throws InvalidClientException;
084}