feat: add AIP 4120 - Universe Domain support

aip/auth/4120.md

@@ -25,31 +25,30 @@ We aim to have a consistent user experience across a broad range of clients. One
 
 > This requirement applies to **all** flows.
 
-Every credentials class/object **must** expose the `universe_domain` getter (property, method, etc). The auth library end-users, including the client libraries will use this property.
+Every credentials class/object **must** expose the `universe_domain` getter (property, method, etc).
+
+This property will be used by the client libraries and auth library end-users. This value can be used to make decisions about whether the library is in the GDU or not e.g. the purpose of throwing specific errors if the end-user is forcing an unsupported authentication flow with non-GDU credentials.
 
 The credentials classes for flows that are not supported outside the GDU (e.g. user credentials) **must** still expose the `universe_domain` to the end-user. These credentials **must** return the default value `"googleapis.com"` for the `universe_domain`.
 
 ### Credentials accept a user-supplied `universe_domain`
 
 > This requirement applies **only** to the flows supported outside the GDU.
 
-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.
+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. This will allow users to explicitly override the credential universe domain for testing and development.
 
 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 outside the GDU. 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 read the universe domain from the credentials JSON file
+### Service Account Key credentials read the universe domain from the Service account key 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 Google default universe, 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 the GDU or not e.g. the purpose of throwing specific errors if the end-user is forcing an unsupported authentication flow with non-GDU credentials.
-
-#### Authentication libraries **must** use the self-signed JWT flow when authenticating outside the GDU using Service Account credentials
+#### Authentication libraries **must** use the self-signed JWT flow when authenticating outside the GDU using Service Account Key credentials
 
-Currently the self-signed JWT (SSJ) 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.
-The token exchange for Service Accounts is not a supported flow outside the GDU, and services must support SSJ with scopes. Therefore authentication libraries **must** use the self-signed JWT flow when authenticating outside the GDU using Service Account credentials. If the `useJwtWithScopes` parameter exists (whatever form it takes in specific languages), it **must** be ignored outside the GDU, and its documentation **must** be updated to reflect that.
+The token exchange for Service Accounts is not a supported flow outside the GDU, and services must support SSJ with scopes. Therefore authentication libraries **must** use the self-signed JWT flow when authenticating outside the GDU using Service Accountj key credentials. If the `UseJWTAccessWithScope` parameter exists (whatever form it takes in specific languages), it **must** be ignored outside the GDU, and its documentation **must** be updated to reflect that.
 
 ### GCE credentials retrieve the universe domain from the metadata server
 
@@ -91,6 +90,6 @@ This constructor property should have a default value of `"googleapis.com"` for
 
 The official authentication flows which are supported outside the GDU are the following:
 
- - Service Account Credentials (through use of Service Account JWT Access Credentials only)
- - Metadata Credentials
+ - Service Account Key Credentials (through use of Service Account JWT Access Credentials only)
+ - Credentials provided by metadata service
  - External Account Credentials