001/*
002* The contents of this file are subject to the terms of the Common Development and
003* Distribution License (the License). You may not use this file except in compliance with the
004* License.
005*
006* You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007* specific language governing permission and limitations under the License.
008*
009* When distributing Covered Software, include this CDDL Header Notice in each file and include
010* the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011* Header, with the fields enclosed by brackets [] replaced by your own identifying
012* information: "Portions copyright [year] [name of copyright owner]".
013*
014* Copyright 2014 ForgeRock AS.
015*/
016package org.forgerock.jaspi.modules.openid.resolvers.service;
017
018import java.net.URL;
019import org.forgerock.jaspi.modules.openid.resolvers.OpenIdResolver;
020
021/**
022 * Interface through which OpenIdResolvers are obtained, and the service providing
023 * them is configured.
024 *
025 * A resolver can be configured through a number of configurations, each of which results
026 * in the generation of a key which can be used to perform cryptographic verification
027 * of the JWS which will be provided to the resolver once it is configured inside the service.
028 *
029 * The service will then provide access to the specific resolver needed at the point of
030 * verification by keying on its
031 * {@link org.forgerock.jaspi.modules.openid.resolvers.OpenIdResolver#getIssuer()} value.
032 *
033 * Resolvers can be configured by supplying one of the following configurations:
034 *
035 * - The issuer's name, along with the specific location of the public key to use
036 * when performing verification as drawn from a standard trust store.
037 * - The issuer's name, along with a shared secret which can be used to create an HMAC
038 * which will verify the signature in the provided JWS.
039 * - The issuer's name, along with the URL of a JWK set, which provides keys through
040 * a public exposure point.
041 * - A .well-known configuration URL, which provides both the issuer name and location
042 * of the corresponding JWK set which it should use to configure the resolver.
043 */
044public interface OpenIdResolverService {
045
046    /**
047     * Returns the appropriate OpenId Connect resolver for the issuer. The
048     * OpenId Connect JWT's "iss" field MUST be identical to the issuer param.
049     *
050     * @param issuer Reference to the issuer of the OpenID Connect JWT
051     * @return an OpenIdResolver for the corresponding provider
052     */
053    public OpenIdResolver getResolverForIssuer(final String issuer);
054
055    /**
056     * Configures a new resolver implementation using the given parameters for this
057     * service which is later retrievable.
058     *
059     * @param issuer issuer's name - the OpenID Connect "iss" field
060     * @param keyAlias alias inside the keystore of the public key for this resolver
061     * @param keystoreLocation location of the keystore from which to retrieve the key
062     * @param keystoreType the type of keystore to connect to
063     * @param keystorePassword password for connecting to the keystore
064     * @return true if resolver configured successfully, false otherwise
065     */
066    public boolean configureResolverWithKey(final String issuer,
067                                     final String keyAlias, final String keystoreLocation,
068                                     final String keystoreType, final String keystorePassword);
069
070    /**
071     * Configures a new resolver implementation using the given parameters for this
072     * service which is later retrievable.
073     *
074     * @param issuer issuer's name - the OpenID Connect "iss" field
075     * @param sharedSecret secret shared between client and provider
076     * @return true if resolver configured successfully, false otherwise
077     */
078    public boolean configureResolverWithSecret(final String issuer,
079                                            final String sharedSecret);
080
081
082    /**
083     * Configures a new resolver implementation using the given parameters for this
084     * service which is later retrievable.
085     *
086     * @param issuer issuer's name - the OpenID Connect "iss" field
087     * @param jwkUrl location from which to determine which public key to use
088     * @return true if resolver configured successfully, false otherwise
089     */
090    public boolean configureResolverWithJWK(final String issuer, final URL jwkUrl);
091
092    /**
093     * Configures a new resolver implementation using the given configUrl as the
094     * location from which to draw all necessary information pertaining to the resolver.
095     * Specifically and minimally this means the issuer value and the location of the
096     * JWK url
097     *
098     * @param configUrl The well-known Open Id Connect configuration url
099     * @return true if resolver configured successfully, false otherwise
100     */
101    public boolean configureResolverWithWellKnownOpenIdConfiguration(final URL configUrl);
102
103}