feat/sg: add 'sg sams' commands 'create-client-token' and 'introspect-token'

[bobheadxi]

Right now, developing SAMS clients involves raw cURL commands (see operator cheat sheet) (which is fine), but other steps like "testing auth" require using accounts-clients-example, which isn't very well documented and requires a bit of hand-wringing to get to and start using.

We previously talked about making a SAMS-specific CLI, but IMO that's a pretty big pain point if we want SAMS integration adoption when everything else lives in sg, and all the nice tooling lives here as well.

This PR migrates the next steps after using cURL to set up clients (create-client-token and introspect-token) from accounts-clients-example to a new sg sams toolchain for better DX (docs, completions, flags)

Test plan

export SG_SAMS_CLIENT_ID="..."
export SG_SAMS_CLIENT_SECRET="..."
sg sams create-client-token -s 'enterprise_portal::codyaccess::read'

[chrsmith]

We previously talked about making a SAMS-specific CLI, but IMO that's a pretty big pain point if we want SAMS integration adoption when everything else lives in sg, and all the nice tooling lives here as well.

Directionally, this sounds like the right call. (Though I still liked the idea of a Sam Adams 🍺 sams-admin tool 😢.)

In case it helps, these are the things that I've needed to do as an admin of a SAMS integration:

CRUD on the scopes that a SAMS client can send in a request. (e.g. authorize "my app" to send tokens with "your app"'s permissions.) It seems like we'd need to be careful about how we expose that type of functionality though. (e.g. requiring that only an admin of "your app" can update "my app" to issue scopes for "your app", etc.)

[chrsmith]

Not to over-think it, but it would be nice to separate concerns from "CLI tooling stuff" from "SAMS client interactions"?

e.g. within this file, maybe have a:

// samsClientAdmin is an API client for interacting with
// the SAMS APIs on behalf of a SAMS client, e.g. an OAuth
// app that _uses_ SAMS.
type samsClientAdmin struct {
   TokenSource ouath.TokenSource
}

// GetClientToken returns the current OAuth access token generated from
// the underlying token source.
func (sac *samsAdminClient) GetClientToken() string { ... }

// And later...
func (sac *samsAdminClient) ListScopes() ([]sdk.Scope, error) { ... }
func (sac *samsAdminClient) AddScopeToApp(newScope sdk.Scope) error { ... }

[bobheadxi]

Hmm, I'm inclined to keep this as is for now - I don't think this makes the callsite here much simpler (e.g. I don't think this client type should handle JSON marshalling, so the callsite still needs to handle the get-token error and then the JSON marshalling), and in between the other client types (oauth2.TokenSource is arguably a client type, as the .Token() gives us a structured type and whatnot with the credentials, as well as the existing sams.ClientV1) we already have a lot of logic that is separated from the CLI tooling stuff.

[bobheadxi]

In other words, what we have here is basically already all CLI concerns (constructing type from flag, doing the thing, checking the error, dumping the output appropriately)

[bobheadxi]

In case it helps, these are the things that I've needed to do as an admin of a SAMS integration:

It does help; I'd love to expand on the tooling here for all your SAMS-integration-development needs 😁 once @unknwon gets the chance to review, I'll open some tickets tracking some follow-up ideas

[unknwon]

In case it helps, these are the things that I've needed to do as an admin of a SAMS integration:

It does help; I'd love to expand on the tooling here for all your SAMS-integration-development needs 😁 once @unknwon gets the chance to review, I'll open some tickets tracking some follow-up ideas

The direction sounds good, tho I'd want SAMS to first stop using shared-static management secret, e.g. somehow supporting/take advantage of (validating) credentials produced by gcloud auth application-default.

[unknwon]

🎉