Package com.google.jenkins.plugins.credentials.oauth

This package implements Jenkins plugins providing Google-specific OAuth2 Credentials, Domain Requirements and Specifications.

For OAuth2, these are inherently a provider-specific triple because each provider (e.g. Google, Facebook, GitHub) may only provide tokens for their own credentials and scopes. In a nutshell, an OAuth2 access token is like "limited power of attorney". You are giving the bearer of that token permission to interact with the set of limited scopes as the user who provided it.

This package provides the following Google-specific triple: 

  1. GoogleOAuth2ScopeRequirement
  extends OAuth2ScopeRequirement
  extends DomainRequirement
  2. GoogleOAuth2ScopeSpecification
  extends OAuth2ScopeSpecification<GoogleOAuth2ScopeRequirement>
  extends DomainSpecification
  3. GoogleOAuth2Credentials
  extends OAuth2Credentials<GoogleOAuth2ScopeRequirement>
  extends Credentials

As the set of scopes determine what you may do with a credential, each plugin asks for an access token by providing a provider-specific OAuth2ScopeRequirement to OAuth2Credentials.getAccessToken(OAuth2ScopeRequirement).

When enumerating credentials suitable for use with a given plugin, we only want to show those that allow a suitable set of scopes. This is where OAuth2ScopeRequirement pairs with OAuth2ScopeSpecification. An OAuth2ScopeSpecification is attached to a Domain and is the superset of scopes to which the contained Credentials may be applied.

However, since entering OAuth2 scopes is unwieldy, we provide the necessary concepts to make it multiple choice. Enter DomainRequirementProvider, a new ExtensionPoint that allows OAuth2ScopeSpecification to automatically discover the set of OAuth2 scopes required by installed plugins.

For Example:

 @RequiredDomain(value = MyGoogleOAuth2Requirement.class)
 public class Foo extends SomeDescribable
In this example, the DescribableDomainRequirementProvider would discover that Foo required the set of scopes specified by MyGoogleOAuth2Requirement. These would be aggregated with any other required scopes and presented in the UI for any OAuth2ScopeSpecification whose type parameter is a super-type of MyGoogleOAuth2Requirement.

So for instance if MyGoogleOAuth2Requirement extends GoogleOAuth2ScopeRequirement then GoogleOAuth2ScopeSpecification, which extends OAuth2ScopeSpecification<GoogleOAuth2ScopeRequirement>, would have MyGoogleOAuth2Requirement's scopes appear in its UI.

This package provides two types of GoogleOAuth2Credentials:

  • GoogleRobotMetadataCredentials: a robot credential that utilizes the Google Compute Engine "metadata" service attached to a virtual machine for providing access tokens.
  • GoogleRobotPrivateKeyCredentials: a robot credential that retrieves access tokens for a robot account using its client_secrets.json and private key file.