Figure out what to do about the relationship between ADC and JWT credentials.

[theacodes]

We have jwt.Credentials in order to support the small set of APIs that support using directly using a JWT as the bearer token (only BigTable right now, as far as I know).

In oauth2client, _JWTAccessCredentials (the equivalent of our jwt.Credentials) will actually return an instance of ServiceAccountCredentials if create_scoped is called (here). This was done so that GoogleCredentials.get_application_default can return a class that works for all APIs (here).

For some reference, the Java library just returns regular service account credentials with ADC (here). The other auth libraries also seem to just return service account credentials.

So what should we do here? I see a few options:

1. Just make ADC return service account credentials (google.oauth2.service_account.Credentials), make users explicitly construct jwt.Credentials if that's what they want. Optionally provide an easy way to convert service account credentials to jwt credentials.
2. Make ADC return a new class that inherits from jwt.Credentials and Scoped that behaves like oauth2client.

[theacodes]

@bjwatson @anthmgoogle I'd really appreciate your input on this as well.

[dhermes]

@jonparrott What are the core differences between google.oauth2.service_account.Credentials and google.auth.jwt.Credentials? I'll start a partial list:

• jwt.Credentials NOT scoped (i.e. means no scope in ctor, no with_scopes / requires_scopes method)
• jwt.Credentials allows token lifetime be set by user
• jwt.Credentials accepts audience
• service_account.Credentials needs an email and a token URI
• from_service_account_info USES token URI in service_account.Credentials
• In from_service_account_info the email is used as the service account in service_account.Credentials but used as the subject (if not already set) in jwt.Credentials
• service_account.Credentials has with_subject (unclear why jwt.Credentials doesn't?)
• jwt.Credentials has with_claims (unclear why service_account.Credentials doesn't?)
• jwt.Credentials has custom before_request to handle the no audience case
• refresh makes an actual HTTP request in service_account.Credentials, just does local Crypto in jwt.Credentials

[theacodes]

@dhermes it's important to look at the conceptual differences:

• Service account credentials generate a JWT to obtain an OAuth 2.0 access token to use a the bearer token. The JWT claims are intended to be consumed by the OAuth 2.0 token endpoint.
• JWT credentials use the JWT as the bearer token. The claims are meant to be consumed by the service's API directly (in the usual case ESP consumes the auth token).

This is where the differences in implementation come from:

jwt.Credentials NOT scoped (i.e. means no scope in ctor, no with_scopes / requires_scopes method)

Scopes are only valid in an OAuth 2.0 context. JWT authentication exists separately from the OAuth 2.0 authorization framework.

jwt.Credentials accepts audience

The audience for service account's claims is always the OAuth 2.0 token endpoint. The audience for jwt credentials is the service's API endpoint.

service_account.Credentials needs an email and a token URI

Because this is where the JWT will be sent.

In from_service_account_info the email is used as the service account in service_account.Credentials but used as the subject (if not already set) in jwt.Credentials

The subject for service account credentials can be used for domain-wide delegation to obtain an access token for a user other than the service account itself.

service_account.Credentials has with_subject (unclear why jwt.Credentials doesn't?)

As mentioned above, subject is used for delegation. Jwt credentials will always use the service account name as the subject for Google APIs, but could use a different subject for custom APIs (the subject can be set on the constructor, or with_claims).

jwt.Credentials has with_claims (unclear why service_account.Credentials doesn't?)

Because it may be useful to pass more claims along to the service endpoint / ESP frontend. The set of claims for service account credentials are defined by an RFC, so there is less need for those to be customized.

[dhermes]

I am 👎 on a THIRD umbrella class for ADC. I'd prefer instead a simple way to promote service_account.Credentials to jwt.Credentials. This way, any credentials-using code can just check the type and do the promotion in place before use.

[theacodes]

@dhermes I'm with you. I just wanted to sanity check with others first.

So google-cloud-bigtable would just do something like this:

if isinstance(credentials, service_account.Credentials):
    credentials = credentials.to_jwt_credentials()

Not sure what the promoter should be called/should live? jwt.Credentials.from_service_account_credentials() or sevice_account.Credentials.to_jwt_credentials() or google.auth.service_account_to_jwt() ?

(Note that service_account imports jwt)

[dhermes]

I am for service_account.Credentials.to_jwt_credentials()

[theacodes]

I am for service_account.Credentials.to_jwt_credentials()

Cool, that's the plan unless someone else feels strongly otherwise.

[theacodes]

Closing as we've come up with a plan. #35 will track the implementation of the plan.