Documentation
¶
Overview ¶
Package idtoken provides utilities for creating authenticated transports with ID Tokens for Google HTTP APIs. It also provides methods to validate Google issued ID tokens.
Index ¶
- Constants
- func NewClient(ctx context.Context, audience string, opts ...ClientOption) (*http.Client, error)
- func NewTokenSource(ctx context.Context, audience string, opts ...ClientOption) (oauth2.TokenSource, error)
- type ClientOption
- func WithAuthCredentialsFile(credType CredentialsType, filename string) ClientOption
- func WithAuthCredentialsJSON(credType CredentialsType, json []byte) ClientOption
- func WithCredentialsFile(filename string) ClientOptiondeprecated
- func WithCredentialsJSON(p []byte) ClientOptiondeprecated
- func WithCustomClaims(customClaims map[string]interface{}) ClientOption
- func WithHTTPClient(client *http.Client) ClientOption
- type CredentialsType
- type Payload
- type Validator
Examples ¶
Constants ¶
const ( // ServiceAccount represents a service account file type. ServiceAccount = credentialstype.ServiceAccount // AuthorizedUser represents an authorized user credentials file type. AuthorizedUser = credentialstype.AuthorizedUser // ImpersonatedServiceAccount represents an impersonated service account file type. // // IMPORTANT: // This credential type does not validate the credential configuration. A security // risk occurs when a credential configuration configured with malicious urls // is used. // You should validate credential configurations provided by untrusted sources. // See [Security requirements when using credential configurations from an external // source] https://cloud.google.com/docs/authentication/external/externally-sourced-credentials // for more details. ImpersonatedServiceAccount = credentialstype.ImpersonatedServiceAccount // ExternalAccount represents an external account file type. // // IMPORTANT: // This credential type does not validate the credential configuration. A security // risk occurs when a credential configuration configured with malicious urls // is used. // You should validate credential configurations provided by untrusted sources. // See [Security requirements when using credential configurations from an external // source] https://cloud.google.com/docs/authentication/external/externally-sourced-credentials // for more details. ExternalAccount = credentialstype.ExternalAccount )
Variables ¶
This section is empty.
Functions ¶
func NewClient ¶
NewClient creates a HTTP Client that automatically adds an ID token to each request via an Authorization header. The token will have the audience provided and be configured with the supplied options. The parameter audience may not be empty.
func NewTokenSource ¶
func NewTokenSource(ctx context.Context, audience string, opts ...ClientOption) (oauth2.TokenSource, error)
NewTokenSource creates a TokenSource that returns ID tokens with the audience provided and configured with the supplied options. The parameter audience may not be empty.
Example (SetAuthorizationHeader) ¶
package main
import (
"context"
"net/http"
"google.golang.org/api/idtoken"
)
func main() {
ctx := context.Background()
audience := "http://example.com"
ts, err := idtoken.NewTokenSource(ctx, audience)
if err != nil {
// TODO: Handle error.
}
token, err := ts.Token()
if err != nil {
// TODO: Handle error.
}
req, err := http.NewRequest(http.MethodGet, audience, nil)
if err != nil {
// TODO: Handle error.
}
token.SetAuthHeader(req)
}
Types ¶
type ClientOption ¶
type ClientOption = option.ClientOption
ClientOption is for configuring a Google API client or transport.
func WithAuthCredentialsFile ¶ added in v0.258.0
func WithAuthCredentialsFile(credType CredentialsType, filename string) ClientOption
WithAuthCredentialsFile returns a ClientOption that authenticates API calls with the given JSON credentials file and credential type.
Important: If you accept a credential configuration (credential JSON/File/Stream) from an external source for authentication to Google Cloud Platform, you must validate it before providing it to any Google API or library. Providing an unvalidated credential configuration to Google APIs can compromise the security of your systems and data. For more information, refer to [Validate credential configurations from external sources](https://cloud.google.com/docs/authentication/external/externally-sourced-credentials).
func WithAuthCredentialsJSON ¶ added in v0.258.0
func WithAuthCredentialsJSON(credType CredentialsType, json []byte) ClientOption
WithAuthCredentialsJSON returns a ClientOption that authenticates API calls with the given JSON credentials and credential type.
Important: If you accept a credential configuration (credential JSON/File/Stream) from an external source for authentication to Google Cloud Platform, you must validate it before providing it to any Google API or library. Providing an unvalidated credential configuration to Google APIs can compromise the security of your systems and data. For more information, refer to [Validate credential configurations from external sources](https://cloud.google.com/docs/authentication/external/externally-sourced-credentials).
func WithCredentialsFile
deprecated
func WithCredentialsFile(filename string) ClientOption
WithCredentialsFile returns a ClientOption that authenticates API calls with the given service account or refresh token JSON credentials file.
Deprecated: This function is being deprecated because of a potential security risk.
This function does not validate the credential configuration. The security risk occurs when a credential configuration is accepted from a source that is not under your control and used without validation on your side.
If you know that you will be loading credential configurations of a specific type, it is recommended to use a credential-type-specific option function. This will ensure that an unexpected credential type with potential for malicious intent is not loaded unintentionally. You might still have to do validation for certain credential types. Please follow the recommendation for that function. For example, if you want to load only service accounts, you can use WithAuthCredentialsFile with ServiceAccount:
option.WithAuthCredentialsFile(option.ServiceAccount, "/path/to/file.json")
If you are loading your credential configuration from an untrusted source and have not mitigated the risks (e.g. by validating the configuration yourself), make these changes as soon as possible to prevent security risks to your environment.
Regardless of the function used, it is always your responsibility to validate configurations received from external sources.
func WithCredentialsJSON
deprecated
func WithCredentialsJSON(p []byte) ClientOption
WithCredentialsJSON returns a ClientOption that authenticates API calls with the given service account or refresh token JSON credentials.
Deprecated: This function is being deprecated because of a potential security risk.
This function does not validate the credential configuration. The security risk occurs when a credential configuration is accepted from a source that is not under your control and used without validation on your side.
If you know that you will be loading credential configurations of a specific type, it is recommended to use a credential-type-specific option function. This will ensure that an unexpected credential type with potential for malicious intent is not loaded unintentionally. You might still have to do validation for certain credential types. Please follow the recommendation for that function. For example, if you want to load only service accounts, you can use WithAuthCredentialsJSON with ServiceAccount:
option.WithAuthCredentialsJSON(option.ServiceAccount, json)
If you are loading your credential configuration from an untrusted source and have not mitigated the risks (e.g. by validating the configuration yourself), make these changes as soon as possible to prevent security risks to your environment.
Regardless of the function used, it is always your responsibility to validate configurations received from external sources.
func WithCustomClaims ¶
func WithCustomClaims(customClaims map[string]interface{}) ClientOption
WithCustomClaims optionally specifies custom private claims for an ID token.
func WithHTTPClient ¶
func WithHTTPClient(client *http.Client) ClientOption
WithHTTPClient returns a ClientOption that specifies the HTTP client to use as the basis of communications. This option may only be used with services that support HTTP as their communication transport. When used, the WithHTTPClient option takes precedent over all other supplied options.
type CredentialsType ¶ added in v0.258.0
type CredentialsType = credentialstype.CredType
CredentialsType specifies the type of JSON credentials being provided to a loading function such as WithAuthCredentialsFile or WithAuthCredentialsJSON.
type Payload ¶
type Payload struct {
Issuer string `json:"iss"`
Audience string `json:"aud"`
Expires int64 `json:"exp"`
IssuedAt int64 `json:"iat"`
Subject string `json:"sub,omitempty"`
Claims map[string]interface{} `json:"-"`
}
Payload represents a decoded payload of an ID Token.
func ParsePayload ¶ added in v0.141.0
ParsePayload parses the given token and returns its payload.
Warning: This function does not validate the token prior to parsing it.
ParsePayload is primarily meant to be used to inspect a token's payload. This is useful when validation fails and the payload needs to be inspected.
Note: A successful Validate() invocation with the same token will return an identical payload.
type Validator ¶
type Validator struct {
// contains filtered or unexported fields
}
Validator provides a way to validate Google ID Tokens with a user provided http.Client.
func NewValidator ¶
func NewValidator(ctx context.Context, opts ...ClientOption) (*Validator, error)
NewValidator creates a Validator that uses the options provided to configure a the internal http.Client that will be used to make requests to fetch JWKs.
func (*Validator) Validate ¶
func (v *Validator) Validate(ctx context.Context, idToken string, audience string) (*Payload, error)
Validate is used to validate the provided idToken with a known Google cert URL. If audience is not empty the audience claim of the Token is validated. Upon successful validation a parsed token Payload is returned allowing the caller to validate any additional claims.
Source Files