com.taboola.backstage.services.AuthenticationService Maven / Gradle / Ivy

package com.taboola.backstage.services;

import com.taboola.backstage.exceptions.BackstageAPIConnectivityException;
import com.taboola.backstage.exceptions.BackstageAPIRequestException;
import com.taboola.backstage.exceptions.BackstageAPIUnauthorizedException;
import com.taboola.backstage.model.auth.BackstageAuthentication;
import com.taboola.backstage.model.auth.TokenDetails;

/**
 * Authentication service allow different authentication types and supply additional token metadata
 *
 * @author vladi
 * @version 1.0
 */
public interface AuthenticationService {

    /**
     * 
     *     Client Credentials: The client submits a Client ID + Client Secret pair to the
     *     token-endpoint, and in exchange receives an Access Token.
     *     This scheme is only appropriate when a confidential app performs server-to-server communication.
     * 
     *
     * @param clientId specific client id (given by Taboola)
     * @param clientSecret specific client secret (given by Taboola)
     * @return {@link BackstageAuthentication} object which is being required by all services
     * @throws BackstageAPIUnauthorizedException {@link com.taboola.backstage.model.auth.Token Token} is expired or bad credentials
     * @throws BackstageAPIConnectivityException Connectivity issues (HTTP status 5xx)
     * @throws BackstageAPIRequestException Bad request (HTTP status 4xx)
     */
    BackstageAuthentication clientCredentials(String clientId, String clientSecret) throws BackstageAPIUnauthorizedException, BackstageAPIConnectivityException, BackstageAPIRequestException;

    /**
     * 
     *     Password Authentication: The client submits a valid Username + Password pair to the
     *     token-endpoint, and in exchange receives an Access Token and a Refresh Token.
     *     This scheme is more appropriate for non-confidential client apps (e.g. web-apps, mobile apps).
     * 
     *
     * @param clientId specific client id (given by Taboola)
     * @param clientSecret specific client secret (given by Taboola)
     * @param username specific Taboola username (given by Taboola)
     * @param password specific Taboola user password (given by Taboola)
     * @return {@link BackstageAuthentication} object which is being required by all services
     * @throws BackstageAPIUnauthorizedException {@link com.taboola.backstage.model.auth.Token Token} is expired or bad credentials
     * @throws BackstageAPIConnectivityException Connectivity issues (HTTP status 5xx)
     * @throws BackstageAPIRequestException Bad request (HTTP status 4xx)
     */
    BackstageAuthentication passwordAuthentication(String clientId, String clientSecret, String username, String password) throws BackstageAPIUnauthorizedException, BackstageAPIConnectivityException, BackstageAPIRequestException;

    /**
     * Refresh previously created {@link BackstageAuthentication} object
     *
     * @param auth Authentication object {@link BackstageAuthentication}
     * @return re-authenticated {@link BackstageAuthentication} new object
     * @throws BackstageAPIUnauthorizedException {@link com.taboola.backstage.model.auth.Token Token} is expired or bad credentials
     * @throws BackstageAPIConnectivityException Connectivity issues (HTTP status 5xx)
     * @throws BackstageAPIRequestException Bad request (HTTP status 4xx)
     */
    BackstageAuthentication reAuthenticate(BackstageAuthentication auth) throws BackstageAPIUnauthorizedException, BackstageAPIConnectivityException, BackstageAPIRequestException;


    /**
     * Creates {@link BackstageAuthentication} based on received access token string.
     * Keep in mind after such authentication it is NOT possible to use {@link #reAuthenticate(BackstageAuthentication) reAuthenticate} method.
     *
     * @param accessToken supplied by authentication {@link com.taboola.backstage.model.auth.Token Token}
     * @return {@link BackstageAuthentication} object which is being required by all services
     */
    BackstageAuthentication authenticate(String accessToken);

    /**
     * Specific {@link com.taboola.backstage.model.auth.Token Token} metadata
     *
     * 
     *     Fetching the Token Details resource associated with an Access Token is probably
     *     crucial for any client-app, because that's the only way you can know which Accounts
     *     this Access Token allows you to access.
     * 
     *
     * @param auth Authentication object {@link BackstageAuthentication}
     * @return {@link TokenDetails} metadata of specific {@link com.taboola.backstage.model.auth.Token Token}
     * @throws BackstageAPIUnauthorizedException {@link com.taboola.backstage.model.auth.Token Token} is expired or bad credentials
     * @throws BackstageAPIConnectivityException Connectivity issues (HTTP status 5xx)
     * @throws BackstageAPIRequestException Bad request (HTTP status 4xx)
     */
    TokenDetails getTokenDetails(BackstageAuthentication auth) throws BackstageAPIUnauthorizedException, BackstageAPIConnectivityException, BackstageAPIRequestException;

}