diff --git a/oauth2_http/java/com/google/auth/oauth2/CredentialAccessBoundary.java b/oauth2_http/java/com/google/auth/oauth2/CredentialAccessBoundary.java index 92cacc258..be74d2747 100644 --- a/oauth2_http/java/com/google/auth/oauth2/CredentialAccessBoundary.java +++ b/oauth2_http/java/com/google/auth/oauth2/CredentialAccessBoundary.java @@ -120,6 +120,9 @@ private Builder() {} * Sets the list of {@link AccessBoundaryRule}'s. * *

This list must not exceed 10 rules. + * + * @param rule the collection of rules to be set, should not be null + * @return this {@code Builder} object */ public Builder setRules(List rule) { accessBoundaryRules = new ArrayList<>(checkNotNull(rule)); @@ -211,6 +214,9 @@ private Builder() {} * access to. * *

For example: "//storage.googleapis.com/projects/_/buckets/example". + * + * @param availableResource the resource name to set + * @return this {@code Builder} object */ public Builder setAvailableResource(String availableResource) { this.availableResource = availableResource; @@ -222,6 +228,9 @@ public Builder setAvailableResource(String availableResource) { * roles prefixed by inRole. * *

For example: {"inRole:roles/storage.objectViewer"}. + * + * @param availablePermissions the collection of permissions to set, should not be null + * @return this {@code Builder} object */ public Builder setAvailablePermissions(List availablePermissions) { this.availablePermissions = new ArrayList<>(checkNotNull(availablePermissions)); @@ -233,6 +242,9 @@ public Builder setAvailablePermissions(List availablePermissions) { * inRole. * *

For example: "inRole:roles/storage.objectViewer". + * + * @param availablePermission a permission to add, should not be null + * @return this {@code Builder} object */ public Builder addAvailablePermission(String availablePermission) { if (availablePermissions == null) { @@ -245,6 +257,9 @@ public Builder addAvailablePermission(String availablePermission) { /** * Sets the availability condition which is an IAM condition that defines constraints to apply * to the token expressed in CEL format. + * + * @param availabilityCondition the {@code AvailabilityCondition} to set + * @return this {@code Builder} object */ public Builder setAvailabilityCondition(AvailabilityCondition availabilityCondition) { this.availabilityCondition = availabilityCondition; @@ -318,19 +333,32 @@ private Builder() {} *

This expression specifies the Cloud Storage object where permissions are available. * See for more * information. + * + * @param expression the expression to set + * @return this {@code Builder} object */ public Builder setExpression(String expression) { this.expression = expression; return this; } - /** Sets the optional title that identifies the purpose of the condition. */ + /** + * Sets the optional title that identifies the purpose of the condition. + * + * @param title the title to set + * @return this {@code Builder} object + */ public Builder setTitle(String title) { this.title = title; return this; } - /** Sets the description that details the purpose of the condition. */ + /** + * Sets the description that details the purpose of the condition. + * + * @param description the description to set + * @return this {@code Builder} object + */ public Builder setDescription(String description) { this.description = description; return this; diff --git a/oauth2_http/java/com/google/auth/oauth2/ExternalAccountCredentials.java b/oauth2_http/java/com/google/auth/oauth2/ExternalAccountCredentials.java index d08bd132e..447b6eb91 100644 --- a/oauth2_http/java/com/google/auth/oauth2/ExternalAccountCredentials.java +++ b/oauth2_http/java/com/google/auth/oauth2/ExternalAccountCredentials.java @@ -159,9 +159,25 @@ protected ExternalAccountCredentials( } /** - * See {@link ExternalAccountCredentials#ExternalAccountCredentials(HttpTransportFactory, String, - * String, String, CredentialSource, String, String, String, String, String, Collection)} + * Constructor with minimum identifying information and custom HTTP transport. Does not support + * workforce credentials. * + * @param transportFactory HTTP transport factory, creates the transport used to get access tokens + * @param audience the Security Token Service audience, which is usually the fully specified + * resource name of the workload/workforce pool provider + * @param subjectTokenType the Security Token Service subject token type based on the OAuth 2.0 + * token exchange spec. Indicates the type of the security token in the credential file + * @param tokenUrl the Security Token Service token exchange endpoint + * @param tokenInfoUrl the endpoint used to retrieve account related information. Required for + * gCloud session account identification. + * @param credentialSource the external credential source + * @param serviceAccountImpersonationUrl the URL for the service account impersonation request. + * This URL is required for some APIs. If this URL is not available, the access token from the + * Security Token Service is used directly. May be null. + * @param quotaProjectId the project used for quota and billing purposes. May be null. + * @param clientId client ID of the service account from the console. May be null. + * @param clientSecret client secret of the service account from the console. May be null. + * @param scopes the scopes to request during the authorization grant. May be null. * @param environmentProvider the environment provider. May be null. Defaults to {@link * SystemEnvironmentProvider}. */ @@ -211,6 +227,8 @@ protected ExternalAccountCredentials( /** * Internal constructor with minimum identifying information and custom HTTP transport. See {@link * ExternalAccountCredentials.Builder}. + * + * @param builder the {@code Builder} object used to construct the credentials. */ protected ExternalAccountCredentials(ExternalAccountCredentials.Builder builder) { this.transportFactory = @@ -494,6 +512,7 @@ protected AccessToken exchangeExternalCredentialForAccessToken( * source. * * @return the external subject token + * @throws IOException if the subject token cannot be retrieved */ public abstract String retrieveSubjectToken() throws IOException; @@ -522,7 +541,7 @@ public String getServiceAccountImpersonationUrl() { return serviceAccountImpersonationUrl; } - /** The service account email to be impersonated, if available. */ + /** @return The service account email to be impersonated, if available */ @Nullable public String getServiceAccountEmail() { if (serviceAccountImpersonationUrl == null || serviceAccountImpersonationUrl.isEmpty()) { @@ -567,8 +586,8 @@ EnvironmentProvider getEnvironmentProvider() { } /** - * Returns whether the current configuration is for Workforce Pools (which enable 3p user - * identities, rather than workloads). + * @return whether the current configuration is for Workforce Pools (which enable 3p user + * identities, rather than workloads) */ public boolean isWorkforcePoolConfiguration() { Pattern workforceAudiencePattern = @@ -728,7 +747,12 @@ protected Builder(ExternalAccountCredentials credentials) { this.serviceAccountImpersonationOptions = credentials.serviceAccountImpersonationOptions; } - /** Sets the HTTP transport factory, creates the transport used to get access tokens. */ + /** + * Sets the HTTP transport factory, creates the transport used to get access tokens. + * + * @param transportFactory the {@code HttpTransportFactory} to set + * @return this {@code Builder} object + */ public Builder setHttpTransportFactory(HttpTransportFactory transportFactory) { this.transportFactory = transportFactory; return this; @@ -737,6 +761,9 @@ public Builder setHttpTransportFactory(HttpTransportFactory transportFactory) { /** * Sets the Security Token Service audience, which is usually the fully specified resource name * of the workload/workforce pool provider. + * + * @param audience the Security Token Service audience to set + * @return this {@code Builder} object */ public Builder setAudience(String audience) { this.audience = audience; @@ -746,19 +773,32 @@ public Builder setAudience(String audience) { /** * Sets the Security Token Service subject token type based on the OAuth 2.0 token exchange * spec. Indicates the type of the security token in the credential file. + * + * @param subjectTokenType the Security Token Service subject token type to set + * @return this {@code Builder} object */ public Builder setSubjectTokenType(String subjectTokenType) { this.subjectTokenType = subjectTokenType; return this; } - /** Sets the Security Token Service token exchange endpoint. */ + /** + * Sets the Security Token Service token exchange endpoint. + * + * @param tokenUrl the Security Token Service token exchange url to set + * @return this {@code Builder} object + */ public Builder setTokenUrl(String tokenUrl) { this.tokenUrl = tokenUrl; return this; } - /** Sets the external credential source. */ + /** + * Sets the external credential source. + * + * @param credentialSource the {@code CredentialSource} to set + * @return this {@code Builder} object + */ public Builder setCredentialSource(CredentialSource credentialSource) { this.credentialSource = credentialSource; return this; @@ -768,6 +808,9 @@ public Builder setCredentialSource(CredentialSource credentialSource) { * Sets the optional URL used for service account impersonation, which is required for some * APIs. If this URL is not available, the access token from the Security Token Service is used * directly. + * + * @param serviceAccountImpersonationUrl the service account impersonation url to set + * @return this {@code Builder} object */ public Builder setServiceAccountImpersonationUrl(String serviceAccountImpersonationUrl) { this.serviceAccountImpersonationUrl = serviceAccountImpersonationUrl; @@ -777,31 +820,54 @@ public Builder setServiceAccountImpersonationUrl(String serviceAccountImpersonat /** * Sets the optional endpoint used to retrieve account related information. Required for gCloud * session account identification. + * + * @param tokenInfoUrl the token info url to set + * @return this {@code Builder} object */ public Builder setTokenInfoUrl(String tokenInfoUrl) { this.tokenInfoUrl = tokenInfoUrl; return this; } - /** Sets the optional project used for quota and billing purposes. */ + /** + * Sets the optional project used for quota and billing purposes. + * + * @param quotaProjectId the quota and billing project id to set + * @return this {@code Builder} object + */ public Builder setQuotaProjectId(String quotaProjectId) { this.quotaProjectId = quotaProjectId; return this; } - /** Sets the optional client ID of the service account from the console. */ + /** + * Sets the optional client ID of the service account from the console. + * + * @param clientId the service account client id to set + * @return this {@code Builder} object + */ public Builder setClientId(String clientId) { this.clientId = clientId; return this; } - /** Sets the optional client secret of the service account from the console. */ + /** + * Sets the optional client secret of the service account from the console. + * + * @param clientSecret the service account client secret to set + * @return this {@code Builder} object + */ public Builder setClientSecret(String clientSecret) { this.clientSecret = clientSecret; return this; } - /** Sets the optional scopes to request during the authorization grant. */ + /** + * Sets the optional scopes to request during the authorization grant. + * + * @param scopes the request scopes to set + * @return this {@code Builder} object + */ public Builder setScopes(Collection scopes) { this.scopes = scopes; return this; @@ -811,18 +877,32 @@ public Builder setScopes(Collection scopes) { * Sets the optional workforce pool user project number when the credential corresponds to a * workforce pool and not a workload identity pool. The underlying principal must still have * serviceusage.services.use IAM permission to use the project for billing/quota. + * + * @param workforcePoolUserProject the workforce pool user project number to set + * @return this {@code Builder} object */ public Builder setWorkforcePoolUserProject(String workforcePoolUserProject) { this.workforcePoolUserProject = workforcePoolUserProject; return this; } - /** Sets the optional service account impersonation options. */ + /** + * Sets the optional service account impersonation options. + * + * @param optionsMap the service account impersonation options to set + * @return this {@code Builder} object + */ public Builder setServiceAccountImpersonationOptions(Map optionsMap) { this.serviceAccountImpersonationOptions = new ServiceAccountImpersonationOptions(optionsMap); return this; } + /** + * Sets the optional Environment Provider. + * + * @param environmentProvider the {@code EnvironmentProvider} to set + * @return this {@code Builder} object + */ Builder setEnvironmentProvider(EnvironmentProvider environmentProvider) { this.environmentProvider = environmentProvider; return this; diff --git a/oauth2_http/java/com/google/auth/oauth2/PluggableAuthCredentials.java b/oauth2_http/java/com/google/auth/oauth2/PluggableAuthCredentials.java index 7fba136a4..0042dfdc2 100644 --- a/oauth2_http/java/com/google/auth/oauth2/PluggableAuthCredentials.java +++ b/oauth2_http/java/com/google/auth/oauth2/PluggableAuthCredentials.java @@ -84,17 +84,17 @@ * "code": "401", * "message": "Error message." * } + * * - *

The `expiration_time` field in the JSON response is only required for successful - * responses when an output file was specified in the credential configuration. + *

The `expiration_time` field in the JSON response is only required for successful responses + * when an output file was specified in the credential configuration. * - * The auth libraries will populate certain environment variables that will be accessible by the + *

The auth libraries will populate certain environment variables that will be accessible by the * executable, such as: GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE, GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE, * GOOGLE_EXTERNAL_ACCOUNT_INTERACTIVE, GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL, and * GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE. * *

Please see this repositories README for a complete executable request/response specification. - * */ public class PluggableAuthCredentials extends ExternalAccountCredentials {