1 | <img src="https://avatars2.githubusercontent.com/u/2810941?v=3&s=96" alt="Google Cloud Platform logo" title="Google Cloud Platform" align="right" height="96" width="96"/>
|
2 |
|
3 | # [node-gtoken](https://github.com/googleapis/node-gtoken)
|
4 |
|
5 | [![npm version][npm-image]][npm-url]
|
6 | [![Known Vulnerabilities][snyk-image]][snyk-url]
|
7 | [![codecov][codecov-image]][codecov-url]
|
8 | [![Code Style: Google][gts-image]][gts-url]
|
9 |
|
10 | > Node.js Google Authentication Service Account Tokens
|
11 |
|
12 | This is a low level utility library used to interact with Google Authentication services. **In most cases, you probably want to use the [google-auth-library](https://github.com/googleapis/google-auth-library-nodejs) instead.**
|
13 |
|
14 | * [gtoken API Reference][client-docs]
|
15 | * [github.com/googleapis/node-gtoken](https://github.com/googleapis/node-gtoken)
|
16 |
|
17 | ## Installation
|
18 |
|
19 | ``` sh
|
20 | npm install gtoken
|
21 | ```
|
22 |
|
23 | ## Usage
|
24 |
|
25 | ### Use with a `.pem` or `.p12` key file:
|
26 |
|
27 | ``` js
|
28 | const { GoogleToken } = require('gtoken');
|
29 | const gtoken = new GoogleToken({
|
30 | keyFile: 'path/to/key.pem', // or path to .p12 key file
|
31 | email: 'my_service_account_email@developer.gserviceaccount.com',
|
32 | scope: ['https://scope1', 'https://scope2'], // or space-delimited string of scopes
|
33 | eagerRefreshThresholdMillis: 5 * 60 * 1000
|
34 | });
|
35 |
|
36 | gtoken.getToken((err, tokens) => {
|
37 | if (err) {
|
38 | console.log(err);
|
39 | return;
|
40 | }
|
41 | console.log(tokens);
|
42 | // {
|
43 | // access_token: 'very-secret-token',
|
44 | // expires_in: 3600,
|
45 | // token_type: 'Bearer'
|
46 | // }
|
47 | });
|
48 | ```
|
49 |
|
50 | You can also use the async/await style API:
|
51 |
|
52 | ``` js
|
53 | const tokens = await gtoken.getToken()
|
54 | console.log(tokens);
|
55 | ```
|
56 |
|
57 | Or use promises:
|
58 |
|
59 | ```js
|
60 | gtoken.getToken()
|
61 | .then(tokens => {
|
62 | console.log(tokens)
|
63 | })
|
64 | .catch(console.error);
|
65 | ```
|
66 |
|
67 | ### Use with a service account `.json` key file:
|
68 |
|
69 | ``` js
|
70 | const { GoogleToken } = require('gtoken');
|
71 | const gtoken = new GoogleToken({
|
72 | keyFile: 'path/to/key.json',
|
73 | scope: ['https://scope1', 'https://scope2'], // or space-delimited string of scopes
|
74 | eagerRefreshThresholdMillis: 5 * 60 * 1000
|
75 | });
|
76 |
|
77 | gtoken.getToken((err, tokens) => {
|
78 | if (err) {
|
79 | console.log(err);
|
80 | return;
|
81 | }
|
82 | console.log(tokens);
|
83 | });
|
84 | ```
|
85 |
|
86 | ### Pass the private key as a string directly:
|
87 |
|
88 | ``` js
|
89 | const key = '-----BEGIN RSA PRIVATE KEY-----\nXXXXXXXXXXX...';
|
90 | const { GoogleToken } = require('gtoken');
|
91 | const gtoken = new GoogleToken({
|
92 | email: 'my_service_account_email@developer.gserviceaccount.com',
|
93 | scope: ['https://scope1', 'https://scope2'], // or space-delimited string of scopes
|
94 | key: key,
|
95 | eagerRefreshThresholdMillis: 5 * 60 * 1000
|
96 | });
|
97 | ```
|
98 |
|
99 | ## Options
|
100 |
|
101 | > Various options that can be set when creating initializing the `gtoken` object.
|
102 |
|
103 | - `options.email or options.iss`: The service account email address.
|
104 | - `options.scope`: An array of scope strings or space-delimited string of scopes.
|
105 | - `options.sub`: The email address of the user requesting delegated access.
|
106 | - `options.keyFile`: The filename of `.json` key, `.pem` key or `.p12` key.
|
107 | - `options.key`: The raw RSA private key value, in place of using `options.keyFile`.
|
108 | - `options.additionalClaims`: Additional claims to include in the JWT when requesting a token.
|
109 | - `options.eagerRefreshThresholdMillis`: How long must a token be valid for in order to return it from the cache. Defaults to 0.
|
110 |
|
111 | ### .getToken(callback)
|
112 |
|
113 | > Returns the cached tokens or requests a new one and returns it.
|
114 |
|
115 | ``` js
|
116 | gtoken.getToken((err, token) => {
|
117 | console.log(err || token);
|
118 | // gtoken.rawToken value is also set
|
119 | });
|
120 | ```
|
121 |
|
122 | ### .getCredentials('path/to/key.json')
|
123 |
|
124 | > Given a keyfile, returns the key and (if available) the client email.
|
125 |
|
126 | ```js
|
127 | const creds = await gtoken.getCredentials('path/to/key.json');
|
128 | ```
|
129 |
|
130 | ### Properties
|
131 |
|
132 | > Various properties set on the gtoken object after call to `.getToken()`.
|
133 |
|
134 | - `gtoken.idToken`: The OIDC token returned (if any).
|
135 | - `gtoken.accessToken`: The access token.
|
136 | - `gtoken.expiresAt`: The expiry date as milliseconds since 1970/01/01
|
137 | - `gtoken.key`: The raw key value.
|
138 | - `gtoken.rawToken`: Most recent raw token data received from Google.
|
139 |
|
140 | ### .hasExpired()
|
141 |
|
142 | > Returns true if the token has expired, or token does not exist.
|
143 |
|
144 | ``` js
|
145 | const tokens = await gtoken.getToken();
|
146 | gtoken.hasExpired(); // false
|
147 | ```
|
148 |
|
149 | ### .revokeToken()
|
150 |
|
151 | > Revoke the token if set.
|
152 |
|
153 | ``` js
|
154 | await gtoken.revokeToken();
|
155 | console.log('Token revoked!');
|
156 | ```
|
157 |
|
158 | ## Downloading your private `.p12` key from Google
|
159 |
|
160 | 1. Open the [Google Developer Console][gdevconsole].
|
161 | 2. Open your project and under "APIs & auth", click Credentials.
|
162 | 3. Generate a new `.p12` key and download it into your project.
|
163 |
|
164 | ## Converting your `.p12` key to a `.pem` key
|
165 |
|
166 | You can just specify your `.p12` file (with `.p12` extension) as the `keyFile` and it will automatically be converted to a `.pem` on the fly, however this results in a slight performance hit. If you'd like to convert to a `.pem` for use later, use OpenSSL if you have it installed.
|
167 |
|
168 | ``` sh
|
169 | $ openssl pkcs12 -in key.p12 -nodes -nocerts > key.pem
|
170 | ```
|
171 |
|
172 | Don't forget, the passphrase when converting these files is the string `'notasecret'`
|
173 |
|
174 | ## License
|
175 |
|
176 | [MIT](https://github.com/googleapis/node-gtoken/blob/main/LICENSE)
|
177 |
|
178 | [codecov-image]: https://codecov.io/gh/googleapis/node-gtoken/branch/main/graph/badge.svg
|
179 | [codecov-url]: https://codecov.io/gh/googleapis/node-gtoken
|
180 | [gdevconsole]: https://console.developers.google.com
|
181 | [gts-image]: https://img.shields.io/badge/code%20style-google-blueviolet.svg
|
182 | [gts-url]: https://www.npmjs.com/package/gts
|
183 | [npm-image]: https://img.shields.io/npm/v/gtoken.svg
|
184 | [npm-url]: https://npmjs.org/package/gtoken
|
185 | [snyk-image]: https://snyk.io/test/github/googleapis/node-gtoken/badge.svg
|
186 | [snyk-url]: https://snyk.io/test/github/googleapis/node-gtoken
|
187 | [client-docs]: https://googleapis.dev/nodejs/gtoken/latest/
|