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