Document oauth 2 usage of analytics-admin/data etc

[eldair]

Please document analytics admin/data API usage via oauth 2 - we should not be forced to go through issues and rejected pull requests to get this info.

e.g.

$credentials =  \Google\ApiCore\CredentialsWrapper::build([
                'keyFile' => [
                    'type' => 'authorized_user',
                    'client_id' => $clientId,
                    'client_secret' => $clientSecret,
                    'access_token' => $token,
                    'refresh_token' => $refreshToken,
                    'expires_in' => $expiresAt,
                ],
            ]);
$client = new Google\Analytics\Admin\V1beta\Client\AnalyticsAdminServiceClient(['credentials' => $credentials]);
$stream = $client->listAccounts(new Google\Analytics\Admin\V1beta\ListAccountsRequest())

[bshaffer]

Hello @eldair ! Sorry to hear you've had issues.

Check out our Authentication documentation here: https://docs.cloud.google.com/php/docs/reference/help/authentication

Rather than provide the keyFile explicitly as you have here, the recommended approach is to provide the path to your file using Application Default Credentials (ADC):

GOOGLE_APPLICATION_CREDENTIALS=/path/to/my/keyfile.json

or in PHP

putenv('GOOGLE_APPLICATION_CREDENTIALS=/path/to/my/keyfile.json');
// no credentials option needed, they will be detected from the environment
$client = new Google\Analytics\Admin\V1beta\Client\AnalyticsAdminServiceClient(); 
$stream = $client->listAccounts(new Google\Analytics\Admin\V1beta\ListAccountsRequest())

[eldair]

@bshaffer thanks for the response but I think you are missing the point. The actual keyfile is an "impossible" usage when the app has multiple clients on whose behalf we communicate with google APIs via oauth hence my code example.

EDIT: What I'm trying to say is that it is not feasible to write hundreds of json files for each user's info and update all those files when their token/refresh token/expiration changes.

[bshaffer]

It sounds like your use-case (saving credentials for multiple clients) is fairly unique, and for that reason, not well-documented.

Also, rather than using the credentials wrapper, I'd suggest you use the google/auth library credentials directly, like this:

use Google\Auth\Credentials\UserRefreshCredentials;
use Google\Analytics\Admin\V1beta\Client\AnalyticsAdminServiceClient;

$scope = 'your-scope';
$jsonkey = json_decode(file_get_contents('/path/to/usercredentials.json'));
$userCredentials = new UserRefreshCredentials($scope, $jsonKey);
$client = new AnalyticsAdminServiceClient(['credentials' => $userCredentials]); 

I am not sure how we could better document this, but I am open to suggestions.

[eldair]

@bshaffer are you sure it is that unique? User connects their GA account within our app and then they can see their GA data inside our app, there are plenty of similar apps I've seen 🙄

When user connects their GA account, their auth data (token/refresh token/expiration) is stored in db (which is no hassle compared to json files, especially in distributed systems). That same auth data (from db) is provided to Credentials wrapper like in my original post - code that works perfectly (both for analytics admin and analytics data APIs), it just isn't documented anywhere.

[bshaffer]

@eldair you're certainly not the first to implement this use case, but I would consider it a more advanced usage of the library. I also hope that since we do have the credentials option documented in the client constructor, that this use-case is sufficiently documented.

But as you have explained that this use case ISN'T sufficiently documented, please let me know how and where it could be improved, and I am happy to do so. For one, I see that the type reference for Google\Auth\FetchAuthTokenInterface is not linked. This could be a way to improve the doc by guiding users to the credentials classes in google/auth such as UserRefrechCredentials.

[eldair]

Hi @bshaffer, sorry for not responding earlier.

In library documentation (provided link) it really is mentioned but marked as DEPRECATED without providing alternative for the same use case (I didn't even know it is "deprecated") and I am not really sure why is it deemed insecure when used correctly with information from oauth flow.

Back to the lack of documentation, the reason I think that this is not enough is because there isn't any code example for this use case. Having no example of this way of providing credentials and marking that option as deprecated is making it hard for us to know that this library can be used in such way.

Taking Google analytics data as an example, it only mentiones GOOGLE_APPLICATION_CREDENTIALS as being a default option https://developers.google.com/analytics/devguides/reporting/data/v1/quickstart?account_type=service#php_1 but does not explain what that is and if there are any alternatives. Those are the places where more examples are needed and all auth options explained.

[bshaffer]

Thanks for your reply! The option is not marked deprecated, only the use of a string filepath or array are deprecated. You must explicitly define the TYPE of credentials you're using, otherwise dynamically loading credentials from user input (as you're doing) is dangerous, and a user could upload malicious credentials.

In your example, you've hard coded "authorized_user", so there is no issue.

The previous types were removed almost a year ago, so we could potentially remove DEPRECATED from the comments now

EDIT: I submitted a PR to the analytics sample you mentioned to link to the reference documentation. Hopefully this helps resolve the issue (see googleanalytics/php-docs-samples#26)