# Security Token Service API . v1beta

## Instance Methods

Close httplib2 connections.

Exchanges a credential for a Google OAuth 2.0 access token. The token asserts an external identity within a WorkloadIdentityPool, or applies an Access Boundary on a Google access token.

### Method Details

`close()`

    Close httplib2 connections.

`token(body=None, x__xgafv=None)`

    Exchanges a credential for a Google OAuth 2.0 access token. The token asserts an external identity within a WorkloadIdentityPool, or applies an Access Boundary on a Google access token.

    Args:
      body: object, The request body.
        The object takes the form of:

    { # Request message for ExchangeToken.
        "requestedTokenType": "A String", # Required. An identifier for the type of requested security token. Must be `urn:ietf:params:oauth:token-type:access_token`.
        "audience": "A String", # The full resource name of the identity provider; for example: `https://iam.googleapis.com/projects/{PROJECT_ID}/workloadIdentityPools/{POOL_ID}/providers/{PROVIDER_ID}`. Required when exchanging an external credential for a Google access token.
        "options": "A String", # 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.
        "subjectTokenType": "A String", # 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`.
        "scope": "A String", # 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.
        "subjectToken": "A String", # Required. The input token. This is a either an external credential issued by a WorkloadIdentityPoolProvider, 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 `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`. 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 `/.well-known/openid-configuration`, 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 epoch. Must be in the past. - **`exp`**: The expiration time, in seconds, since epoch. Must be fewer than 48 hours after `iat`. Shorter expiration times are more. secure. If possible, we recommend setting an expiration time fewer than 6 hours. - **`sub`**: The identity asserted in the JWT. - **`aud`**: Configured by the mapper policy. The default value is the service account's unique ID. Example header: ``` { "alg": "RS256", "kid": "us-east-11" } ``` Example payload: ``` { "iss": "https://accounts.google.com", "iat": 1517963104, "exp": 1517966704, "aud": "113475438248934895348", "sub": "113475438248934895348", "my_claims": { "additional_claim": "value" } } ``` If `subject_token` is an AWS token, it must be a serialized, [signed](https://docs.aws.amazon.com/general/latest/gr/signing_aws_api_requests.html) request to the AWS [`GetCallerIdentity()`](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetCallerIdentity) method. 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 is typically set to the current time, and used to 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 WorkloadIdentityPoolProvider, with or without the HTTPS prefix. For example: ``` //iam.googleapis.com/projects//locations//workloadIdentityPools//providers/ https://iam.googleapis.com/projects//locations//workloadIdentityPools//providers/ ``` Signing this header as part of the signature is recommended to ensure data integrity. If you are using temporary security credentials provided by AWS, you must also include the header `x-amz-security-token`, with the value `[SESSION_TOKEN]`. The following is an example of a signed, serialized request: ``` { "headers":[ {"key": "x-amz-date", "value": "20200815T015049Z"}, {"key": "Authorization", "value": "AWS4-HMAC-SHA256+Credential=$credential,+SignedHeaders=host;x-amz-date;x-goog-cloud-target-resource,+Signature=$signature"}, {"key": "x-goog-cloud-target-resource", "value": "//iam.googleapis.com/projects//locations//workloadIdentityPools//providers/"}, {"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 an AccessBoundary. In this case, set `subject_token_type` to `urn:ietf:params:oauth:token-type:access_token`. Applying additional security attributes on access tokens that already contain security attributes is not allowed.
        "grantType": "A String", # Required. The grant type. Must be `urn:ietf:params:oauth:grant-type:token-exchange`, which indicates a token exchange is requested.
      }

      x__xgafv: string, V1 error format.
        Allowed values
          1 - v1 error format
          2 - v2 error format

    Returns:
      An object of the form:

        { # Response message for ExchangeToken.
        "token_type": "A String", # The type of `access_token`. Always has the value `Bearer`.
        "expires_in": 42, # The expiration time of `access_token`, in seconds, from the time of issuance. This field is absent when the `subject_token` in the request is a Google-issued, short-lived access token. In this case, the expiration time of the `access_token` is the same as the `subject_token`.
        "access_token": "A String", # An OAuth 2.0 security token, issued by Google, in response to the token exchange request. Tokens can vary in size (mainly depending on the size of mapped claims), currently up to the 12288 bytes (12 KB) size limit. Google reserves the right to change token size, including increasing these limits. Your application must support variable token sizes accordingly.
        "issued_token_type": "A String", # The token type. Always matches the value of `requested_token_type` from the request.
      }