Documentation
¶
Overview ¶
Package sts provides access to the Security Token Service API.
For product documentation, see: http://cloud.google.com/iam/docs/workload-identity-federation
Creating a client ¶
Usage example:
import "google.golang.org/api/sts/v1" ... ctx := context.Background() stsService, err := sts.NewService(ctx)
In this example, Google Application Default Credentials are used for authentication.
For information on how to create and obtain Application Default Credentials, see https://developers.google.com/identity/protocols/application-default-credentials.
Other authentication options ¶
To use an API key for authentication (note: some APIs do not support API keys), use option.WithAPIKey:
stsService, err := sts.NewService(ctx, option.WithAPIKey("AIza..."))
To use an OAuth token (e.g., a user token obtained via a three-legged OAuth flow), use option.WithTokenSource:
config := &oauth2.Config{...}
// ...
token, err := config.Exchange(ctx, ...)
stsService, err := sts.NewService(ctx, option.WithTokenSource(config.TokenSource(ctx, token)))
See https://godoc.org/google.golang.org/api/option/ for details on options.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type GoogleIdentityStsV1ExchangeTokenRequest ¶
type GoogleIdentityStsV1ExchangeTokenRequest struct {
// Audience: The full resource name of the identity provider; for
// example:
// `//iam.googleapis.com/projects//workloadIdentityPools//providers/`.
// Required when exchanging an external credential for a Google access
// token.
Audience string `json:"audience,omitempty"`
// GrantType: Required. The grant type. Must be
// `urn:ietf:params:oauth:grant-type:token-exchange`, which indicates a
// token exchange.
GrantType string `json:"grantType,omitempty"`
// Options: A set of features that Security Token Service supports, in
// addition to the standard OAuth 2.0 token exchange, formatted as a
// serialized JSON object of Options.
Options string `json:"options,omitempty"`
// RequestedTokenType: Required. An identifier for the type of requested
// security token. Must be
// `urn:ietf:params:oauth:token-type:access_token`.
RequestedTokenType string `json:"requestedTokenType,omitempty"`
// Scope: The OAuth 2.0 scopes to include on the resulting access token,
// formatted as a list of space-delimited, case-sensitive strings.
// Required when exchanging an external credential for a Google access
// token.
Scope string `json:"scope,omitempty"`
// SubjectToken: Required. The input token. This token is a either an
// external credential issued by a workload identity pool provider, or a
// short-lived access token issued by Google. If the token is an OIDC
// JWT, it must use the JWT format defined in RFC 7523
// (https://tools.ietf.org/html/rfc7523), and the `subject_token_type`
// must be `urn:ietf:params:oauth:token-type:jwt`. The following headers
// are required: - `kid`: The identifier of the signing key securing the
// JWT. - `alg`: The cryptographic algorithm securing the JWT. Must be
// `RS256` or `ES256`. The following payload fields are required. For
// more information, see RFC 7523, Section 3
// (https://tools.ietf.org/html/rfc7523#section-3): - `iss`: The issuer
// of the token. The issuer must provide a discovery document at the URL
// `/.well-known/openid-configuration`, where “ is the value of this
// field. The document must be formatted according to section 4.2 of the
// OIDC 1.0 Discovery specification
// (https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse).
// - `iat`: The issue time, in seconds, since the Unix epoch. Must be in
// the past. - `exp`: The expiration time, in seconds, since the Unix
// epoch. Must be less than 48 hours after `iat`. Shorter expiration
// times are more secure. If possible, we recommend setting an
// expiration time less than 6 hours. - `sub`: The identity asserted in
// the JWT. - `aud`: For workload identity pools, this must be a value
// specified in the allowed audiences for the workload identity pool
// provider, or one of the audiences allowed by default if no audiences
// were specified. See
// https://cloud.google.com/iam/docs/reference/rest/v1/projects.locations.workloadIdentityPools.providers#oidc
// Example header: “` { "alg": "RS256", "kid": "us-east-11" } “`
// Example payload: “` { "iss": "https://accounts.google.com", "iat":
// 1517963104, "exp": 1517966704, "aud":
// "//iam.googleapis.com/projects/1234567890123/locations/global/workload
// IdentityPools/my-pool/providers/my-provider", "sub":
// "113475438248934895348", "my_claims": { "additional_claim": "value" }
// } “` If `subject_token` is for AWS, it must be a serialized
// `GetCallerIdentity` token. This token contains the same information
// as a request to the AWS `GetCallerIdentity()`
// (https://docs.aws.amazon.com/STS/latest/APIReference/API_GetCallerIdentity)
// method, as well as the AWS signature
// (https://docs.aws.amazon.com/general/latest/gr/signing_aws_api_requests.html)
// for the request information. Use Signature Version 4. Format the
// request as URL-encoded JSON, and set the `subject_token_type`
// parameter to `urn:ietf:params:aws:token-type:aws4_request`. The
// following parameters are required: - `url`: The URL of the AWS STS
// endpoint for `GetCallerIdentity()`, such as
// `https://sts.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15
// `. Regional endpoints are also supported. - `method`: The HTTP
// request method: `POST`. - `headers`: The HTTP request headers, which
// must include: - `Authorization`: The request signature. -
// `x-amz-date`: The time you will send the request, formatted as an
// ISO8601 Basic
// (https://docs.aws.amazon.com/general/latest/gr/sigv4_elements.html#sigv4_elements_date)
// string. This value is typically set to the current time and is used
// to help prevent replay attacks. - `host`: The hostname of the `url`
// field; for example, `sts.amazonaws.com`. -
// `x-goog-cloud-target-resource`: The full, canonical resource name of
// the workload identity pool provider, with or without an `https:`
// prefix. To help ensure data integrity, we recommend including this
// header in the `SignedHeaders` field of the signed request. For
// example:
// //iam.googleapis.com/projects//locations//workloadIdentityPools//provi
// ders/
// https://iam.googleapis.com/projects//locations//workloadIdentityPools//providers/
// If you are using temporary security credentials provided by AWS, you
// must also include the header `x-amz-security-token`, with the value
// set to the session token. The following example shows a
// `GetCallerIdentity` token: “` { "headers": [ {"key": "x-amz-date",
// "value": "20200815T015049Z"}, {"key": "Authorization", "value":
// "AWS4-HMAC-SHA256+Credential=$credential,+SignedHeaders=host;x-amz-dat
// e;x-goog-cloud-target-resource,+Signature=$signature"}, {"key":
// "x-goog-cloud-target-resource", "value":
// "//iam.googleapis.com/projects//locations//workloadIdentityPools//prov
// iders/"}, {"key": "host", "value": "sts.amazonaws.com"} . ],
// "method": "POST", "url":
// "https://sts.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15
// " } “` You can also use a Google-issued OAuth 2.0 access token with
// this field to obtain an access token with new security attributes
// applied, such as a Credential Access Boundary. In this case, set
// `subject_token_type` to
// `urn:ietf:params:oauth:token-type:access_token`. If an access token
// already contains security attributes, you cannot apply additional
// security attributes.
SubjectToken string `json:"subjectToken,omitempty"`
// SubjectTokenType: Required. An identifier that indicates the type of
// the security token in the `subject_token` parameter. Supported values
// are `urn:ietf:params:oauth:token-type:jwt`,
// `urn:ietf:params:aws:token-type:aws4_request`, and
// `urn:ietf:params:oauth:token-type:access_token`.
SubjectTokenType string `json:"subjectTokenType,omitempty"`
// ForceSendFields is a list of field names (e.g. "Audience") to
// unconditionally include in API requests. By default, fields with
// empty values are omitted from API requests. However, any non-pointer,
// non-interface field appearing in ForceSendFields will be sent to the
// server regardless of whether the field is empty or not. This may be
// used to include empty fields in Patch requests.
ForceSendFields []string `json:"-"`
// NullFields is a list of field names (e.g. "Audience") to include in
// API requests with the JSON null value. By default, fields with empty
// values are omitted from API requests. However, any field with an
// empty value appearing in NullFields will be sent to the server as
// null. It is an error if a field in this list has a non-empty value.
// This may be used to include null fields in Patch requests.
NullFields []string `json:"-"`
}
GoogleIdentityStsV1ExchangeTokenRequest: Request message for ExchangeToken.
func (*GoogleIdentityStsV1ExchangeTokenRequest) MarshalJSON ¶
func (s *GoogleIdentityStsV1ExchangeTokenRequest) MarshalJSON() ([]byte, error)
type GoogleIdentityStsV1ExchangeTokenResponse ¶
type GoogleIdentityStsV1ExchangeTokenResponse struct {
// AccessToken: An OAuth 2.0 security token, issued by Google, in
// response to the token exchange request. Tokens can vary in size,
// depending in part on the size of mapped claims, up to a maximum of
// 12288 bytes (12 KB). Google reserves the right to change the token
// size and the maximum length at any time.
AccessToken string `json:"access_token,omitempty"`
// ExpiresIn: The amount of time, in seconds, between the time when the
// access token was issued and the time when the access token will
// expire. This field is absent when the `subject_token` in the request
// is a Google-issued, short-lived access token. In this case, the
// access token has the same expiration time as the `subject_token`.
ExpiresIn int64 `json:"expires_in,omitempty"`
// IssuedTokenType: The token type. Always matches the value of
// `requested_token_type` from the request.
IssuedTokenType string `json:"issued_token_type,omitempty"`
// TokenType: The type of access token. Always has the value `Bearer`.
TokenType string `json:"token_type,omitempty"`
// ServerResponse contains the HTTP response code and headers from the
// server.
googleapi.ServerResponse `json:"-"`
// ForceSendFields is a list of field names (e.g. "AccessToken") to
// unconditionally include in API requests. By default, fields with
// empty values are omitted from API requests. However, any non-pointer,
// non-interface field appearing in ForceSendFields will be sent to the
// server regardless of whether the field is empty or not. This may be
// used to include empty fields in Patch requests.
ForceSendFields []string `json:"-"`
// NullFields is a list of field names (e.g. "AccessToken") to include
// in API requests with the JSON null value. By default, fields with
// empty values are omitted from API requests. However, any field with
// an empty value appearing in NullFields will be sent to the server as
// null. It is an error if a field in this list has a non-empty value.
// This may be used to include null fields in Patch requests.
NullFields []string `json:"-"`
}
GoogleIdentityStsV1ExchangeTokenResponse: Response message for ExchangeToken.
func (*GoogleIdentityStsV1ExchangeTokenResponse) MarshalJSON ¶
func (s *GoogleIdentityStsV1ExchangeTokenResponse) MarshalJSON() ([]byte, error)
type Service ¶
type Service struct {
BasePath string // API endpoint base URL
UserAgent string // optional additional User-Agent fragment
V1 *V1Service
// contains filtered or unexported fields
}
func New
deprecated
New creates a new Service. It uses the provided http.Client for requests.
Deprecated: please use NewService instead. To provide a custom HTTP client, use option.WithHTTPClient. If you are using google.golang.org/api/googleapis/transport.APIKey, use option.WithAPIKey with NewService instead.
func NewService ¶
NewService creates a new Service.
type V1Service ¶
type V1Service struct {
// contains filtered or unexported fields
}
func NewV1Service ¶
func (*V1Service) Token ¶
func (r *V1Service) Token(googleidentitystsv1exchangetokenrequest *GoogleIdentityStsV1ExchangeTokenRequest) *V1TokenCall
Token: Exchanges a credential for a Google OAuth 2.0 access token. The token asserts an external identity within a workload identity pool, or it applies a Credential Access Boundary to a Google access token. When you call this method, do not send the `Authorization` HTTP header in the request. This method does not require the `Authorization` header, and using the header can cause the request to fail.
type V1TokenCall ¶
type V1TokenCall struct {
// contains filtered or unexported fields
}
func (*V1TokenCall) Context ¶
func (c *V1TokenCall) Context(ctx context.Context) *V1TokenCall
Context sets the context to be used in this call's Do method. Any pending HTTP request will be aborted if the provided context is canceled.
func (*V1TokenCall) Do ¶
func (c *V1TokenCall) Do(opts ...googleapi.CallOption) (*GoogleIdentityStsV1ExchangeTokenResponse, error)
Do executes the "sts.token" call. Exactly one of *GoogleIdentityStsV1ExchangeTokenResponse or error will be non-nil. Any non-2xx status code is an error. Response headers are in either *GoogleIdentityStsV1ExchangeTokenResponse.ServerResponse.Header or (if a response was returned at all) in error.(*googleapi.Error).Header. Use googleapi.IsNotModified to check whether the returned error was because http.StatusNotModified was returned.
func (*V1TokenCall) Fields ¶
func (c *V1TokenCall) Fields(s ...googleapi.Field) *V1TokenCall
Fields allows partial responses to be retrieved. See https://developers.google.com/gdata/docs/2.0/basics#PartialResponse for more information.
func (*V1TokenCall) Header ¶
func (c *V1TokenCall) Header() http.Header
Header returns an http.Header that can be modified by the caller to add HTTP headers to the request.
Source Files
Click to show internal directories.
Click to hide internal directories.