wp-stateless / lib / Google / vendor / google / auth / README.md

README.md in WP-Stateless – Google Cloud Storage 3.0.3, at lib/Google/vendor/google/auth/README.md

230 lines 7.6 KB

Raw Download Zip

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:[email protected]">Tim Emiola</a></dd>
7	<dd><a href="mailto:[email protected]">Stanley Cheung</a></dd>
8	<dd><a href="mailto:[email protected]">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
15	This is Google's officially supported PHP client library for using OAuth 2.0
16	authorization and authentication with Google APIs.
17
18	View the [reference documentation][ref-docs].
19
20	### Installing via Composer
21
22	The recommended way to install the google auth library is through
23	[](http://getcomposer.orgComposer](http://getcomposer.org](http://getcomposer.org).
24
25	```bash
26	# Install Composer
27	curl -sS https://getcomposer.org/installer \| php
28	```
29
30	Next, run the Composer command to install the latest stable version:
31
32	```bash
33	composer.phar require google/auth
34	```
35
36	## Application Default Credentials
37
38	This library provides an implementation of
39	[application default credentials][application default credentials] for PHP.
40
41	The Application Default Credentials provide a simple way to get authorization
42	credentials for use in calling Google APIs.
43
44	They are best suited for cases when the call needs to have the same identity
45	and authorization level for the application independent of the user. This is
46	the recommended approach to authorize calls to Cloud APIs, particularly when
47	you're building an application that uses Google Compute Engine.
48
49	#### Download your Service Account Credentials JSON file
50
51	To use `Application Default Credentials`, You first need to download a set of
52	JSON credentials for your project. Go to APIs & Services > Credentials in
53	the [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
59	Once downloaded, store the path to this file in the
60	`GOOGLE_APPLICATION_CREDENTIALS` environment variable.
61
62	```php
63	putenv('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
71	Before making your API call, you must be sure the API you're calling has been
72	enabled. Go to APIs & Auth > APIs in the
73	[Google Developers Console][developer console] and enable the APIs you'd like to
74	call. For the example below, you must enable the `Drive API`.
75
76	#### Call the APIs
77
78	As long as you update the environment variable below to point to your JSON
79	credentials file, the following code should output a list of your Drive files.
80
81	```php
82	use Google\Auth\ApplicationDefaultCredentials;
83	use GuzzleHttp\Client;
84	use GuzzleHttp\HandlerStack;
85
86	// specify the path to your application credentials
87	putenv('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!
108	print_r((string) $response->getBody());
109	```
110
111	##### Guzzle 5 Compatibility
112
113	If 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
129	If your application is running behind Cloud Run, or using Cloud Identity-Aware
130	Proxy (IAP), you will need to fetch an ID token to access your application. For
131	this, use the static method `getIdTokenMiddleware` on
132	`ApplicationDefaultCredentials`.
133
134	```php
135	use Google\Auth\ApplicationDefaultCredentials;
136	use GuzzleHttp\Client;
137	use GuzzleHttp\HandlerStack;
138
139	// specify the path to your application credentials
140	putenv('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!
165	print_r((string) $response->getBody());
166	```
167
168	For invoking Cloud Run services, your service account will need the
169	[](https://cloud.google.com/run/docs/authenticating/service-to-service`Cloud Run Invoker`](https://cloud.google.com/run/docs/authenticating/service-to-service](https://cloud.google.com/run/docs/authenticating/service-to-service)
170	IAM permission.
171
172	For invoking Cloud Identity-Aware Proxy, you will need to pass the Client ID
173	used when you set up your protected resource as the target audience. See how to
174	[](https://cloud.google.com/iap/docs/signed-headers-howtosecure your IAP app with signed headers](https://cloud.google.com/iap/docs/signed-headers-howto](https://cloud.google.com/iap/docs/signed-headers-howto).
175
176	#### Verifying JWTs
177
178	If you are [using Google ID tokens to authenticate users][google-id-tokens], use
179	the `Google\Auth\AccessToken` class to verify the ID token:
180
181	```php
182	use Google\Auth\AccessToken;
183
184	$auth = new AccessToken();
185	$auth->verify($idToken);
186	```
187
188	If 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
190	appropriate certificate URL for IAP. This is because IAP signs the ID
191	tokens with a different key than the Google Identity service:
192
193	```php
194	use 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
207	This library is licensed under Apache 2.0. Full license text is
208	available in [COPYING][copying].
209
210	## Contributing
211
212	See [CONTRIBUTING][contributing].
213
214	## Support
215
216	Please
217	[](https://github.com/google/google-auth-library-php/issuesreport bugs at the project on Github](https://github.com/google/google-auth-library-php/issues](https://github.com/google/google-auth-library-php/issues). Don't
218	hesitate to
219	[](http://stackoverflow.com/questions/tagged/google-auth-library-phpask questions](http://stackoverflow.com/questions/tagged/google-auth-library-php](http://stackoverflow.com/questions/tagged/google-auth-library-php)
220	about the client or APIs on [](http://stackoverflow.comStackOverflow](http://stackoverflow.com](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