001/*
002 * SonarQube
003 * Copyright (C) 2009-2017 SonarSource SA
004 * mailto:info AT sonarsource DOT com
005 *
006 * This program is free software; you can redistribute it and/or
007 * modify it under the terms of the GNU Lesser General Public
008 * License as published by the Free Software Foundation; either
009 * version 3 of the License, or (at your option) any later version.
010 *
011 * This program is distributed in the hope that it will be useful,
012 * but WITHOUT ANY WARRANTY; without even the implied warranty of
013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014 * Lesser General Public License for more details.
015 *
016 * You should have received a copy of the GNU Lesser General Public License
017 * along with this program; if not, write to the Free Software Foundation,
018 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
019 */
020package org.sonar.api.server.authentication;
021
022import javax.servlet.http.HttpServletRequest;
023import javax.servlet.http.HttpServletResponse;
024
025/**
026 * @since 5.4
027 */
028public interface OAuth2IdentityProvider extends IdentityProvider {
029
030  /**
031   * Entry-point of authentication workflow. Executed by core when user
032   * clicks on the related button in login form (GET /sessions/init/{provider key}).
033   */
034  void init(InitContext context);
035
036  /**
037   * This method is called when the identity provider has authenticated a user.
038   */
039  void callback(CallbackContext context);
040
041  interface OAuth2Context {
042
043    /**
044     * The callback URL that must be used by the identity provider
045     */
046    String getCallbackUrl();
047
048    /**
049     * Get the received HTTP request.
050     * Note - {@code getRequest().getSession()} must not be used in order to support
051     * future clustering of web servers without stateful server sessions.
052     */
053    HttpServletRequest getRequest();
054
055    /**
056     * Get the HTTP response to send
057     */
058    HttpServletResponse getResponse();
059  }
060
061  interface InitContext extends OAuth2Context {
062
063    /**
064     * Generate a non-guessable state to prevent Cross Site Request Forgery.
065     */
066    String generateCsrfState();
067
068    /**
069     * Redirect the request to the url.
070     * Can be used to redirect to the identity provider authentication url.
071     */
072    void redirectTo(String url);
073  }
074
075  interface CallbackContext extends OAuth2Context {
076
077    /**
078     * Check that the state is valid.
079     * It should only be called If {@link InitContext#generateCsrfState()} was used in the init
080     */
081    void verifyCsrfState();
082
083    /**
084     * Redirect the request to the requested page.
085     * Must be called at the end of {@link OAuth2IdentityProvider#callback(CallbackContext)}
086     */
087    void redirectToRequestedPage();
088
089    /**
090     * Authenticate and register the user into the platform.
091     * @see org.sonar.api.server.authentication.BaseIdentityProvider.Context#authenticate(UserIdentity)
092     */
093    void authenticate(UserIdentity userIdentity);
094  }
095
096}