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;
011import com.nimbusds.oauth2.sdk.id.Subject;
012import com.nimbusds.openid.connect.sdk.claims.UserInfo;
013
014
015/**
016 * Advanced Service Provider Interface (SPI) for sourcing OpenID Connect
017 * UserInfo and other claims about a subject (end-user). This interface is
018 * intended for claims sources that require access to additional parameters,
019 * such as the client identifier (client_id); if that's not needed stick to the
020 * {@link ClaimsSource basic interface}. Implementations must be thread-safe.
021 *
022 * <p>Claims sources can be:
023 *
024 * <ul>
025 *     <li>LDAP directories
026 *     <li>SQL or NoSQL databases
027 *     <li>Web services
028 *     <li>Files
029 * </ul>
030 */
031@ThreadSafe
032public interface AdvancedClaimsSource extends CommonClaimsSource {
033        
034        
035        /**
036         * The {@code verified:} prefix for names of verified claims.
037         */
038        String VERIFIED_CLAIM_NAME_PREFIX = "verified:";
039
040        
041        /**
042         * Requests claims for the specified subject.
043         *
044         * @param subject        The subject. Must not be {@code null}.
045         * @param claims         The names of the requested claims, with
046         *                       optional language tags. The names of verified
047         *                       claims (OpenID Connect for Identity Assurance
048         *                       1.0) are prefixed with "verified:". Not
049         *                       {@code null}.
050         * @param claimsLocales  The preferred languages and scripts for the
051         *                       claims to return, {@code null} if not
052         *                       specified.
053         * @param requestContext Provides access to additional parameters
054         *                       about the request. Not {@code null}.
055         *
056         * @return The claims, {@code null} if the subject wasn't found or the
057         *         claims source is {@link #isEnabled disabled}.
058         *
059         * @throws Exception If retrieval of the claims failed.
060         */
061        UserInfo getClaims(final Subject subject,
062                           final Set<String> claims,
063                           final @Nullable List<LangTag> claimsLocales,
064                           final ClaimsSourceRequestContext requestContext)
065                throws Exception;
066}