1# Google Auth Library for PHP
  2
  3<dl>
  4  <dt>Homepage</dt><dd><a href="http://www.github.com/google/google-auth-library-php">http://www.github.com/google/google-auth-library-php</a></dd>
  5  <dt>Authors</dt>
  6    <dd><a href="mailto:temiola@google.com">Tim Emiola</a></dd>
  7    <dd><a href="mailto:stanleycheung@google.com">Stanley Cheung</a></dd>
  8    <dd><a href="mailto:betterbrent@google.com">Brent Shaffer</a></dd>
  9  <dt>Copyright</dt><dd>Copyright © 2015 Google, Inc.</dd>
 10  <dt>License</dt><dd>Apache 2.0</dd>
 11</dl>
 12
 13## Description
 14
 15This is Google's officially supported PHP client library for using OAuth 2.0
 16authorization and authentication with Google APIs.
 17
 18View the [reference documentation][ref-docs].
 19
 20### Installing via Composer
 21
 22The recommended way to install the google auth library is through
 23[Composer](http://getcomposer.org).
 24
 25```bash
 26# Install Composer
 27curl -sS https://getcomposer.org/installer | php
 28```
 29
 30Next, run the Composer command to install the latest stable version:
 31
 32```bash
 33composer.phar require google/auth
 34```
 35
 36## Application Default Credentials
 37
 38This library provides an implementation of
 39[application default credentials][application default credentials] for PHP.
 40
 41The Application Default Credentials provide a simple way to get authorization
 42credentials for use in calling Google APIs.
 43
 44They are best suited for cases when the call needs to have the same identity
 45and authorization level for the application independent of the user. This is
 46the recommended approach to authorize calls to Cloud APIs, particularly when
 47you're building an application that uses Google Compute Engine.
 48
 49#### Download your Service Account Credentials JSON file
 50
 51To use `Application Default Credentials`, You first need to download a set of
 52JSON credentials for your project. Go to **APIs & Services** > **Credentials** in
 53the [Google Developers Console][developer console] and select
 54**Service account** from the **Add credentials** dropdown.
 55
 56> This file is your *only copy* of these credentials. It should never be
 57> committed with your source code, and should be stored securely.
 58
 59Once downloaded, store the path to this file in the
 60`GOOGLE_APPLICATION_CREDENTIALS` environment variable.
 61
 62```php
 63putenv('GOOGLE_APPLICATION_CREDENTIALS=/path/to/my/credentials.json');
 64```
 65
 66> PHP's `putenv` function is just one way to set an environment variable.
 67> Consider using `.htaccess` or apache configuration files as well.
 68
 69#### Enable the API you want to use
 70
 71Before making your API call, you must be sure the API you're calling has been
 72enabled. Go to **APIs & Auth** > **APIs** in the
 73[Google Developers Console][developer console] and enable the APIs you'd like to
 74call. For the example below, you must enable the `Drive API`.
 75
 76#### Call the APIs
 77
 78As long as you update the environment variable below to point to *your* JSON
 79credentials file, the following code should output a list of your Drive files.
 80
 81```php
 82use Google\Auth\ApplicationDefaultCredentials;
 83use GuzzleHttp\Client;
 84use GuzzleHttp\HandlerStack;
 85
 86// specify the path to your application credentials
 87putenv('GOOGLE_APPLICATION_CREDENTIALS=/path/to/my/credentials.json');
 88
 89// define the scopes for your API call
 90$scopes = ['https://www.googleapis.com/auth/drive.readonly'];
 91
 92// create middleware
 93$middleware = ApplicationDefaultCredentials::getMiddleware($scopes);
 94$stack = HandlerStack::create();
 95$stack->push($middleware);
 96
 97// create the HTTP client
 98$client = new Client([
 99  'handler' => $stack,
100  'base_uri' => 'https://www.googleapis.com',
101  'auth' => 'google_auth'  // authorize all requests
102]);
103
104// make the request
105$response = $client->get('drive/v2/files');
106
107// show the result!
108print_r((string) $response->getBody());
109```
110
111##### Guzzle 5 Compatibility
112
113If you are using [Guzzle 5][Guzzle 5], replace the `create middleware` and
114`create the HTTP Client` steps with the following:
115
116```php
117// create the HTTP client
118$client = new Client([
119  'base_url' => 'https://www.googleapis.com',
120  'auth' => 'google_auth'  // authorize all requests
121]);
122
123// create subscriber
124$subscriber = ApplicationDefaultCredentials::getSubscriber($scopes);
125$client->getEmitter()->attach($subscriber);
126```
127
128#### Call using an ID Token
129If your application is running behind Cloud Run, or using Cloud Identity-Aware
130Proxy (IAP), you will need to fetch an ID token to access your application. For
131this, use the static method `getIdTokenMiddleware` on
132`ApplicationDefaultCredentials`.
133
134```php
135use Google\Auth\ApplicationDefaultCredentials;
136use GuzzleHttp\Client;
137use GuzzleHttp\HandlerStack;
138
139// specify the path to your application credentials
140putenv('GOOGLE_APPLICATION_CREDENTIALS=/path/to/my/credentials.json');
141
142// Provide the ID token audience. This can be a Client ID associated with an IAP application,
143// Or the URL associated with a CloudRun App
144//    $targetAudience = 'IAP_CLIENT_ID.apps.googleusercontent.com';
145//    $targetAudience = 'https://service-1234-uc.a.run.app';
146$targetAudience = 'YOUR_ID_TOKEN_AUDIENCE';
147
148// create middleware
149$middleware = ApplicationDefaultCredentials::getIdTokenMiddleware($targetAudience);
150$stack = HandlerStack::create();
151$stack->push($middleware);
152
153// create the HTTP client
154$client = new Client([
155  'handler' => $stack,
156  'auth' => 'google_auth',
157  // Cloud Run, IAP, or custom resource URL
158  'base_uri' => 'https://YOUR_PROTECTED_RESOURCE',
159]);
160
161// make the request
162$response = $client->get('/');
163
164// show the result!
165print_r((string) $response->getBody());
166```
167
168For invoking Cloud Run services, your service account will need the
169[`Cloud Run Invoker`](https://cloud.google.com/run/docs/authenticating/service-to-service)
170IAM permission.
171
172For invoking Cloud Identity-Aware Proxy, you will need to pass the Client ID
173used when you set up your protected resource as the target audience. See how to
174[secure your IAP app with signed headers](https://cloud.google.com/iap/docs/signed-headers-howto).
175
176#### Verifying JWTs
177
178If you are [using Google ID tokens to authenticate users][google-id-tokens], use
179the `Google\Auth\AccessToken` class to verify the ID token:
180
181```php
182use Google\Auth\AccessToken;
183
184$auth = new AccessToken();
185$auth->verify($idToken);
186```
187
188If your app is running behind [Google Identity-Aware Proxy][iap-id-tokens]
189(IAP), you can verify the ID token coming from the IAP server by pointing to the
190appropriate certificate URL for IAP. This is because IAP signs the ID
191tokens with a different key than the Google Identity service:
192
193```php
194use Google\Auth\AccessToken;
195
196$auth = new AccessToken();
197$auth->verify($idToken, [
198  'certsLocation' => AccessToken::IAP_CERT_URL
199]);
200```
201
202[google-id-tokens]: https://developers.google.com/identity/sign-in/web/backend-auth
203[iap-id-tokens]: https://cloud.google.com/iap/docs/signed-headers-howto
204
205## License
206
207This library is licensed under Apache 2.0. Full license text is
208available in [COPYING][copying].
209
210## Contributing
211
212See [CONTRIBUTING][contributing].
213
214## Support
215
216Please
217[report bugs at the project on Github](https://github.com/google/google-auth-library-php/issues). Don't
218hesitate to
219[ask questions](http://stackoverflow.com/questions/tagged/google-auth-library-php)
220about the client or APIs on [StackOverflow](http://stackoverflow.com).
221
222[ref-docs]: https://googleapis.github.io/google-auth-library-php/master/
223[google-apis-php-client]: https://github.com/google/google-api-php-client
224[application default credentials]: https://developers.google.com/accounts/docs/application-default-credentials
225[contributing]: https://github.com/google/google-auth-library-php/tree/master/.github/CONTRIBUTING.md
226[copying]: https://github.com/google/google-auth-library-php/tree/master/COPYING
227[Guzzle]: https://github.com/guzzle/guzzle
228[Guzzle 5]: http://docs.guzzlephp.org/en/5.3
229[developer console]: https://console.developers.google.com
230