From dd7a3f7db84322c1360e1bbee52baa29609a7013 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 25 Sep 2025 22:26:17 +0000 Subject: [PATCH 1/3] Initial plan From 3b7ecc6316c4107fa61869355e285b24ca65f01f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 25 Sep 2025 22:47:19 +0000 Subject: [PATCH 2/3] Remove inappropriate @internal tags from exported members in identity packages Co-authored-by: minhanh-phan <111523473+minhanh-phan@users.noreply.github.com> --- sdk/identity/identity-broker/src/index.ts | 7 +---- .../samples-dev/extension.ts | 2 -- .../identity-cache-persistence/src/index.ts | 8 ------ .../src/platforms.ts | 15 ++++------ .../src/provider.ts | 3 +- .../identity-vscode/samples-dev/extension.ts | 1 - .../identity-vscode/samples-dev/nodeEnv.ts | 3 -- sdk/identity/identity-vscode/src/index.ts | 11 +------- .../samples-dev/defaultAzureCredential.ts | 1 - .../typescript/src/defaultAzureCredential.ts | 1 - .../typescript/src/defaultAzureCredential.ts | 1 - .../typescript/src/defaultAzureCredential.ts | 1 - .../identity/src/client/identityClient.ts | 9 +----- sdk/identity/identity/src/constants.ts | 15 ---------- .../authorizationCodeCredential.ts | 10 +------ .../src/credentials/azureCliCredential.ts | 14 +++------- .../azureDeveloperCliCredential.ts | 15 +++------- .../credentials/azurePipelinesCredential.ts | 2 -- .../credentials/azurePowerShellCredential.ts | 19 ++++--------- .../src/credentials/brokerAuthOptions.ts | 1 - .../src/credentials/brokerCredential.ts | 4 --- .../src/credentials/chainedTokenCredential.ts | 10 ------- .../credentials/clientAssertionCredential.ts | 2 -- .../clientCertificateCredential.ts | 7 ----- .../src/credentials/clientSecretCredential.ts | 4 --- .../credentialPersistenceOptions.ts | 5 ---- .../src/credentials/defaultAzureCredential.ts | 9 ------ .../defaultAzureCredentialFunctions.ts | 25 ++++++----------- .../src/credentials/deviceCodeCredential.ts | 9 ------ .../src/credentials/environmentCredential.ts | 10 +------ .../interactiveBrowserCredential.ts | 8 ------ .../interactiveBrowserCredentialOptions.ts | 1 - .../interactiveCredentialOptions.ts | 3 -- .../managedIdentityCredential/imdsMsi.ts | 1 - .../imdsRetryPolicy.ts | 1 - .../managedIdentityCredential/index.ts | 8 +----- .../managedIdentityCredential/models.ts | 4 +-- .../tokenExchangeMsi.ts | 1 - .../managedIdentityCredential/utils.ts | 4 +-- .../src/credentials/onBehalfOfCredential.ts | 16 ----------- .../credentials/usernamePasswordCredential.ts | 3 -- .../credentials/visualStudioCodeCredential.ts | 3 -- .../visualStudioCodeCredentialOptions.ts | 1 - .../visualStudioCodeCredentialPlugin.ts | 4 +-- .../credentials/workloadIdentityCredential.ts | 5 +--- sdk/identity/identity/src/errors.ts | 3 -- .../msal/browserFlows/msalBrowserCommon.ts | 6 ++-- .../msal/browserFlows/msalBrowserOptions.ts | 6 +--- sdk/identity/identity/src/msal/credentials.ts | 4 +-- .../identity/src/msal/nodeFlows/msalClient.ts | 25 ++--------------- .../src/msal/nodeFlows/msalPlugins.ts | 17 +++++------ .../nodeFlows/tokenCachePersistenceOptions.ts | 1 - sdk/identity/identity/src/msal/types.ts | 10 +++---- sdk/identity/identity/src/msal/utils.ts | 28 ++++++------------- sdk/identity/identity/src/plugins/consumer.ts | 7 +---- sdk/identity/identity/src/plugins/provider.ts | 4 +-- .../identity/src/regionalAuthority.ts | 4 +-- sdk/identity/identity/src/tokenProvider.ts | 3 -- sdk/identity/identity/src/util/logging.ts | 6 ---- .../src/util/processMultiTenantRequest.ts | 2 +- .../identity/src/util/processUtils.ts | 4 +-- sdk/identity/identity/src/util/scopeUtils.ts | 6 ++-- .../identity/src/util/subscriptionUtils.ts | 2 +- .../identity/src/util/tenantIdUtils.ts | 6 ++-- sdk/identity/identity/src/util/tracing.ts | 2 +- 65 files changed, 83 insertions(+), 350 deletions(-) diff --git a/sdk/identity/identity-broker/src/index.ts b/sdk/identity/identity-broker/src/index.ts index 1c4d68411458..085ed85c1e96 100644 --- a/sdk/identity/identity-broker/src/index.ts +++ b/sdk/identity/identity-broker/src/index.ts @@ -6,8 +6,7 @@ import { NativeBrokerPlugin } from "@azure/msal-node-extensions"; /** * A subset of the AzurePluginContext provided by \@azure/identity - * - * @internal + */ interface AzurePluginContext { nativeBrokerPluginControl: NativeBrokerPluginControl; @@ -23,15 +22,11 @@ interface NativeBrokerPluginControl { * credentials. The plugin API is compatible with `@azure/identity` versions * 4.0.0 and later. Load this plugin using the `useIdentityPlugin` * function, imported from `@azure/identity`. - * * Example: - * * ```ts snippet:using_plugins * import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity"; * import { nativeBrokerPlugin } from "@azure/identity-broker"; - * * useIdentityPlugin(nativeBrokerPlugin); - * * const credential = new InteractiveBrowserCredential({ * brokerOptions: { * enabled: true, diff --git a/sdk/identity/identity-cache-persistence/samples-dev/extension.ts b/sdk/identity/identity-cache-persistence/samples-dev/extension.ts index 5c8ea1dfd6da..678c47141bb0 100644 --- a/sdk/identity/identity-cache-persistence/samples-dev/extension.ts +++ b/sdk/identity/identity-cache-persistence/samples-dev/extension.ts @@ -7,11 +7,9 @@ * through `useIdentityPlugin`, some credentials, such as * `DeviceCodeCredential`, will be able to retrieve tokens from the cache rather * than requesting new tokens from the Microsoft Entra token endpoint. - * * In order to utilize the persistent token cache, the `enabled` property must * be set to `true` within `tokenCachePersistenceOptions` in the credential's * options. - * * @summary import and use the persistence plugin */ diff --git a/sdk/identity/identity-cache-persistence/src/index.ts b/sdk/identity/identity-cache-persistence/src/index.ts index c012d9dc91b7..762b37aa36ca 100644 --- a/sdk/identity/identity-cache-persistence/src/index.ts +++ b/sdk/identity/identity-cache-persistence/src/index.ts @@ -17,9 +17,7 @@ interface CachePluginControl { } /** * Context options passed to a plugin during initialization. - * * Represents a subset of the context defined in `@azure/identity` - * */ interface AzurePluginContext { cachePluginControl: CachePluginControl; @@ -30,25 +28,19 @@ interface AzurePluginContext { * credentials. The plugin API is compatible with `@azure/identity` versions * 2.0.0 and later. Load this plugin using the `useIdentityPlugin` * function, imported from `@azure/identity`. - * * In order to enable this functionality, you must also pass * `tokenCachePersistenceOptions` to your credential constructors with an * `enabled` property set to true. - * * Example: - * * ```ts snippet:ReadmeSampleDeviceCodeCredential * import { DeviceCodeCredential } from "@azure/identity"; - * * const credential = new DeviceCodeCredential({ * tokenCachePersistenceOptions: { * enabled: true, * }, * }); - * * // We'll use the Microsoft Graph scope as an example * const scope = "https://graph.microsoft.com/.default"; - * * // Print out part of the access token * console.log((await credential.getToken(scope)).token.substring(0, 10), "..."); * ``` diff --git a/sdk/identity/identity-cache-persistence/src/platforms.ts b/sdk/identity/identity-cache-persistence/src/platforms.ts index 2e831e0ee253..4a3c80d007a9 100644 --- a/sdk/identity/identity-cache-persistence/src/platforms.ts +++ b/sdk/identity/identity-cache-persistence/src/platforms.ts @@ -20,14 +20,14 @@ import type { TokenCachePersistenceOptions } from "@azure/identity"; * - Darwin: '/Users/user/' * - Windows 8+: 'C:\Users\user\AppData\Local' * - Linux: '/home/user/.local/share' - * @internal + */ const localApplicationDataFolder = process.env.APPDATA?.replace?.(/(.Roaming)*$/, "\\Local") ?? process.env.HOME!; /** * Dictionary of values that we use as default as we discover, pick and enable the persistence layer. - * @internal + */ export const defaultMsalValues = { tokenCache: { @@ -57,13 +57,13 @@ export const defaultMsalValues = { /** * Options that are used by the underlying MSAL cache provider. - * @internal + */ export type MsalPersistenceOptions = Omit; /** * A function that returns a persistent token cache instance. - * @internal + */ type MsalPersistenceFactory = (options?: MsalPersistenceOptions) => Promise; @@ -72,7 +72,7 @@ type MsalPersistenceFactory = (options?: MsalPersistenceOptions) => Promise' * - Windows 8+: 'C:\Users\user\AppData\Local\.IdentityService\' * - Linux: '/home/user/.IdentityService/' - * @internal + */ function getPersistencePath(name: string): string { return path.join(defaultMsalValues.tokenCache.directory, name); @@ -80,14 +80,11 @@ function getPersistencePath(name: string): string { /** * Set of the platforms we attempt to deliver persistence on. - * * - On Windows we use DPAPI. * - On OSX (Darwin), we try to use the system's Keychain, otherwise if the property `unsafeAllowUnencryptedStorage` is set to true, we use an unencrypted file. * - On Linux, we try to use the system's Keyring, otherwise if the property `unsafeAllowUnencryptedStorage` is set to true, we use an unencrypted file. - * * Other platforms _are not supported_ at this time. - * - * @internal + */ export const msalPersistencePlatforms: Partial> = { win32: ({ name = defaultMsalValues.tokenCache.name } = {}): Promise => diff --git a/sdk/identity/identity-cache-persistence/src/provider.ts b/sdk/identity/identity-cache-persistence/src/provider.ts index 03446da679ed..40241afc7af9 100644 --- a/sdk/identity/identity-cache-persistence/src/provider.ts +++ b/sdk/identity/identity-cache-persistence/src/provider.ts @@ -9,9 +9,8 @@ import type { ICachePlugin as CachePlugin } from "@azure/msal-node"; /** * This is used to gain access to the underlying Persistence instance, which we use for testing - * * @returns a raw persistence instance - * @internal + */ export async function createPersistence(options: MsalPersistenceOptions): Promise { const persistence = await msalPersistencePlatforms[process.platform]?.(options); diff --git a/sdk/identity/identity-vscode/samples-dev/extension.ts b/sdk/identity/identity-vscode/samples-dev/extension.ts index 1fcdeeebe9ba..3e7080860c84 100644 --- a/sdk/identity/identity-vscode/samples-dev/extension.ts +++ b/sdk/identity/identity-vscode/samples-dev/extension.ts @@ -8,7 +8,6 @@ * credential will simply throw a `CredentialNotFoundError`, and the * `DefaultAzureCredential` will use a different credential, if one is * available. - * * @summary loads the `VisualStudioCodeCredential` plugin and uses it through * `DefaultAzureCredential` */ diff --git a/sdk/identity/identity-vscode/samples-dev/nodeEnv.ts b/sdk/identity/identity-vscode/samples-dev/nodeEnv.ts index 356a94a79930..73307cdc8f9d 100644 --- a/sdk/identity/identity-vscode/samples-dev/nodeEnv.ts +++ b/sdk/identity/identity-vscode/samples-dev/nodeEnv.ts @@ -5,15 +5,12 @@ * This sample shows an example of how to load the `@azure/identity-vscode` * plugin only in certain environments. As an example, we use the NODE_ENV * environment variable to determine whether or not to load the plugin. - * * NOTE: The NODE_ENV environment variable is merely a convention, and you are * responsible for setting it as appropriate, for example, by setting the * variable at runtime: - * * ```bash * $ NODE_ENV="production" node dist/nodeEnv.js * ``` - * * @summary uses NODE_ENV to load the plugin only in development environments * @azsdk-weight -10 */ diff --git a/sdk/identity/identity-vscode/src/index.ts b/sdk/identity/identity-vscode/src/index.ts index 44b5362db0a3..bbd7b80ae879 100644 --- a/sdk/identity/identity-vscode/src/index.ts +++ b/sdk/identity/identity-vscode/src/index.ts @@ -17,11 +17,9 @@ interface VSCodeCredentialControl { /** * Context options passed to a plugin during initialization. - * * Plugin authors are responsible for casting their plugin context values * to this type. - * - * @internal + */ interface AzurePluginContext { vsCodeCredentialControl: VSCodeCredentialControl; @@ -54,26 +52,19 @@ function findAuthRecordPath(): string | undefined { * and enables it within `@azure/identity`. The plugin API is compatible with * `@azure/identity` versions 4.11.0 and later. Load this plugin using the * `useIdentityPlugin` function, imported from `@azure/identity`. - * * To use this functionality, import `VisualStudioCodeCredential` or * `DefaultAzureCredential` from `@azure/identity`. If this plugin is not * enabled, then `VisualStudioCodeCredential` will throw a * `CredentialUnavailableError`, and `DefaultAzureCredential` will not be able * to use authentication through Visual Studio Code. - * * Example: - * * ```ts snippet:ReadmeSampleVisualStudioCodeCredential * import { useIdentityPlugin, VisualStudioCodeCredential } from "@azure/identity"; * import { vsCodePlugin } from "@azure/identity-vscode"; - * * useIdentityPlugin(vsCodePlugin); - * * const credential = new VisualStudioCodeCredential(); - * * // The graph.microsoft.com scope is used as an example * const scope = "https://graph.microsoft.com/.default"; - * * // Print out part of the access token * console.log((await credential.getToken(scope)).token.substr(0, 10), "..."); * ``` diff --git a/sdk/identity/identity/samples-dev/defaultAzureCredential.ts b/sdk/identity/identity/samples-dev/defaultAzureCredential.ts index a5819a4e86f7..62ed319efafe 100644 --- a/sdk/identity/identity/samples-dev/defaultAzureCredential.ts +++ b/sdk/identity/identity/samples-dev/defaultAzureCredential.ts @@ -15,7 +15,6 @@ import "dotenv/config"; * The `DefaultAzureCredential` is appropriate for most scenarios where the application is intended to ultimately be run in the Azure Cloud. * This is because the `DefaultAzureCredential` combines credentials commonly used to authenticate when deployed, * with credentials used to authenticate in a development environment. - * * For more information, you may go to our readme: [link](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity#defaultazurecredential) */ diff --git a/sdk/identity/identity/samples/v2/typescript/src/defaultAzureCredential.ts b/sdk/identity/identity/samples/v2/typescript/src/defaultAzureCredential.ts index 135fba853717..827d5e194a6b 100644 --- a/sdk/identity/identity/samples/v2/typescript/src/defaultAzureCredential.ts +++ b/sdk/identity/identity/samples/v2/typescript/src/defaultAzureCredential.ts @@ -15,7 +15,6 @@ require("dotenv").config(); * The `DefaultAzureCredential` is appropriate for most scenarios where the application is intended to ultimately be run in the Azure Cloud. * This is because the `DefaultAzureCredential` combines credentials commonly used to authenticate when deployed, * with credentials used to authenticate in a development environment. - * * For more information, you may go to our readme: [link](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity#defaultazurecredential) */ diff --git a/sdk/identity/identity/samples/v3/typescript/src/defaultAzureCredential.ts b/sdk/identity/identity/samples/v3/typescript/src/defaultAzureCredential.ts index 5ae2ff824883..5a6dc152e134 100644 --- a/sdk/identity/identity/samples/v3/typescript/src/defaultAzureCredential.ts +++ b/sdk/identity/identity/samples/v3/typescript/src/defaultAzureCredential.ts @@ -15,7 +15,6 @@ require("dotenv").config(); * The `DefaultAzureCredential` is appropriate for most scenarios where the application is intended to ultimately be run in the Azure Cloud. * This is because the `DefaultAzureCredential` combines credentials commonly used to authenticate when deployed, * with credentials used to authenticate in a development environment. - * * For more information, you may go to our readme: [link](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity#defaultazurecredential) */ diff --git a/sdk/identity/identity/samples/v4/typescript/src/defaultAzureCredential.ts b/sdk/identity/identity/samples/v4/typescript/src/defaultAzureCredential.ts index a5819a4e86f7..62ed319efafe 100644 --- a/sdk/identity/identity/samples/v4/typescript/src/defaultAzureCredential.ts +++ b/sdk/identity/identity/samples/v4/typescript/src/defaultAzureCredential.ts @@ -15,7 +15,6 @@ import "dotenv/config"; * The `DefaultAzureCredential` is appropriate for most scenarios where the application is intended to ultimately be run in the Azure Cloud. * This is because the `DefaultAzureCredential` combines credentials commonly used to authenticate when deployed, * with credentials used to authenticate in a development environment. - * * For more information, you may go to our readme: [link](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity#defaultazurecredential) */ diff --git a/sdk/identity/identity/src/client/identityClient.ts b/sdk/identity/identity/src/client/identityClient.ts index 2181170ef2f1..29df8935fb50 100644 --- a/sdk/identity/identity/src/client/identityClient.ts +++ b/sdk/identity/identity/src/client/identityClient.ts @@ -37,9 +37,6 @@ export interface TokenResponse { refreshToken?: string; } -/** - * @internal - */ export function getIdentityClientAuthorityHost(options?: TokenCredentialOptions): string { // The authorityHost can come from options or from the AZURE_AUTHORITY_HOST environment variable. let authorityHost = options?.authorityHost; @@ -55,10 +52,8 @@ export function getIdentityClientAuthorityHost(options?: TokenCredentialOptions) /** * The network module used by the Identity credentials. - * * It allows for credentials to abort any pending request independently of the MSAL flow, * by calling to the `abortRequests()` method. - * */ export class IdentityClient extends ServiceClient implements INetworkModule { public authorityHost: string; @@ -302,8 +297,7 @@ export class IdentityClient extends ServiceClient implements INetworkModule { } /** - * - * @internal + */ getTokenCredentialOptions(): TokenCredentialOptions { return this.tokenCredentialOptions; @@ -311,7 +305,6 @@ export class IdentityClient extends ServiceClient implements INetworkModule { /** * If allowLoggingAccountIdentifiers was set on the constructor options * we try to log the account identifiers by parsing the received access token. - * * The account identifiers we try to log are: * - `appid`: The application or Client Identifier. * - `upn`: User Principal Name. diff --git a/sdk/identity/identity/src/constants.ts b/sdk/identity/identity/src/constants.ts index c0e992e45871..30f85332095e 100644 --- a/sdk/identity/identity/src/constants.ts +++ b/sdk/identity/identity/src/constants.ts @@ -8,7 +8,6 @@ export const SDK_VERSION = `4.12.1`; /** * The default client ID for authentication - * @internal */ // TODO: temporary - this is the Azure CLI clientID - we'll replace it when // Developer Sign On application is available @@ -17,7 +16,6 @@ export const DeveloperSignOnClientId = "04b07795-8ddb-461a-bbee-02f9e1bf7b46"; /** * The default tenant for authentication - * @internal */ export const DefaultTenantId = "common"; @@ -31,9 +29,7 @@ export enum AzureAuthorityHosts { AzureChina = "https://login.chinacloudapi.cn", /** * Germany-based Azure Authority Host - * * @deprecated Microsoft Cloud Germany was closed on October 29th, 2021. - * * */ AzureGermany = "https://login.microsoftonline.de", /** @@ -47,36 +43,25 @@ export enum AzureAuthorityHosts { } /** - * @internal * The default authority host. */ export const DefaultAuthorityHost = AzureAuthorityHosts.AzurePublicCloud; /** - * @internal * The default environment host for Azure Public Cloud */ export const DefaultAuthority = "login.microsoftonline.com"; /** - * @internal * Allow acquiring tokens for any tenant for multi-tentant auth. */ export const ALL_TENANTS: string[] = ["*"]; -/** - * @internal - */ export const CACHE_CAE_SUFFIX = "cae"; -/** - * @internal - */ export const CACHE_NON_CAE_SUFFIX = "nocae"; /** - * @internal - * * The default name for the cache persistence plugin. * Matches the constant defined in the cache persistence package. */ diff --git a/sdk/identity/identity/src/credentials/authorizationCodeCredential.ts b/sdk/identity/identity/src/credentials/authorizationCodeCredential.ts index 44dc18ed4e99..9b28eea24412 100644 --- a/sdk/identity/identity/src/credentials/authorizationCodeCredential.ts +++ b/sdk/identity/identity/src/credentials/authorizationCodeCredential.ts @@ -20,7 +20,6 @@ const logger = credentialLogger("AuthorizationCodeCredential"); * Enables authentication to Microsoft Entra ID using an authorization code * that was obtained through the authorization code flow, described in more detail * in the Microsoft Entra ID documentation: - * * https://learn.microsoft.com/entra/identity-platform/v2-oauth2-auth-code-flow */ export class AuthorizationCodeCredential implements TokenCredential { @@ -36,13 +35,10 @@ export class AuthorizationCodeCredential implements TokenCredential { * Creates an instance of AuthorizationCodeCredential with the details needed * to request an access token using an authentication that was obtained * from Microsoft Entra ID. - * * It is currently necessary for the user of this credential to initiate * the authorization code flow to obtain an authorization code to be used * with this credential. A full example of this flow is provided here: - * * https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/v2/manual/authorizationCodeSample.ts - * * @param tenantId - The Microsoft Entra tenant (directory) ID or name. * 'common' may be used when dealing with multi-tenant scenarios. * @param clientId - The client (application) ID of an App Registration in the tenant. @@ -66,13 +62,10 @@ export class AuthorizationCodeCredential implements TokenCredential { * Creates an instance of AuthorizationCodeCredential with the details needed * to request an access token using an authentication that was obtained * from Microsoft Entra ID. - * * It is currently necessary for the user of this credential to initiate * the authorization code flow to obtain an authorization code to be used * with this credential. A full example of this flow is provided here: - * * https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/v2/manual/authorizationCodeSample.ts - * * @param tenantId - The Microsoft Entra tenant (directory) ID or name. * 'common' may be used when dealing with multi-tenant scenarios. * @param clientId - The client (application) ID of an App Registration in the tenant. @@ -92,7 +85,7 @@ export class AuthorizationCodeCredential implements TokenCredential { ); /** * @hidden - * @internal + */ constructor( tenantId: string | "common", @@ -134,7 +127,6 @@ export class AuthorizationCodeCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. - * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * TokenCredential implementation might make. diff --git a/sdk/identity/identity/src/credentials/azureCliCredential.ts b/sdk/identity/identity/src/credentials/azureCliCredential.ts index e1c44f4cb194..35a8a78b1ca8 100644 --- a/sdk/identity/identity/src/credentials/azureCliCredential.ts +++ b/sdk/identity/identity/src/credentials/azureCliCredential.ts @@ -20,7 +20,7 @@ const logger = credentialLogger("AzureCliCredential"); /** * Messages to use when throwing in this credential. - * @internal + */ export const azureCliPublicErrorMessages = { claim: @@ -36,11 +36,11 @@ export const azureCliPublicErrorMessages = { /** * Mockable reference to the CLI credential cliCredentialFunctions - * @internal + */ export const cliCredentialInternals = { /** - * @internal + */ getSafeWorkingDir(): string { if (process.platform === "win32") { @@ -61,7 +61,7 @@ export const cliCredentialInternals = { /** * Gets the access token from Azure CLI * @param resource - The resource to use when getting the token - * @internal + */ async getAzureCliAccessToken( resource: string, @@ -119,10 +119,8 @@ export class AzureCliCredential implements TokenCredential { /** * Creates an instance of the {@link AzureCliCredential}. - * * To use this credential, ensure that you have already logged * in via the 'az' tool using the command "az login" from the commandline. - * * @param options - Options, to optionally allow multi-tenant requests. */ constructor(options?: AzureCliCredentialOptions) { @@ -143,7 +141,6 @@ export class AzureCliCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. - * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * TokenCredential implementation might make. @@ -234,12 +231,9 @@ export class AzureCliCredential implements TokenCredential { /** * Parses the raw JSON response from the Azure CLI into a usable AccessToken object - * * @param rawResponse - The raw JSON response from the Azure CLI * @returns An access token with the expiry time parsed from the raw response - * * The expiryTime of the credential's access token, in milliseconds, is calculated as follows: - * * When available, expires_on (introduced in Azure CLI v2.54.0) will be preferred. Otherwise falls back to expiresOn. */ private parseRawResponse(rawResponse: string): AccessToken { diff --git a/sdk/identity/identity/src/credentials/azureDeveloperCliCredential.ts b/sdk/identity/identity/src/credentials/azureDeveloperCliCredential.ts index 211f0d519acf..7bf660f07f22 100644 --- a/sdk/identity/identity/src/credentials/azureDeveloperCliCredential.ts +++ b/sdk/identity/identity/src/credentials/azureDeveloperCliCredential.ts @@ -18,7 +18,7 @@ const logger = credentialLogger("AzureDeveloperCliCredential"); /** * Messages to use when throwing in this credential. - * @internal + */ export const azureDeveloperCliPublicErrorMessages = { notInstalled: @@ -32,11 +32,11 @@ export const azureDeveloperCliPublicErrorMessages = { /** * Mockable reference to the Developer CLI credential cliCredentialFunctions - * @internal + */ export const developerCliCredentialInternals = { /** - * @internal + */ getSafeWorkingDir(): string { if (process.platform === "win32") { @@ -58,7 +58,7 @@ export const developerCliCredentialInternals = { /** * Gets the access token from Azure Developer CLI * @param scopes - The scopes to use when getting the token - * @internal + */ async getAzdAccessToken( scopes: string[], @@ -118,18 +118,14 @@ export const developerCliCredentialInternals = { * the logged-in user or service principal in the Azure Developer CLI. It acts as the Azure Developer CLI logged in user or * service principal and executes an Azure CLI command underneath to authenticate the application against * Microsoft Entra ID. - * *

Configure AzureDeveloperCliCredential

- * * To use this credential, the developer needs to authenticate locally in Azure Developer CLI using one of the * commands below: - * *
    *
  1. Run "azd auth login" in Azure Developer CLI to authenticate interactively as a user.
    2. *
  2. Run "azd auth login --client-id clientID --client-secret clientSecret * --tenant-id tenantID" to authenticate as a service principal.
    3. *
- * * You may need to repeat this process after a certain time period, depending on the refresh token validity in your * organization. Generally, the refresh token validity period is a few weeks to a few months. * AzureDeveloperCliCredential will prompt you to sign in again. @@ -141,10 +137,8 @@ export class AzureDeveloperCliCredential implements TokenCredential { /** * Creates an instance of the {@link AzureDeveloperCliCredential}. - * * To use this credential, ensure that you have already logged * in via the 'azd' tool using the command "azd auth login" from the commandline. - * * @param options - Options, to optionally allow multi-tenant requests. */ constructor(options?: AzureDeveloperCliCredentialOptions) { @@ -161,7 +155,6 @@ export class AzureDeveloperCliCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. - * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * TokenCredential implementation might make. diff --git a/sdk/identity/identity/src/credentials/azurePipelinesCredential.ts b/sdk/identity/identity/src/credentials/azurePipelinesCredential.ts index b9e5527c1226..c301fb8b84a3 100644 --- a/sdk/identity/identity/src/credentials/azurePipelinesCredential.ts +++ b/sdk/identity/identity/src/credentials/azurePipelinesCredential.ts @@ -96,7 +96,6 @@ export class AzurePipelinesCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} or {@link AuthenticationError} will be thrown with the details of the failure. - * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * TokenCredential implementation might make. @@ -121,7 +120,6 @@ export class AzurePipelinesCredential implements TokenCredential { } /** - * * @param oidcRequestUrl - oidc request url * @param systemAccessToken - system access token * @returns OIDC token from Azure Pipelines diff --git a/sdk/identity/identity/src/credentials/azurePowerShellCredential.ts b/sdk/identity/identity/src/credentials/azurePowerShellCredential.ts index 4afaf5125fc0..46929aaf7ba5 100644 --- a/sdk/identity/identity/src/credentials/azurePowerShellCredential.ts +++ b/sdk/identity/identity/src/credentials/azurePowerShellCredential.ts @@ -21,8 +21,7 @@ const isWindows = process.platform === "win32"; /** * Returns a platform-appropriate command name by appending ".exe" on Windows. - * - * @internal + */ export function formatCommand(commandName: string): string { if (isWindows) { @@ -35,7 +34,7 @@ export function formatCommand(commandName: string): string { /** * Receives a list of commands to run, executes them, then returns the outputs. * If anything fails, an error is thrown. - * @internal + */ async function runCommands(commands: string[][], timeout?: number): Promise { const results: string[] = []; @@ -55,7 +54,7 @@ async function runCommands(commands: string[][], timeout?: number): Promise RegExpMatchArray | null = (err: Error /** * The PowerShell commands to be tried, in order. - * - * @internal + */ export const commandStack = [formatCommand("pwsh")]; @@ -107,13 +105,11 @@ export class AzurePowerShellCredential implements TokenCredential { /** * Creates an instance of the {@link AzurePowerShellCredential}. - * * To use this credential: * - Install the Azure Az PowerShell module with: * `Install-Module -Name Az -Scope CurrentUser -Repository PSGallery -Force`. * - You have already logged in to Azure PowerShell using the command * `Connect-AzAccount` from the command line. - * * @param options - Options, to optionally allow multi-tenant requests. */ constructor(options?: AzurePowerShellCredentialOptions) { @@ -206,7 +202,6 @@ export class AzurePowerShellCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If the authentication cannot be performed through PowerShell, a {@link CredentialUnavailableError} will be thrown. - * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this TokenCredential implementation might make. */ @@ -273,10 +268,6 @@ export class AzurePowerShellCredential implements TokenCredential { } } -/** - * - * @internal - */ export async function parseJsonToken( result: string, ): Promise<{ Token: string; ExpiresOn: string }> { diff --git a/sdk/identity/identity/src/credentials/brokerAuthOptions.ts b/sdk/identity/identity/src/credentials/brokerAuthOptions.ts index ccccb7b14ccf..06474f0f79b1 100644 --- a/sdk/identity/identity/src/credentials/brokerAuthOptions.ts +++ b/sdk/identity/identity/src/credentials/brokerAuthOptions.ts @@ -10,7 +10,6 @@ import type { BrokerOptions } from "../msal/nodeFlows/brokerOptions.js"; export interface BrokerAuthOptions { /** * Options to allow broker authentication when using InteractiveBrowserCredential - * */ brokerOptions?: BrokerOptions; } diff --git a/sdk/identity/identity/src/credentials/brokerCredential.ts b/sdk/identity/identity/src/credentials/brokerCredential.ts index 835f3dc14808..42d560dcb6f9 100644 --- a/sdk/identity/identity/src/credentials/brokerCredential.ts +++ b/sdk/identity/identity/src/credentials/brokerCredential.ts @@ -31,10 +31,8 @@ export class BrokerCredential implements TokenCredential { /** * Creates an instance of BrokerCredential with the required broker options. - * * This credential uses WAM (Web Account Manager) for authentication, which provides * better security and user experience on Windows platforms. - * * @param options - Options for configuring the broker credential, including required broker options. */ constructor( @@ -65,10 +63,8 @@ export class BrokerCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID using WAM broker and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. - * * This method extends the base getToken method to support silentAuthenticationOnly option * when using broker authentication. - * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure the token request, including silentAuthenticationOnly option. */ diff --git a/sdk/identity/identity/src/credentials/chainedTokenCredential.ts b/sdk/identity/identity/src/credentials/chainedTokenCredential.ts index a21a80d109d9..fc5f97e7c461 100644 --- a/sdk/identity/identity/src/credentials/chainedTokenCredential.ts +++ b/sdk/identity/identity/src/credentials/chainedTokenCredential.ts @@ -6,9 +6,6 @@ import { AggregateAuthenticationError, CredentialUnavailableError } from "../err import { credentialLogger, formatError, formatSuccess } from "../util/logging.js"; import { tracingClient } from "../util/tracing.js"; -/** - * @internal - */ export const logger = credentialLogger("ChainedTokenCredential"); /** @@ -21,22 +18,17 @@ export class ChainedTokenCredential implements TokenCredential { /** * Creates an instance of ChainedTokenCredential using the given credentials. - * * @param sources - `TokenCredential` implementations to be tried in order. - * * Example usage: * ```ts snippet:chained_token_credential_example * import { ClientSecretCredential, ChainedTokenCredential } from "@azure/identity"; - * * const tenantId = ""; * const clientId = ""; * const clientSecret = ""; * const anotherClientId = ""; * const anotherSecret = ""; - * * const firstCredential = new ClientSecretCredential(tenantId, clientId, clientSecret); * const secondCredential = new ClientSecretCredential(tenantId, anotherClientId, anotherSecret); - * * const credentialChain = new ChainedTokenCredential(firstCredential, secondCredential); * ``` */ @@ -49,10 +41,8 @@ export class ChainedTokenCredential implements TokenCredential { * `TokenCredential` implementations. Throws an {@link AggregateAuthenticationError} * when one or more credentials throws an {@link AuthenticationError} and * no credentials have returned an access token. - * * This method is called automatically by Azure SDK client libraries. You may call this method * directly, but you must also handle token caching and token refreshing. - * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * `TokenCredential` implementation might make. diff --git a/sdk/identity/identity/src/credentials/clientAssertionCredential.ts b/sdk/identity/identity/src/credentials/clientAssertionCredential.ts index e3b0bc21defc..1976e65e4558 100644 --- a/sdk/identity/identity/src/credentials/clientAssertionCredential.ts +++ b/sdk/identity/identity/src/credentials/clientAssertionCredential.ts @@ -30,7 +30,6 @@ export class ClientAssertionCredential implements TokenCredential { * Creates an instance of the ClientAssertionCredential with the details * needed to authenticate against Microsoft Entra ID with a client * assertion provided by the developer through the `getAssertion` function parameter. - * * @param tenantId - The Microsoft Entra tenant (directory) ID. * @param clientId - The client (application) ID of an App Registration in the tenant. * @param getAssertion - A function that retrieves the assertion for the credential to use. @@ -76,7 +75,6 @@ export class ClientAssertionCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. - * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * TokenCredential implementation might make. diff --git a/sdk/identity/identity/src/credentials/clientCertificateCredential.ts b/sdk/identity/identity/src/credentials/clientCertificateCredential.ts index 641598aa92b0..f702fa28eb46 100644 --- a/sdk/identity/identity/src/credentials/clientCertificateCredential.ts +++ b/sdk/identity/identity/src/credentials/clientCertificateCredential.ts @@ -28,9 +28,7 @@ const logger = credentialLogger(credentialName); * Enables authentication to Microsoft Entra ID using a PEM-encoded * certificate that is assigned to an App Registration. More information * on how to configure certificate authentication can be found here: - * * https://learn.microsoft.com/azure/active-directory/develop/active-directory-certificate-credentials#register-your-certificate-with-azure-ad - * */ export class ClientCertificateCredential implements TokenCredential { private tenantId: string; @@ -42,7 +40,6 @@ export class ClientCertificateCredential implements TokenCredential { /** * Creates an instance of the ClientCertificateCredential with the details * needed to authenticate against Microsoft Entra ID with a certificate. - * * @param tenantId - The Microsoft Entra tenant (directory) ID. * @param clientId - The client (application) ID of an App Registration in the tenant. * @param certificatePath - The path to a PEM-encoded public/private key certificate on the filesystem. @@ -58,7 +55,6 @@ export class ClientCertificateCredential implements TokenCredential { /** * Creates an instance of the ClientCertificateCredential with the details * needed to authenticate against Microsoft Entra ID with a certificate. - * * @param tenantId - The Microsoft Entra tenant (directory) ID. * @param clientId - The client (application) ID of an App Registration in the tenant. * @param configuration - Other parameters required, including the path of the certificate on the filesystem. @@ -74,7 +70,6 @@ export class ClientCertificateCredential implements TokenCredential { /** * Creates an instance of the ClientCertificateCredential with the details * needed to authenticate against Microsoft Entra ID with a certificate. - * * @param tenantId - The Microsoft Entra tenant (directory) ID. * @param clientId - The client (application) ID of an App Registration in the tenant. * @param configuration - Other parameters required, including the PEM-encoded certificate as a string. @@ -135,7 +130,6 @@ export class ClientCertificateCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. - * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * TokenCredential implementation might make. @@ -188,7 +182,6 @@ export class ClientCertificateCredential implements TokenCredential { /** * Parses a certificate into its relevant parts - * * @param certificateConfiguration - The certificate contents or path to the certificate * @param sendCertificateChain - true if the entire certificate chain should be sent for SNI, false otherwise * @returns The parsed certificate parts and the certificate contents diff --git a/sdk/identity/identity/src/credentials/clientSecretCredential.ts b/sdk/identity/identity/src/credentials/clientSecretCredential.ts index 6e118f5dbc8e..d1ae0c4c8a83 100644 --- a/sdk/identity/identity/src/credentials/clientSecretCredential.ts +++ b/sdk/identity/identity/src/credentials/clientSecretCredential.ts @@ -21,9 +21,7 @@ const logger = credentialLogger("ClientSecretCredential"); * Enables authentication to Microsoft Entra ID using a client secret * that was generated for an App Registration. More information on how * to configure a client secret can be found here: - * * https://learn.microsoft.com/entra/identity-platform/quickstart-configure-app-access-web-apis#add-credentials-to-your-web-application - * */ export class ClientSecretCredential implements TokenCredential { private tenantId: string; @@ -35,7 +33,6 @@ export class ClientSecretCredential implements TokenCredential { * Creates an instance of the ClientSecretCredential with the details * needed to authenticate against Microsoft Entra ID with a client * secret. - * * @param tenantId - The Microsoft Entra tenant (directory) ID. * @param clientId - The client (application) ID of an App Registration in the tenant. * @param clientSecret - A client secret that was generated for the App Registration. @@ -81,7 +78,6 @@ export class ClientSecretCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. - * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * TokenCredential implementation might make. diff --git a/sdk/identity/identity/src/credentials/credentialPersistenceOptions.ts b/sdk/identity/identity/src/credentials/credentialPersistenceOptions.ts index cddd3ab71d88..2b730a0fba10 100644 --- a/sdk/identity/identity/src/credentials/credentialPersistenceOptions.ts +++ b/sdk/identity/identity/src/credentials/credentialPersistenceOptions.ts @@ -11,17 +11,12 @@ export interface CredentialPersistenceOptions { /** * Options to provide to the persistence layer (if one is available) when * storing credentials. - * * You must first register a persistence provider plugin. See the * `@azure/identity-cache-persistence` package on NPM. - * * Example: - * * ```ts snippet:credential_persistence_options_example * import { useIdentityPlugin, DeviceCodeCredential } from "@azure/identity"; - * * useIdentityPlugin(cachePersistencePlugin); - * * const credential = new DeviceCodeCredential({ * tokenCachePersistenceOptions: { * enabled: true, diff --git a/sdk/identity/identity/src/credentials/defaultAzureCredential.ts b/sdk/identity/identity/src/credentials/defaultAzureCredential.ts index bd1c4574d957..5ede670212c2 100644 --- a/sdk/identity/identity/src/credentials/defaultAzureCredential.ts +++ b/sdk/identity/identity/src/credentials/defaultAzureCredential.ts @@ -32,7 +32,6 @@ const logger = credentialLogger("DefaultAzureCredential"); /** * A no-op credential that logs the reason it was skipped if getToken is called. - * @internal */ export class UnavailableDefaultCredential implements TokenCredential { credentialUnavailableErrorMessage: string; @@ -55,9 +54,7 @@ export class UnavailableDefaultCredential implements TokenCredential { * Provides a default {@link ChainedTokenCredential} configuration that works for most * applications that use Azure SDK client libraries. For more information, see * [DefaultAzureCredential overview](https://aka.ms/azsdk/js/identity/credential-chains#use-defaultazurecredential-for-flexibility). - * * The following credential types will be tried, in order: - * * - {@link EnvironmentCredential} * - {@link WorkloadIdentityCredential} * - {@link ManagedIdentityCredential} @@ -66,17 +63,14 @@ export class UnavailableDefaultCredential implements TokenCredential { * - {@link AzurePowerShellCredential} * - {@link AzureDeveloperCliCredential} * - BrokerCredential (a broker-enabled credential that requires \@azure/identity-broker is installed) - * * Consult the documentation of these credential types for more information * on how they attempt authentication. - * * The following example demonstrates how to use the `requiredEnvVars` option to ensure that certain environment variables are set before the `DefaultAzureCredential` is instantiated. * If any of the specified environment variables are missing or empty, an error will be thrown, preventing the application from continuing execution without the necessary configuration. * It also demonstrates how to set the `AZURE_TOKEN_CREDENTIALS` environment variable to control which credentials are included in the chain. * ```ts snippet:defaultazurecredential_requiredEnvVars * import { DefaultAzureCredential } from "@azure/identity"; - * * const credential = new DefaultAzureCredential({ * requiredEnvVars: [ * "AZURE_CLIENT_ID", @@ -90,21 +84,18 @@ export class UnavailableDefaultCredential implements TokenCredential { export class DefaultAzureCredential extends ChainedTokenCredential { /** * Creates an instance of the DefaultAzureCredential class with {@link DefaultAzureCredentialClientIdOptions}. - * * @param options - Optional parameters. See {@link DefaultAzureCredentialClientIdOptions}. */ constructor(options?: DefaultAzureCredentialClientIdOptions); /** * Creates an instance of the DefaultAzureCredential class with {@link DefaultAzureCredentialResourceIdOptions}. - * * @param options - Optional parameters. See {@link DefaultAzureCredentialResourceIdOptions}. */ constructor(options?: DefaultAzureCredentialResourceIdOptions); /** * Creates an instance of the DefaultAzureCredential class with {@link DefaultAzureCredentialOptions}. - * * @param options - Optional parameters. See {@link DefaultAzureCredentialOptions}. */ constructor(options?: DefaultAzureCredentialOptions); diff --git a/sdk/identity/identity/src/credentials/defaultAzureCredentialFunctions.ts b/sdk/identity/identity/src/credentials/defaultAzureCredentialFunctions.ts index 92830e7f63c8..3d70596c998c 100644 --- a/sdk/identity/identity/src/credentials/defaultAzureCredentialFunctions.ts +++ b/sdk/identity/identity/src/credentials/defaultAzureCredentialFunctions.ts @@ -25,10 +25,8 @@ import { BrokerCredential } from "./brokerCredential.js"; * Creates a {@link BrokerCredential} instance with the provided options. * This credential uses the Windows Authentication Manager (WAM) broker for authentication. * It will only attempt to authenticate silently using the default broker account - * * @param options - Options for configuring the credential. - * - * @internal + */ export function createDefaultBrokerCredential( options: DefaultAzureCredentialOptions = {}, @@ -39,8 +37,7 @@ export function createDefaultBrokerCredential( /** * Creates a {@link VisualStudioCodeCredential} from the provided options. * @param options - Options to configure the credential. - * - * @internal + */ export function createDefaultVisualStudioCodeCredential( options: DefaultAzureCredentialOptions = {}, @@ -51,8 +48,7 @@ export function createDefaultVisualStudioCodeCredential( /** * Creates a {@link ManagedIdentityCredential} from the provided options. * @param options - Options to configure the credential. - * - * @internal + */ export function createDefaultManagedIdentityCredential( options: @@ -110,8 +106,7 @@ export function createDefaultManagedIdentityCredential( /** * Creates a {@link WorkloadIdentityCredential} from the provided options. * @param options - Options to configure the credential. - * - * @internal + */ export function createDefaultWorkloadIdentityCredential( options?: DefaultAzureCredentialOptions | DefaultAzureCredentialClientIdOptions, @@ -148,8 +143,7 @@ export function createDefaultWorkloadIdentityCredential( /** * Creates a {@link AzureDeveloperCliCredential} from the provided options. * @param options - Options to configure the credential. - * - * @internal + */ export function createDefaultAzureDeveloperCliCredential( options: DefaultAzureCredentialOptions = {}, @@ -160,8 +154,7 @@ export function createDefaultAzureDeveloperCliCredential( /** * Creates a {@link AzureCliCredential} from the provided options. * @param options - Options to configure the credential. - * - * @internal + */ export function createDefaultAzureCliCredential( options: DefaultAzureCredentialOptions = {}, @@ -172,8 +165,7 @@ export function createDefaultAzureCliCredential( /** * Creates a {@link AzurePowerShellCredential} from the provided options. * @param options - Options to configure the credential. - * - * @internal + */ export function createDefaultAzurePowershellCredential( options: DefaultAzureCredentialOptions = {}, @@ -184,8 +176,7 @@ export function createDefaultAzurePowershellCredential( /** * Creates an {@link EnvironmentCredential} from the provided options. * @param options - Options to configure the credential. - * - * @internal + */ export function createDefaultEnvironmentCredential( options: DefaultAzureCredentialOptions = {}, diff --git a/sdk/identity/identity/src/credentials/deviceCodeCredential.ts b/sdk/identity/identity/src/credentials/deviceCodeCredential.ts index 85abf5f3ee4c..5a52721c2e63 100644 --- a/sdk/identity/identity/src/credentials/deviceCodeCredential.ts +++ b/sdk/identity/identity/src/credentials/deviceCodeCredential.ts @@ -44,14 +44,10 @@ export class DeviceCodeCredential implements TokenCredential { /** * Creates an instance of DeviceCodeCredential with the details needed * to initiate the device code authorization flow with Microsoft Entra ID. - * * A message will be logged, giving users a code that they can use to authenticate once they go to https://microsoft.com/devicelogin - * * Developers can configure how this message is shown by passing a custom `userPromptCallback`: - * * ```ts snippet:device_code_credential_example * import { DeviceCodeCredential } from "@azure/identity"; - * * const credential = new DeviceCodeCredential({ * tenantId: process.env.AZURE_TENANT_ID, * clientId: process.env.AZURE_CLIENT_ID, @@ -60,7 +56,6 @@ export class DeviceCodeCredential implements TokenCredential { * }, * }); * ``` - * * @param options - Options for configuring the client which makes the authentication requests. */ constructor(options?: DeviceCodeCredentialOptions) { @@ -82,11 +77,9 @@ export class DeviceCodeCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. - * * If the user provided the option `disableAutomaticAuthentication`, * once the token can't be retrieved silently, * this method won't attempt to request user interaction to retrieve the token. - * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * TokenCredential implementation might make. @@ -115,9 +108,7 @@ export class DeviceCodeCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. - * * If the token can't be retrieved silently, this method will always generate a challenge for the user. - * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * TokenCredential implementation might make. diff --git a/sdk/identity/identity/src/credentials/environmentCredential.ts b/sdk/identity/identity/src/credentials/environmentCredential.ts index d8fc39564b17..b2d745a5aee6 100644 --- a/sdk/identity/identity/src/credentials/environmentCredential.ts +++ b/sdk/identity/identity/src/credentials/environmentCredential.ts @@ -16,8 +16,7 @@ import { tracingClient } from "../util/tracing.js"; * Contains the list of all supported environment variable names so that an * appropriate error message can be generated when no credentials can be * configured. - * - * @internal + */ export const AllSupportedEnvironmentVariables = [ "AZURE_TENANT_ID", @@ -60,27 +59,21 @@ export class EnvironmentCredential implements TokenCredential { | UsernamePasswordCredential = undefined; /** * Creates an instance of the EnvironmentCredential class and decides what credential to use depending on the available environment variables. - * * Required environment variables: * - `AZURE_TENANT_ID`: The Microsoft Entra tenant (directory) ID. * - `AZURE_CLIENT_ID`: The client (application) ID of an App Registration in the tenant. - * * If setting the AZURE_TENANT_ID, then you can also set the additionally allowed tenants * - `AZURE_ADDITIONALLY_ALLOWED_TENANTS`: For multi-tenant applications, specifies additional tenants for which the credential may acquire tokens with a single semicolon delimited string. Use * to allow all tenants. - * * Environment variables used for client credential authentication: * - `AZURE_CLIENT_SECRET`: A client secret that was generated for the App Registration. * - `AZURE_CLIENT_CERTIFICATE_PATH`: The path to a PEM certificate to use during the authentication, instead of the client secret. * - `AZURE_CLIENT_CERTIFICATE_PASSWORD`: (optional) password for the certificate file. * - `AZURE_CLIENT_SEND_CERTIFICATE_CHAIN`: (optional) indicates that the certificate chain should be set in x5c header to support subject name / issuer based authentication. - * * Username and password authentication is deprecated, since it doesn't support multifactor authentication (MFA). See https://aka.ms/azsdk/identity/mfa for more details. Users can still provide environment variables for this authentication method: * - `AZURE_USERNAME`: Username to authenticate with. * - `AZURE_PASSWORD`: Password to authenticate with. - * * If the environment variables required to perform the authentication are missing, a {@link CredentialUnavailableError} will be thrown. * If the authentication fails, or if there's an unknown error, an {@link AuthenticationError} will be thrown. - * * @param options - Options for configuring the client which makes the authentication request. */ constructor(options?: EnvironmentCredentialOptions) { @@ -146,7 +139,6 @@ export class EnvironmentCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. - * * @param scopes - The list of scopes for which the token will have access. * @param options - Optional parameters. See {@link GetTokenOptions}. */ diff --git a/sdk/identity/identity/src/credentials/interactiveBrowserCredential.ts b/sdk/identity/identity/src/credentials/interactiveBrowserCredential.ts index a582de85f52d..089b2d725606 100644 --- a/sdk/identity/identity/src/credentials/interactiveBrowserCredential.ts +++ b/sdk/identity/identity/src/credentials/interactiveBrowserCredential.ts @@ -36,14 +36,11 @@ export class InteractiveBrowserCredential implements TokenCredential { /** * Creates an instance of InteractiveBrowserCredential with the details needed. - * * This credential uses the [Authorization Code Flow](https://learn.microsoft.com/entra/identity-platform/v2-oauth2-auth-code-flow). * On Node.js, it will open a browser window while it listens for a redirect response from the authentication service. * On browsers, it authenticates via popups. The `loginStyle` optional parameter can be set to `redirect` to authenticate by redirecting the user to an Azure secure login page, which then will redirect the user back to the web application where the authentication started. - * * For Node.js, if a `clientId` is provided, the Microsoft Entra application will need to be configured to have a "Mobile and desktop applications" redirect endpoint. * Follow our guide on [setting up Redirect URIs for Desktop apps that calls to web APIs](https://learn.microsoft.com/entra/identity-platform/scenario-desktop-app-registration#redirect-uris). - * * @param options - Options for configuring the client which makes the authentication requests. */ constructor( @@ -87,11 +84,9 @@ export class InteractiveBrowserCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. - * * If the user provided the option `disableAutomaticAuthentication`, * once the token can't be retrieved silently, * this method won't attempt to request user interaction to retrieve the token. - * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * TokenCredential implementation might make. @@ -122,12 +117,9 @@ export class InteractiveBrowserCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. - * * If the token can't be retrieved silently, this method will always generate a challenge for the user. - * * On Node.js, this credential has [Proof Key for Code Exchange (PKCE)](https://datatracker.ietf.org/doc/html/rfc7636) enabled by default. * PKCE is a security feature that mitigates authentication code interception attacks. - * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * TokenCredential implementation might make. diff --git a/sdk/identity/identity/src/credentials/interactiveBrowserCredentialOptions.ts b/sdk/identity/identity/src/credentials/interactiveBrowserCredentialOptions.ts index 08f78cc5b826..8a9ed894dc2d 100644 --- a/sdk/identity/identity/src/credentials/interactiveBrowserCredentialOptions.ts +++ b/sdk/identity/identity/src/credentials/interactiveBrowserCredentialOptions.ts @@ -81,7 +81,6 @@ export interface InteractiveBrowserCredentialInBrowserOptions extends Interactiv * Specifies whether a redirect or a popup window should be used to * initiate the user authentication flow. Possible values are "redirect" * or "popup" (default) for browser and "popup" (default) for node. - * */ loginStyle?: BrowserLoginStyle; diff --git a/sdk/identity/identity/src/credentials/interactiveCredentialOptions.ts b/sdk/identity/identity/src/credentials/interactiveCredentialOptions.ts index 5a3e046de428..ec805727e1a8 100644 --- a/sdk/identity/identity/src/credentials/interactiveCredentialOptions.ts +++ b/sdk/identity/identity/src/credentials/interactiveCredentialOptions.ts @@ -15,11 +15,8 @@ export interface InteractiveCredentialOptions * Result of a previous authentication that can be used to retrieve the cached credentials of each individual account. * This is necessary to provide in case the application wants to work with more than one account per * Client ID and Tenant ID pair. - * * This record can be retrieved by calling to the credential's `authenticate()` method, as follows: - * * const authenticationRecord = await credential.authenticate(); - * */ authenticationRecord?: AuthenticationRecord; diff --git a/sdk/identity/identity/src/credentials/managedIdentityCredential/imdsMsi.ts b/sdk/identity/identity/src/credentials/managedIdentityCredential/imdsMsi.ts index 74eb496de0f7..1f2e4b09e0f4 100644 --- a/sdk/identity/identity/src/credentials/managedIdentityCredential/imdsMsi.ts +++ b/sdk/identity/identity/src/credentials/managedIdentityCredential/imdsMsi.ts @@ -46,7 +46,6 @@ function prepareInvalidRequestOptions(scopes: string | string[]): PipelineReques /** * Defines how to determine whether the Azure IMDS MSI is available. - * * Actually getting the token once we determine IMDS is available is handled by MSAL. */ export const imdsMsi = { diff --git a/sdk/identity/identity/src/credentials/managedIdentityCredential/imdsRetryPolicy.ts b/sdk/identity/identity/src/credentials/managedIdentityCredential/imdsRetryPolicy.ts index 104a5ee8726b..d31b3e59a0a0 100644 --- a/sdk/identity/identity/src/credentials/managedIdentityCredential/imdsRetryPolicy.ts +++ b/sdk/identity/identity/src/credentials/managedIdentityCredential/imdsRetryPolicy.ts @@ -21,7 +21,6 @@ const MIN_DELAY_FOR_410_MS = 3000; * 404s or 410s, but the IMDS endpoint can return these when the token is not yet available or when * the identity is still being set up. This policy will retry on 404s and 410s with an exponential backoff. * For 410 responses, it uses a minimum 3-second initial delay to ensure at least 70 seconds total duration. - * * @param msiRetryConfig - The retry configuration for the MSI credential. * @returns - The policy that will retry on 404s and 410s. */ diff --git a/sdk/identity/identity/src/credentials/managedIdentityCredential/index.ts b/sdk/identity/identity/src/credentials/managedIdentityCredential/index.ts index 347266228cdb..fa1215512810 100644 --- a/sdk/identity/identity/src/credentials/managedIdentityCredential/index.ts +++ b/sdk/identity/identity/src/credentials/managedIdentityCredential/index.ts @@ -29,7 +29,6 @@ const logger = credentialLogger("ManagedIdentityCredential"); * Attempts authentication using a managed identity available at the deployment environment. * This authentication type works in Azure VMs, App Service instances, Azure Functions applications, * Azure Kubernetes Services, Azure Service Fabric instances and inside of the Azure Cloud Shell. - * * More information about configuring managed identities can be found here: * https://learn.microsoft.com/azure/active-directory/managed-identities-azure-resources/overview */ @@ -49,31 +48,27 @@ export class ManagedIdentityCredential implements TokenCredential { /** * Creates an instance of ManagedIdentityCredential with the client ID of a * user-assigned identity, or app registration (when working with AKS pod-identity). - * * @param clientId - The client ID of the user-assigned identity, or app registration (when working with AKS pod-identity). * @param options - Options for configuring the client which makes the access token request. */ constructor(clientId: string, options?: TokenCredentialOptions); /** * Creates an instance of ManagedIdentityCredential with a client ID - * * @param options - Options for configuring the client which makes the access token request. */ constructor(options?: ManagedIdentityCredentialClientIdOptions); /** * Creates an instance of ManagedIdentityCredential with a resource ID - * * @param options - Options for configuring the resource which makes the access token request. */ constructor(options?: ManagedIdentityCredentialResourceIdOptions); /** * Creates an instance of ManagedIdentityCredential with an object ID - * * @param options - Options for configuring the resource which makes the access token request. */ constructor(options?: ManagedIdentityCredentialObjectIdOptions); /** - * @internal + * @hidden */ constructor( @@ -195,7 +190,6 @@ export class ManagedIdentityCredential implements TokenCredential { * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. * If an unexpected error occurs, an {@link AuthenticationError} will be thrown with the details of the failure. - * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * TokenCredential implementation might make. diff --git a/sdk/identity/identity/src/credentials/managedIdentityCredential/models.ts b/sdk/identity/identity/src/credentials/managedIdentityCredential/models.ts index ae87223f55f2..243cbdbc6d86 100644 --- a/sdk/identity/identity/src/credentials/managedIdentityCredential/models.ts +++ b/sdk/identity/identity/src/credentials/managedIdentityCredential/models.ts @@ -6,7 +6,7 @@ import type { AccessToken } from "@azure/core-auth"; import type { IdentityClient } from "../../client/identityClient.js"; /** - * @internal + */ export interface MSIConfiguration { retryConfig: { @@ -21,7 +21,7 @@ export interface MSIConfiguration { } /** - * @internal + * Represents an access token for {@link ManagedIdentity} for internal usage, * with an expiration time and the time in which token should refresh. */ diff --git a/sdk/identity/identity/src/credentials/managedIdentityCredential/tokenExchangeMsi.ts b/sdk/identity/identity/src/credentials/managedIdentityCredential/tokenExchangeMsi.ts index 62e8285d0a9b..adae6ddaf1ed 100644 --- a/sdk/identity/identity/src/credentials/managedIdentityCredential/tokenExchangeMsi.ts +++ b/sdk/identity/identity/src/credentials/managedIdentityCredential/tokenExchangeMsi.ts @@ -12,7 +12,6 @@ const logger = credentialLogger(msiName); /** * Defines how to determine whether the token exchange MSI is available, and also how to retrieve a token from the token exchange MSI. - * * Token exchange MSI (used by AKS) is the only MSI implementation handled entirely by Azure Identity. * The rest have been migrated to MSAL. */ diff --git a/sdk/identity/identity/src/credentials/managedIdentityCredential/utils.ts b/sdk/identity/identity/src/credentials/managedIdentityCredential/utils.ts index ee974b4a91f4..24bff5f9eb9f 100644 --- a/sdk/identity/identity/src/credentials/managedIdentityCredential/utils.ts +++ b/sdk/identity/identity/src/credentials/managedIdentityCredential/utils.ts @@ -14,7 +14,6 @@ export const serviceFabricErrorMessage = * These are GET requests that require sending a `resource` parameter on the query. * This resource can be derived from the scopes received through the getToken call, as long as only one scope is received. * Multiple scopes assume that the resulting token will have access to multiple resources, which won't be the case. - * * For that reason, when we encounter multiple scopes, we return undefined. * It's up to the individual MSI implementations to throw the errors (which helps us provide less generic errors). */ @@ -39,8 +38,7 @@ export function mapScopesToResource(scopes: string | string[]): string | undefin /** * Internal type roughly matching the raw responses of the authentication endpoints. - * - * @internal + */ export interface TokenResponseParsedBody { access_token?: string; diff --git a/sdk/identity/identity/src/credentials/onBehalfOfCredential.ts b/sdk/identity/identity/src/credentials/onBehalfOfCredential.ts index 4efec098422f..c4677590fb37 100644 --- a/sdk/identity/identity/src/credentials/onBehalfOfCredential.ts +++ b/sdk/identity/identity/src/credentials/onBehalfOfCredential.ts @@ -46,13 +46,10 @@ export class OnBehalfOfCredential implements TokenCredential { * Creates an instance of the {@link OnBehalfOfCredential} with the details * needed to authenticate against Microsoft Entra ID with path to a PEM certificate, * and an user assertion. - * * Example using the `KeyClient` from [\@azure/keyvault-keys](https://www.npmjs.com/package/\@azure/keyvault-keys): - * * ```ts snippet:on_behalf_of_credential_pem_example * import { OnBehalfOfCredential } from "@azure/identity"; * import { KeyClient } from "@azure/keyvault-keys"; - * * const tokenCredential = new OnBehalfOfCredential({ * tenantId: "tenant-id", * clientId: "client-id", @@ -60,10 +57,8 @@ export class OnBehalfOfCredential implements TokenCredential { * userAssertionToken: "access-token", * }); * const client = new KeyClient("vault-url", tokenCredential); - * * await client.getKey("key-name"); * ``` - * * @param options - Optional parameters, generally common across credentials. */ constructor( @@ -75,13 +70,10 @@ export class OnBehalfOfCredential implements TokenCredential { * Creates an instance of the {@link OnBehalfOfCredential} with the details * needed to authenticate against Microsoft Entra ID with a client * secret and an user assertion. - * * Example using the `KeyClient` from [\@azure/keyvault-keys](https://www.npmjs.com/package/\@azure/keyvault-keys): - * * ```ts snippet:on_behalf_of_credential_secret_example * import { OnBehalfOfCredential } from "@azure/identity"; * import { KeyClient } from "@azure/keyvault-keys"; - * * const tokenCredential = new OnBehalfOfCredential({ * tenantId: "tenant-id", * clientId: "client-id", @@ -89,10 +81,8 @@ export class OnBehalfOfCredential implements TokenCredential { * userAssertionToken: "access-token", * }); * const client = new KeyClient("vault-url", tokenCredential); - * * await client.getKey("key-name"); * ``` - * * @param options - Optional parameters, generally common across credentials. */ constructor( @@ -105,13 +95,10 @@ export class OnBehalfOfCredential implements TokenCredential { * Creates an instance of the {@link OnBehalfOfCredential} with the details * needed to authenticate against Microsoft Entra ID with a client `getAssertion` * and an user assertion. - * * Example using the `KeyClient` from [\@azure/keyvault-keys](https://www.npmjs.com/package/\@azure/keyvault-keys): - * * ```ts snippet:on_behalf_of_credential_assertion_example * import { OnBehalfOfCredential } from "@azure/identity"; * import { KeyClient } from "@azure/keyvault-keys"; - * * const tokenCredential = new OnBehalfOfCredential({ * tenantId: "tenant-id", * clientId: "client-id", @@ -121,10 +108,8 @@ export class OnBehalfOfCredential implements TokenCredential { * userAssertionToken: "access-token", * }); * const client = new KeyClient("vault-url", tokenCredential); - * * await client.getKey("key-name"); * ``` - * * @param options - Optional parameters, generally common across credentials. */ constructor( @@ -188,7 +173,6 @@ export class OnBehalfOfCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. - * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure the underlying network requests. */ diff --git a/sdk/identity/identity/src/credentials/usernamePasswordCredential.ts b/sdk/identity/identity/src/credentials/usernamePasswordCredential.ts index 3c872b5d91c4..e1d6460d18ab 100644 --- a/sdk/identity/identity/src/credentials/usernamePasswordCredential.ts +++ b/sdk/identity/identity/src/credentials/usernamePasswordCredential.ts @@ -35,7 +35,6 @@ export class UsernamePasswordCredential implements TokenCredential { * Creates an instance of the UsernamePasswordCredential with the details * needed to authenticate against Microsoft Entra ID with a username * and password. - * * @param tenantId - The Microsoft Entra tenant (directory). * @param clientId - The client (application) ID of an App Registration in the tenant. * @param username - The user account's e-mail address (user name). @@ -90,11 +89,9 @@ export class UsernamePasswordCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. - * * If the user provided the option `disableAutomaticAuthentication`, * once the token can't be retrieved silently, * this method won't attempt to request user interaction to retrieve the token. - * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * TokenCredential implementation might make. diff --git a/sdk/identity/identity/src/credentials/visualStudioCodeCredential.ts b/sdk/identity/identity/src/credentials/visualStudioCodeCredential.ts index 14185b7052f3..ac986ce472ba 100644 --- a/sdk/identity/identity/src/credentials/visualStudioCodeCredential.ts +++ b/sdk/identity/identity/src/credentials/visualStudioCodeCredential.ts @@ -47,11 +47,9 @@ export class VisualStudioCodeCredential implements TokenCredential { /** * Creates an instance of VisualStudioCodeCredential to use for automatically authenticating via VSCode. - * * **Note**: `VisualStudioCodeCredential` is provided by a plugin package: * `@azure/identity-vscode`. If this package is not installed, then authentication using * `VisualStudioCodeCredential` will not be available. - * * @param options - Options for configuring the client which makes the authentication request. */ constructor(options?: VisualStudioCodeCredentialOptions) { @@ -127,7 +125,6 @@ export class VisualStudioCodeCredential implements TokenCredential { /** * Returns the token found by searching VSCode's authentication cache or * returns null if no token could be found. - * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * `TokenCredential` implementation might make. diff --git a/sdk/identity/identity/src/credentials/visualStudioCodeCredentialOptions.ts b/sdk/identity/identity/src/credentials/visualStudioCodeCredentialOptions.ts index d76486fcca64..0ecd2d2e60b3 100644 --- a/sdk/identity/identity/src/credentials/visualStudioCodeCredentialOptions.ts +++ b/sdk/identity/identity/src/credentials/visualStudioCodeCredentialOptions.ts @@ -5,7 +5,6 @@ import type { MultiTenantTokenCredentialOptions } from "./multiTenantTokenCreden /** * Provides options to configure the Visual Studio Code credential. - * */ export interface VisualStudioCodeCredentialOptions extends MultiTenantTokenCredentialOptions { /** diff --git a/sdk/identity/identity/src/credentials/visualStudioCodeCredentialPlugin.ts b/sdk/identity/identity/src/credentials/visualStudioCodeCredentialPlugin.ts index 14daa77caa9e..8c58f76c8655 100644 --- a/sdk/identity/identity/src/credentials/visualStudioCodeCredentialPlugin.ts +++ b/sdk/identity/identity/src/credentials/visualStudioCodeCredentialPlugin.ts @@ -3,9 +3,7 @@ /** * A function that searches for credentials in the Visual Studio Code credential store. - * * @returns an array of credentials (username and password) - * @internal - * + */ export type VSCodeCredentialFinder = () => Promise>; diff --git a/sdk/identity/identity/src/credentials/workloadIdentityCredential.ts b/sdk/identity/identity/src/credentials/workloadIdentityCredential.ts index 766984f532e6..defce3692ce3 100644 --- a/sdk/identity/identity/src/credentials/workloadIdentityCredential.ts +++ b/sdk/identity/identity/src/credentials/workloadIdentityCredential.ts @@ -15,8 +15,7 @@ const credentialName = "WorkloadIdentityCredential"; * Contains the list of all supported environment variable names so that an * appropriate error message can be generated when no credentials can be * configured. - * - * @internal + */ export const SupportedWorkloadEnvironmentVariables = [ "AZURE_TENANT_ID", @@ -46,7 +45,6 @@ export class WorkloadIdentityCredential implements TokenCredential { /** * WorkloadIdentityCredential supports Microsoft Entra Workload ID on Kubernetes. - * * @param options - The identity client options to use for authentication. */ constructor(options?: WorkloadIdentityCredentialOptions) { @@ -97,7 +95,6 @@ export class WorkloadIdentityCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. - * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * TokenCredential implementation might make. diff --git a/sdk/identity/identity/src/errors.ts b/sdk/identity/identity/src/errors.ts index 43d3d8c9c811..200b680f43cc 100644 --- a/sdk/identity/identity/src/errors.ts +++ b/sdk/identity/identity/src/errors.ts @@ -5,9 +5,7 @@ import type { GetTokenOptions } from "@azure/core-auth"; /** * See the official documentation for more details: - * * https://learn.microsoft.com/azure/active-directory/develop/v1-protocols-oauth-code#error-response-1 - * * NOTE: This documentation is for v1 OAuth support but the same error * response details still apply to v2. */ @@ -45,7 +43,6 @@ export interface ErrorResponse { /** * Used for internal deserialization of OAuth responses. Public model is ErrorResponse - * @internal */ export interface OAuthErrorResponse { error: string; diff --git a/sdk/identity/identity/src/msal/browserFlows/msalBrowserCommon.ts b/sdk/identity/identity/src/msal/browserFlows/msalBrowserCommon.ts index 58ed5e292d35..7c1cabdefeb1 100644 --- a/sdk/identity/identity/src/msal/browserFlows/msalBrowserCommon.ts +++ b/sdk/identity/identity/src/msal/browserFlows/msalBrowserCommon.ts @@ -34,7 +34,7 @@ const isLocationDefined = typeof self !== "undefined" && self.location !== undef /** * Generates a MSAL configuration that generally works for browsers - * @internal + */ function generateMsalBrowserConfiguration( options: MsalBrowserFlowOptions, @@ -67,7 +67,7 @@ function generateMsalBrowserConfiguration( /** * Methods that are used by InteractiveBrowserCredential - * @internal + */ export interface MsalBrowserClient { getActiveAccount(): Promise; @@ -80,7 +80,7 @@ const redirectHash = isLocationDefined ? self.location.hash : undefined; /** * Uses MSAL Browser 2.X for browser authentication, * which uses the [Auth Code Flow](https://learn.microsoft.com/azure/active-directory/develop/v2-oauth2-auth-code-flow). - * @internal + */ export function createMsalBrowserClient(options: MsalBrowserFlowOptions): MsalBrowserClient { const loginStyle = options.loginStyle; diff --git a/sdk/identity/identity/src/msal/browserFlows/msalBrowserOptions.ts b/sdk/identity/identity/src/msal/browserFlows/msalBrowserOptions.ts index 9de00f343c36..bd191050f6d2 100644 --- a/sdk/identity/identity/src/msal/browserFlows/msalBrowserOptions.ts +++ b/sdk/identity/identity/src/msal/browserFlows/msalBrowserOptions.ts @@ -9,7 +9,7 @@ import type { CredentialLogger } from "../../util/logging.js"; /** * Options for the MSAL browser flows. - * @internal + */ export interface MsalBrowserFlowOptions { logger: CredentialLogger; @@ -36,11 +36,8 @@ export interface MsalBrowserFlowOptions { * Result of a previous authentication that can be used to retrieve the cached credentials of each individual account. * This is necessary to provide in case the application wants to work with more than one account per * Client ID and Tenant ID pair. - * * This record can be retrieved by calling to the credential's `authenticate()` method, as follows: - * * const authenticationRecord = await credential.authenticate(); - * */ authenticationRecord?: AuthenticationRecord; @@ -75,7 +72,6 @@ export interface MsalBrowserFlowOptions { * Specifies whether a redirect or a popup window should be used to * initiate the user authentication flow. Possible values are "redirect" * or "popup" (default) for browser and "popup" (default) for node. - * */ loginStyle: BrowserLoginStyle; diff --git a/sdk/identity/identity/src/msal/credentials.ts b/sdk/identity/identity/src/msal/credentials.ts index 2922ae54a737..09da2652c97c 100644 --- a/sdk/identity/identity/src/msal/credentials.ts +++ b/sdk/identity/identity/src/msal/credentials.ts @@ -7,7 +7,7 @@ import type { AuthenticationRecord } from "./types.js"; /** * The MSAL clients `getToken` requests can receive a `correlationId` and `disableAutomaticAuthentication`. * (which is used to prevent `getToken` from triggering the manual authentication if `getTokenSilent` fails). - * @internal + */ export interface CredentialFlowGetTokenOptions extends GetTokenOptions { /** @@ -38,7 +38,7 @@ export interface CredentialFlowGetTokenOptions extends GetTokenOptions { /** * Simplified representation of the internal authentication flow. - * @internal + */ export interface CredentialFlow { /** diff --git a/sdk/identity/identity/src/msal/nodeFlows/msalClient.ts b/sdk/identity/identity/src/msal/nodeFlows/msalClient.ts index c836a235fccb..a6038484d3f0 100644 --- a/sdk/identity/identity/src/msal/nodeFlows/msalClient.ts +++ b/sdk/identity/identity/src/msal/nodeFlows/msalClient.ts @@ -42,9 +42,7 @@ const msalLogger = credentialLogger("MsalClient"); export interface GetTokenWithSilentAuthOptions extends GetTokenOptions { /** * Disables automatic authentication. If set to true, the method will throw an error if the user needs to authenticate. - * * @remarks - * * This option will be set to `false` when the user calls `authenticate` directly on a credential that supports it. */ disableAutomaticAuthentication?: boolean; @@ -74,9 +72,7 @@ export interface GetTokenInteractiveOptions extends GetTokenWithSilentAuthOption */ export interface MsalClient { /** - * * Retrieves an access token by using the on-behalf-of flow and a client assertion callback of the calling service. - * * @param scopes - The scopes for which the access token is requested. These represent the resources that the application wants to access. * @param userAssertionToken - The access token that was sent to the middle-tier API. This token must have an audience of the app making this OBO request. * @param clientCredentials - The client secret OR client certificate OR client `getAssertion` callback. @@ -102,7 +98,6 @@ export interface MsalClient { ): Promise; /** * Retrieves an access token by using a user's username and password. - * * @param scopes - The scopes for which the access token is requested. These represent the resources that the application wants to access. * @param username - The username provided by the developer. * @param password - The user's password provided by the developer. @@ -117,7 +112,6 @@ export interface MsalClient { ): Promise; /** * Retrieves an access token by prompting the user to authenticate using a device code. - * * @param scopes - The scopes for which the access token is requested. These represent the resources that the application wants to access. * @param userPromptCallback - The callback function that allows developers to customize the prompt message. * @param options - Additional options that may be provided to the method. @@ -130,7 +124,6 @@ export interface MsalClient { ): Promise; /** * Retrieves an access token by using a client certificate. - * * @param scopes - The scopes for which the access token is requested. These represent the resources that the application wants to access. * @param certificate - The client certificate used for authentication. * @param options - Additional options that may be provided to the method. @@ -144,7 +137,6 @@ export interface MsalClient { /** * Retrieves an access token by using a client assertion. - * * @param scopes - The scopes for which the access token is requested. These represent the resources that the application wants to access. * @param clientAssertion - The client `getAssertion` callback used for authentication. * @param options - Additional options that may be provided to the method. @@ -158,7 +150,6 @@ export interface MsalClient { /** * Retrieves an access token by using a client secret. - * * @param scopes - The scopes for which the access token is requested. These represent the resources that the application wants to access. * @param clientSecret - The client secret of the application. This is a credential that the application can use to authenticate itself. * @param options - Additional options that may be provided to the method. @@ -172,7 +163,6 @@ export interface MsalClient { /** * Retrieves an access token by using an authorization code flow. - * * @param scopes - The scopes for which the access token is requested. These represent the resources that the application wants to access. * @param authorizationCode - An authorization code that was received from following the authorization code flow. This authorization code must not @@ -192,14 +182,12 @@ export interface MsalClient { /** * Retrieves the last authenticated account. This method expects an authentication record to have been previously loaded. - * * An authentication record could be loaded by calling the `getToken` method, or by providing an `authenticationRecord` when creating a credential. */ getActiveAccount(): AuthenticationRecord | undefined; /** * Retrieves an access token using brokered authentication. - * * @param scopes - The scopes for which the access token is requested. These represent the resources that the application wants to access. * @param useDefaultBrokerAccount - Whether to use the default broker account for authentication. * @param options - Additional options that may be provided to the method. @@ -264,7 +252,6 @@ export interface MsalClientOptions { /** * Generates the configuration for MSAL (Microsoft Authentication Library). - * * @param clientId - The client ID of the application. * @param tenantId - The tenant ID of the Azure Active Directory. * @param msalClientOptions - Optional. Additional options for creating the MSAL client. @@ -315,8 +302,7 @@ export function generateMsalConfiguration( /** * Represents the state necessary for the MSAL (Microsoft Authentication Library) client to operate. * This includes the MSAL configuration, cached account information, Azure region, and a flag to disable automatic authentication. - * - * @internal + */ interface MsalClientState { /** The configuration for the MSAL client. */ @@ -337,12 +323,10 @@ interface MsalClientState { /** * Creates an instance of the MSAL (Microsoft Authentication Library) client. - * * @param clientId - The client ID of the application. * @param tenantId - The tenant ID of the Azure Active Directory. * @param createMsalClientOptions - Optional. Additional options for creating the MSAL client. * @returns An instance of the MSAL client. - * * @public */ export function createMsalClient( @@ -487,7 +471,6 @@ export function createMsalClient( /** * Performs silent authentication using MSAL to acquire an access token. * If silent authentication fails, falls back to interactive authentication. - * * @param msalApp - The MSAL application instance. * @param scopes - The scopes for which to acquire the access token. * @param options - The options for acquiring the access token. @@ -769,8 +752,7 @@ export function createMsalClient( /** * Creates a base interactive request configuration for MSAL interactive authentication. * This is shared between interactive and brokered authentication flows. - * - * @internal + */ function createBaseInteractiveRequest( scopes: string[], @@ -792,7 +774,7 @@ export function createMsalClient( } /** - * @internal + */ async function getBrokeredTokenInternal( scopes: string[], @@ -855,7 +837,6 @@ export function createMsalClient( /** * A helper function that supports brokered authentication through the MSAL's public application. - * * When useDefaultBrokerAccount is true, the method will attempt to authenticate using the default broker account. * If the default broker account is not available, the method will fall back to interactive authentication. */ diff --git a/sdk/identity/identity/src/msal/nodeFlows/msalPlugins.ts b/sdk/identity/identity/src/msal/nodeFlows/msalPlugins.ts index 30888fab613e..5344c9d9c603 100644 --- a/sdk/identity/identity/src/msal/nodeFlows/msalPlugins.ts +++ b/sdk/identity/identity/src/msal/nodeFlows/msalPlugins.ts @@ -39,7 +39,6 @@ export interface PluginConfiguration { broker: { /** * True if the broker plugin is enabled and available. False otherwise. - * * It is a bug if this is true and the broker plugin is not available. */ isEnabled: boolean; @@ -64,7 +63,7 @@ export interface PluginConfiguration { /** * The current persistence provider, undefined by default. - * @internal + */ export let persistenceProvider: | ((options?: TokenCachePersistenceOptions) => Promise) @@ -72,7 +71,7 @@ export let persistenceProvider: /** * An object that allows setting the persistence provider. - * @internal + */ export const msalNodeFlowCacheControl = { setPersistence(pluginProvider: Exclude): void { @@ -82,7 +81,7 @@ export const msalNodeFlowCacheControl = { /** * The current native broker provider, undefined by default. - * @internal + */ export let nativeBrokerInfo: | { @@ -92,13 +91,13 @@ export let nativeBrokerInfo: /** * The current VSCode auth record path, undefined by default. - * @internal + */ export let vsCodeAuthRecordPath: string | undefined = undefined; /** * The current VSCode broker, undefined by default. - * @internal + */ export let vsCodeBrokerInfo: | { @@ -116,7 +115,7 @@ export function hasVSCodePlugin(): boolean { /** * An object that allows setting the native broker provider. - * @internal + */ export const msalNodeFlowNativeBrokerControl: NativeBrokerPluginControl = { setNativeBroker(broker): void { @@ -128,7 +127,7 @@ export const msalNodeFlowNativeBrokerControl: NativeBrokerPluginControl = { /** * An object that allows setting the VSCode credential auth record path and broker. - * @internal + */ export const msalNodeFlowVSCodeCredentialControl: VisualStudioCodeCredentialControl = { setVSCodeAuthRecordPath(path: string): void { @@ -143,9 +142,7 @@ export const msalNodeFlowVSCodeCredentialControl: VisualStudioCodeCredentialCont /** * Configures plugins, validating that required plugins are available and enabled. - * * Does not create the plugins themselves, but rather returns the configuration that will be used to create them. - * * @param options - options for creating the MSAL client * @returns plugin configuration */ diff --git a/sdk/identity/identity/src/msal/nodeFlows/tokenCachePersistenceOptions.ts b/sdk/identity/identity/src/msal/nodeFlows/tokenCachePersistenceOptions.ts index 49dbcab25b6b..04d0fc106250 100644 --- a/sdk/identity/identity/src/msal/nodeFlows/tokenCachePersistenceOptions.ts +++ b/sdk/identity/identity/src/msal/nodeFlows/tokenCachePersistenceOptions.ts @@ -11,7 +11,6 @@ export interface TokenCachePersistenceOptions { enabled: boolean; /** * Unique identifier for the persistent token cache. - * * Based on this identifier, the persistence file will be located in any of the following places: * - Darwin: '/Users/user/.IdentityService/' * - Windows 8+: 'C:\\Users\\user\\AppData\\Local\\.IdentityService\\' diff --git a/sdk/identity/identity/src/msal/types.ts b/sdk/identity/identity/src/msal/types.ts index 16f2a6a3c5ec..53821c72c26d 100644 --- a/sdk/identity/identity/src/msal/types.ts +++ b/sdk/identity/identity/src/msal/types.ts @@ -2,13 +2,13 @@ // Licensed under the MIT License. /** - * @internal + */ export type AppType = "public" | "confidential" | "publicFirst" | "confidentialFirst"; /** * The shape we use return the token (and the expiration date). - * @internal + */ export interface MsalToken { accessToken?: string; @@ -23,7 +23,7 @@ export type ValidMsalToken = { [P in keyof MsalToken]-?: NonNullable [message]` - * */ export function credentialLoggerInstance( title: string, @@ -128,12 +125,9 @@ export interface CredentialLogger extends CredentialLoggerInstance { /** * Generates a CredentialLogger, which is a logger declared at the credential's constructor, and used at any point in the credential. * It has all the properties of a CredentialLoggerInstance, plus other logger instances, one per method. - * * It logs with the format: - * * `[title] => [message]` * `[title] => getToken() => [message]` - * */ export function credentialLogger(title: string, log: AzureLogger = logger): CredentialLogger { const credLogger = credentialLoggerInstance(title, undefined, log); diff --git a/sdk/identity/identity/src/util/processMultiTenantRequest.ts b/sdk/identity/identity/src/util/processMultiTenantRequest.ts index 2201e59daa9c..9673b8507e09 100644 --- a/sdk/identity/identity/src/util/processMultiTenantRequest.ts +++ b/sdk/identity/identity/src/util/processMultiTenantRequest.ts @@ -13,7 +13,7 @@ function createConfigurationErrorMessage(tenantId: string): string { * Of getToken contains a tenantId, this functions allows picking this tenantId as the appropriate for authentication, * unless multitenant authentication has been disabled through the AZURE_IDENTITY_DISABLE_MULTITENANTAUTH (on Node.js), * or unless the original tenant Id is `adfs`. - * @internal + */ export function processMultiTenantRequest( tenantId?: string, diff --git a/sdk/identity/identity/src/util/processUtils.ts b/sdk/identity/identity/src/util/processUtils.ts index b37fa8485036..59ed3926eebb 100644 --- a/sdk/identity/identity/src/util/processUtils.ts +++ b/sdk/identity/identity/src/util/processUtils.ts @@ -5,12 +5,12 @@ import childProcess from "node:child_process"; /** * Easy to mock childProcess utils. - * @internal + */ export const processUtils = { /** * Promisifying childProcess.execFile - * @internal + */ execFile( file: string, diff --git a/sdk/identity/identity/src/util/scopeUtils.ts b/sdk/identity/identity/src/util/scopeUtils.ts index 9d158114f660..6b6c8baa59e5 100644 --- a/sdk/identity/identity/src/util/scopeUtils.ts +++ b/sdk/identity/identity/src/util/scopeUtils.ts @@ -6,7 +6,7 @@ import { formatError } from "./logging.js"; /** * Ensures the scopes value is an array. - * @internal + */ export function ensureScopes(scopes: string | string[]): string[] { return Array.isArray(scopes) ? scopes : [scopes]; @@ -14,7 +14,7 @@ export function ensureScopes(scopes: string | string[]): string[] { /** * Throws if the received scope is not valid. - * @internal + */ export function ensureValidScopeForDevTimeCreds(scope: string, logger: CredentialLogger): void { if (!scope.match(/^[0-9a-zA-Z-_.:/]+$/)) { @@ -26,7 +26,7 @@ export function ensureValidScopeForDevTimeCreds(scope: string, logger: Credentia /** * Returns the resource out of a scope. - * @internal + */ export function getScopeResource(scope: string): string { return scope.replace(/\/.default$/, ""); diff --git a/sdk/identity/identity/src/util/subscriptionUtils.ts b/sdk/identity/identity/src/util/subscriptionUtils.ts index f9456e450061..237cf4a3732f 100644 --- a/sdk/identity/identity/src/util/subscriptionUtils.ts +++ b/sdk/identity/identity/src/util/subscriptionUtils.ts @@ -5,7 +5,7 @@ import type { CredentialLogger } from "./logging.js"; import { formatError } from "./logging.js"; /** - * @internal + */ export function checkSubscription(logger: CredentialLogger, subscription: string): void { if (!subscription.match(/^[0-9a-zA-Z-._ ]+$/)) { diff --git a/sdk/identity/identity/src/util/tenantIdUtils.ts b/sdk/identity/identity/src/util/tenantIdUtils.ts index e88f8668a35b..3d987750c100 100644 --- a/sdk/identity/identity/src/util/tenantIdUtils.ts +++ b/sdk/identity/identity/src/util/tenantIdUtils.ts @@ -7,7 +7,7 @@ import { formatError } from "./logging.js"; export { processMultiTenantRequest } from "./processMultiTenantRequest.js"; /** - * @internal + */ export function checkTenantId(logger: CredentialLogger, tenantId: string): void { if (!tenantId.match(/^[0-9a-zA-Z-.]+$/)) { @@ -20,7 +20,7 @@ export function checkTenantId(logger: CredentialLogger, tenantId: string): void } /** - * @internal + */ export function resolveTenantId( logger: CredentialLogger, @@ -41,7 +41,7 @@ export function resolveTenantId( } /** - * @internal + */ export function resolveAdditionallyAllowedTenantIds( additionallyAllowedTenants?: string[], diff --git a/sdk/identity/identity/src/util/tracing.ts b/sdk/identity/identity/src/util/tracing.ts index d25ac092d921..4801878032f9 100644 --- a/sdk/identity/identity/src/util/tracing.ts +++ b/sdk/identity/identity/src/util/tracing.ts @@ -6,7 +6,7 @@ import { createTracingClient } from "@azure/core-tracing"; /** * Creates a span using the global tracer. - * @internal + */ export const tracingClient = createTracingClient({ namespace: "Microsoft.AAD", From 610581030ea529a4675ba673279070bcb1f83732 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 25 Sep 2025 23:24:01 +0000 Subject: [PATCH 3/3] Fix inappropriate @internal tags - remove only from non-exported members Co-authored-by: minhanh-phan <111523473+minhanh-phan@users.noreply.github.com> --- sdk/identity/identity-broker/src/index.ts | 5 +++- .../samples-dev/extension.ts | 2 ++ .../identity-cache-persistence/src/index.ts | 8 ++++++ .../src/platforms.ts | 12 ++++---- .../src/provider.ts | 3 +- .../identity-vscode/samples-dev/extension.ts | 1 + .../identity-vscode/samples-dev/nodeEnv.ts | 3 ++ sdk/identity/identity-vscode/src/index.ts | 9 +++++- .../samples-dev/defaultAzureCredential.ts | 1 + .../typescript/src/defaultAzureCredential.ts | 1 + .../typescript/src/defaultAzureCredential.ts | 1 + .../typescript/src/defaultAzureCredential.ts | 1 + .../identity/src/client/identityClient.ts | 9 +++++- sdk/identity/identity/src/constants.ts | 15 ++++++++++ .../authorizationCodeCredential.ts | 10 ++++++- .../src/credentials/azureCliCredential.ts | 14 +++++++--- .../azureDeveloperCliCredential.ts | 15 +++++++--- .../credentials/azurePipelinesCredential.ts | 2 ++ .../credentials/azurePowerShellCredential.ts | 19 +++++++++---- .../src/credentials/brokerAuthOptions.ts | 1 + .../src/credentials/brokerCredential.ts | 4 +++ .../src/credentials/chainedTokenCredential.ts | 10 +++++++ .../credentials/clientAssertionCredential.ts | 2 ++ .../clientCertificateCredential.ts | 7 +++++ .../src/credentials/clientSecretCredential.ts | 4 +++ .../credentialPersistenceOptions.ts | 5 ++++ .../src/credentials/defaultAzureCredential.ts | 11 +++++++- .../defaultAzureCredentialFunctions.ts | 25 +++++++++++------ .../src/credentials/deviceCodeCredential.ts | 9 ++++++ .../src/credentials/environmentCredential.ts | 10 ++++++- .../interactiveBrowserCredential.ts | 8 ++++++ .../interactiveBrowserCredentialOptions.ts | 1 + .../interactiveCredentialOptions.ts | 3 ++ .../managedIdentityCredential/imdsMsi.ts | 1 + .../imdsRetryPolicy.ts | 1 + .../managedIdentityCredential/index.ts | 8 +++++- .../managedIdentityCredential/models.ts | 4 +-- .../tokenExchangeMsi.ts | 1 + .../managedIdentityCredential/utils.ts | 4 ++- .../src/credentials/onBehalfOfCredential.ts | 16 +++++++++++ .../credentials/usernamePasswordCredential.ts | 3 ++ .../credentials/visualStudioCodeCredential.ts | 3 ++ .../visualStudioCodeCredentialOptions.ts | 1 + .../visualStudioCodeCredentialPlugin.ts | 4 ++- .../credentials/workloadIdentityCredential.ts | 5 +++- sdk/identity/identity/src/errors.ts | 3 ++ .../msal/browserFlows/msalBrowserCommon.ts | 5 ++-- .../msal/browserFlows/msalBrowserOptions.ts | 6 +++- sdk/identity/identity/src/msal/credentials.ts | 4 +-- .../identity/src/msal/nodeFlows/msalClient.ts | 21 ++++++++++++-- .../src/msal/nodeFlows/msalPlugins.ts | 17 ++++++----- .../nodeFlows/tokenCachePersistenceOptions.ts | 1 + sdk/identity/identity/src/msal/types.ts | 10 +++---- sdk/identity/identity/src/msal/utils.ts | 28 +++++++++++-------- sdk/identity/identity/src/plugins/consumer.ts | 6 +++- sdk/identity/identity/src/plugins/provider.ts | 4 ++- .../identity/src/regionalAuthority.ts | 4 ++- sdk/identity/identity/src/tokenProvider.ts | 3 ++ sdk/identity/identity/src/util/logging.ts | 6 ++++ .../src/util/processMultiTenantRequest.ts | 2 +- .../identity/src/util/processUtils.ts | 4 +-- sdk/identity/identity/src/util/scopeUtils.ts | 6 ++-- .../identity/src/util/subscriptionUtils.ts | 2 +- .../identity/src/util/tenantIdUtils.ts | 6 ++-- sdk/identity/identity/src/util/tracing.ts | 2 +- 65 files changed, 336 insertions(+), 86 deletions(-) diff --git a/sdk/identity/identity-broker/src/index.ts b/sdk/identity/identity-broker/src/index.ts index 085ed85c1e96..c8c2b4c99cf9 100644 --- a/sdk/identity/identity-broker/src/index.ts +++ b/sdk/identity/identity-broker/src/index.ts @@ -6,7 +6,6 @@ import { NativeBrokerPlugin } from "@azure/msal-node-extensions"; /** * A subset of the AzurePluginContext provided by \@azure/identity - */ interface AzurePluginContext { nativeBrokerPluginControl: NativeBrokerPluginControl; @@ -22,11 +21,15 @@ interface NativeBrokerPluginControl { * credentials. The plugin API is compatible with `@azure/identity` versions * 4.0.0 and later. Load this plugin using the `useIdentityPlugin` * function, imported from `@azure/identity`. + * * Example: + * * ```ts snippet:using_plugins * import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity"; * import { nativeBrokerPlugin } from "@azure/identity-broker"; + * * useIdentityPlugin(nativeBrokerPlugin); + * * const credential = new InteractiveBrowserCredential({ * brokerOptions: { * enabled: true, diff --git a/sdk/identity/identity-cache-persistence/samples-dev/extension.ts b/sdk/identity/identity-cache-persistence/samples-dev/extension.ts index 678c47141bb0..5c8ea1dfd6da 100644 --- a/sdk/identity/identity-cache-persistence/samples-dev/extension.ts +++ b/sdk/identity/identity-cache-persistence/samples-dev/extension.ts @@ -7,9 +7,11 @@ * through `useIdentityPlugin`, some credentials, such as * `DeviceCodeCredential`, will be able to retrieve tokens from the cache rather * than requesting new tokens from the Microsoft Entra token endpoint. + * * In order to utilize the persistent token cache, the `enabled` property must * be set to `true` within `tokenCachePersistenceOptions` in the credential's * options. + * * @summary import and use the persistence plugin */ diff --git a/sdk/identity/identity-cache-persistence/src/index.ts b/sdk/identity/identity-cache-persistence/src/index.ts index 762b37aa36ca..c012d9dc91b7 100644 --- a/sdk/identity/identity-cache-persistence/src/index.ts +++ b/sdk/identity/identity-cache-persistence/src/index.ts @@ -17,7 +17,9 @@ interface CachePluginControl { } /** * Context options passed to a plugin during initialization. + * * Represents a subset of the context defined in `@azure/identity` + * */ interface AzurePluginContext { cachePluginControl: CachePluginControl; @@ -28,19 +30,25 @@ interface AzurePluginContext { * credentials. The plugin API is compatible with `@azure/identity` versions * 2.0.0 and later. Load this plugin using the `useIdentityPlugin` * function, imported from `@azure/identity`. + * * In order to enable this functionality, you must also pass * `tokenCachePersistenceOptions` to your credential constructors with an * `enabled` property set to true. + * * Example: + * * ```ts snippet:ReadmeSampleDeviceCodeCredential * import { DeviceCodeCredential } from "@azure/identity"; + * * const credential = new DeviceCodeCredential({ * tokenCachePersistenceOptions: { * enabled: true, * }, * }); + * * // We'll use the Microsoft Graph scope as an example * const scope = "https://graph.microsoft.com/.default"; + * * // Print out part of the access token * console.log((await credential.getToken(scope)).token.substring(0, 10), "..."); * ``` diff --git a/sdk/identity/identity-cache-persistence/src/platforms.ts b/sdk/identity/identity-cache-persistence/src/platforms.ts index 4a3c80d007a9..afe22be5e4a6 100644 --- a/sdk/identity/identity-cache-persistence/src/platforms.ts +++ b/sdk/identity/identity-cache-persistence/src/platforms.ts @@ -20,14 +20,13 @@ import type { TokenCachePersistenceOptions } from "@azure/identity"; * - Darwin: '/Users/user/' * - Windows 8+: 'C:\Users\user\AppData\Local' * - Linux: '/home/user/.local/share' - */ const localApplicationDataFolder = process.env.APPDATA?.replace?.(/(.Roaming)*$/, "\\Local") ?? process.env.HOME!; /** * Dictionary of values that we use as default as we discover, pick and enable the persistence layer. - + * @internal */ export const defaultMsalValues = { tokenCache: { @@ -57,13 +56,12 @@ export const defaultMsalValues = { /** * Options that are used by the underlying MSAL cache provider. - + * @internal */ export type MsalPersistenceOptions = Omit; /** * A function that returns a persistent token cache instance. - */ type MsalPersistenceFactory = (options?: MsalPersistenceOptions) => Promise; @@ -72,7 +70,6 @@ type MsalPersistenceFactory = (options?: MsalPersistenceOptions) => Promise' * - Windows 8+: 'C:\Users\user\AppData\Local\.IdentityService\' * - Linux: '/home/user/.IdentityService/' - */ function getPersistencePath(name: string): string { return path.join(defaultMsalValues.tokenCache.directory, name); @@ -80,11 +77,14 @@ function getPersistencePath(name: string): string { /** * Set of the platforms we attempt to deliver persistence on. + * * - On Windows we use DPAPI. * - On OSX (Darwin), we try to use the system's Keychain, otherwise if the property `unsafeAllowUnencryptedStorage` is set to true, we use an unencrypted file. * - On Linux, we try to use the system's Keyring, otherwise if the property `unsafeAllowUnencryptedStorage` is set to true, we use an unencrypted file. + * * Other platforms _are not supported_ at this time. - + * + * @internal */ export const msalPersistencePlatforms: Partial> = { win32: ({ name = defaultMsalValues.tokenCache.name } = {}): Promise => diff --git a/sdk/identity/identity-cache-persistence/src/provider.ts b/sdk/identity/identity-cache-persistence/src/provider.ts index 40241afc7af9..03446da679ed 100644 --- a/sdk/identity/identity-cache-persistence/src/provider.ts +++ b/sdk/identity/identity-cache-persistence/src/provider.ts @@ -9,8 +9,9 @@ import type { ICachePlugin as CachePlugin } from "@azure/msal-node"; /** * This is used to gain access to the underlying Persistence instance, which we use for testing + * * @returns a raw persistence instance - + * @internal */ export async function createPersistence(options: MsalPersistenceOptions): Promise { const persistence = await msalPersistencePlatforms[process.platform]?.(options); diff --git a/sdk/identity/identity-vscode/samples-dev/extension.ts b/sdk/identity/identity-vscode/samples-dev/extension.ts index 3e7080860c84..1fcdeeebe9ba 100644 --- a/sdk/identity/identity-vscode/samples-dev/extension.ts +++ b/sdk/identity/identity-vscode/samples-dev/extension.ts @@ -8,6 +8,7 @@ * credential will simply throw a `CredentialNotFoundError`, and the * `DefaultAzureCredential` will use a different credential, if one is * available. + * * @summary loads the `VisualStudioCodeCredential` plugin and uses it through * `DefaultAzureCredential` */ diff --git a/sdk/identity/identity-vscode/samples-dev/nodeEnv.ts b/sdk/identity/identity-vscode/samples-dev/nodeEnv.ts index 73307cdc8f9d..356a94a79930 100644 --- a/sdk/identity/identity-vscode/samples-dev/nodeEnv.ts +++ b/sdk/identity/identity-vscode/samples-dev/nodeEnv.ts @@ -5,12 +5,15 @@ * This sample shows an example of how to load the `@azure/identity-vscode` * plugin only in certain environments. As an example, we use the NODE_ENV * environment variable to determine whether or not to load the plugin. + * * NOTE: The NODE_ENV environment variable is merely a convention, and you are * responsible for setting it as appropriate, for example, by setting the * variable at runtime: + * * ```bash * $ NODE_ENV="production" node dist/nodeEnv.js * ``` + * * @summary uses NODE_ENV to load the plugin only in development environments * @azsdk-weight -10 */ diff --git a/sdk/identity/identity-vscode/src/index.ts b/sdk/identity/identity-vscode/src/index.ts index bbd7b80ae879..f6c58df7d667 100644 --- a/sdk/identity/identity-vscode/src/index.ts +++ b/sdk/identity/identity-vscode/src/index.ts @@ -17,9 +17,9 @@ interface VSCodeCredentialControl { /** * Context options passed to a plugin during initialization. + * * Plugin authors are responsible for casting their plugin context values * to this type. - */ interface AzurePluginContext { vsCodeCredentialControl: VSCodeCredentialControl; @@ -52,19 +52,26 @@ function findAuthRecordPath(): string | undefined { * and enables it within `@azure/identity`. The plugin API is compatible with * `@azure/identity` versions 4.11.0 and later. Load this plugin using the * `useIdentityPlugin` function, imported from `@azure/identity`. + * * To use this functionality, import `VisualStudioCodeCredential` or * `DefaultAzureCredential` from `@azure/identity`. If this plugin is not * enabled, then `VisualStudioCodeCredential` will throw a * `CredentialUnavailableError`, and `DefaultAzureCredential` will not be able * to use authentication through Visual Studio Code. + * * Example: + * * ```ts snippet:ReadmeSampleVisualStudioCodeCredential * import { useIdentityPlugin, VisualStudioCodeCredential } from "@azure/identity"; * import { vsCodePlugin } from "@azure/identity-vscode"; + * * useIdentityPlugin(vsCodePlugin); + * * const credential = new VisualStudioCodeCredential(); + * * // The graph.microsoft.com scope is used as an example * const scope = "https://graph.microsoft.com/.default"; + * * // Print out part of the access token * console.log((await credential.getToken(scope)).token.substr(0, 10), "..."); * ``` diff --git a/sdk/identity/identity/samples-dev/defaultAzureCredential.ts b/sdk/identity/identity/samples-dev/defaultAzureCredential.ts index 62ed319efafe..a5819a4e86f7 100644 --- a/sdk/identity/identity/samples-dev/defaultAzureCredential.ts +++ b/sdk/identity/identity/samples-dev/defaultAzureCredential.ts @@ -15,6 +15,7 @@ import "dotenv/config"; * The `DefaultAzureCredential` is appropriate for most scenarios where the application is intended to ultimately be run in the Azure Cloud. * This is because the `DefaultAzureCredential` combines credentials commonly used to authenticate when deployed, * with credentials used to authenticate in a development environment. + * * For more information, you may go to our readme: [link](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity#defaultazurecredential) */ diff --git a/sdk/identity/identity/samples/v2/typescript/src/defaultAzureCredential.ts b/sdk/identity/identity/samples/v2/typescript/src/defaultAzureCredential.ts index 827d5e194a6b..135fba853717 100644 --- a/sdk/identity/identity/samples/v2/typescript/src/defaultAzureCredential.ts +++ b/sdk/identity/identity/samples/v2/typescript/src/defaultAzureCredential.ts @@ -15,6 +15,7 @@ require("dotenv").config(); * The `DefaultAzureCredential` is appropriate for most scenarios where the application is intended to ultimately be run in the Azure Cloud. * This is because the `DefaultAzureCredential` combines credentials commonly used to authenticate when deployed, * with credentials used to authenticate in a development environment. + * * For more information, you may go to our readme: [link](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity#defaultazurecredential) */ diff --git a/sdk/identity/identity/samples/v3/typescript/src/defaultAzureCredential.ts b/sdk/identity/identity/samples/v3/typescript/src/defaultAzureCredential.ts index 5a6dc152e134..5ae2ff824883 100644 --- a/sdk/identity/identity/samples/v3/typescript/src/defaultAzureCredential.ts +++ b/sdk/identity/identity/samples/v3/typescript/src/defaultAzureCredential.ts @@ -15,6 +15,7 @@ require("dotenv").config(); * The `DefaultAzureCredential` is appropriate for most scenarios where the application is intended to ultimately be run in the Azure Cloud. * This is because the `DefaultAzureCredential` combines credentials commonly used to authenticate when deployed, * with credentials used to authenticate in a development environment. + * * For more information, you may go to our readme: [link](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity#defaultazurecredential) */ diff --git a/sdk/identity/identity/samples/v4/typescript/src/defaultAzureCredential.ts b/sdk/identity/identity/samples/v4/typescript/src/defaultAzureCredential.ts index 62ed319efafe..a5819a4e86f7 100644 --- a/sdk/identity/identity/samples/v4/typescript/src/defaultAzureCredential.ts +++ b/sdk/identity/identity/samples/v4/typescript/src/defaultAzureCredential.ts @@ -15,6 +15,7 @@ import "dotenv/config"; * The `DefaultAzureCredential` is appropriate for most scenarios where the application is intended to ultimately be run in the Azure Cloud. * This is because the `DefaultAzureCredential` combines credentials commonly used to authenticate when deployed, * with credentials used to authenticate in a development environment. + * * For more information, you may go to our readme: [link](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity#defaultazurecredential) */ diff --git a/sdk/identity/identity/src/client/identityClient.ts b/sdk/identity/identity/src/client/identityClient.ts index 29df8935fb50..2181170ef2f1 100644 --- a/sdk/identity/identity/src/client/identityClient.ts +++ b/sdk/identity/identity/src/client/identityClient.ts @@ -37,6 +37,9 @@ export interface TokenResponse { refreshToken?: string; } +/** + * @internal + */ export function getIdentityClientAuthorityHost(options?: TokenCredentialOptions): string { // The authorityHost can come from options or from the AZURE_AUTHORITY_HOST environment variable. let authorityHost = options?.authorityHost; @@ -52,8 +55,10 @@ export function getIdentityClientAuthorityHost(options?: TokenCredentialOptions) /** * The network module used by the Identity credentials. + * * It allows for credentials to abort any pending request independently of the MSAL flow, * by calling to the `abortRequests()` method. + * */ export class IdentityClient extends ServiceClient implements INetworkModule { public authorityHost: string; @@ -297,7 +302,8 @@ export class IdentityClient extends ServiceClient implements INetworkModule { } /** - + * + * @internal */ getTokenCredentialOptions(): TokenCredentialOptions { return this.tokenCredentialOptions; @@ -305,6 +311,7 @@ export class IdentityClient extends ServiceClient implements INetworkModule { /** * If allowLoggingAccountIdentifiers was set on the constructor options * we try to log the account identifiers by parsing the received access token. + * * The account identifiers we try to log are: * - `appid`: The application or Client Identifier. * - `upn`: User Principal Name. diff --git a/sdk/identity/identity/src/constants.ts b/sdk/identity/identity/src/constants.ts index 30f85332095e..c0e992e45871 100644 --- a/sdk/identity/identity/src/constants.ts +++ b/sdk/identity/identity/src/constants.ts @@ -8,6 +8,7 @@ export const SDK_VERSION = `4.12.1`; /** * The default client ID for authentication + * @internal */ // TODO: temporary - this is the Azure CLI clientID - we'll replace it when // Developer Sign On application is available @@ -16,6 +17,7 @@ export const DeveloperSignOnClientId = "04b07795-8ddb-461a-bbee-02f9e1bf7b46"; /** * The default tenant for authentication + * @internal */ export const DefaultTenantId = "common"; @@ -29,7 +31,9 @@ export enum AzureAuthorityHosts { AzureChina = "https://login.chinacloudapi.cn", /** * Germany-based Azure Authority Host + * * @deprecated Microsoft Cloud Germany was closed on October 29th, 2021. + * * */ AzureGermany = "https://login.microsoftonline.de", /** @@ -43,25 +47,36 @@ export enum AzureAuthorityHosts { } /** + * @internal * The default authority host. */ export const DefaultAuthorityHost = AzureAuthorityHosts.AzurePublicCloud; /** + * @internal * The default environment host for Azure Public Cloud */ export const DefaultAuthority = "login.microsoftonline.com"; /** + * @internal * Allow acquiring tokens for any tenant for multi-tentant auth. */ export const ALL_TENANTS: string[] = ["*"]; +/** + * @internal + */ export const CACHE_CAE_SUFFIX = "cae"; +/** + * @internal + */ export const CACHE_NON_CAE_SUFFIX = "nocae"; /** + * @internal + * * The default name for the cache persistence plugin. * Matches the constant defined in the cache persistence package. */ diff --git a/sdk/identity/identity/src/credentials/authorizationCodeCredential.ts b/sdk/identity/identity/src/credentials/authorizationCodeCredential.ts index 9b28eea24412..44dc18ed4e99 100644 --- a/sdk/identity/identity/src/credentials/authorizationCodeCredential.ts +++ b/sdk/identity/identity/src/credentials/authorizationCodeCredential.ts @@ -20,6 +20,7 @@ const logger = credentialLogger("AuthorizationCodeCredential"); * Enables authentication to Microsoft Entra ID using an authorization code * that was obtained through the authorization code flow, described in more detail * in the Microsoft Entra ID documentation: + * * https://learn.microsoft.com/entra/identity-platform/v2-oauth2-auth-code-flow */ export class AuthorizationCodeCredential implements TokenCredential { @@ -35,10 +36,13 @@ export class AuthorizationCodeCredential implements TokenCredential { * Creates an instance of AuthorizationCodeCredential with the details needed * to request an access token using an authentication that was obtained * from Microsoft Entra ID. + * * It is currently necessary for the user of this credential to initiate * the authorization code flow to obtain an authorization code to be used * with this credential. A full example of this flow is provided here: + * * https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/v2/manual/authorizationCodeSample.ts + * * @param tenantId - The Microsoft Entra tenant (directory) ID or name. * 'common' may be used when dealing with multi-tenant scenarios. * @param clientId - The client (application) ID of an App Registration in the tenant. @@ -62,10 +66,13 @@ export class AuthorizationCodeCredential implements TokenCredential { * Creates an instance of AuthorizationCodeCredential with the details needed * to request an access token using an authentication that was obtained * from Microsoft Entra ID. + * * It is currently necessary for the user of this credential to initiate * the authorization code flow to obtain an authorization code to be used * with this credential. A full example of this flow is provided here: + * * https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/v2/manual/authorizationCodeSample.ts + * * @param tenantId - The Microsoft Entra tenant (directory) ID or name. * 'common' may be used when dealing with multi-tenant scenarios. * @param clientId - The client (application) ID of an App Registration in the tenant. @@ -85,7 +92,7 @@ export class AuthorizationCodeCredential implements TokenCredential { ); /** * @hidden - + * @internal */ constructor( tenantId: string | "common", @@ -127,6 +134,7 @@ export class AuthorizationCodeCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. + * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * TokenCredential implementation might make. diff --git a/sdk/identity/identity/src/credentials/azureCliCredential.ts b/sdk/identity/identity/src/credentials/azureCliCredential.ts index 35a8a78b1ca8..e1c44f4cb194 100644 --- a/sdk/identity/identity/src/credentials/azureCliCredential.ts +++ b/sdk/identity/identity/src/credentials/azureCliCredential.ts @@ -20,7 +20,7 @@ const logger = credentialLogger("AzureCliCredential"); /** * Messages to use when throwing in this credential. - + * @internal */ export const azureCliPublicErrorMessages = { claim: @@ -36,11 +36,11 @@ export const azureCliPublicErrorMessages = { /** * Mockable reference to the CLI credential cliCredentialFunctions - + * @internal */ export const cliCredentialInternals = { /** - + * @internal */ getSafeWorkingDir(): string { if (process.platform === "win32") { @@ -61,7 +61,7 @@ export const cliCredentialInternals = { /** * Gets the access token from Azure CLI * @param resource - The resource to use when getting the token - + * @internal */ async getAzureCliAccessToken( resource: string, @@ -119,8 +119,10 @@ export class AzureCliCredential implements TokenCredential { /** * Creates an instance of the {@link AzureCliCredential}. + * * To use this credential, ensure that you have already logged * in via the 'az' tool using the command "az login" from the commandline. + * * @param options - Options, to optionally allow multi-tenant requests. */ constructor(options?: AzureCliCredentialOptions) { @@ -141,6 +143,7 @@ export class AzureCliCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. + * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * TokenCredential implementation might make. @@ -231,9 +234,12 @@ export class AzureCliCredential implements TokenCredential { /** * Parses the raw JSON response from the Azure CLI into a usable AccessToken object + * * @param rawResponse - The raw JSON response from the Azure CLI * @returns An access token with the expiry time parsed from the raw response + * * The expiryTime of the credential's access token, in milliseconds, is calculated as follows: + * * When available, expires_on (introduced in Azure CLI v2.54.0) will be preferred. Otherwise falls back to expiresOn. */ private parseRawResponse(rawResponse: string): AccessToken { diff --git a/sdk/identity/identity/src/credentials/azureDeveloperCliCredential.ts b/sdk/identity/identity/src/credentials/azureDeveloperCliCredential.ts index 7bf660f07f22..211f0d519acf 100644 --- a/sdk/identity/identity/src/credentials/azureDeveloperCliCredential.ts +++ b/sdk/identity/identity/src/credentials/azureDeveloperCliCredential.ts @@ -18,7 +18,7 @@ const logger = credentialLogger("AzureDeveloperCliCredential"); /** * Messages to use when throwing in this credential. - + * @internal */ export const azureDeveloperCliPublicErrorMessages = { notInstalled: @@ -32,11 +32,11 @@ export const azureDeveloperCliPublicErrorMessages = { /** * Mockable reference to the Developer CLI credential cliCredentialFunctions - + * @internal */ export const developerCliCredentialInternals = { /** - + * @internal */ getSafeWorkingDir(): string { if (process.platform === "win32") { @@ -58,7 +58,7 @@ export const developerCliCredentialInternals = { /** * Gets the access token from Azure Developer CLI * @param scopes - The scopes to use when getting the token - + * @internal */ async getAzdAccessToken( scopes: string[], @@ -118,14 +118,18 @@ export const developerCliCredentialInternals = { * the logged-in user or service principal in the Azure Developer CLI. It acts as the Azure Developer CLI logged in user or * service principal and executes an Azure CLI command underneath to authenticate the application against * Microsoft Entra ID. + * *

Configure AzureDeveloperCliCredential

+ * * To use this credential, the developer needs to authenticate locally in Azure Developer CLI using one of the * commands below: + * *
    *
  1. Run "azd auth login" in Azure Developer CLI to authenticate interactively as a user.
    2. *
  2. Run "azd auth login --client-id clientID --client-secret clientSecret * --tenant-id tenantID" to authenticate as a service principal.
    3. *
+ * * You may need to repeat this process after a certain time period, depending on the refresh token validity in your * organization. Generally, the refresh token validity period is a few weeks to a few months. * AzureDeveloperCliCredential will prompt you to sign in again. @@ -137,8 +141,10 @@ export class AzureDeveloperCliCredential implements TokenCredential { /** * Creates an instance of the {@link AzureDeveloperCliCredential}. + * * To use this credential, ensure that you have already logged * in via the 'azd' tool using the command "azd auth login" from the commandline. + * * @param options - Options, to optionally allow multi-tenant requests. */ constructor(options?: AzureDeveloperCliCredentialOptions) { @@ -155,6 +161,7 @@ export class AzureDeveloperCliCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. + * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * TokenCredential implementation might make. diff --git a/sdk/identity/identity/src/credentials/azurePipelinesCredential.ts b/sdk/identity/identity/src/credentials/azurePipelinesCredential.ts index c301fb8b84a3..b9e5527c1226 100644 --- a/sdk/identity/identity/src/credentials/azurePipelinesCredential.ts +++ b/sdk/identity/identity/src/credentials/azurePipelinesCredential.ts @@ -96,6 +96,7 @@ export class AzurePipelinesCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} or {@link AuthenticationError} will be thrown with the details of the failure. + * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * TokenCredential implementation might make. @@ -120,6 +121,7 @@ export class AzurePipelinesCredential implements TokenCredential { } /** + * * @param oidcRequestUrl - oidc request url * @param systemAccessToken - system access token * @returns OIDC token from Azure Pipelines diff --git a/sdk/identity/identity/src/credentials/azurePowerShellCredential.ts b/sdk/identity/identity/src/credentials/azurePowerShellCredential.ts index 46929aaf7ba5..4afaf5125fc0 100644 --- a/sdk/identity/identity/src/credentials/azurePowerShellCredential.ts +++ b/sdk/identity/identity/src/credentials/azurePowerShellCredential.ts @@ -21,7 +21,8 @@ const isWindows = process.platform === "win32"; /** * Returns a platform-appropriate command name by appending ".exe" on Windows. - + * + * @internal */ export function formatCommand(commandName: string): string { if (isWindows) { @@ -34,7 +35,7 @@ export function formatCommand(commandName: string): string { /** * Receives a list of commands to run, executes them, then returns the outputs. * If anything fails, an error is thrown. - + * @internal */ async function runCommands(commands: string[][], timeout?: number): Promise { const results: string[] = []; @@ -54,7 +55,7 @@ async function runCommands(commands: string[][], timeout?: number): Promise RegExpMatchArray | null = (err: Error /** * The PowerShell commands to be tried, in order. - + * + * @internal */ export const commandStack = [formatCommand("pwsh")]; @@ -105,11 +107,13 @@ export class AzurePowerShellCredential implements TokenCredential { /** * Creates an instance of the {@link AzurePowerShellCredential}. + * * To use this credential: * - Install the Azure Az PowerShell module with: * `Install-Module -Name Az -Scope CurrentUser -Repository PSGallery -Force`. * - You have already logged in to Azure PowerShell using the command * `Connect-AzAccount` from the command line. + * * @param options - Options, to optionally allow multi-tenant requests. */ constructor(options?: AzurePowerShellCredentialOptions) { @@ -202,6 +206,7 @@ export class AzurePowerShellCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If the authentication cannot be performed through PowerShell, a {@link CredentialUnavailableError} will be thrown. + * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this TokenCredential implementation might make. */ @@ -268,6 +273,10 @@ export class AzurePowerShellCredential implements TokenCredential { } } +/** + * + * @internal + */ export async function parseJsonToken( result: string, ): Promise<{ Token: string; ExpiresOn: string }> { diff --git a/sdk/identity/identity/src/credentials/brokerAuthOptions.ts b/sdk/identity/identity/src/credentials/brokerAuthOptions.ts index 06474f0f79b1..ccccb7b14ccf 100644 --- a/sdk/identity/identity/src/credentials/brokerAuthOptions.ts +++ b/sdk/identity/identity/src/credentials/brokerAuthOptions.ts @@ -10,6 +10,7 @@ import type { BrokerOptions } from "../msal/nodeFlows/brokerOptions.js"; export interface BrokerAuthOptions { /** * Options to allow broker authentication when using InteractiveBrowserCredential + * */ brokerOptions?: BrokerOptions; } diff --git a/sdk/identity/identity/src/credentials/brokerCredential.ts b/sdk/identity/identity/src/credentials/brokerCredential.ts index 42d560dcb6f9..835f3dc14808 100644 --- a/sdk/identity/identity/src/credentials/brokerCredential.ts +++ b/sdk/identity/identity/src/credentials/brokerCredential.ts @@ -31,8 +31,10 @@ export class BrokerCredential implements TokenCredential { /** * Creates an instance of BrokerCredential with the required broker options. + * * This credential uses WAM (Web Account Manager) for authentication, which provides * better security and user experience on Windows platforms. + * * @param options - Options for configuring the broker credential, including required broker options. */ constructor( @@ -63,8 +65,10 @@ export class BrokerCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID using WAM broker and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. + * * This method extends the base getToken method to support silentAuthenticationOnly option * when using broker authentication. + * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure the token request, including silentAuthenticationOnly option. */ diff --git a/sdk/identity/identity/src/credentials/chainedTokenCredential.ts b/sdk/identity/identity/src/credentials/chainedTokenCredential.ts index fc5f97e7c461..a21a80d109d9 100644 --- a/sdk/identity/identity/src/credentials/chainedTokenCredential.ts +++ b/sdk/identity/identity/src/credentials/chainedTokenCredential.ts @@ -6,6 +6,9 @@ import { AggregateAuthenticationError, CredentialUnavailableError } from "../err import { credentialLogger, formatError, formatSuccess } from "../util/logging.js"; import { tracingClient } from "../util/tracing.js"; +/** + * @internal + */ export const logger = credentialLogger("ChainedTokenCredential"); /** @@ -18,17 +21,22 @@ export class ChainedTokenCredential implements TokenCredential { /** * Creates an instance of ChainedTokenCredential using the given credentials. + * * @param sources - `TokenCredential` implementations to be tried in order. + * * Example usage: * ```ts snippet:chained_token_credential_example * import { ClientSecretCredential, ChainedTokenCredential } from "@azure/identity"; + * * const tenantId = ""; * const clientId = ""; * const clientSecret = ""; * const anotherClientId = ""; * const anotherSecret = ""; + * * const firstCredential = new ClientSecretCredential(tenantId, clientId, clientSecret); * const secondCredential = new ClientSecretCredential(tenantId, anotherClientId, anotherSecret); + * * const credentialChain = new ChainedTokenCredential(firstCredential, secondCredential); * ``` */ @@ -41,8 +49,10 @@ export class ChainedTokenCredential implements TokenCredential { * `TokenCredential` implementations. Throws an {@link AggregateAuthenticationError} * when one or more credentials throws an {@link AuthenticationError} and * no credentials have returned an access token. + * * This method is called automatically by Azure SDK client libraries. You may call this method * directly, but you must also handle token caching and token refreshing. + * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * `TokenCredential` implementation might make. diff --git a/sdk/identity/identity/src/credentials/clientAssertionCredential.ts b/sdk/identity/identity/src/credentials/clientAssertionCredential.ts index 1976e65e4558..e3b0bc21defc 100644 --- a/sdk/identity/identity/src/credentials/clientAssertionCredential.ts +++ b/sdk/identity/identity/src/credentials/clientAssertionCredential.ts @@ -30,6 +30,7 @@ export class ClientAssertionCredential implements TokenCredential { * Creates an instance of the ClientAssertionCredential with the details * needed to authenticate against Microsoft Entra ID with a client * assertion provided by the developer through the `getAssertion` function parameter. + * * @param tenantId - The Microsoft Entra tenant (directory) ID. * @param clientId - The client (application) ID of an App Registration in the tenant. * @param getAssertion - A function that retrieves the assertion for the credential to use. @@ -75,6 +76,7 @@ export class ClientAssertionCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. + * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * TokenCredential implementation might make. diff --git a/sdk/identity/identity/src/credentials/clientCertificateCredential.ts b/sdk/identity/identity/src/credentials/clientCertificateCredential.ts index f702fa28eb46..641598aa92b0 100644 --- a/sdk/identity/identity/src/credentials/clientCertificateCredential.ts +++ b/sdk/identity/identity/src/credentials/clientCertificateCredential.ts @@ -28,7 +28,9 @@ const logger = credentialLogger(credentialName); * Enables authentication to Microsoft Entra ID using a PEM-encoded * certificate that is assigned to an App Registration. More information * on how to configure certificate authentication can be found here: + * * https://learn.microsoft.com/azure/active-directory/develop/active-directory-certificate-credentials#register-your-certificate-with-azure-ad + * */ export class ClientCertificateCredential implements TokenCredential { private tenantId: string; @@ -40,6 +42,7 @@ export class ClientCertificateCredential implements TokenCredential { /** * Creates an instance of the ClientCertificateCredential with the details * needed to authenticate against Microsoft Entra ID with a certificate. + * * @param tenantId - The Microsoft Entra tenant (directory) ID. * @param clientId - The client (application) ID of an App Registration in the tenant. * @param certificatePath - The path to a PEM-encoded public/private key certificate on the filesystem. @@ -55,6 +58,7 @@ export class ClientCertificateCredential implements TokenCredential { /** * Creates an instance of the ClientCertificateCredential with the details * needed to authenticate against Microsoft Entra ID with a certificate. + * * @param tenantId - The Microsoft Entra tenant (directory) ID. * @param clientId - The client (application) ID of an App Registration in the tenant. * @param configuration - Other parameters required, including the path of the certificate on the filesystem. @@ -70,6 +74,7 @@ export class ClientCertificateCredential implements TokenCredential { /** * Creates an instance of the ClientCertificateCredential with the details * needed to authenticate against Microsoft Entra ID with a certificate. + * * @param tenantId - The Microsoft Entra tenant (directory) ID. * @param clientId - The client (application) ID of an App Registration in the tenant. * @param configuration - Other parameters required, including the PEM-encoded certificate as a string. @@ -130,6 +135,7 @@ export class ClientCertificateCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. + * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * TokenCredential implementation might make. @@ -182,6 +188,7 @@ export class ClientCertificateCredential implements TokenCredential { /** * Parses a certificate into its relevant parts + * * @param certificateConfiguration - The certificate contents or path to the certificate * @param sendCertificateChain - true if the entire certificate chain should be sent for SNI, false otherwise * @returns The parsed certificate parts and the certificate contents diff --git a/sdk/identity/identity/src/credentials/clientSecretCredential.ts b/sdk/identity/identity/src/credentials/clientSecretCredential.ts index d1ae0c4c8a83..6e118f5dbc8e 100644 --- a/sdk/identity/identity/src/credentials/clientSecretCredential.ts +++ b/sdk/identity/identity/src/credentials/clientSecretCredential.ts @@ -21,7 +21,9 @@ const logger = credentialLogger("ClientSecretCredential"); * Enables authentication to Microsoft Entra ID using a client secret * that was generated for an App Registration. More information on how * to configure a client secret can be found here: + * * https://learn.microsoft.com/entra/identity-platform/quickstart-configure-app-access-web-apis#add-credentials-to-your-web-application + * */ export class ClientSecretCredential implements TokenCredential { private tenantId: string; @@ -33,6 +35,7 @@ export class ClientSecretCredential implements TokenCredential { * Creates an instance of the ClientSecretCredential with the details * needed to authenticate against Microsoft Entra ID with a client * secret. + * * @param tenantId - The Microsoft Entra tenant (directory) ID. * @param clientId - The client (application) ID of an App Registration in the tenant. * @param clientSecret - A client secret that was generated for the App Registration. @@ -78,6 +81,7 @@ export class ClientSecretCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. + * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * TokenCredential implementation might make. diff --git a/sdk/identity/identity/src/credentials/credentialPersistenceOptions.ts b/sdk/identity/identity/src/credentials/credentialPersistenceOptions.ts index 2b730a0fba10..cddd3ab71d88 100644 --- a/sdk/identity/identity/src/credentials/credentialPersistenceOptions.ts +++ b/sdk/identity/identity/src/credentials/credentialPersistenceOptions.ts @@ -11,12 +11,17 @@ export interface CredentialPersistenceOptions { /** * Options to provide to the persistence layer (if one is available) when * storing credentials. + * * You must first register a persistence provider plugin. See the * `@azure/identity-cache-persistence` package on NPM. + * * Example: + * * ```ts snippet:credential_persistence_options_example * import { useIdentityPlugin, DeviceCodeCredential } from "@azure/identity"; + * * useIdentityPlugin(cachePersistencePlugin); + * * const credential = new DeviceCodeCredential({ * tokenCachePersistenceOptions: { * enabled: true, diff --git a/sdk/identity/identity/src/credentials/defaultAzureCredential.ts b/sdk/identity/identity/src/credentials/defaultAzureCredential.ts index 5ede670212c2..2a5b4018b517 100644 --- a/sdk/identity/identity/src/credentials/defaultAzureCredential.ts +++ b/sdk/identity/identity/src/credentials/defaultAzureCredential.ts @@ -32,6 +32,7 @@ const logger = credentialLogger("DefaultAzureCredential"); /** * A no-op credential that logs the reason it was skipped if getToken is called. + * @internal */ export class UnavailableDefaultCredential implements TokenCredential { credentialUnavailableErrorMessage: string; @@ -54,7 +55,9 @@ export class UnavailableDefaultCredential implements TokenCredential { * Provides a default {@link ChainedTokenCredential} configuration that works for most * applications that use Azure SDK client libraries. For more information, see * [DefaultAzureCredential overview](https://aka.ms/azsdk/js/identity/credential-chains#use-defaultazurecredential-for-flexibility). + * * The following credential types will be tried, in order: + * * - {@link EnvironmentCredential} * - {@link WorkloadIdentityCredential} * - {@link ManagedIdentityCredential} @@ -63,14 +66,17 @@ export class UnavailableDefaultCredential implements TokenCredential { * - {@link AzurePowerShellCredential} * - {@link AzureDeveloperCliCredential} * - BrokerCredential (a broker-enabled credential that requires \@azure/identity-broker is installed) + * * Consult the documentation of these credential types for more information * on how they attempt authentication. + * * The following example demonstrates how to use the `requiredEnvVars` option to ensure that certain environment variables are set before the `DefaultAzureCredential` is instantiated. * If any of the specified environment variables are missing or empty, an error will be thrown, preventing the application from continuing execution without the necessary configuration. * It also demonstrates how to set the `AZURE_TOKEN_CREDENTIALS` environment variable to control which credentials are included in the chain. * ```ts snippet:defaultazurecredential_requiredEnvVars * import { DefaultAzureCredential } from "@azure/identity"; + * * const credential = new DefaultAzureCredential({ * requiredEnvVars: [ * "AZURE_CLIENT_ID", @@ -84,18 +90,21 @@ export class UnavailableDefaultCredential implements TokenCredential { export class DefaultAzureCredential extends ChainedTokenCredential { /** * Creates an instance of the DefaultAzureCredential class with {@link DefaultAzureCredentialClientIdOptions}. + * * @param options - Optional parameters. See {@link DefaultAzureCredentialClientIdOptions}. */ constructor(options?: DefaultAzureCredentialClientIdOptions); /** * Creates an instance of the DefaultAzureCredential class with {@link DefaultAzureCredentialResourceIdOptions}. + * * @param options - Optional parameters. See {@link DefaultAzureCredentialResourceIdOptions}. */ constructor(options?: DefaultAzureCredentialResourceIdOptions); /** * Creates an instance of the DefaultAzureCredential class with {@link DefaultAzureCredentialOptions}. + * * @param options - Optional parameters. See {@link DefaultAzureCredentialOptions}. */ constructor(options?: DefaultAzureCredentialOptions); @@ -186,7 +195,7 @@ export class DefaultAzureCredential extends ChainedTokenCredential { } /** - * @internal This function checks that all environment variables in `options.requiredEnvVars` are set and non-empty. + * This function checks that all environment variables in `options.requiredEnvVars` are set and non-empty. * If any are missing or empty, it throws an error. */ function validateRequiredEnvVars(options?: DefaultAzureCredentialOptions) { diff --git a/sdk/identity/identity/src/credentials/defaultAzureCredentialFunctions.ts b/sdk/identity/identity/src/credentials/defaultAzureCredentialFunctions.ts index 3d70596c998c..92830e7f63c8 100644 --- a/sdk/identity/identity/src/credentials/defaultAzureCredentialFunctions.ts +++ b/sdk/identity/identity/src/credentials/defaultAzureCredentialFunctions.ts @@ -25,8 +25,10 @@ import { BrokerCredential } from "./brokerCredential.js"; * Creates a {@link BrokerCredential} instance with the provided options. * This credential uses the Windows Authentication Manager (WAM) broker for authentication. * It will only attempt to authenticate silently using the default broker account + * * @param options - Options for configuring the credential. - + * + * @internal */ export function createDefaultBrokerCredential( options: DefaultAzureCredentialOptions = {}, @@ -37,7 +39,8 @@ export function createDefaultBrokerCredential( /** * Creates a {@link VisualStudioCodeCredential} from the provided options. * @param options - Options to configure the credential. - + * + * @internal */ export function createDefaultVisualStudioCodeCredential( options: DefaultAzureCredentialOptions = {}, @@ -48,7 +51,8 @@ export function createDefaultVisualStudioCodeCredential( /** * Creates a {@link ManagedIdentityCredential} from the provided options. * @param options - Options to configure the credential. - + * + * @internal */ export function createDefaultManagedIdentityCredential( options: @@ -106,7 +110,8 @@ export function createDefaultManagedIdentityCredential( /** * Creates a {@link WorkloadIdentityCredential} from the provided options. * @param options - Options to configure the credential. - + * + * @internal */ export function createDefaultWorkloadIdentityCredential( options?: DefaultAzureCredentialOptions | DefaultAzureCredentialClientIdOptions, @@ -143,7 +148,8 @@ export function createDefaultWorkloadIdentityCredential( /** * Creates a {@link AzureDeveloperCliCredential} from the provided options. * @param options - Options to configure the credential. - + * + * @internal */ export function createDefaultAzureDeveloperCliCredential( options: DefaultAzureCredentialOptions = {}, @@ -154,7 +160,8 @@ export function createDefaultAzureDeveloperCliCredential( /** * Creates a {@link AzureCliCredential} from the provided options. * @param options - Options to configure the credential. - + * + * @internal */ export function createDefaultAzureCliCredential( options: DefaultAzureCredentialOptions = {}, @@ -165,7 +172,8 @@ export function createDefaultAzureCliCredential( /** * Creates a {@link AzurePowerShellCredential} from the provided options. * @param options - Options to configure the credential. - + * + * @internal */ export function createDefaultAzurePowershellCredential( options: DefaultAzureCredentialOptions = {}, @@ -176,7 +184,8 @@ export function createDefaultAzurePowershellCredential( /** * Creates an {@link EnvironmentCredential} from the provided options. * @param options - Options to configure the credential. - + * + * @internal */ export function createDefaultEnvironmentCredential( options: DefaultAzureCredentialOptions = {}, diff --git a/sdk/identity/identity/src/credentials/deviceCodeCredential.ts b/sdk/identity/identity/src/credentials/deviceCodeCredential.ts index 5a52721c2e63..85abf5f3ee4c 100644 --- a/sdk/identity/identity/src/credentials/deviceCodeCredential.ts +++ b/sdk/identity/identity/src/credentials/deviceCodeCredential.ts @@ -44,10 +44,14 @@ export class DeviceCodeCredential implements TokenCredential { /** * Creates an instance of DeviceCodeCredential with the details needed * to initiate the device code authorization flow with Microsoft Entra ID. + * * A message will be logged, giving users a code that they can use to authenticate once they go to https://microsoft.com/devicelogin + * * Developers can configure how this message is shown by passing a custom `userPromptCallback`: + * * ```ts snippet:device_code_credential_example * import { DeviceCodeCredential } from "@azure/identity"; + * * const credential = new DeviceCodeCredential({ * tenantId: process.env.AZURE_TENANT_ID, * clientId: process.env.AZURE_CLIENT_ID, @@ -56,6 +60,7 @@ export class DeviceCodeCredential implements TokenCredential { * }, * }); * ``` + * * @param options - Options for configuring the client which makes the authentication requests. */ constructor(options?: DeviceCodeCredentialOptions) { @@ -77,9 +82,11 @@ export class DeviceCodeCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. + * * If the user provided the option `disableAutomaticAuthentication`, * once the token can't be retrieved silently, * this method won't attempt to request user interaction to retrieve the token. + * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * TokenCredential implementation might make. @@ -108,7 +115,9 @@ export class DeviceCodeCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. + * * If the token can't be retrieved silently, this method will always generate a challenge for the user. + * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * TokenCredential implementation might make. diff --git a/sdk/identity/identity/src/credentials/environmentCredential.ts b/sdk/identity/identity/src/credentials/environmentCredential.ts index b2d745a5aee6..d8fc39564b17 100644 --- a/sdk/identity/identity/src/credentials/environmentCredential.ts +++ b/sdk/identity/identity/src/credentials/environmentCredential.ts @@ -16,7 +16,8 @@ import { tracingClient } from "../util/tracing.js"; * Contains the list of all supported environment variable names so that an * appropriate error message can be generated when no credentials can be * configured. - + * + * @internal */ export const AllSupportedEnvironmentVariables = [ "AZURE_TENANT_ID", @@ -59,21 +60,27 @@ export class EnvironmentCredential implements TokenCredential { | UsernamePasswordCredential = undefined; /** * Creates an instance of the EnvironmentCredential class and decides what credential to use depending on the available environment variables. + * * Required environment variables: * - `AZURE_TENANT_ID`: The Microsoft Entra tenant (directory) ID. * - `AZURE_CLIENT_ID`: The client (application) ID of an App Registration in the tenant. + * * If setting the AZURE_TENANT_ID, then you can also set the additionally allowed tenants * - `AZURE_ADDITIONALLY_ALLOWED_TENANTS`: For multi-tenant applications, specifies additional tenants for which the credential may acquire tokens with a single semicolon delimited string. Use * to allow all tenants. + * * Environment variables used for client credential authentication: * - `AZURE_CLIENT_SECRET`: A client secret that was generated for the App Registration. * - `AZURE_CLIENT_CERTIFICATE_PATH`: The path to a PEM certificate to use during the authentication, instead of the client secret. * - `AZURE_CLIENT_CERTIFICATE_PASSWORD`: (optional) password for the certificate file. * - `AZURE_CLIENT_SEND_CERTIFICATE_CHAIN`: (optional) indicates that the certificate chain should be set in x5c header to support subject name / issuer based authentication. + * * Username and password authentication is deprecated, since it doesn't support multifactor authentication (MFA). See https://aka.ms/azsdk/identity/mfa for more details. Users can still provide environment variables for this authentication method: * - `AZURE_USERNAME`: Username to authenticate with. * - `AZURE_PASSWORD`: Password to authenticate with. + * * If the environment variables required to perform the authentication are missing, a {@link CredentialUnavailableError} will be thrown. * If the authentication fails, or if there's an unknown error, an {@link AuthenticationError} will be thrown. + * * @param options - Options for configuring the client which makes the authentication request. */ constructor(options?: EnvironmentCredentialOptions) { @@ -139,6 +146,7 @@ export class EnvironmentCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. + * * @param scopes - The list of scopes for which the token will have access. * @param options - Optional parameters. See {@link GetTokenOptions}. */ diff --git a/sdk/identity/identity/src/credentials/interactiveBrowserCredential.ts b/sdk/identity/identity/src/credentials/interactiveBrowserCredential.ts index 089b2d725606..a582de85f52d 100644 --- a/sdk/identity/identity/src/credentials/interactiveBrowserCredential.ts +++ b/sdk/identity/identity/src/credentials/interactiveBrowserCredential.ts @@ -36,11 +36,14 @@ export class InteractiveBrowserCredential implements TokenCredential { /** * Creates an instance of InteractiveBrowserCredential with the details needed. + * * This credential uses the [Authorization Code Flow](https://learn.microsoft.com/entra/identity-platform/v2-oauth2-auth-code-flow). * On Node.js, it will open a browser window while it listens for a redirect response from the authentication service. * On browsers, it authenticates via popups. The `loginStyle` optional parameter can be set to `redirect` to authenticate by redirecting the user to an Azure secure login page, which then will redirect the user back to the web application where the authentication started. + * * For Node.js, if a `clientId` is provided, the Microsoft Entra application will need to be configured to have a "Mobile and desktop applications" redirect endpoint. * Follow our guide on [setting up Redirect URIs for Desktop apps that calls to web APIs](https://learn.microsoft.com/entra/identity-platform/scenario-desktop-app-registration#redirect-uris). + * * @param options - Options for configuring the client which makes the authentication requests. */ constructor( @@ -84,9 +87,11 @@ export class InteractiveBrowserCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. + * * If the user provided the option `disableAutomaticAuthentication`, * once the token can't be retrieved silently, * this method won't attempt to request user interaction to retrieve the token. + * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * TokenCredential implementation might make. @@ -117,9 +122,12 @@ export class InteractiveBrowserCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. + * * If the token can't be retrieved silently, this method will always generate a challenge for the user. + * * On Node.js, this credential has [Proof Key for Code Exchange (PKCE)](https://datatracker.ietf.org/doc/html/rfc7636) enabled by default. * PKCE is a security feature that mitigates authentication code interception attacks. + * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * TokenCredential implementation might make. diff --git a/sdk/identity/identity/src/credentials/interactiveBrowserCredentialOptions.ts b/sdk/identity/identity/src/credentials/interactiveBrowserCredentialOptions.ts index 8a9ed894dc2d..08f78cc5b826 100644 --- a/sdk/identity/identity/src/credentials/interactiveBrowserCredentialOptions.ts +++ b/sdk/identity/identity/src/credentials/interactiveBrowserCredentialOptions.ts @@ -81,6 +81,7 @@ export interface InteractiveBrowserCredentialInBrowserOptions extends Interactiv * Specifies whether a redirect or a popup window should be used to * initiate the user authentication flow. Possible values are "redirect" * or "popup" (default) for browser and "popup" (default) for node. + * */ loginStyle?: BrowserLoginStyle; diff --git a/sdk/identity/identity/src/credentials/interactiveCredentialOptions.ts b/sdk/identity/identity/src/credentials/interactiveCredentialOptions.ts index ec805727e1a8..5a3e046de428 100644 --- a/sdk/identity/identity/src/credentials/interactiveCredentialOptions.ts +++ b/sdk/identity/identity/src/credentials/interactiveCredentialOptions.ts @@ -15,8 +15,11 @@ export interface InteractiveCredentialOptions * Result of a previous authentication that can be used to retrieve the cached credentials of each individual account. * This is necessary to provide in case the application wants to work with more than one account per * Client ID and Tenant ID pair. + * * This record can be retrieved by calling to the credential's `authenticate()` method, as follows: + * * const authenticationRecord = await credential.authenticate(); + * */ authenticationRecord?: AuthenticationRecord; diff --git a/sdk/identity/identity/src/credentials/managedIdentityCredential/imdsMsi.ts b/sdk/identity/identity/src/credentials/managedIdentityCredential/imdsMsi.ts index 1f2e4b09e0f4..74eb496de0f7 100644 --- a/sdk/identity/identity/src/credentials/managedIdentityCredential/imdsMsi.ts +++ b/sdk/identity/identity/src/credentials/managedIdentityCredential/imdsMsi.ts @@ -46,6 +46,7 @@ function prepareInvalidRequestOptions(scopes: string | string[]): PipelineReques /** * Defines how to determine whether the Azure IMDS MSI is available. + * * Actually getting the token once we determine IMDS is available is handled by MSAL. */ export const imdsMsi = { diff --git a/sdk/identity/identity/src/credentials/managedIdentityCredential/imdsRetryPolicy.ts b/sdk/identity/identity/src/credentials/managedIdentityCredential/imdsRetryPolicy.ts index d31b3e59a0a0..104a5ee8726b 100644 --- a/sdk/identity/identity/src/credentials/managedIdentityCredential/imdsRetryPolicy.ts +++ b/sdk/identity/identity/src/credentials/managedIdentityCredential/imdsRetryPolicy.ts @@ -21,6 +21,7 @@ const MIN_DELAY_FOR_410_MS = 3000; * 404s or 410s, but the IMDS endpoint can return these when the token is not yet available or when * the identity is still being set up. This policy will retry on 404s and 410s with an exponential backoff. * For 410 responses, it uses a minimum 3-second initial delay to ensure at least 70 seconds total duration. + * * @param msiRetryConfig - The retry configuration for the MSI credential. * @returns - The policy that will retry on 404s and 410s. */ diff --git a/sdk/identity/identity/src/credentials/managedIdentityCredential/index.ts b/sdk/identity/identity/src/credentials/managedIdentityCredential/index.ts index fa1215512810..347266228cdb 100644 --- a/sdk/identity/identity/src/credentials/managedIdentityCredential/index.ts +++ b/sdk/identity/identity/src/credentials/managedIdentityCredential/index.ts @@ -29,6 +29,7 @@ const logger = credentialLogger("ManagedIdentityCredential"); * Attempts authentication using a managed identity available at the deployment environment. * This authentication type works in Azure VMs, App Service instances, Azure Functions applications, * Azure Kubernetes Services, Azure Service Fabric instances and inside of the Azure Cloud Shell. + * * More information about configuring managed identities can be found here: * https://learn.microsoft.com/azure/active-directory/managed-identities-azure-resources/overview */ @@ -48,27 +49,31 @@ export class ManagedIdentityCredential implements TokenCredential { /** * Creates an instance of ManagedIdentityCredential with the client ID of a * user-assigned identity, or app registration (when working with AKS pod-identity). + * * @param clientId - The client ID of the user-assigned identity, or app registration (when working with AKS pod-identity). * @param options - Options for configuring the client which makes the access token request. */ constructor(clientId: string, options?: TokenCredentialOptions); /** * Creates an instance of ManagedIdentityCredential with a client ID + * * @param options - Options for configuring the client which makes the access token request. */ constructor(options?: ManagedIdentityCredentialClientIdOptions); /** * Creates an instance of ManagedIdentityCredential with a resource ID + * * @param options - Options for configuring the resource which makes the access token request. */ constructor(options?: ManagedIdentityCredentialResourceIdOptions); /** * Creates an instance of ManagedIdentityCredential with an object ID + * * @param options - Options for configuring the resource which makes the access token request. */ constructor(options?: ManagedIdentityCredentialObjectIdOptions); /** - + * @internal * @hidden */ constructor( @@ -190,6 +195,7 @@ export class ManagedIdentityCredential implements TokenCredential { * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. * If an unexpected error occurs, an {@link AuthenticationError} will be thrown with the details of the failure. + * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * TokenCredential implementation might make. diff --git a/sdk/identity/identity/src/credentials/managedIdentityCredential/models.ts b/sdk/identity/identity/src/credentials/managedIdentityCredential/models.ts index 243cbdbc6d86..ae87223f55f2 100644 --- a/sdk/identity/identity/src/credentials/managedIdentityCredential/models.ts +++ b/sdk/identity/identity/src/credentials/managedIdentityCredential/models.ts @@ -6,7 +6,7 @@ import type { AccessToken } from "@azure/core-auth"; import type { IdentityClient } from "../../client/identityClient.js"; /** - + * @internal */ export interface MSIConfiguration { retryConfig: { @@ -21,7 +21,7 @@ export interface MSIConfiguration { } /** - + * @internal * Represents an access token for {@link ManagedIdentity} for internal usage, * with an expiration time and the time in which token should refresh. */ diff --git a/sdk/identity/identity/src/credentials/managedIdentityCredential/tokenExchangeMsi.ts b/sdk/identity/identity/src/credentials/managedIdentityCredential/tokenExchangeMsi.ts index adae6ddaf1ed..62e8285d0a9b 100644 --- a/sdk/identity/identity/src/credentials/managedIdentityCredential/tokenExchangeMsi.ts +++ b/sdk/identity/identity/src/credentials/managedIdentityCredential/tokenExchangeMsi.ts @@ -12,6 +12,7 @@ const logger = credentialLogger(msiName); /** * Defines how to determine whether the token exchange MSI is available, and also how to retrieve a token from the token exchange MSI. + * * Token exchange MSI (used by AKS) is the only MSI implementation handled entirely by Azure Identity. * The rest have been migrated to MSAL. */ diff --git a/sdk/identity/identity/src/credentials/managedIdentityCredential/utils.ts b/sdk/identity/identity/src/credentials/managedIdentityCredential/utils.ts index 24bff5f9eb9f..ee974b4a91f4 100644 --- a/sdk/identity/identity/src/credentials/managedIdentityCredential/utils.ts +++ b/sdk/identity/identity/src/credentials/managedIdentityCredential/utils.ts @@ -14,6 +14,7 @@ export const serviceFabricErrorMessage = * These are GET requests that require sending a `resource` parameter on the query. * This resource can be derived from the scopes received through the getToken call, as long as only one scope is received. * Multiple scopes assume that the resulting token will have access to multiple resources, which won't be the case. + * * For that reason, when we encounter multiple scopes, we return undefined. * It's up to the individual MSI implementations to throw the errors (which helps us provide less generic errors). */ @@ -38,7 +39,8 @@ export function mapScopesToResource(scopes: string | string[]): string | undefin /** * Internal type roughly matching the raw responses of the authentication endpoints. - + * + * @internal */ export interface TokenResponseParsedBody { access_token?: string; diff --git a/sdk/identity/identity/src/credentials/onBehalfOfCredential.ts b/sdk/identity/identity/src/credentials/onBehalfOfCredential.ts index c4677590fb37..4efec098422f 100644 --- a/sdk/identity/identity/src/credentials/onBehalfOfCredential.ts +++ b/sdk/identity/identity/src/credentials/onBehalfOfCredential.ts @@ -46,10 +46,13 @@ export class OnBehalfOfCredential implements TokenCredential { * Creates an instance of the {@link OnBehalfOfCredential} with the details * needed to authenticate against Microsoft Entra ID with path to a PEM certificate, * and an user assertion. + * * Example using the `KeyClient` from [\@azure/keyvault-keys](https://www.npmjs.com/package/\@azure/keyvault-keys): + * * ```ts snippet:on_behalf_of_credential_pem_example * import { OnBehalfOfCredential } from "@azure/identity"; * import { KeyClient } from "@azure/keyvault-keys"; + * * const tokenCredential = new OnBehalfOfCredential({ * tenantId: "tenant-id", * clientId: "client-id", @@ -57,8 +60,10 @@ export class OnBehalfOfCredential implements TokenCredential { * userAssertionToken: "access-token", * }); * const client = new KeyClient("vault-url", tokenCredential); + * * await client.getKey("key-name"); * ``` + * * @param options - Optional parameters, generally common across credentials. */ constructor( @@ -70,10 +75,13 @@ export class OnBehalfOfCredential implements TokenCredential { * Creates an instance of the {@link OnBehalfOfCredential} with the details * needed to authenticate against Microsoft Entra ID with a client * secret and an user assertion. + * * Example using the `KeyClient` from [\@azure/keyvault-keys](https://www.npmjs.com/package/\@azure/keyvault-keys): + * * ```ts snippet:on_behalf_of_credential_secret_example * import { OnBehalfOfCredential } from "@azure/identity"; * import { KeyClient } from "@azure/keyvault-keys"; + * * const tokenCredential = new OnBehalfOfCredential({ * tenantId: "tenant-id", * clientId: "client-id", @@ -81,8 +89,10 @@ export class OnBehalfOfCredential implements TokenCredential { * userAssertionToken: "access-token", * }); * const client = new KeyClient("vault-url", tokenCredential); + * * await client.getKey("key-name"); * ``` + * * @param options - Optional parameters, generally common across credentials. */ constructor( @@ -95,10 +105,13 @@ export class OnBehalfOfCredential implements TokenCredential { * Creates an instance of the {@link OnBehalfOfCredential} with the details * needed to authenticate against Microsoft Entra ID with a client `getAssertion` * and an user assertion. + * * Example using the `KeyClient` from [\@azure/keyvault-keys](https://www.npmjs.com/package/\@azure/keyvault-keys): + * * ```ts snippet:on_behalf_of_credential_assertion_example * import { OnBehalfOfCredential } from "@azure/identity"; * import { KeyClient } from "@azure/keyvault-keys"; + * * const tokenCredential = new OnBehalfOfCredential({ * tenantId: "tenant-id", * clientId: "client-id", @@ -108,8 +121,10 @@ export class OnBehalfOfCredential implements TokenCredential { * userAssertionToken: "access-token", * }); * const client = new KeyClient("vault-url", tokenCredential); + * * await client.getKey("key-name"); * ``` + * * @param options - Optional parameters, generally common across credentials. */ constructor( @@ -173,6 +188,7 @@ export class OnBehalfOfCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. + * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure the underlying network requests. */ diff --git a/sdk/identity/identity/src/credentials/usernamePasswordCredential.ts b/sdk/identity/identity/src/credentials/usernamePasswordCredential.ts index e1d6460d18ab..3c872b5d91c4 100644 --- a/sdk/identity/identity/src/credentials/usernamePasswordCredential.ts +++ b/sdk/identity/identity/src/credentials/usernamePasswordCredential.ts @@ -35,6 +35,7 @@ export class UsernamePasswordCredential implements TokenCredential { * Creates an instance of the UsernamePasswordCredential with the details * needed to authenticate against Microsoft Entra ID with a username * and password. + * * @param tenantId - The Microsoft Entra tenant (directory). * @param clientId - The client (application) ID of an App Registration in the tenant. * @param username - The user account's e-mail address (user name). @@ -89,9 +90,11 @@ export class UsernamePasswordCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. + * * If the user provided the option `disableAutomaticAuthentication`, * once the token can't be retrieved silently, * this method won't attempt to request user interaction to retrieve the token. + * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * TokenCredential implementation might make. diff --git a/sdk/identity/identity/src/credentials/visualStudioCodeCredential.ts b/sdk/identity/identity/src/credentials/visualStudioCodeCredential.ts index ac986ce472ba..14185b7052f3 100644 --- a/sdk/identity/identity/src/credentials/visualStudioCodeCredential.ts +++ b/sdk/identity/identity/src/credentials/visualStudioCodeCredential.ts @@ -47,9 +47,11 @@ export class VisualStudioCodeCredential implements TokenCredential { /** * Creates an instance of VisualStudioCodeCredential to use for automatically authenticating via VSCode. + * * **Note**: `VisualStudioCodeCredential` is provided by a plugin package: * `@azure/identity-vscode`. If this package is not installed, then authentication using * `VisualStudioCodeCredential` will not be available. + * * @param options - Options for configuring the client which makes the authentication request. */ constructor(options?: VisualStudioCodeCredentialOptions) { @@ -125,6 +127,7 @@ export class VisualStudioCodeCredential implements TokenCredential { /** * Returns the token found by searching VSCode's authentication cache or * returns null if no token could be found. + * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * `TokenCredential` implementation might make. diff --git a/sdk/identity/identity/src/credentials/visualStudioCodeCredentialOptions.ts b/sdk/identity/identity/src/credentials/visualStudioCodeCredentialOptions.ts index 0ecd2d2e60b3..d76486fcca64 100644 --- a/sdk/identity/identity/src/credentials/visualStudioCodeCredentialOptions.ts +++ b/sdk/identity/identity/src/credentials/visualStudioCodeCredentialOptions.ts @@ -5,6 +5,7 @@ import type { MultiTenantTokenCredentialOptions } from "./multiTenantTokenCreden /** * Provides options to configure the Visual Studio Code credential. + * */ export interface VisualStudioCodeCredentialOptions extends MultiTenantTokenCredentialOptions { /** diff --git a/sdk/identity/identity/src/credentials/visualStudioCodeCredentialPlugin.ts b/sdk/identity/identity/src/credentials/visualStudioCodeCredentialPlugin.ts index 8c58f76c8655..14daa77caa9e 100644 --- a/sdk/identity/identity/src/credentials/visualStudioCodeCredentialPlugin.ts +++ b/sdk/identity/identity/src/credentials/visualStudioCodeCredentialPlugin.ts @@ -3,7 +3,9 @@ /** * A function that searches for credentials in the Visual Studio Code credential store. + * * @returns an array of credentials (username and password) - + * @internal + * */ export type VSCodeCredentialFinder = () => Promise>; diff --git a/sdk/identity/identity/src/credentials/workloadIdentityCredential.ts b/sdk/identity/identity/src/credentials/workloadIdentityCredential.ts index defce3692ce3..766984f532e6 100644 --- a/sdk/identity/identity/src/credentials/workloadIdentityCredential.ts +++ b/sdk/identity/identity/src/credentials/workloadIdentityCredential.ts @@ -15,7 +15,8 @@ const credentialName = "WorkloadIdentityCredential"; * Contains the list of all supported environment variable names so that an * appropriate error message can be generated when no credentials can be * configured. - + * + * @internal */ export const SupportedWorkloadEnvironmentVariables = [ "AZURE_TENANT_ID", @@ -45,6 +46,7 @@ export class WorkloadIdentityCredential implements TokenCredential { /** * WorkloadIdentityCredential supports Microsoft Entra Workload ID on Kubernetes. + * * @param options - The identity client options to use for authentication. */ constructor(options?: WorkloadIdentityCredentialOptions) { @@ -95,6 +97,7 @@ export class WorkloadIdentityCredential implements TokenCredential { /** * Authenticates with Microsoft Entra ID and returns an access token if successful. * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure. + * * @param scopes - The list of scopes for which the token will have access. * @param options - The options used to configure any requests this * TokenCredential implementation might make. diff --git a/sdk/identity/identity/src/errors.ts b/sdk/identity/identity/src/errors.ts index 200b680f43cc..43d3d8c9c811 100644 --- a/sdk/identity/identity/src/errors.ts +++ b/sdk/identity/identity/src/errors.ts @@ -5,7 +5,9 @@ import type { GetTokenOptions } from "@azure/core-auth"; /** * See the official documentation for more details: + * * https://learn.microsoft.com/azure/active-directory/develop/v1-protocols-oauth-code#error-response-1 + * * NOTE: This documentation is for v1 OAuth support but the same error * response details still apply to v2. */ @@ -43,6 +45,7 @@ export interface ErrorResponse { /** * Used for internal deserialization of OAuth responses. Public model is ErrorResponse + * @internal */ export interface OAuthErrorResponse { error: string; diff --git a/sdk/identity/identity/src/msal/browserFlows/msalBrowserCommon.ts b/sdk/identity/identity/src/msal/browserFlows/msalBrowserCommon.ts index 7c1cabdefeb1..a4c19ff35d54 100644 --- a/sdk/identity/identity/src/msal/browserFlows/msalBrowserCommon.ts +++ b/sdk/identity/identity/src/msal/browserFlows/msalBrowserCommon.ts @@ -34,7 +34,6 @@ const isLocationDefined = typeof self !== "undefined" && self.location !== undef /** * Generates a MSAL configuration that generally works for browsers - */ function generateMsalBrowserConfiguration( options: MsalBrowserFlowOptions, @@ -67,7 +66,7 @@ function generateMsalBrowserConfiguration( /** * Methods that are used by InteractiveBrowserCredential - + * @internal */ export interface MsalBrowserClient { getActiveAccount(): Promise; @@ -80,7 +79,7 @@ const redirectHash = isLocationDefined ? self.location.hash : undefined; /** * Uses MSAL Browser 2.X for browser authentication, * which uses the [Auth Code Flow](https://learn.microsoft.com/azure/active-directory/develop/v2-oauth2-auth-code-flow). - + * @internal */ export function createMsalBrowserClient(options: MsalBrowserFlowOptions): MsalBrowserClient { const loginStyle = options.loginStyle; diff --git a/sdk/identity/identity/src/msal/browserFlows/msalBrowserOptions.ts b/sdk/identity/identity/src/msal/browserFlows/msalBrowserOptions.ts index bd191050f6d2..9de00f343c36 100644 --- a/sdk/identity/identity/src/msal/browserFlows/msalBrowserOptions.ts +++ b/sdk/identity/identity/src/msal/browserFlows/msalBrowserOptions.ts @@ -9,7 +9,7 @@ import type { CredentialLogger } from "../../util/logging.js"; /** * Options for the MSAL browser flows. - + * @internal */ export interface MsalBrowserFlowOptions { logger: CredentialLogger; @@ -36,8 +36,11 @@ export interface MsalBrowserFlowOptions { * Result of a previous authentication that can be used to retrieve the cached credentials of each individual account. * This is necessary to provide in case the application wants to work with more than one account per * Client ID and Tenant ID pair. + * * This record can be retrieved by calling to the credential's `authenticate()` method, as follows: + * * const authenticationRecord = await credential.authenticate(); + * */ authenticationRecord?: AuthenticationRecord; @@ -72,6 +75,7 @@ export interface MsalBrowserFlowOptions { * Specifies whether a redirect or a popup window should be used to * initiate the user authentication flow. Possible values are "redirect" * or "popup" (default) for browser and "popup" (default) for node. + * */ loginStyle: BrowserLoginStyle; diff --git a/sdk/identity/identity/src/msal/credentials.ts b/sdk/identity/identity/src/msal/credentials.ts index 09da2652c97c..2922ae54a737 100644 --- a/sdk/identity/identity/src/msal/credentials.ts +++ b/sdk/identity/identity/src/msal/credentials.ts @@ -7,7 +7,7 @@ import type { AuthenticationRecord } from "./types.js"; /** * The MSAL clients `getToken` requests can receive a `correlationId` and `disableAutomaticAuthentication`. * (which is used to prevent `getToken` from triggering the manual authentication if `getTokenSilent` fails). - + * @internal */ export interface CredentialFlowGetTokenOptions extends GetTokenOptions { /** @@ -38,7 +38,7 @@ export interface CredentialFlowGetTokenOptions extends GetTokenOptions { /** * Simplified representation of the internal authentication flow. - + * @internal */ export interface CredentialFlow { /** diff --git a/sdk/identity/identity/src/msal/nodeFlows/msalClient.ts b/sdk/identity/identity/src/msal/nodeFlows/msalClient.ts index a6038484d3f0..b277e8bdd0b8 100644 --- a/sdk/identity/identity/src/msal/nodeFlows/msalClient.ts +++ b/sdk/identity/identity/src/msal/nodeFlows/msalClient.ts @@ -42,7 +42,9 @@ const msalLogger = credentialLogger("MsalClient"); export interface GetTokenWithSilentAuthOptions extends GetTokenOptions { /** * Disables automatic authentication. If set to true, the method will throw an error if the user needs to authenticate. + * * @remarks + * * This option will be set to `false` when the user calls `authenticate` directly on a credential that supports it. */ disableAutomaticAuthentication?: boolean; @@ -72,7 +74,9 @@ export interface GetTokenInteractiveOptions extends GetTokenWithSilentAuthOption */ export interface MsalClient { /** + * * Retrieves an access token by using the on-behalf-of flow and a client assertion callback of the calling service. + * * @param scopes - The scopes for which the access token is requested. These represent the resources that the application wants to access. * @param userAssertionToken - The access token that was sent to the middle-tier API. This token must have an audience of the app making this OBO request. * @param clientCredentials - The client secret OR client certificate OR client `getAssertion` callback. @@ -98,6 +102,7 @@ export interface MsalClient { ): Promise; /** * Retrieves an access token by using a user's username and password. + * * @param scopes - The scopes for which the access token is requested. These represent the resources that the application wants to access. * @param username - The username provided by the developer. * @param password - The user's password provided by the developer. @@ -112,6 +117,7 @@ export interface MsalClient { ): Promise; /** * Retrieves an access token by prompting the user to authenticate using a device code. + * * @param scopes - The scopes for which the access token is requested. These represent the resources that the application wants to access. * @param userPromptCallback - The callback function that allows developers to customize the prompt message. * @param options - Additional options that may be provided to the method. @@ -124,6 +130,7 @@ export interface MsalClient { ): Promise; /** * Retrieves an access token by using a client certificate. + * * @param scopes - The scopes for which the access token is requested. These represent the resources that the application wants to access. * @param certificate - The client certificate used for authentication. * @param options - Additional options that may be provided to the method. @@ -137,6 +144,7 @@ export interface MsalClient { /** * Retrieves an access token by using a client assertion. + * * @param scopes - The scopes for which the access token is requested. These represent the resources that the application wants to access. * @param clientAssertion - The client `getAssertion` callback used for authentication. * @param options - Additional options that may be provided to the method. @@ -150,6 +158,7 @@ export interface MsalClient { /** * Retrieves an access token by using a client secret. + * * @param scopes - The scopes for which the access token is requested. These represent the resources that the application wants to access. * @param clientSecret - The client secret of the application. This is a credential that the application can use to authenticate itself. * @param options - Additional options that may be provided to the method. @@ -163,6 +172,7 @@ export interface MsalClient { /** * Retrieves an access token by using an authorization code flow. + * * @param scopes - The scopes for which the access token is requested. These represent the resources that the application wants to access. * @param authorizationCode - An authorization code that was received from following the authorization code flow. This authorization code must not @@ -182,12 +192,14 @@ export interface MsalClient { /** * Retrieves the last authenticated account. This method expects an authentication record to have been previously loaded. + * * An authentication record could be loaded by calling the `getToken` method, or by providing an `authenticationRecord` when creating a credential. */ getActiveAccount(): AuthenticationRecord | undefined; /** * Retrieves an access token using brokered authentication. + * * @param scopes - The scopes for which the access token is requested. These represent the resources that the application wants to access. * @param useDefaultBrokerAccount - Whether to use the default broker account for authentication. * @param options - Additional options that may be provided to the method. @@ -252,6 +264,7 @@ export interface MsalClientOptions { /** * Generates the configuration for MSAL (Microsoft Authentication Library). + * * @param clientId - The client ID of the application. * @param tenantId - The tenant ID of the Azure Active Directory. * @param msalClientOptions - Optional. Additional options for creating the MSAL client. @@ -302,7 +315,6 @@ export function generateMsalConfiguration( /** * Represents the state necessary for the MSAL (Microsoft Authentication Library) client to operate. * This includes the MSAL configuration, cached account information, Azure region, and a flag to disable automatic authentication. - */ interface MsalClientState { /** The configuration for the MSAL client. */ @@ -323,10 +335,12 @@ interface MsalClientState { /** * Creates an instance of the MSAL (Microsoft Authentication Library) client. + * * @param clientId - The client ID of the application. * @param tenantId - The tenant ID of the Azure Active Directory. * @param createMsalClientOptions - Optional. Additional options for creating the MSAL client. * @returns An instance of the MSAL client. + * * @public */ export function createMsalClient( @@ -471,6 +485,7 @@ export function createMsalClient( /** * Performs silent authentication using MSAL to acquire an access token. * If silent authentication fails, falls back to interactive authentication. + * * @param msalApp - The MSAL application instance. * @param scopes - The scopes for which to acquire the access token. * @param options - The options for acquiring the access token. @@ -752,7 +767,6 @@ export function createMsalClient( /** * Creates a base interactive request configuration for MSAL interactive authentication. * This is shared between interactive and brokered authentication flows. - */ function createBaseInteractiveRequest( scopes: string[], @@ -774,7 +788,7 @@ export function createMsalClient( } /** - + * @internal */ async function getBrokeredTokenInternal( scopes: string[], @@ -837,6 +851,7 @@ export function createMsalClient( /** * A helper function that supports brokered authentication through the MSAL's public application. + * * When useDefaultBrokerAccount is true, the method will attempt to authenticate using the default broker account. * If the default broker account is not available, the method will fall back to interactive authentication. */ diff --git a/sdk/identity/identity/src/msal/nodeFlows/msalPlugins.ts b/sdk/identity/identity/src/msal/nodeFlows/msalPlugins.ts index 5344c9d9c603..30888fab613e 100644 --- a/sdk/identity/identity/src/msal/nodeFlows/msalPlugins.ts +++ b/sdk/identity/identity/src/msal/nodeFlows/msalPlugins.ts @@ -39,6 +39,7 @@ export interface PluginConfiguration { broker: { /** * True if the broker plugin is enabled and available. False otherwise. + * * It is a bug if this is true and the broker plugin is not available. */ isEnabled: boolean; @@ -63,7 +64,7 @@ export interface PluginConfiguration { /** * The current persistence provider, undefined by default. - + * @internal */ export let persistenceProvider: | ((options?: TokenCachePersistenceOptions) => Promise) @@ -71,7 +72,7 @@ export let persistenceProvider: /** * An object that allows setting the persistence provider. - + * @internal */ export const msalNodeFlowCacheControl = { setPersistence(pluginProvider: Exclude): void { @@ -81,7 +82,7 @@ export const msalNodeFlowCacheControl = { /** * The current native broker provider, undefined by default. - + * @internal */ export let nativeBrokerInfo: | { @@ -91,13 +92,13 @@ export let nativeBrokerInfo: /** * The current VSCode auth record path, undefined by default. - + * @internal */ export let vsCodeAuthRecordPath: string | undefined = undefined; /** * The current VSCode broker, undefined by default. - + * @internal */ export let vsCodeBrokerInfo: | { @@ -115,7 +116,7 @@ export function hasVSCodePlugin(): boolean { /** * An object that allows setting the native broker provider. - + * @internal */ export const msalNodeFlowNativeBrokerControl: NativeBrokerPluginControl = { setNativeBroker(broker): void { @@ -127,7 +128,7 @@ export const msalNodeFlowNativeBrokerControl: NativeBrokerPluginControl = { /** * An object that allows setting the VSCode credential auth record path and broker. - + * @internal */ export const msalNodeFlowVSCodeCredentialControl: VisualStudioCodeCredentialControl = { setVSCodeAuthRecordPath(path: string): void { @@ -142,7 +143,9 @@ export const msalNodeFlowVSCodeCredentialControl: VisualStudioCodeCredentialCont /** * Configures plugins, validating that required plugins are available and enabled. + * * Does not create the plugins themselves, but rather returns the configuration that will be used to create them. + * * @param options - options for creating the MSAL client * @returns plugin configuration */ diff --git a/sdk/identity/identity/src/msal/nodeFlows/tokenCachePersistenceOptions.ts b/sdk/identity/identity/src/msal/nodeFlows/tokenCachePersistenceOptions.ts index 04d0fc106250..49dbcab25b6b 100644 --- a/sdk/identity/identity/src/msal/nodeFlows/tokenCachePersistenceOptions.ts +++ b/sdk/identity/identity/src/msal/nodeFlows/tokenCachePersistenceOptions.ts @@ -11,6 +11,7 @@ export interface TokenCachePersistenceOptions { enabled: boolean; /** * Unique identifier for the persistent token cache. + * * Based on this identifier, the persistence file will be located in any of the following places: * - Darwin: '/Users/user/.IdentityService/' * - Windows 8+: 'C:\\Users\\user\\AppData\\Local\\.IdentityService\\' diff --git a/sdk/identity/identity/src/msal/types.ts b/sdk/identity/identity/src/msal/types.ts index 53821c72c26d..16f2a6a3c5ec 100644 --- a/sdk/identity/identity/src/msal/types.ts +++ b/sdk/identity/identity/src/msal/types.ts @@ -2,13 +2,13 @@ // Licensed under the MIT License. /** - + * @internal */ export type AppType = "public" | "confidential" | "publicFirst" | "confidentialFirst"; /** * The shape we use return the token (and the expiration date). - + * @internal */ export interface MsalToken { accessToken?: string; @@ -23,7 +23,7 @@ export type ValidMsalToken = { [P in keyof MsalToken]-?: NonNullable [message]` + * */ export function credentialLoggerInstance( title: string, @@ -125,9 +128,12 @@ export interface CredentialLogger extends CredentialLoggerInstance { /** * Generates a CredentialLogger, which is a logger declared at the credential's constructor, and used at any point in the credential. * It has all the properties of a CredentialLoggerInstance, plus other logger instances, one per method. + * * It logs with the format: + * * `[title] => [message]` * `[title] => getToken() => [message]` + * */ export function credentialLogger(title: string, log: AzureLogger = logger): CredentialLogger { const credLogger = credentialLoggerInstance(title, undefined, log); diff --git a/sdk/identity/identity/src/util/processMultiTenantRequest.ts b/sdk/identity/identity/src/util/processMultiTenantRequest.ts index 9673b8507e09..2201e59daa9c 100644 --- a/sdk/identity/identity/src/util/processMultiTenantRequest.ts +++ b/sdk/identity/identity/src/util/processMultiTenantRequest.ts @@ -13,7 +13,7 @@ function createConfigurationErrorMessage(tenantId: string): string { * Of getToken contains a tenantId, this functions allows picking this tenantId as the appropriate for authentication, * unless multitenant authentication has been disabled through the AZURE_IDENTITY_DISABLE_MULTITENANTAUTH (on Node.js), * or unless the original tenant Id is `adfs`. - + * @internal */ export function processMultiTenantRequest( tenantId?: string, diff --git a/sdk/identity/identity/src/util/processUtils.ts b/sdk/identity/identity/src/util/processUtils.ts index 59ed3926eebb..b37fa8485036 100644 --- a/sdk/identity/identity/src/util/processUtils.ts +++ b/sdk/identity/identity/src/util/processUtils.ts @@ -5,12 +5,12 @@ import childProcess from "node:child_process"; /** * Easy to mock childProcess utils. - + * @internal */ export const processUtils = { /** * Promisifying childProcess.execFile - + * @internal */ execFile( file: string, diff --git a/sdk/identity/identity/src/util/scopeUtils.ts b/sdk/identity/identity/src/util/scopeUtils.ts index 6b6c8baa59e5..9d158114f660 100644 --- a/sdk/identity/identity/src/util/scopeUtils.ts +++ b/sdk/identity/identity/src/util/scopeUtils.ts @@ -6,7 +6,7 @@ import { formatError } from "./logging.js"; /** * Ensures the scopes value is an array. - + * @internal */ export function ensureScopes(scopes: string | string[]): string[] { return Array.isArray(scopes) ? scopes : [scopes]; @@ -14,7 +14,7 @@ export function ensureScopes(scopes: string | string[]): string[] { /** * Throws if the received scope is not valid. - + * @internal */ export function ensureValidScopeForDevTimeCreds(scope: string, logger: CredentialLogger): void { if (!scope.match(/^[0-9a-zA-Z-_.:/]+$/)) { @@ -26,7 +26,7 @@ export function ensureValidScopeForDevTimeCreds(scope: string, logger: Credentia /** * Returns the resource out of a scope. - + * @internal */ export function getScopeResource(scope: string): string { return scope.replace(/\/.default$/, ""); diff --git a/sdk/identity/identity/src/util/subscriptionUtils.ts b/sdk/identity/identity/src/util/subscriptionUtils.ts index 237cf4a3732f..f9456e450061 100644 --- a/sdk/identity/identity/src/util/subscriptionUtils.ts +++ b/sdk/identity/identity/src/util/subscriptionUtils.ts @@ -5,7 +5,7 @@ import type { CredentialLogger } from "./logging.js"; import { formatError } from "./logging.js"; /** - + * @internal */ export function checkSubscription(logger: CredentialLogger, subscription: string): void { if (!subscription.match(/^[0-9a-zA-Z-._ ]+$/)) { diff --git a/sdk/identity/identity/src/util/tenantIdUtils.ts b/sdk/identity/identity/src/util/tenantIdUtils.ts index 3d987750c100..e88f8668a35b 100644 --- a/sdk/identity/identity/src/util/tenantIdUtils.ts +++ b/sdk/identity/identity/src/util/tenantIdUtils.ts @@ -7,7 +7,7 @@ import { formatError } from "./logging.js"; export { processMultiTenantRequest } from "./processMultiTenantRequest.js"; /** - + * @internal */ export function checkTenantId(logger: CredentialLogger, tenantId: string): void { if (!tenantId.match(/^[0-9a-zA-Z-.]+$/)) { @@ -20,7 +20,7 @@ export function checkTenantId(logger: CredentialLogger, tenantId: string): void } /** - + * @internal */ export function resolveTenantId( logger: CredentialLogger, @@ -41,7 +41,7 @@ export function resolveTenantId( } /** - + * @internal */ export function resolveAdditionallyAllowedTenantIds( additionallyAllowedTenants?: string[], diff --git a/sdk/identity/identity/src/util/tracing.ts b/sdk/identity/identity/src/util/tracing.ts index 4801878032f9..d25ac092d921 100644 --- a/sdk/identity/identity/src/util/tracing.ts +++ b/sdk/identity/identity/src/util/tracing.ts @@ -6,7 +6,7 @@ import { createTracingClient } from "@azure/core-tracing"; /** * Creates a span using the global tracer. - + * @internal */ export const tracingClient = createTracingClient({ namespace: "Microsoft.AAD",