downscope: implement support for token downscoping
Implements support for token downscoping to allow for the creation of tokens with restricted permissions
Change-Id: I52459bdb0dfdd5e8d86e6043ba0362f4bf4b823c
GitHub-Last-Rev: 941cf10a8ebe14d2b03bf7253731134629fc7f80
GitHub-Pull-Request: golang/oauth2#502
Reviewed-on: https://go-review.googlesource.com/c/oauth2/+/326529
Reviewed-by: Chris Broadfoot <cbro@golang.org>
Run-TryBot: Chris Broadfoot <cbro@golang.org>
TryBot-Result: Go Bot <gobot@golang.org>
Trust: Tyler Bui-Palsulich <tbp@google.com>
Trust: Cody Oss <codyoss@google.com>
diff --git a/google/downscope/downscoping.go b/google/downscope/downscoping.go
new file mode 100644
index 0000000..2d74c37
--- /dev/null
+++ b/google/downscope/downscoping.go
@@ -0,0 +1,190 @@
+// Copyright 2021 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+/*
+Package downscope implements the ability to downscope, or restrict, the
+Identity and AccessManagement 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
+*/
+package downscope
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "io/ioutil"
+ "net/http"
+ "net/url"
+ "time"
+
+ "golang.org/x/oauth2"
+)
+
+var (
+ identityBindingEndpoint = "https://sts.googleapis.com/v1/token"
+)
+
+type accessBoundary struct {
+ AccessBoundaryRules []AccessBoundaryRule `json:"accessBoundaryRules"`
+}
+
+// An AvailabilityCondition restricts access to a given Resource.
+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-overview
+ Expression string `json:"expression"`
+ // Title is short string that identifies the purpose of the condition. Optional.
+ Title string `json:"title,omitempty"`
+ // Description details about the purpose of the condition. Optional.
+ Description string `json:"description,omitempty"`
+}
+
+// An AccessBoundaryRule Sets the permissions (and optionally conditions)
+// that the new token has on given resource.
+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.
+ AvailableResource string `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"`
+}
+
+type downscopedTokenResponse struct {
+ AccessToken string `json:"access_token"`
+ IssuedTokenType string `json:"issued_token_type"`
+ TokenType string `json:"token_type"`
+ ExpiresIn int `json:"expires_in"`
+}
+
+// DownscopingConfig specifies the information necessary to request a downscoped token.
+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.
+ RootSource oauth2.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
+}
+
+// A downscopingTokenSource is used to retrieve a downscoped token with restricted
+// permissions compared to the root Token that is used to generate it.
+type downscopingTokenSource struct {
+ // ctx is the context used to query the API to retrieve a downscoped Token.
+ ctx context.Context
+ // config holds the information necessary to generate a downscoped Token.
+ config DownscopingConfig
+}
+
+// NewTokenSource returns an empty downscopingTokenSource.
+func NewTokenSource(ctx context.Context, conf DownscopingConfig) (oauth2.TokenSource, error) {
+ if conf.RootSource == nil {
+ return nil, fmt.Errorf("downscope: rootSource cannot be nil")
+ }
+ if len(conf.Rules) == 0 {
+ return nil, fmt.Errorf("downscope: length of AccessBoundaryRules must be at least 1")
+ }
+ if len(conf.Rules) > 10 {
+ return nil, fmt.Errorf("downscope: length of AccessBoundaryRules may not be greater than 10")
+ }
+ for _, val := range conf.Rules {
+ if val.AvailableResource == "" {
+ return nil, fmt.Errorf("downscope: all rules must have a nonempty AvailableResource: %+v", val)
+ }
+ if len(val.AvailablePermissions) == 0 {
+ return nil, fmt.Errorf("downscope: all rules must provide at least one permission: %+v", val)
+ }
+ }
+ return downscopingTokenSource{ctx: ctx, config: conf}, nil
+}
+
+// Token() uses a downscopingTokenSource to generate an oauth2 Token.
+// Do note that the returned TokenSource is an oauth2.StaticTokenSource. If you wish
+// to refresh this token automatically, then initialize a locally defined
+// TokenSource struct with the Token held by the StaticTokenSource and wrap
+// that TokenSource in an oauth2.ReuseTokenSource.
+func (dts downscopingTokenSource) Token() (*oauth2.Token, error) {
+
+ downscopedOptions := struct {
+ Boundary accessBoundary `json:"accessBoundary"`
+ }{
+ Boundary: accessBoundary{
+ AccessBoundaryRules: dts.config.Rules,
+ },
+ }
+
+ tok, err := dts.config.RootSource.Token()
+ if err != nil {
+ return nil, fmt.Errorf("downscope: unable to obtain root token: %v", err)
+ }
+
+ b, err := json.Marshal(downscopedOptions)
+ if err != nil {
+ return nil, fmt.Errorf("downscope: unable to marshal AccessBoundary payload %v", err)
+ }
+
+ form := url.Values{}
+ form.Add("grant_type", "urn:ietf:params:oauth:grant-type:token-exchange")
+ form.Add("subject_token_type", "urn:ietf:params:oauth:token-type:access_token")
+ form.Add("requested_token_type", "urn:ietf:params:oauth:token-type:access_token")
+ form.Add("subject_token", tok.AccessToken)
+ form.Add("options", string(b))
+
+ myClient := oauth2.NewClient(dts.ctx, nil)
+ resp, err := myClient.PostForm(identityBindingEndpoint, form)
+ if err != nil {
+ return nil, fmt.Errorf("unable to generate POST Request %v", err)
+ }
+ defer resp.Body.Close()
+ respBody, err := ioutil.ReadAll(resp.Body)
+ if err != nil {
+ return nil, fmt.Errorf("downscope: unable to read reaponse body: %v", err)
+ }
+ if resp.StatusCode != http.StatusOK {
+ b, err := ioutil.ReadAll(resp.Body)
+ if err != nil {
+ return nil, fmt.Errorf("downscope: unable to exchange token; %v. Failed to read response body: %v", resp.StatusCode, err)
+ }
+ return nil, fmt.Errorf("downscope: unable to exchange token; %v. Server responsed: %v", resp.StatusCode, string(b))
+ }
+
+ var tresp downscopedTokenResponse
+
+ err = json.Unmarshal(respBody, &tresp)
+ if err != nil {
+ return nil, fmt.Errorf("downscope: unable to unmarshal response body: %v", err)
+ }
+
+ // an exchanged token that is derived from a service account (2LO) has an expired_in value
+ // a token derived from a users token (3LO) does not.
+ // The following code uses the time remaining on rootToken for a user as the value for the
+ // derived token's lifetime
+ var expiryTime time.Time
+ if tresp.ExpiresIn > 0 {
+ expiryTime = time.Now().Add(time.Duration(tresp.ExpiresIn) * time.Second)
+ } else {
+ expiryTime = tok.Expiry
+ }
+
+ newToken := &oauth2.Token{
+ AccessToken: tresp.AccessToken,
+ TokenType: tresp.TokenType,
+ Expiry: expiryTime,
+ }
+ return newToken, nil
+}
diff --git a/google/downscope/downscoping_test.go b/google/downscope/downscoping_test.go
new file mode 100644
index 0000000..d5adda1
--- /dev/null
+++ b/google/downscope/downscoping_test.go
@@ -0,0 +1,55 @@
+// Copyright 2021 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package downscope
+
+import (
+ "context"
+ "io/ioutil"
+ "net/http"
+ "net/http/httptest"
+ "testing"
+
+ "golang.org/x/oauth2"
+)
+
+var (
+ standardReqBody = "grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange&options=%7B%22accessBoundary%22%3A%7B%22accessBoundaryRules%22%3A%5B%7B%22availableResource%22%3A%22test1%22%2C%22availablePermissions%22%3A%5B%22Perm1%22%2C%22Perm2%22%5D%7D%5D%7D%7D&requested_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token&subject_token=Mellon&subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token"
+ standardRespBody = `{"access_token":"Open Sesame","expires_in":432,"issued_token_type":"urn:ietf:params:oauth:token-type:access_token","token_type":"Bearer"}`
+)
+
+func Test_DownscopedTokenSource(t *testing.T) {
+ ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.Method != "POST" {
+ t.Errorf("Unexpected request method, %v is found", r.Method)
+ }
+ if r.URL.String() != "/" {
+ t.Errorf("Unexpected request URL, %v is found", r.URL)
+ }
+ body, err := ioutil.ReadAll(r.Body)
+ if err != nil {
+ t.Fatalf("Failed to read request body: %v", err)
+ }
+ if got, want := string(body), standardReqBody; got != want {
+ t.Errorf("Unexpected exchange payload: got %v but want %v,", got, want)
+ }
+ w.Header().Set("Content-Type", "application/json")
+ w.Write([]byte(standardRespBody))
+
+ }))
+ new := []AccessBoundaryRule{
+ {
+ AvailableResource: "test1",
+ AvailablePermissions: []string{"Perm1", "Perm2"},
+ },
+ }
+ myTok := oauth2.Token{AccessToken: "Mellon"}
+ tmpSrc := oauth2.StaticTokenSource(&myTok)
+ dts := downscopingTokenSource{context.Background(), DownscopingConfig{tmpSrc, new}}
+ identityBindingEndpoint = ts.URL
+ _, err := dts.Token()
+ if err != nil {
+ t.Fatalf("NewDownscopedTokenSource failed with error: %v", err)
+ }
+}
diff --git a/google/downscope/example_test.go b/google/downscope/example_test.go
new file mode 100644
index 0000000..061cf57
--- /dev/null
+++ b/google/downscope/example_test.go
@@ -0,0 +1,38 @@
+// Copyright 2021 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package downscope_test
+
+import (
+ "context"
+
+ "golang.org/x/oauth2"
+ "golang.org/x/oauth2/google/downscope"
+)
+
+func ExampleNewTokenSource() {
+ ctx := context.Background()
+ // Initializes an accessBoundary with one Rule.
+ 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 {
+ _ = dts
+ }
+ // You can now use the token held in myTokenSource to make
+ // Google Cloud Storage calls, as follows:
+
+ // storageClient, err := storage.NewClient(ctx, option.WithTokenSource(myTokenSource))
+}
