Promote some Azure account API typings (#20615)

extensions/azurecore/src/account-provider/auths/azureAuth.ts

@@ -730,27 +730,142 @@ export interface Token extends AccountKey {
 }
 
 export interface TokenClaims { // https://docs.microsoft.com/en-us/azure/active-directory/develop/id-tokens
+	/**
+	 * Identifies the intended recipient of the token. In id_tokens, the audience
+	 * is your app's Application ID, assigned to your app in the Azure portal.
+	 * This value should be validated. The token should be rejected if it fails
+	 * to match your app's Application ID.
+	 */
 	aud: string;
+	/**
+	 * Identifies the issuer, or "authorization server" that constructs and
+	 * returns the token. It also identifies the Azure AD tenant for which
+	 * the user was authenticated. If the token was issued by the v2.0 endpoint,
+	 * the URI will end in /v2.0. The GUID that indicates that the user is a consumer
+	 * user from a Microsoft account is 9188040d-6c67-4c5b-b112-36a304b66dad.
+	 * Your app should use the GUID portion of the claim to restrict the set of
+	 * tenants that can sign in to the app, if applicable.
+	 */
 	iss: string;
+	/**
+	 * "Issued At" indicates when the authentication for this token occurred.
+	 */
 	iat: number;
+	/**
+	 * Records the identity provider that authenticated the subject of the token.
+	 * This value is identical to the value of the Issuer claim unless the user
+	 * account not in the same tenant as the issuer - guests, for instance.
+	 * If the claim isn't present, it means that the value of iss can be used instead.
+	 * For personal accounts being used in an organizational context (for instance,
+	 * a personal account invited to an Azure AD tenant), the idp claim may be
+	 * 'live.com' or an STS URI containing the Microsoft account tenant
+	 * 9188040d-6c67-4c5b-b112-36a304b66dad.
+	 */
 	idp: string,
+	/**
+	 * The "nbf" (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing.
+	 */
 	nbf: number;
+	/**
+	 * The "exp" (expiration time) claim identifies the expiration time on or
+	 * after which the JWT must not be accepted for processing. It's important
+	 * to note that in certain circumstances, a resource may reject the token
+	 * before this time. For example, if a change in authentication is required
+	 * or a token revocation has been detected.
+	 */
 	exp: number;
 	home_oid?: string;
+	/**
+	 * The code hash is included in ID tokens only when the ID token is issued with an
+	 * OAuth 2.0 authorization code. It can be used to validate the authenticity of an
+	 * authorization code. To understand how to do this validation, see the OpenID
+	 * Connect specification.
+	 */
 	c_hash: string;
+	/**
+	 * The access token hash is included in ID tokens only when the ID token is issued
+	 * from the /authorize endpoint with an OAuth 2.0 access token. It can be used to
+	 * validate the authenticity of an access token. To understand how to do this validation,
+	 * see the OpenID Connect specification. This is not returned on ID tokens from the /token endpoint.
+	 */
 	at_hash: string;
+	/**
+	 * An internal claim used by Azure AD to record data for token reuse. Should be ignored.
+	 */
 	aio: string;
+	/**
+	 * The primary username that represents the user. It could be an email address, phone number,
+	 * or a generic username without a specified format. Its value is mutable and might change
+	 * over time. Since it is mutable, this value must not be used to make authorization decisions.
+	 * It can be used for username hints, however, and in human-readable UI as a username. The profile
+	 * scope is required in order to receive this claim. Present only in v2.0 tokens.
+	 */
 	preferred_username: string;
+	/**
+	 * The email claim is present by default for guest accounts that have an email address.
+	 * Your app can request the email claim for managed users (those from the same tenant as the resource)
+	 * using the email optional claim. On the v2.0 endpoint, your app can also request the email OpenID
+	 * Connect scope - you don't need to request both the optional claim and the scope to get the claim.
+	 */
 	email: string;
+	/**
+	 * The name claim provides a human-readable value that identifies the subject of the token. The value
+	 * isn't guaranteed to be unique, it can be changed, and it's designed to be used only for display purposes.
+	 * The profile scope is required to receive this claim.
+	 */
 	name: string;
+	/**
+	 * The nonce matches the parameter included in the original /authorize request to the IDP. If it does not
+	 * match, your application should reject the token.
+	 */
 	nonce: string;
+	/**
+	 * The immutable identifier for an object in the Microsoft identity system, in this case, a user account.
+	 * This ID uniquely identifies the user across applications - two different applications signing in the
+	 * same user will receive the same value in the oid claim. The Microsoft Graph will return this ID as
+	 * the id property for a given user account. Because the oid allows multiple apps to correlate users,
+	 * the profile scope is required to receive this claim. Note that if a single user exists in multiple
+	 * tenants, the user will contain a different object ID in each tenant - they're considered different
+	 * accounts, even though the user logs into each account with the same credentials. The oid claim is a
+	 * GUID and cannot be reused.
+	 */
 	oid: string;
+	/**
+	 * The set of roles that were assigned to the user who is logging in.
+	 */
 	roles: string[];
+	/**
+	 * An internal claim used by Azure to revalidate tokens. Should be ignored.
+	 */
 	rh: string;
+	/**
+	 * The principal about which the token asserts information, such as the user
+	 * of an app. This value is immutable and cannot be reassigned or reused.
+	 * The subject is a pairwise identifier - it is unique to a particular application ID.
+	 * If a single user signs into two different apps using two different client IDs,
+	 * those apps will receive two different values for the subject claim.
+	 * This may or may not be wanted depending on your architecture and privacy requirements.
+	 */
 	sub: string;
+	/**
+	 * Represents the tenant that the user is signing in to. For work and school accounts,
+	 * the GUID is the immutable tenant ID of the organization that the user is signing in to.
+	 * For sign-ins to the personal Microsoft account tenant (services like Xbox, Teams for Life, or Outlook),
+	 * the value is 9188040d-6c67-4c5b-b112-36a304b66dad.
+	 */
 	tid: string;
+	/**
+	 * Only present in v1.0 tokens. Provides a human readable value that identifies the subject of the token.
+	 * This value is not guaranteed to be unique within a tenant and should be used only for display purposes.
+	 */
 	unique_name: string;
+	/**
+	 * Token identifier claim, equivalent to jti in the JWT specification. Unique, per-token identifier that is case-sensitive.
+	 */
 	uti: string;
+	/**
+	 * Indicates the version of the id_token.
+	 */
 	ver: string;
 }
 

src/sql/azdata.d.ts

@@ -2341,6 +2341,11 @@ declare module 'azdata' {
 			 * What type of token this is (such as Bearer)
 			 */
 			tokenType?: string | undefined;
+
+			/**
+			 * Access token expiry timestamp
+			 */
+			expiresOn?: number | undefined
 		}
 
 		/**
@@ -2373,7 +2378,7 @@ declare module 'azdata' {
 		accountType: string;
 
 		/**
-		 * A display name that identifies the account, such as "User Name".
+		 * A display name that identifies the account, such as "User Name". Will include the e-mail address if available.
 		 */
 		displayName: string;
 
@@ -2381,6 +2386,14 @@ declare module 'azdata' {
 		 * Unique user id that identifies the account.
 		 */
 		userId: string;
+		/**
+		 * The e-mail address associated with this account
+		 */
+		email?: string;
+		/**
+		 * A display name that identifies the account, such as "User Name".
+		 */
+		name?: string;
 	}
 
 	/**
@@ -2401,6 +2414,11 @@ declare module 'azdata' {
 		 * Identifier for the account, unique to the provider
 		 */
 		accountId: string;
+
+		/**
+		 * A version string for an account
+		 */
+		accountVersion?: string;
 	}
 
 	/**
@@ -2426,6 +2444,11 @@ declare module 'azdata' {
 		 * Indicates if the account needs refreshing
 		 */
 		isStale: boolean;
+
+		/**
+		 * Specifies if an account should be deleted
+		 */
+		delete?: boolean;
 	}
 
 	export enum AzureResource {
@@ -2540,10 +2563,18 @@ declare module 'azdata' {
 		 * @param account The account to generate a security token for
 		 * @param resource The resource to get the token for
 		 * @return Promise to return a security token object
-		 * @deprecated use getAccountSecurityToken
+		 * @deprecated use {@link AccountProvider.getAccountSecurityToken}
 		 */
 		getSecurityToken(account: Account, resource: AzureResource): Thenable<{} | undefined>;
 
+		/**
+		 * Generates a security token for the provided account and tenant
+		 * @param account The account to generate a security token for
+		 * @param resource The resource to get the token for
+		 * @return Promise to return a security token object
+		 */
+		getAccountSecurityToken(account: Account, tenant: string, resource: AzureResource): Thenable<accounts.AccountSecurityToken | undefined>;
+
 		/**
 		 * Prompts the user to enter account information.
 		 * Returns an error if the user canceled the operation.

src/sql/azdata.proposed.d.ts

@@ -477,35 +477,6 @@ declare module 'azdata' {
 		type?: ExtensionNodeType;
 	}
 
-	export interface AccountDisplayInfo {
-		email?: string;
-		name?: string;
-	}
-
-	export interface AccountProvider {
-		/**
-		 * Generates a security token for the provided account and tenant
-		 * @param account The account to generate a security token for
-		 * @param resource The resource to get the token for
-		 * @return Promise to return a security token object
-		 */
-		getAccountSecurityToken(account: Account, tenant: string, resource: AzureResource): Thenable<accounts.AccountSecurityToken | undefined>;
-	}
-
-	export interface AccountKey {
-		/**
-		 * A version string for an account
-		 */
-		accountVersion?: string;
-	}
-
-	export interface Account {
-		/**
-		 * Specifies if an account should be deleted
-		 */
-		delete?: boolean;
-	}
-
 	export namespace workspace {
 		/**
 		 * Creates and enters a workspace at the specified location
@@ -671,15 +642,6 @@ declare module 'azdata' {
 		connectionUriChanged(newUri: string, oldUri: string): Thenable<void>;
 	}
 
-	export namespace accounts {
-		export interface AccountSecurityToken {
-			/**
-			 * Access token expiry timestamp
-			 */
-			expiresOn?: number
-		}
-	}
-
 	export enum DataProviderType {
 		TableDesignerProvider = 'TableDesignerProvider',
 		ExecutionPlanProvider = 'ExecutionPlanProvider'