Preston_PLB
/
oauth2
forked from Mirrors/oauth2
1
0
Fork 0
Code Pull Requests Activity

google/downscope: update documentation 

Change-Id: Ib4dfc7b554c1e7565cc61bc372a98ddd390e7453
GitHub-Last-Rev: 63894e5681
GitHub-Pull-Request: golang/oauth2#512
Reviewed-on: https://go-review.googlesource.com/c/oauth2/+/338389
Reviewed-by: Cody Oss <codyoss@google.com>
Reviewed-by: Chris Broadfoot <cbro@golang.org>
Trust: Cody Oss <codyoss@google.com>
Trust: Chris Broadfoot <cbro@golang.org>
Run-TryBot: Cody Oss <codyoss@google.com>
Run-TryBot: Chris Broadfoot <cbro@golang.org>
TryBot-Result: Go Bot <gobot@golang.org>
This commit is contained in:
Patrick Jones 2021-08-04 21:45:42 +00:00 committed by Cody Oss
parent a41e5a7819
commit 6f1e639406
2 changed files with 34 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
google/downscope/downscoping.go
View File

@ -4,9 +4,34 @@
/*
Package downscope implements the ability to downscope, or restrict, the
Identity and AccessManagement permissions that a short-lived Token
Identity and Access Management permissions that a short-lived Token
can use. Please note that only Google Cloud Storage supports this feature.
For complete documentation, see https://cloud.google.com/iam/docs/downscoping-short-lived-credentials
To downscope permissions of a source credential, you need to define
a Credential Access Boundary. Said Boundary specifies which resources
the newly created credential can access, an upper bound on the permissions
it has over those resources, and optionally attribute-based conditional
access to the aforementioned resources. For more information on IAM
Conditions, see https://cloud.google.com/iam/docs/conditions-overview.
This functionality would typically be used to provide a third party with
limited access to and permissions on resources held by the owner of the root
credential or internally in conjunction with the principle of least privilege
to ensure that internal services only hold the minimum necessary privileges
for 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 authenticated
requests to that broker for downscoped tokens to access or modify specific google
cloud storage buckets. See the NewTokenSource example for an example of how a
token broker would use this package.
The broker will use the functionality in this package to generate a downscoped
token with the requested configuration, and then pass it back to the token
consumer. These downscoped access tokens can then be used to access Google
Storage resources. For instance, you can create a NewClient from the
"cloud.google.com/go/storage" package and pass in option.WithTokenSource(yourTokenSource))
*/
package downscope
@ -91,7 +116,7 @@ type downscopingTokenSource struct {
config DownscopingConfig
}
// NewTokenSource returns an empty downscopingTokenSource.
// NewTokenSource returns a configured downscopingTokenSource.
func NewTokenSource(ctx context.Context, conf DownscopingConfig) (oauth2.TokenSource, error) {
if conf.RootSource == nil {
return nil, fmt.Errorf("downscope: rootSource cannot be nil")

8
google/downscope/example_test.go
View File

@ -6,6 +6,7 @@ package downscope_test
import (
"context"
"fmt"
"golang.org/x/oauth2"
"golang.org/x/oauth2/google/downscope"
@ -29,8 +30,13 @@ func ExampleNewTokenSource() {
dts, err := downscope.NewTokenSource(ctx, downscope.DownscopingConfig{RootSource: rootSource, Rules: accessBoundary})
if err != nil {
_ = dts
fmt.Printf("failed to generate downscoped token source: %v", err)
return
}
// Enables automatic token refreshing
_ = oauth2.ReuseTokenSource(nil, dts)
// You can now use the token held in myTokenSource to make
// Google Cloud Storage calls, as follows: