downscope
package
This package is not in the latest version of its module.
Details
Validgo.mod file
The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
- Redistributable license
Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
- Tagged version
Modules with tagged versions give importers more predictable builds.
Stable versionWhen a project reaches major version v1 it is considered stable.
- Learn more about best practices
Repository
Links
Report a Vulnerability
Open Source Insights
Documentation¶
Overview¶
Package downscope implements the ability to downscope, or restrict, theIdentity and Access Management permissions that a short-lived Tokencan use. Please note that only Google Cloud Storage supports this feature.For complete documentation, seehttps://cloud.google.com/iam/docs/downscoping-short-lived-credentials
To downscope permissions of a source credential, you need to definea Credential Access Boundary. Said Boundary specifies which resourcesthe newly created credential can access, an upper bound on the permissionsit has over those resources, and optionally attribute-based conditionalaccess to the aforementioned resources. For more information on IAMConditions, seehttps://cloud.google.com/iam/docs/conditions-overview.
This functionality can be used to provide a third party withlimited access to and permissions on resources held by the owner of the rootcredential or internally in conjunction with the principle of least privilegeto ensure that internal services only hold the minimum necessary privilegesfor their function.
For example, a token broker can be set up on a server in a private network.Various workloads (token consumers) in the same network will send authenticatedrequests to that broker for downscoped tokens to access or modify specific googlecloud storage buckets. See the NewTokenSource example for an example of how atoken broker would use this package.
The broker will use the functionality in this package to generate a downscopedtoken with the requested configuration, and then pass it back to the tokenconsumer. These downscoped access tokens can then be used to access GoogleStorage resources. For instance, you can create a NewClient from the"cloud.google.com/go/storage" package and pass in option.WithTokenSource(yourTokenSource))
Index¶
Examples¶
Constants¶
This section is empty.
Variables¶
This section is empty.
Functions¶
funcNewTokenSource¶
func NewTokenSource(ctxcontext.Context, confDownscopingConfig) (oauth2.TokenSource,error)
NewTokenSource returns a configured downscopingTokenSource.
Example¶
package mainimport ("context""fmt""golang.org/x/oauth2/google""golang.org/x/oauth2""golang.org/x/oauth2/google/downscope")func main() {// This shows how to generate a downscoped token. This code would be run on the// token broker, which holds the root token used to generate the downscoped token.ctx := context.Background()// Initializes an accessBoundary with one Rule which restricts the downscoped// token to only be able to access the bucket "foo" and only grants it the// permission "storage.objectViewer".accessBoundary := []downscope.AccessBoundaryRule{{AvailableResource: "//storage.googleapis.com/projects/_/buckets/foo",AvailablePermissions: []string{"inRole:roles/storage.objectViewer"},},}var rootSource oauth2.TokenSource// This Source can be initialized in multiple ways; the following example uses// Application Default Credentials.rootSource, err := google.DefaultTokenSource(ctx, "https://www.googleapis.com/auth/cloud-platform")dts, err := downscope.NewTokenSource(ctx, downscope.DownscopingConfig{RootSource: rootSource, Rules: accessBoundary})if err != nil {fmt.Printf("failed to generate downscoped token source: %v", err)return}tok, err := dts.Token()if err != nil {fmt.Printf("failed to generate token: %v", err)return}_ = tok// You can now pass tok to a token consumer however you wish, such as exposing// a REST API and sending it over HTTP.// You can instead use the token held in dts to make// Google Cloud Storage calls, as follows:// storageClient, err := storage.NewClient(ctx, option.WithTokenSource(dts))}Types¶
typeAccessBoundaryRule¶
type AccessBoundaryRule struct {// AvailableResource is the full resource name of the Cloud Storage bucket that the rule applies to.// Use the format //storage.googleapis.com/projects/_/buckets/bucket-name.AvailableResourcestring `json:"availableResource"`// AvailablePermissions is a list that defines the upper bound on the available permissions// for the resource. Each value is the identifier for an IAM predefined role or custom role,// with the prefix inRole:. For example: inRole:roles/storage.objectViewer.// Only the permissions in these roles will be available.AvailablePermissions []string `json:"availablePermissions"`// An Condition restricts the availability of permissions// to specific Cloud Storage objects. Optional.//// A Condition can be used to make permissions available for specific objects,// rather than all objects in a Cloud Storage bucket.Condition *AvailabilityCondition `json:"availabilityCondition,omitempty"`}An AccessBoundaryRule Sets the permissions (and optionally conditions)that the new token has on given resource.
typeAvailabilityCondition¶
type AvailabilityCondition struct {// An Expression specifies the Cloud Storage objects where// permissions are available. For further documentation, see//https://cloud.google.com/iam/docs/conditions-overviewExpressionstring `json:"expression"`// Title is short string that identifies the purpose of the condition. Optional.Titlestring `json:"title,omitempty"`// Description details about the purpose of the condition. Optional.Descriptionstring `json:"description,omitempty"`}An AvailabilityCondition restricts access to a given Resource.
typeDownscopingConfig¶
type DownscopingConfig struct {// RootSource is the TokenSource used to create the downscoped token.// The downscoped token therefore has some subset of the accesses of// the original RootSource.RootSourceoauth2.TokenSource// Rules defines the accesses held by the new// downscoped Token. One or more AccessBoundaryRules are required to// define permissions for the new downscoped token. Each one defines an// access (or set of accesses) that the new token has to a given resource.// There can be a maximum of 10 AccessBoundaryRules.Rules []AccessBoundaryRule// UniverseDomain is the default service domain for a given Cloud universe.// The default value is "googleapis.com". Optional.UniverseDomainstring}DownscopingConfig specifies the information necessary to request a downscoped token.
Source Files