001package com.nimbusds.openid.connect.provider.claims.source.spi;
002
003
004import java.util.List;
005import java.util.Set;
006
007import com.nimbusds.langtag.LangTag;
008
009import com.nimbusds.oauth2.sdk.id.Subject;
010
011import com.nimbusds.openid.connect.sdk.claims.UserInfo;
012
013
014/**
015 * Source of OpenID Connect UserInfo and other claims about a subject.
016 */
017public interface ClaimsSource {
018
019
020        /**
021         * Initialises the OpenID Connect claims source. This method is called
022         * after the claims source SPI implementation is loaded.
023         *
024         * @param initContext The initialisation context. Can be used to
025         *                    retrieve a configuration file required to set up
026         *                    the claims source, e.g. the parameters to
027         *                    establish a database connection. Not
028         *                    {@code null}.
029         *
030         * @throws Exception If initialisation failed.
031         */
032        public void init(final InitContext initContext)
033                throws Exception;
034
035
036        /**
037         * Checks if the OpenID Connect claims source is enabled.
038         *
039         * @return {@code true} if the claims source is enabled, else
040         *         {@code false}.
041         */
042        public boolean isEnabled();
043
044
045        /**
046         * Returns the names of the supported OpenID Connect claims.
047         *
048         * <p>Example:
049         *
050         * <pre>
051         * name
052         * email
053         * email_verified
054         * </pre>
055         *
056         * @return The supported claim names. Should not include the reserved
057         *         {@code sub} (subject) claim name.
058         */
059        public Set<String> supportedClaims();
060
061
062        /**
063         * Requests claims for the specified subject.
064         *
065         * @param subject       The subject. Must not be {@code null}.
066         * @param claims        The names of the requested claims, with
067         *                      optional language tags. Must not be
068         *                      {@code null}.
069         * @param claimsLocales The preferred languages and scripts for the
070         *                      claims to return, {@code null} if not
071         *                      specified.
072         *
073         * @return The claims, {@code null} if the subject wasn't found or the
074         *         claims source is {@link #isEnabled disabled}.
075         *
076         * @throws Exception If retrieval of the claims failed.
077         */
078        public UserInfo getClaims(final Subject subject,
079                                  final Set<String> claims,
080                                  final List<LangTag> claimsLocales)
081                throws Exception;
082
083
084        /**
085         * Shuts down the OpenID Connect claims source. This method is called
086         * on OpenID Connect Provider (OP) shutdown.
087         *
088         * @throws Exception If proper shutdown failed.
089         */
090        public void shutdown()
091                throws Exception;
092}
093