001package com.nimbusds.openid.connect.provider.spi.claims;
002
003
004import java.util.List;
005import java.util.Set;
006
007import net.jcip.annotations.ThreadSafe;
008import org.checkerframework.checker.nullness.qual.Nullable;
009
010import com.nimbusds.langtag.LangTag;
011
012import com.nimbusds.oauth2.sdk.id.Subject;
013import com.nimbusds.openid.connect.sdk.claims.UserInfo;
014
015
016/**
017 * Service Provider Interface (SPI) for sourcing OpenID Connect UserInfo and
018 * other claims about a subject (end-user). Implementations must be thread-
019 * safe.
020 *
021 * <p>Claims sources can be:
022 *
023 * <ul>
024 *     <li>LDAP directories
025 *     <li>SQL or NoSQL databases
026 *     <li>Web services
027 *     <li>Files
028 * </ul>
029 */
030@ThreadSafe
031public interface ClaimsSource extends CommonClaimsSource {
032
033
034        /**
035         * Requests claims for the specified subject.
036         *
037         * @param subject       The subject. Must not be {@code null}.
038         * @param claims        The names of the requested claims, with
039         *                      optional language tags. Must not be
040         *                      {@code null}.
041         * @param claimsLocales The preferred languages and scripts for the
042         *                      claims to return, {@code null} if not
043         *                      specified.
044         *
045         * @return The claims, {@code null} if the subject wasn't found or the
046         *         claims source is {@link #isEnabled disabled}.
047         *
048         * @throws Exception If retrieval of the claims failed.
049         */
050        UserInfo getClaims(final Subject subject,
051                           final Set<String> claims,
052                           final @Nullable List<LangTag> claimsLocales)
053                throws Exception;
054}
055