com.sap.cloud.yaas.servicesdk.authorization.AccessTokenProvider Maven / Gradle / Ivy
/*
* © 2016 SAP SE or an SAP affiliate company.
* All rights reserved.
* Please see http://www.sap.com/corporate-en/legal/copyright/index.epx for additional trademark information and
* notices.
*/
package com.sap.cloud.yaas.servicesdk.authorization;
/**
* Responsible for acquiring and managing OAuth 2.0 {@link AccessToken}s.
*
* {@code AccessToken}s can be used to authorize subsequent requests to Resource Servers, e.g. backing YaaS
* service.
*/
public interface AccessTokenProvider
{
/**
* Checks whether this {@link AccessTokenProvider} is enabled and can be used to acquire {@link AccessToken}s.
*
* Other methods of this interface should only be invoked, if this method returns {@code true}.
*
* @return {@code true}, if authorization is enabled, otherwise {@code false}
*/
boolean isEnabled();
/**
* Acquires (or reuses, if possible) an {@code AccessToken} for the given parameters.
*
* @param scope the scope that the returned {@code AccessToken} should satisfy
* (including the YaaS tenant it is intended for)
* @param diagnosticContext optional diagnostic data that implementations that do requests to other YaaS services
* should pass through. when the {@code AccessTokenProvider} is used from within a YaaS service, it should
* pass a {@code DiagnosticContext} based on the respective HTTP headers of the request that is currently
* being processed. Other clients may pass {@code null}.
* @return the acquired token, never {@code null}
* @throws AccessTokenRequestException when no suitable token could be acquired
* @throws IllegalStateException when {@link #isEnabled()} would return {@code false}, or the implementation is not
* configured correctly
*/
AccessToken acquireToken(final AuthorizationScope scope, final DiagnosticContext diagnosticContext)
throws AccessTokenRequestException;
/**
* Explicitly invalidates an access token.
*
* Clients should call this method when an {@code AccessToken} has been rejected by a Resource Server (e.g.
* a backing YaaS service) and requires a renewal. This is necessary to support implementations that perform caching.
*
* @param token the token to invalidate
*/
void invalidateToken(final AccessToken token);
}