feat: add AIP 4120

aip/auth/4120.md

@@ -0,0 +1,82 @@
+---
+id: 4120
+state: draft
+created: 2023-09-12
+---
+
+# TPC requirements in Authentication Libraries
+
+Trusted Partner Cloud (TPC) is a multi-year program to build local, isolated clouds operated by partner companies. TPC will address the (developing) strict sovereignty requirements imposed by regulators around the world and enable opportunities to serve these customers. This AIP outlines the requirements for authentication libraries to support TPC in the Cloud SDK client libraries.
+
+## Guidance
+
+TPC support in the auth library has the following requirements:
+
+ - Credentials implement a "universe_domain" read property. 
+ - Credentials which support TPC and Application Default Credentials (ADC) accept a user-supplied "universe_domain"
+ - Service Account credentials retrieve the universe domain from the credentials JSON file
+ - GCE credentials retrieve the universe domain from the metadata server
+
+### Naming
+
+We aim to have a consistent user experience across a broad range of clients. One of the constants is the `universe_domain` name that should be used to represent the universe domain in configuration, user-readable properties and methods. Languages that use different casing conventions should adapt the name to be idiomatic but keep the two specific words in the same order, so `universe-domain`, `universeDomain` and `SetUniverseDomain` are all acceptable, but e.g. `DomainOfUniverse` is not.
+
+### Credentials implement a "universe_domain" read property
+
+> This requirement applies to **all** flows.
+
+For all credentials (or possibly in the base class): Create the `universe_domain` read property (get method, etc). The default value for the property is `googleapis.com`.
+This requirement applies to all flows. Flows that are not supported in TPC should raise an error if the `universe_domain` is not `googleapis.com`.
+
+### Application Default Credentials (ADC) and TPC-compatible Credentials accept a user-supplied "universe_domain"
+
+> This requirement applies **only** to the flows supported in TPC.
+
+The end-user MUST be able to create universe-specific credentials in code. This can take many forms: constructor arguments, set properties/methods, copy-on-write methods, etc. This requirement is to treat `universe_domain` as a first-class property in regards to modification and user visibility. 
+E.g. if the authentication library provides a `with_scope` copy-on-write method it can satisfy this requirement by providing a similar `with_universe_domain` method.
+This requirement applies only to the credentials classes that are related to the authentication flows supported in TPC. This is in contrast to the requirement to "expose the `universe_domain` to the end-user" which applies to all credentials classes.
+
+### Service Account credentials retrieve the universe domain from the credentials JSON file
+
+> This requirement applies **only** to the Service Account flow.
+
+The JSON credential files will have a new property: `universe_domain`. The authentication libraries must read it when parsing JSON credential files and expose it to the libraries' end-users. If the `universe_domain` is not present, the credentials file is assumed to be (a legacy one) from the GDU and the `universe_domain` value must default to `googleapis.com`. 
+This value can also be used to make decisions about whether the library is in TPC or GDU context for e.g. the purpose of throwing specific errors if the end-user is forcing an unsupported authentication flow with TPC credentials.
+
+#### Authentication libraries must only attempt self-signed JWT flow for Service Accounts when authenticating against TPC
+
+Currently the self-signed JWT sub-flow is the default option for Service Account auth flow, but user parameters provided, such as scope, audience, or useJwtWithScopes can change that. E.g. setting  useJwtWithScopes to false when specifying scope would result in auth library fallback to token exchange flow for service accounts.
+This was necessary in GDU since some services did not support self-signed JWTs with scopes set. For TPC the token exchange is impossible and services must support SSJ with scopes. Therefore:
+Authentication libraries must only attempt self-signed JWT flow for Service Accounts when authenticating against TPC. useJwtWithScopes parameter (whatever form it takes in specific languages) must be ignored in TPC and its documentation must be updated to reflect that.
+More details can be found in the following document: go/ssj-tpc.
+
+### GCE credentials retrieve the universe domain from the metadata server
+
+> This requirement applies **only** to the VM metadata flow.
+
+The VM metadata flow directly retrieves an access token from the Metadata Server (MDS) which has no universe information. The authentication libraries must modify the VM metadata flow to make a second request to retrieve the universe_domain from the following URI: `http://metadata.google.internal/computeMetadata/v1/universe/universe_domain`.
+
+Once the `universe_domain` is retrieved, the authentication libraries MUST cache it to avoid making unnecessary MDS requests.
+
+Failure modes when retrieving the universe_domain from MDS:
+
+| Error when retrieving the universe_domain from MDS | Action |
+| -------------------------------------------------- | ------ |
+| 404 OR no error, but the retrieved `universe_domain` value is an empty string | The authentication libraries MUST set the `universe_domain` to the default value `googleapis.com`. |
+| Timeout | The authentication libraries MUST NOT fall back to the googleapis.com default value. A retry mechanism is recommended. The authentication libraries SHOULD do the same action as when retrieving the access token times out. |
+| Any other error | The authentication libraries MUST NOT fall back to the `googleapis.com` default value. The authentication libraries SHOULD do the same action as when the same error happens when retrieving the access token. |
+
+### Other requirements
+
+#### Authentication libraries must not use hardcoded non-constant information in the authentication flows.
+
+Any resource containing "googleapis.com" must instead be pulled from the universe domain. Exceptions to this include any resources which are consistent across all universes. Examples of resources which are consistent across all universes include Federated Sign-On URLs, Token Revoke URLs, OAuth2 Authorization URLs for 3LO, and scopes. 
+
+#### Authentication libraries must add the universe_domain property to the token authentication credentials constructor (if supported) and document the default behavior 
+
+This requirement only applies to the "access token" credentials class, if the library provides it.
+
+If the authentication library provides a "helper" credentials class that the end-user can initialize with the access token they already have, this class should additionally expose the universe_domain property in the constructor.
+The access tokens are not guaranteed to be end-user decodable or have universe domain information. Therefore the end-user should be able to conveniently specify which universe's access token they are providing. Preferably it should be in the same fashion that they provide the access token itself, so if e.g. the access token is a constructor parameter, the universe_domain should also be a parameter.
+This constructor property should have a default value of `googleapis.com` for backwards compatibility. This behavior should be documented in a way to draw the developer's attention since we want to prevent them from making a mistake and sending the TPC access token to the GDU "by default".
+