feat: support for API Key client option

[bshaffer]

Adds support for API Keys in GAPIC clients via a new apiKey client option:

$productSearchClient = new ProductSearchClient([
    'apiKey' => $myApiKey
]);

AIP: https://google.aip.dev/auth/4110

• Supports the apiKey client option - this will be sent in using the x-goog-api-key header for all transports.
• If the apiKey and credentials or credentialsConfig.keyFile option are supplied, an exception is thrown
• If the apiKey option AND the quotaProject option are set, the $quotaProject is still sent in

[vishwarajanand]

@bshaffer Is this still in works, else we can close this?
The AIP now doesn't seem to talk about the apiKey?

[bshaffer]

@vishwarajanand looking at the changelog, guidance for the API Key variable was removed. Let's check with the auth team and see what the status is on supporting API keys

@TimurSadykov what are your thoughts on this one?

[TimurSadykov]

I think the latest is that we don't add a generic support in auth libraries
@arithmetic1728 to confirm and reference a doc

[arithmetic1728]

we are not going to add a generic support for api key due to multiple push backs

[bshaffer]

Closing for now

[clundin25]

I want to call out these two conditions from the API Key Design Doc.

1. If both credentials and api key are explicitly set, return an error to the user.
2. If api key is set, do not attempt the ADC flow.

I think the first condition is missing in this code.

Is the second condition also missing?

[bshaffer]

In the block you've highlighted, the logic goes like this:

• IF $credentials are null (e.g. credentials have not been explicitly set), THEN
  • IF the apiKey option has been set, THEN create ApiKeyHeaderCredentials
  • ELSE use applicationDefaultCredentials (this happens in CredentialsWrapper::build)

So no, the second condition is not missing.

I can add validation for the first at the top of this function.

[clundin25]

Do you foresee any issues to adding a universe domain?

I don't have any clear guidance now, but I think eventually it may be relevant

[bshaffer]

We do have guidance on universe domain with API Key - because there is no way to tie the two together, the universe domain is decided based on the supplied client option... so, while there CAN be a universe domain, it is not possible for the API key to validate it.

[bshaffer]

@westarle PTAL!

[westarle]

API Key interface looks good to me!

[Hectorhammett]

Nit:
I think that it looks cleaner with a union type than with a ?. But with the new PHP update, I don't anymore haha.

[bshaffer]

I am definitely undecided on this. I think sometimes the ? looks better (because it's more concise).

[Hectorhammett]

nit:
Type for $unusedAudience

public function getAuthorizationHeaderCallback(null|string $unusdeAudience = null): null|callable

[bshaffer]

good idea! Done

[Hectorhammett]

I know this was written already but all the cases return on each if. What if we forego the elseif for all of them?:

if (is_null($credentials) {
    return CredentialsWrapper::buidl($credentialsConfig, universeDomain);
}

if (is_string($credentials) || is_array($credentials)) {
    return CredentialsWrapper::build(['keyFile' => $credentials] + $credentialsConfig, $universeDomain);
}

if ($credentials instanceof FetchAuthTokenInterface) {
    authHttpHandler = $credentialsConfig['authHttpHandler'] ?? null;
    return new CredentialsWrapper($credentials, $authHttpHandler, $universeDomain);
}

if ($credentials instanceof CredentialsWrapper) {
    return $credentials;
}

throw new ValidationException(
     'Unexpected value in $auth option, got: ' .
     print_r($credentials, true)
);

I find it easier to read and more pleasing.

[bshaffer]

Good catch, I totally agree!

Done.