001/* 002 * Syncany, www.syncany.org 003 * Copyright (C) 2011-2016 Philipp C. Heckel <philipp.heckel@gmail.com> 004 * 005 * This program is free software: you can redistribute it and/or modify 006 * it under the terms of the GNU General Public License as published by 007 * the Free Software Foundation, either version 3 of the License, or 008 * (at your option) any later version. 009 * 010 * This program is distributed in the hope that it will be useful, 011 * but WITHOUT ANY WARRANTY; without even the implied warranty of 012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 013 * GNU General Public License for more details. 014 * 015 * You should have received a copy of the GNU General Public License 016 * along with this program. If not, see <http://www.gnu.org/licenses/>. 017 */ 018package org.syncany.plugins.transfer.oauth; 019 020import java.net.URI; 021 022import org.syncany.plugins.transfer.StorageException; 023import org.syncany.plugins.transfer.TransferPlugin; 024import org.syncany.plugins.transfer.TransferSettings; 025 026/** 027 * For {@link TransferPlugin}s that base their authentication on OAuth, 028 * a generator class can be used to create the authentication URL and 029 * check the user-provided token. The concrete implementation of this 030 * interface should be provided to the {@link TransferSettings} class 031 * via the {@link OAuth} annotation.<br> 032 * A generator can be extended with {@link OAuthGenerator.WithInterceptor}, 033 * {@link OAuthGenerator.WithExtractor} and 034 * {@link OAuthGenerator.WithNoRedirectMode}. 035 * 036 * @author Philipp Heckel (philipp.heckel@gmail.com) 037 * @author Christian Roth (christian.roth@port17.de) 038 */ 039public interface OAuthGenerator { 040 /** 041 * Generate a URL which can be accessed by a user to authorize Syncany 042 * 043 * @param redirectUri The URL to which the OAuth provider should redirect in any case (either success or failure) 044 * @return A URL to authorize Syncany using the provided redirectUri 045 * @throws StorageException 046 */ 047 URI generateAuthUrl(URI redirectUri) throws StorageException; 048 049 /** 050 * Validate the given token and (optional) csrf parameter. 051 * 052 * @param token Token provided by {@link OAuthTokenWebListener}. 053 * @param csrfState Content of the state parameter (optional). 054 * @throws StorageException 055 */ 056 void checkToken(String token, /*@Nullable*/ String csrfState) throws StorageException; 057 058 // Annotation don't support concrete instances of objects, only classes. Thus we need to add two additional interfaces 059 // if a plugin requires custom interceptors or extractors 060 061 /** 062 * Use a custom {@link OAuthTokenInterceptor} instead of the default one which depends on the {@link OAuthMode} in use. 063 * 064 * See: {@link OAuthTokenInterceptor} 065 */ 066 interface WithInterceptor { 067 OAuthTokenInterceptor getInterceptor(); 068 } 069 070 /** 071 * Use a custom {@link OAuthTokenExtractor} instead of the default one which depends on the {@link OAuthMode} in use. 072 * 073 * See: {@link OAuthTokenExtractor} 074 */ 075 interface WithExtractor { 076 OAuthTokenExtractor getExtractor(); 077 } 078 079 /** 080 * If an OAuth based plugin also supports copy&pasting a token from a website it should extend this interface. 081 */ 082 interface WithNoRedirectMode { 083 /** 084 * Called if Syncany is started in headless mode which does not support redirect_to URLs.<br> 085 * The website should output a token which can be copied over to Syncany's repo wizard. 086 * 087 * @return A URL with no redirect URL 088 * @throws StorageException 089 */ 090 URI generateAuthUrl() throws StorageException; 091 } 092}