Documentation

Overview

    Package iam implements wrappers around some Google Cloud IAM APIs.

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

    Index

    Constants

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

    Variables

    View Source
    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",
    	}
    )

    Functions

    This section is empty.

    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.