← All changes | includes/sdk/google/google/auth/README.md +72 -13 1.0.2 → 1.4.2 View file →

		@@ -1,16 +1,7 @@
1	1	# Google Auth Library for PHP
2	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>Reference Docs</dt><dd><a href="https://googleapis.github.io/google-auth-library-php/main/">https://googleapis.github.io/google-auth-library-php/main/</a></dd>
6		- <dt>Authors</dt>
7		- <dd><a href="mailto:[email protected]">Tim Emiola</a></dd>
8		- <dd><a href="mailto:[email protected]">Stanley Cheung</a></dd>
9		- <dd><a href="mailto:[email protected]">Brent Shaffer</a></dd>
10		- <dt>Copyright</dt><dd>Copyright © 2015 Google, Inc.</dd>
11		- <dt>License</dt><dd>Apache 2.0</dd>
12		-</dl>
	3	+<a href="https://cloud.google.com/php/docs/reference/auth/latest">Reference Docs</a>
13	4
14	5	## Description
15	6
16	7	This is Google's officially supported PHP client library for using OAuth 2.0
		@@ -40,8 +31,16 @@
40	31	Application Default Credentials provides a simple way to get authorization
41	32	credentials for use in calling Google APIs, and is
42	33	the recommended approach to authorize calls to Cloud APIs.
43	34
	35	+**Important**: If you accept a credential configuration (credential JSON/File/Stream) from an
	36	+external source for authentication to Google Cloud Platform, you must validate it before providing
	37	+it to any Google API or library. Providing an unvalidated credential configuration to Google APIs
	38	+can compromise the security of your systems and data. For more information, refer to
	39	+[Validate credential configurations from external sources][externally-sourced-credentials].
	40	+
	41	+[externally-sourced-credentials]: https://cloud.google.com/docs/authentication/external/externally-sourced-credentials
	42	+
44	43	### Set up ADC
45	44
46	45	To use ADC, you must set it up by providing credentials.
47	46	How you set up ADC depends on the environment where your code is running,
		@@ -171,13 +170,21 @@
171	170
172	171	// define the scopes for your API call
173	172	$scopes = ['https://www.googleapis.com/auth/drive.readonly'];
174	173
175		-// Load credentials
176		-$creds = CredentialsLoader::makeCredentials($scopes, $jsonKey);
	174	+// Load credentials from JSON containing service account credentials.
	175	+$creds = new ServiceAccountCredentials($scopes, $jsonKey),
177	176
	177	+// For other credentials types, create those classes explicitly using the
	178	+// "type" field in the JSON key, for example:
	179	+$creds = match ($jsonKey['type']) {
	180	+ 'service_account' => new ServiceAccountCredentials($scope, $jsonKey),
	181	+ 'authorized_user' => new UserRefreshCredentials($scope, $jsonKey),
	182	+ default => throw new InvalidArgumentException('This application only supports service account and user account credentials'),
	183	+};
	184	+
178	185	// optional caching
179		-// $creds = new FetchAuthTokenCache($creds, $cacheConfig, $cache);
	186	+$creds = new FetchAuthTokenCache($creds, $cacheConfig, $cache);
180	187
181	188	// create middleware
182	189	$middleware = new AuthTokenMiddleware($creds);
183	190	$stack = HandlerStack::create();
		@@ -280,8 +287,60 @@
280	287	```
281	288
282	289	[google-id-tokens]: https://developers.google.com/identity/sign-in/web/backend-auth
283	290	[iap-id-tokens]: https://cloud.google.com/iap/docs/signed-headers-howto
	291	+
	292	+## Caching
	293	+Caching is enabled by passing a PSR-6 `CacheItemPoolInterface`
	294	+instance to the constructor when instantiating the credentials.
	295	+
	296	+We offer some caching classes out of the box under the `Google\Auth\Cache` namespace.
	297	+
	298	+```php
	299	+use Google\Auth\ApplicationDefaultCredentials;
	300	+use Google\Auth\Cache\MemoryCacheItemPool;
	301	+
	302	+// Cache Instance
	303	+$memoryCache = new MemoryCacheItemPool;
	304	+
	305	+// Get the credentials
	306	+// From here, the credentials will cache the access token
	307	+$middleware = ApplicationDefaultCredentials::getCredentials($scope, cache: $memoryCache);
	308	+```
	309	+
	310	+### FileSystemCacheItemPool Cache
	311	+The `FileSystemCacheItemPool` class is a `PSR-6` compliant cache that stores its
	312	+serialized objects on disk, caching data between processes and making it possible
	313	+to use data between different requests.
	314	+
	315	+```php
	316	+use Google\Auth\Cache\FileSystemCacheItemPool;
	317	+use Google\Auth\ApplicationDefaultCredentials;
	318	+
	319	+// Create a Cache pool instance
	320	+$cache = new FileSystemCacheItemPool(__DIR__ . '/cache');
	321	+
	322	+// Pass your Cache to the Auth Library
	323	+$credentials = ApplicationDefaultCredentials::getCredentials($scope, cache: $cache);
	324	+
	325	+// This token will be cached and be able to be used for the next request
	326	+$token = $credentials->fetchAuthToken();
	327	+```
	328	+
	329	+### Integrating with a third party cache
	330	+You can use a third party that follows the `PSR-6` interface of your choice.
	331	+
	332	+```php
	333	+// run "composer require symfony/cache"
	334	+use Google\Auth\ApplicationDefaultCredentials;
	335	+use Symfony\Component\Cache\Adapter\FilesystemAdapter;
	336	+
	337	+// Create the cache instance
	338	+$filesystemCache = new FilesystemAdapter();
	339	+
	340	+// Create Get the credentials
	341	+$credentials = ApplicationDefaultCredentials::getCredentials($targetAudience, cache: $filesystemCache);
	342	+```
284	343
285	344	## License
286	345
287	346	This library is licensed under Apache 2.0. Full license text is