iam

Documentation

Overview

Package iam implements wrappers around some Google Cloud IAM APIs.

See https://cloud.google.com/iam/docs/ for general info.

Index

• Constants
• Variables
• type ClaimSet
• type Client
  • func (cl *Client) GenerateAccessToken(ctx context.Context, serviceAccount string, scopes []string, ...) (*oauth2.Token, error)
  • func (cl *Client) GenerateIDToken(ctx context.Context, serviceAccount string, audience string, includeEmail bool, ...) (string, error)
  • func (cl *Client) GetIAMPolicy(ctx context.Context, resource string) (*Policy, error)
  • func (cl *Client) ModifyIAMPolicy(ctx context.Context, resource string, cb func(*Policy) error) error
  • func (cl *Client) SetIAMPolicy(ctx context.Context, resource string, p Policy) (*Policy, error)
  • func (cl *Client) SignBlob(ctx context.Context, serviceAccount string, blob []byte) (keyName string, signature []byte, err error)
  • func (cl *Client) SignJWT(ctx context.Context, serviceAccount string, cs *ClaimSet) (keyName, signedJwt string, err error)
• type Policy
  • func (p Policy) Clone() Policy
  • func (p Policy) Equals(another Policy) bool
  • func (p *Policy) GrantRole(role string, principals ...string)
  • func (p Policy) MarshalJSON() ([]byte, error)
  • func (p *Policy) RevokeRole(role string, principals ...string)
  • func (p *Policy) UnmarshalJSON(data []byte) error
• type PolicyBindings
  • func (b PolicyBindings) Clone() PolicyBindings
  • func (b PolicyBindings) Equals(another PolicyBindings) bool
  • func (b PolicyBindings) MarshalJSON() ([]byte, error)
  • func (b *PolicyBindings) UnmarshalJSON(data []byte) error
• type Signer
  • func (s *Signer) SignBytes(c context.Context, blob []byte) (string, []byte, error)

Constants

const (
	// OAuthScope is an OAuth scope required by IAM API.
	OAuthScope = "https://www.googleapis.com/auth/iam"
)

Variables

var (
	// DefaultIamBaseURL is IAM's core API endpoint.
	DefaultIamBaseURL = &url.URL{
		Scheme: "https",
		Host:   "iam.googleapis.com",
	}

	// DefaultAccountCredentialsBaseURL is IAM's account credentials API endpoint.
	DefaultAccountCredentialsBaseURL = &url.URL{
		Scheme: "https",
		Host:   "iamcredentials.googleapis.com",
	}
)

Types

type ClaimSet

type ClaimSet struct {
	Iss   string `json:"iss"`             // email address of the client_id of the application making the access token request
	Scope string `json:"scope,omitempty"` // space-delimited list of the permissions the application requests
	Aud   string `json:"aud"`             // descriptor of the intended target of the assertion (Optional).
	Exp   int64  `json:"exp"`             // the expiration time of the assertion (seconds since Unix epoch)
	Iat   int64  `json:"iat"`             // the time the assertion was issued (seconds since Unix epoch)
	Typ   string `json:"typ,omitempty"`   // token type (Optional).

	// Email for which the application is requesting delegated access (Optional).
	Sub string `json:"sub,omitempty"`
}

ClaimSet contains information about the JWT signature including the permissions being requested (scopes), the target of the token, the issuer, the time the token was issued, and the lifetime of the token.

See RFC 7515.

type Client

type Client struct {
	Client   *http.Client // client to use to make calls
	BasePath string       // replaceable in tests, DefaultIamBaseURL / DefaultAccountCredentials by default.
}

Client knows how to perform IAM API v1 calls.

func (*Client) GenerateAccessToken

func (cl *Client) GenerateAccessToken(ctx context.Context, serviceAccount string, scopes []string, delegates []string, lifetime time.Duration) (*oauth2.Token, error)

GenerateAccessToken creates a service account OAuth token using IAM's :generateAccessToken API.

On non-success HTTP status codes returns googleapi.Error.

func (*Client) GenerateIDToken

func (cl *Client) GenerateIDToken(ctx context.Context, serviceAccount string, audience string, includeEmail bool, delegates []string) (string, error)

GenerateIDToken creates a service account OpenID Connect ID token using IAM's :generateIdToken API.

On non-success HTTP status codes returns googleapi.Error.

func (*Client) GetIAMPolicy

func (cl *Client) GetIAMPolicy(ctx context.Context, resource string) (*Policy, error)

GetIAMPolicy fetches an IAM policy of a resource.

On non-success HTTP status codes returns googleapi.Error.

func (*Client) ModifyIAMPolicy

func (cl *Client) ModifyIAMPolicy(ctx context.Context, resource string, cb func(*Policy) error) error

ModifyIAMPolicy reads IAM policy, calls callback to modify it, and then puts it back (if callback really changed it).

Cast error to *googleapi.Error and compare http status to http.StatusConflict to detect update race conditions. It is usually safe to retry in case of a conflict.

func (*Client) SetIAMPolicy

func (cl *Client) SetIAMPolicy(ctx context.Context, resource string, p Policy) (*Policy, error)

SetIAMPolicy replaces an IAM policy of a resource.

Returns a new policy (with Etag field updated).

func (*Client) SignBlob

func (cl *Client) SignBlob(ctx context.Context, serviceAccount string, blob []byte) (keyName string, signature []byte, err error)

SignBlob signs a blob using a service account's system-managed key.

The caller must have "roles/iam.serviceAccountTokenCreator" role in the service account's IAM policy and caller's OAuth token must have one of the scopes:

• https://www.googleapis.com/auth/iam
• https://www.googleapis.com/auth/cloud-platform

Returns ID of the signing key and the signature on success.

On API-level errors (e.g. insufficient permissions) returns *googleapi.Error.

func (*Client) SignJWT

func (cl *Client) SignJWT(ctx context.Context, serviceAccount string, cs *ClaimSet) (keyName, signedJwt string, err error)

SignJWT signs a claim set using a service account's system-managed key.

It injects the key ID into the JWT header before singing. As a result, JWTs produced by SignJWT are slightly faster to verify, because we know what public key to use exactly and don't need to enumerate all active keys.

It also checks the expiration time and refuses to sign claim sets with 'exp' set to more than 1h from now. Otherwise it is similar to SignBlob.

The caller must have "roles/iam.serviceAccountTokenCreator" role in the service account's IAM policy and caller's OAuth token must have one of the scopes:

• https://www.googleapis.com/auth/iam
• https://www.googleapis.com/auth/cloud-platform

Returns ID of the signing key and the signed JWT on success.

On API-level errors (e.g. insufficient permissions) returns *googleapi.Error.

type Policy

type Policy struct {
	Bindings PolicyBindings
	Etag     string

	// All other JSON fields we are not interested in but must to preserve.
	//
	// They are assumed to be immutable. Clone and Equals below treat them as
	// scalar values, not as pointers to []byte.
	UnrecognizedFields map[string]*json.RawMessage
}

Policy is an IAM policy object.

See https://cloud.google.com/iam/reference/rest/v1/Policy.

func (Policy) Clone

func (p Policy) Clone() Policy

Clone makes a deep copy of this object.

func (Policy) Equals

func (p Policy) Equals(another Policy) bool

Equals returns true if this object is equal to another one.

func (*Policy) GrantRole

func (p *Policy) GrantRole(role string, principals ...string)

GrantRole grants a role to the given set of principals.

func (Policy) MarshalJSON

func (p Policy) MarshalJSON() ([]byte, error)

MarshalJSON is part of json.Marshaler interface.

func (*Policy) RevokeRole

func (p *Policy) RevokeRole(role string, principals ...string)

RevokeRole removes a role from the given set of principals.

func (*Policy) UnmarshalJSON

func (p *Policy) UnmarshalJSON(data []byte) error

UnmarshalJSON is part of json.Unmarshaler interface.

type PolicyBindings

type PolicyBindings map[string]membersSet

PolicyBindings is the IAM policy map {role -> set of members}.

Implements json.Marshaler and json.Unmarshaler.

func (PolicyBindings) Clone

func (b PolicyBindings) Clone() PolicyBindings

Clone makes a deep copy of this object.

func (PolicyBindings) Equals

func (b PolicyBindings) Equals(another PolicyBindings) bool

Equals returns true if this object is equal to another one.

func (PolicyBindings) MarshalJSON

func (b PolicyBindings) MarshalJSON() ([]byte, error)

MarshalJSON is part of json.Marshaler interface.

func (*PolicyBindings) UnmarshalJSON

func (b *PolicyBindings) UnmarshalJSON(data []byte) error

UnmarshalJSON is part of json.Unmarshaler interface.

type Signer

type Signer struct {
	Client         *Client
	ServiceAccount string
}

Signer implements SignBytes interface on top of IAM client.

It signs blobs using some service account's private key via 'signBlob' IAM call.

func (*Signer) SignBytes

func (s *Signer) SignBytes(c context.Context, blob []byte) (string, []byte, error)

SignBytes signs the blob with some active private key.

Hashes the blob using SHA256 and then calculates RSASSA-PKCS1-v1_5 signature using the currently active signing key.

Returns the signature and name of the key used.