Documentation
¶
Overview ¶
Package scopes provides utilities for manipulating and interpreting Taskcluster scopes.
See https://docs.taskcluster.net/presentations/scopes/#/definitions for formal definitions.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Given ¶
type Given []string
`Given` represents a set of scopes assigned to a client. For example:
myScopes := scopes.Given{
"abc:*",
"123:4:56",
"xyz",
"AB:*",
}
In order for a given scope to satisfy a required scope, either the given scope and required scope need to match as strings, or the given scope needs to be a prefix of the required scope, plus the `*` character. For example, the given scope `abc:*` satisfies the required scope `abc:def`.
func (Given) Expand ¶
func (given Given) Expand(scopeExpander ScopeExpander) (expanded Given, err error)
func (Given) Satisfies ¶
func (given Given) Satisfies(required Required, scopeExpander ScopeExpander) (bool, error)
Returns `true` if the given scopes satisfy the required scopes.
This function is ported from https://github.com/taskcluster/taskcluster-base/blob/218225942212e24596cee211389c276b2b985ffe/utils.js#L37-L68
Example (Compound) ¶
This rather complex example is commented to demonstrate the evaluation process.
given := Given{
"abc:*",
"123:4:56",
"xyz",
"AB:*",
}
satisfies, _ := given.Satisfies(
Required{
{
"abc:def", // satisfied by "abc:*"
"AB:CD:EF", // satisfied by "AB:*"
}, // => satisfied since all scopes in set are satisfied
{
"123:4:5", // NOT satisfied
}, // => NOT satisfied since not all scopes in set are satisfied
{
"abc:def", // satisfied by "abc:*"
"123:4", // NOT satisfied
}, // => NOT satisfied since not all scopes in set are satisfied
{
"Xxyz", // NOT satisfied
}, // => NOT satisfied since not all scopes in set are satisfied
}, // => satisfied since at least one set above is satisfied
auth,
)
fmt.Println(satisfies)
Output: true
Example (Expanded) ¶
given := Given{
"assume:repo:github.com/bugzilla/bugzilla:*",
}
satisfies, _ := given.Satisfies(
Required{
{
"assume:repo:github.com/bugzilla/bugzilla:*",
"queue:create-task:aws-provisioner-v1/b2gtest",
"queue:create-task:aws-provisioner-v1/github-worker",
"queue:route:gaia-taskcluster",
"queue:route:index.garbage.*",
"queue:route:tc-treeherder-stage.v2.bugzilla/bugzilla.*",
"queue:route:tc-treeherder.bugzilla-master.*",
"queue:route:tc-treeherder.bugzilla.*",
"queue:route:tc-treeherder.v2.bugzilla/bugzilla-master.*",
"queue:route:tc-treeherder.v2.bugzilla/bugzilla.*",
"secrets:get:garbage/*",
"secrets:set:garbage/*",
},
},
auth,
)
fmt.Println(satisfies)
Output: true
Example (Wildcard) ¶
This example demonstrates the use of a required scope with a trailing `*` character.
given := Given{"queue:*"}
out, _ := given.Satisfies(Required{{"queue:route:*"}}, auth)
fmt.Println(out)
out, _ = given.Satisfies(Required{{"queue:*"}}, auth)
fmt.Println(out)
out, _ = given.Satisfies(Required{{"*"}}, auth)
fmt.Println(out)
given = Given{"queue:route"}
out, _ = given.Satisfies(Required{{"queue:*"}}, auth)
fmt.Println(out)
Output: true true false false
type Required ¶
type Required [][]string
`Required` represents (in disjunctive normal form) permutations of scopes that are sufficient to authorise a client to perform a particular action. For example:
requiredScopes := scopes.Required{
{"abc:def", "AB:CD:EF"},
{"123:4:5"},
{"abc:def", "123:4"},
{"Xxyz"},
}
represents the requirement that the following scopes are "satisfied":
("abc:def" AND "AB:CD:EF") OR "123:4:5" OR ("abc:def" AND "123:4") OR "Xxyz"
Please note that since a required scope satisfies a given scope if they are equal, required scopes ending with a `*` can be used, although are relatively uncommon. See the examples.
type ScopeExpander ¶
type ScopeExpander interface {
ExpandScopes(*tcauth.SetOfScopes) (*tcauth.SetOfScopes, error)
}
Note, this is trivially implemented by *Auth in github.com/taskcluster/taskcluster-client-go/tcauth package, so typically tcauth.New(nil) will satisfy this interface.
Source Files