1 | import { GaxiosOptions, GaxiosPromise, GaxiosResponse } from 'gaxios';
|
2 | import { Credentials } from './credentials';
|
3 | import { AuthClient } from './authclient';
|
4 | import { BodyResponseCallback } from '../transporters';
|
5 | import { GetAccessTokenResponse, Headers, RefreshOptions } from './oauth2client';
|
6 | /**
|
7 | * Offset to take into account network delays and server clock skews.
|
8 | */
|
9 | export declare const EXPIRATION_TIME_OFFSET: number;
|
10 | /**
|
11 | * The credentials JSON file type for external account clients.
|
12 | * There are 3 types of JSON configs:
|
13 | * 1. authorized_user => Google end user credential
|
14 | * 2. service_account => Google service account credential
|
15 | * 3. external_Account => non-GCP service (eg. AWS, Azure, K8s)
|
16 | */
|
17 | export declare const EXTERNAL_ACCOUNT_TYPE = "external_account";
|
18 | /** Cloud resource manager URL used to retrieve project information. */
|
19 | export declare const CLOUD_RESOURCE_MANAGER = "https://cloudresourcemanager.googleapis.com/v1/projects/";
|
20 | /**
|
21 | * Base external account credentials json interface.
|
22 | */
|
23 | export interface BaseExternalAccountClientOptions {
|
24 | type: string;
|
25 | audience: string;
|
26 | subject_token_type: string;
|
27 | service_account_impersonation_url?: string;
|
28 | token_url: string;
|
29 | token_info_url?: string;
|
30 | client_id?: string;
|
31 | client_secret?: string;
|
32 | quota_project_id?: string;
|
33 | workforce_pool_user_project?: string;
|
34 | }
|
35 | /**
|
36 | * Interface defining the successful response for iamcredentials
|
37 | * generateAccessToken API.
|
38 | * https://cloud.google.com/iam/docs/reference/credentials/rest/v1/projects.serviceAccounts/generateAccessToken
|
39 | */
|
40 | export interface IamGenerateAccessTokenResponse {
|
41 | accessToken: string;
|
42 | expireTime: string;
|
43 | }
|
44 | /**
|
45 | * Interface defining the project information response returned by the cloud
|
46 | * resource manager.
|
47 | * https://cloud.google.com/resource-manager/reference/rest/v1/projects#Project
|
48 | */
|
49 | export interface ProjectInfo {
|
50 | projectNumber: string;
|
51 | projectId: string;
|
52 | lifecycleState: string;
|
53 | name: string;
|
54 | createTime?: string;
|
55 | parent: {
|
56 | [key: string]: any;
|
57 | };
|
58 | }
|
59 | /**
|
60 | * Internal interface for tracking the access token expiration time.
|
61 | */
|
62 | interface CredentialsWithResponse extends Credentials {
|
63 | res?: GaxiosResponse | null;
|
64 | }
|
65 | /**
|
66 | * Base external account client. This is used to instantiate AuthClients for
|
67 | * exchanging external account credentials for GCP access token and authorizing
|
68 | * requests to GCP APIs.
|
69 | * The base class implements common logic for exchanging various type of
|
70 | * external credentials for GCP access token. The logic of determining and
|
71 | * retrieving the external credential based on the environment and
|
72 | * credential_source will be left for the subclasses.
|
73 | */
|
74 | export declare abstract class BaseExternalAccountClient extends AuthClient {
|
75 | /**
|
76 | * OAuth scopes for the GCP access token to use. When not provided,
|
77 | * the default https://www.googleapis.com/auth/cloud-platform is
|
78 | * used.
|
79 | */
|
80 | scopes?: string | string[];
|
81 | private cachedAccessToken;
|
82 | protected readonly audience: string;
|
83 | private readonly subjectTokenType;
|
84 | private readonly serviceAccountImpersonationUrl?;
|
85 | private readonly stsCredential;
|
86 | private readonly clientAuth?;
|
87 | private readonly workforcePoolUserProject?;
|
88 | projectId: string | null;
|
89 | projectNumber: string | null;
|
90 | readonly eagerRefreshThresholdMillis: number;
|
91 | readonly forceRefreshOnFailure: boolean;
|
92 | /**
|
93 | * Instantiate a BaseExternalAccountClient instance using the provided JSON
|
94 | * object loaded from an external account credentials file.
|
95 | * @param options The external account options object typically loaded
|
96 | * from the external account JSON credential file.
|
97 | * @param additionalOptions Optional additional behavior customization
|
98 | * options. These currently customize expiration threshold time and
|
99 | * whether to retry on 401/403 API request errors.
|
100 | */
|
101 | constructor(options: BaseExternalAccountClientOptions, additionalOptions?: RefreshOptions);
|
102 | /** The service account email to be impersonated, if available. */
|
103 | getServiceAccountEmail(): string | null;
|
104 | /**
|
105 | * Provides a mechanism to inject GCP access tokens directly.
|
106 | * When the provided credential expires, a new credential, using the
|
107 | * external account options, is retrieved.
|
108 | * @param credentials The Credentials object to set on the current client.
|
109 | */
|
110 | setCredentials(credentials: Credentials): void;
|
111 | /**
|
112 | * Triggered when a external subject token is needed to be exchanged for a GCP
|
113 | * access token via GCP STS endpoint.
|
114 | * This abstract method needs to be implemented by subclasses depending on
|
115 | * the type of external credential used.
|
116 | * @return A promise that resolves with the external subject token.
|
117 | */
|
118 | abstract retrieveSubjectToken(): Promise<string>;
|
119 | /**
|
120 | * @return A promise that resolves with the current GCP access token
|
121 | * response. If the current credential is expired, a new one is retrieved.
|
122 | */
|
123 | getAccessToken(): Promise<GetAccessTokenResponse>;
|
124 | /**
|
125 | * The main authentication interface. It takes an optional url which when
|
126 | * present is the endpoint being accessed, and returns a Promise which
|
127 | * resolves with authorization header fields.
|
128 | *
|
129 | * The result has the form:
|
130 | * { Authorization: 'Bearer <access_token_value>' }
|
131 | */
|
132 | getRequestHeaders(): Promise<Headers>;
|
133 | /**
|
134 | * Provides a request implementation with OAuth 2.0 flow. In cases of
|
135 | * HTTP 401 and 403 responses, it automatically asks for a new access token
|
136 | * and replays the unsuccessful request.
|
137 | * @param opts Request options.
|
138 | * @param callback callback.
|
139 | * @return A promise that resolves with the HTTP response when no callback is
|
140 | * provided.
|
141 | */
|
142 | request<T>(opts: GaxiosOptions): GaxiosPromise<T>;
|
143 | request<T>(opts: GaxiosOptions, callback: BodyResponseCallback<T>): void;
|
144 | /**
|
145 | * @return A promise that resolves with the project ID corresponding to the
|
146 | * current workload identity pool or current workforce pool if
|
147 | * determinable. For workforce pool credential, it returns the project ID
|
148 | * corresponding to the workforcePoolUserProject.
|
149 | * This is introduced to match the current pattern of using the Auth
|
150 | * library:
|
151 | * const projectId = await auth.getProjectId();
|
152 | * const url = `https://dns.googleapis.com/dns/v1/projects/${projectId}`;
|
153 | * const res = await client.request({ url });
|
154 | * The resource may not have permission
|
155 | * (resourcemanager.projects.get) to call this API or the required
|
156 | * scopes may not be selected:
|
157 | * https://cloud.google.com/resource-manager/reference/rest/v1/projects/get#authorization-scopes
|
158 | */
|
159 | getProjectId(): Promise<string | null>;
|
160 | /**
|
161 | * Authenticates the provided HTTP request, processes it and resolves with the
|
162 | * returned response.
|
163 | * @param opts The HTTP request options.
|
164 | * @param retry Whether the current attempt is a retry after a failed attempt.
|
165 | * @return A promise that resolves with the successful response.
|
166 | */
|
167 | protected requestAsync<T>(opts: GaxiosOptions, retry?: boolean): Promise<GaxiosResponse<T>>;
|
168 | /**
|
169 | * Forces token refresh, even if unexpired tokens are currently cached.
|
170 | * External credentials are exchanged for GCP access tokens via the token
|
171 | * exchange endpoint and other settings provided in the client options
|
172 | * object.
|
173 | * If the service_account_impersonation_url is provided, an additional
|
174 | * step to exchange the external account GCP access token for a service
|
175 | * account impersonated token is performed.
|
176 | * @return A promise that resolves with the fresh GCP access tokens.
|
177 | */
|
178 | protected refreshAccessTokenAsync(): Promise<CredentialsWithResponse>;
|
179 | /**
|
180 | * Returns the workload identity pool project number if it is determinable
|
181 | * from the audience resource name.
|
182 | * @param audience The STS audience used to determine the project number.
|
183 | * @return The project number associated with the workload identity pool, if
|
184 | * this can be determined from the STS audience field. Otherwise, null is
|
185 | * returned.
|
186 | */
|
187 | private getProjectNumber;
|
188 | /**
|
189 | * Exchanges an external account GCP access token for a service
|
190 | * account impersonated access token using iamcredentials
|
191 | * GenerateAccessToken API.
|
192 | * @param token The access token to exchange for a service account access
|
193 | * token.
|
194 | * @return A promise that resolves with the service account impersonated
|
195 | * credentials response.
|
196 | */
|
197 | private getImpersonatedAccessToken;
|
198 | /**
|
199 | * Returns whether the provided credentials are expired or not.
|
200 | * If there is no expiry time, assumes the token is not expired or expiring.
|
201 | * @param accessToken The credentials to check for expiration.
|
202 | * @return Whether the credentials are expired or not.
|
203 | */
|
204 | private isExpired;
|
205 | /**
|
206 | * @return The list of scopes for the requested GCP access token.
|
207 | */
|
208 | private getScopesArray;
|
209 | /**
|
210 | * Checks whether Google APIs URL is valid.
|
211 | * @param apiName The apiName of url.
|
212 | * @param url The Google API URL to validate.
|
213 | * @return Whether the URL is valid or not.
|
214 | */
|
215 | private validateGoogleAPIsUrl;
|
216 | }
|
217 | export {};
|