Skip to content

Finalize Auth Challenges caller API #268006

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TylerLeonhardt merged 1 commit into from
Sep 23, 2025
Merged

Finalize Auth Challenges caller API #268006

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 0 additions & 3 deletions src/vs/workbench/api/common/extHost.api.impl.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -302,9 +302,6 @@ export function createApiFactoryAndRegisterActors(accessor: ServicesAccessor): I

const authentication: typeof vscode.authentication = {
getSession(providerId: string, scopesOrChallenge: readonly string[] | vscode.AuthenticationWwwAuthenticateRequest, options?: vscode.AuthenticationGetSessionOptions) {
if (!Array.isArray(scopesOrChallenge)) {
checkProposedApiEnabled(extension, 'authenticationChallenges');
}
if (
(typeof options?.forceNewSession === 'object' && options.forceNewSession.learnMore) ||
(typeof options?.createIfNone === 'object' && options.createIfNone.learnMore)
Expand Down
12 changes: 0 additions & 12 deletions src/vs/workbench/api/common/extHostAuthentication.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,18 +88,6 @@ export class ExtHostAuthentication implements ExtHostAuthenticationShape {
const keys: (keyof vscode.AuthenticationGetSessionOptions)[] = Object.keys(options) as (keyof vscode.AuthenticationGetSessionOptions)[];
const optionsStr = keys.sort().map(key => `${key}:${!!options[key]}`).join(', ');

// old shape, remove next milestone
if (
'scopes' in scopesOrRequest
&& typeof scopesOrRequest.scopes === 'string'
&& !scopesOrRequest.fallbackScopes
) {
scopesOrRequest = {
wwwAuthenticate: scopesOrRequest.wwwAuthenticate,
fallbackScopes: scopesOrRequest.scopes
};
}

let singlerKey: string;
if (isAuthenticationWwwAuthenticateRequest(scopesOrRequest)) {
const challenge = scopesOrRequest as vscode.AuthenticationWwwAuthenticateRequest;
Expand Down
84 changes: 59 additions & 25 deletions src/vscode-dts/vscode.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17814,6 +17814,30 @@ declare module 'vscode' {
account?: AuthenticationSessionAccountInformation;
}

/**
* Represents parameters for creating a session based on a WWW-Authenticate header value.
* This is used when an API returns a 401 with a WWW-Authenticate header indicating
* that additional authentication is required. The details of which will be passed down
* to the authentication provider to create a session.
*
* @note The authorization provider must support handling challenges and specifically
* the challenges in this WWW-Authenticate value.
* @note For more information on WWW-Authenticate please see https://developer.mozilla.org/docs/Web/HTTP/Reference/Headers/WWW-Authenticate
*/
export interface AuthenticationWwwAuthenticateRequest {
/**
* The raw WWW-Authenticate header value that triggered this challenge.
* This will be parsed by the authentication provider to extract the necessary
* challenge information.
*/
readonly wwwAuthenticate: string;

/**
* The fallback scopes to use if no scopes are found in the WWW-Authenticate header.
*/
readonly fallbackScopes?: readonly string[];
}

/**
* Basic information about an {@link AuthenticationProvider}
*/
Expand Down Expand Up @@ -17936,49 +17960,59 @@ declare module 'vscode' {
*/
export namespace authentication {
/**
* Get an authentication session matching the desired scopes. Rejects if a provider with providerId is not
* registered, or if the user does not consent to sharing authentication information with
* the extension. If there are multiple sessions with the same scopes, the user will be shown a
* quickpick to select which account they would like to use.
* Get an authentication session matching the desired scopes or satisfying the WWW-Authenticate request. Rejects if
* a provider with providerId is not registered, or if the user does not consent to sharing authentication information
* with the extension. If there are multiple sessions with the same scopes, the user will be shown a quickpick to
* select which account they would like to use.
*
* Built-in auth providers include:
* * 'github' - For GitHub.com
* * 'microsoft' For both personal & organizational Microsoft accounts
* * (less common) 'github-enterprise' - for alternative GitHub hostings, GHE.com, GitHub Enterprise Server
* * (less common) 'microsoft-sovereign-cloud' - for alternative Microsoft clouds
*
* Currently, there are only two authentication providers that are contributed from built in extensions
* to the editor that implement GitHub and Microsoft authentication: their providerId's are 'github' and 'microsoft'.
* @param providerId The id of the provider to use
* @param scopes A list of scopes representing the permissions requested. These are dependent on the authentication provider
* @param scopeListOrRequest A scope list of permissions requested or a WWW-Authenticate request. These are dependent on the authentication provider.
* @param options The {@link AuthenticationGetSessionOptions} to use
* @returns A thenable that resolves to an authentication session
*/
export function getSession(providerId: string, scopes: readonly string[], options: AuthenticationGetSessionOptions & { /** */createIfNone: true | AuthenticationGetSessionPresentationOptions }): Thenable<AuthenticationSession>;
export function getSession(providerId: string, scopeListOrRequest: ReadonlyArray<string> | AuthenticationWwwAuthenticateRequest, options: AuthenticationGetSessionOptions & { /** */createIfNone: true | AuthenticationGetSessionPresentationOptions }): Thenable<AuthenticationSession>;

/**
* Get an authentication session matching the desired scopes. Rejects if a provider with providerId is not
* registered, or if the user does not consent to sharing authentication information with
* the extension. If there are multiple sessions with the same scopes, the user will be shown a
* quickpick to select which account they would like to use.
* Get an authentication session matching the desired scopes or request. Rejects if a provider with providerId is not
* registered, or if the user does not consent to sharing authentication information with the extension. If there
* are multiple sessions with the same scopes, the user will be shown a quickpick to select which account they would like to use.
*
* Built-in auth providers include:
* * 'github' - For GitHub.com
* * 'microsoft' For both personal & organizational Microsoft accounts
* * (less common) 'github-enterprise' - for alternative GitHub hostings, GHE.com, GitHub Enterprise Server
* * (less common) 'microsoft-sovereign-cloud' - for alternative Microsoft clouds
*
* Currently, there are only two authentication providers that are contributed from built in extensions
* to the editor that implement GitHub and Microsoft authentication: their providerId's are 'github' and 'microsoft'.
* @param providerId The id of the provider to use
* @param scopes A list of scopes representing the permissions requested. These are dependent on the authentication provider
* @param scopeListOrRequest A scope list of permissions requested or a WWW-Authenticate request. These are dependent on the authentication provider.
* @param options The {@link AuthenticationGetSessionOptions} to use
* @returns A thenable that resolves to an authentication session
*/
export function getSession(providerId: string, scopes: readonly string[], options: AuthenticationGetSessionOptions & { /** literal-type defines return type */forceNewSession: true | AuthenticationGetSessionPresentationOptions | AuthenticationForceNewSessionOptions }): Thenable<AuthenticationSession>;
export function getSession(providerId: string, scopeListOrRequest: ReadonlyArray<string> | AuthenticationWwwAuthenticateRequest, options: AuthenticationGetSessionOptions & { /** literal-type defines return type */forceNewSession: true | AuthenticationGetSessionPresentationOptions | AuthenticationForceNewSessionOptions }): Thenable<AuthenticationSession>;

/**
* Get an authentication session matching the desired scopes. Rejects if a provider with providerId is not
* registered, or if the user does not consent to sharing authentication information with
* the extension. If there are multiple sessions with the same scopes, the user will be shown a
* quickpick to select which account they would like to use.
* Get an authentication session matching the desired scopes or request. Rejects if a provider with providerId is not
* registered, or if the user does not consent to sharing authentication information with the extension. If there
* are multiple sessions with the same scopes, the user will be shown a quickpick to select which account they would like to use.
*
* Built-in auth providers include:
* * 'github' - For GitHub.com
* * 'microsoft' For both personal & organizational Microsoft accounts
* * (less common) 'github-enterprise' - for alternative GitHub hostings, GHE.com, GitHub Enterprise Server
* * (less common) 'microsoft-sovereign-cloud' - for alternative Microsoft clouds
*
* Currently, there are only two authentication providers that are contributed from built in extensions
* to the editor that implement GitHub and Microsoft authentication: their providerId's are 'github' and 'microsoft'.
* @param providerId The id of the provider to use
* @param scopes A list of scopes representing the permissions requested. These are dependent on the authentication provider
* @param scopeListOrRequest A scope list of permissions requested or a WWW-Authenticate request. These are dependent on the authentication provider.
* @param options The {@link AuthenticationGetSessionOptions} to use
* @returns A thenable that resolves to an authentication session if available, or undefined if there are no sessions
* @returns A thenable that resolves to an authentication session or undefined if a silent flow was used and no session was found
*/
export function getSession(providerId: string, scopes: readonly string[], options?: AuthenticationGetSessionOptions): Thenable<AuthenticationSession | undefined>;
export function getSession(providerId: string, scopeListOrRequest: ReadonlyArray<string> | AuthenticationWwwAuthenticateRequest, options?: AuthenticationGetSessionOptions): Thenable<AuthenticationSession | undefined>;

/**
* Get all accounts that the user is logged in to for the specified provider.
Expand Down
94 changes: 2 additions & 92 deletions src/vscode-dts/vscode.proposed.authenticationChallenges.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,98 +5,8 @@

declare module 'vscode' {

// https://github.com/microsoft/vscode/issues/260156

/**********
* "Extension asking for auth" API
*******/

/**
* Represents parameters for creating a session based on a WWW-Authenticate header value.
* This is used when an API returns a 401 with a WWW-Authenticate header indicating
* that additional authentication is required. The details of which will be passed down
* to the authentication provider to create a session.
*
* @note The authorization provider must support handling challenges and specifically
* the challenges in this WWW-Authenticate value.
* @note For more information on WWW-Authenticate please see https://developer.mozilla.org/docs/Web/HTTP/Reference/Headers/WWW-Authenticate
*/
export interface AuthenticationWwwAuthenticateRequest {
/**
* The raw WWW-Authenticate header value that triggered this challenge.
* This will be parsed by the authentication provider to extract the necessary
* challenge information.
*/
readonly wwwAuthenticate: string;

/**
* The fallback scopes to use if no scopes are found in the WWW-Authenticate header.
*/
readonly fallbackScopes?: readonly string[];

/**
* @deprecated Use `fallbackScopes` instead.
*/
readonly scopes?: readonly string[];
}

export namespace authentication {
/**
* Get an authentication session matching the desired scopes or satisfying the WWW-Authenticate request. Rejects if
* a provider with providerId is not registered, or if the user does not consent to sharing authentication information
* with the extension. If there are multiple sessions with the same scopes, the user will be shown a quickpick to
* select which account they would like to use.
*
* Built-in auth providers include:
* * 'github' - For GitHub.com
* * 'microsoft' For both personal & organizational Microsoft accounts
* * (less common) 'github-enterprise' - for alternative GitHub hostings, GHE.com, GitHub Enterprise Server
* * (less common) 'microsoft-sovereign-cloud' - for alternative Microsoft clouds
*
* @param providerId The id of the provider to use
* @param scopeListOrRequest A scope list of permissions requested or a WWW-Authenticate request. These are dependent on the authentication provider.
* @param options The {@link AuthenticationGetSessionOptions} to use
* @returns A thenable that resolves to an authentication session
*/
export function getSession(providerId: string, scopeListOrRequest: ReadonlyArray<string> | AuthenticationWwwAuthenticateRequest, options: AuthenticationGetSessionOptions & { /** */createIfNone: true | AuthenticationGetSessionPresentationOptions }): Thenable<AuthenticationSession>;

/**
* Get an authentication session matching the desired scopes or request. Rejects if a provider with providerId is not
* registered, or if the user does not consent to sharing authentication information with the extension. If there
* are multiple sessions with the same scopes, the user will be shown a quickpick to select which account they would like to use.
*
* Built-in auth providers include:
* * 'github' - For GitHub.com
* * 'microsoft' For both personal & organizational Microsoft accounts
* * (less common) 'github-enterprise' - for alternative GitHub hostings, GHE.com, GitHub Enterprise Server
* * (less common) 'microsoft-sovereign-cloud' - for alternative Microsoft clouds
*
* @param providerId The id of the provider to use
* @param scopeListOrRequest A scope list of permissions requested or a WWW-Authenticate request. These are dependent on the authentication provider.
* @param options The {@link AuthenticationGetSessionOptions} to use
* @returns A thenable that resolves to an authentication session
*/
export function getSession(providerId: string, scopeListOrRequest: ReadonlyArray<string> | AuthenticationWwwAuthenticateRequest, options: AuthenticationGetSessionOptions & { /** literal-type defines return type */forceNewSession: true | AuthenticationGetSessionPresentationOptions | AuthenticationForceNewSessionOptions }): Thenable<AuthenticationSession>;

/**
* Get an authentication session matching the desired scopes or request. Rejects if a provider with providerId is not
* registered, or if the user does not consent to sharing authentication information with the extension. If there
* are multiple sessions with the same scopes, the user will be shown a quickpick to select which account they would like to use.
*
* Built-in auth providers include:
* * 'github' - For GitHub.com
* * 'microsoft' For both personal & organizational Microsoft accounts
* * (less common) 'github-enterprise' - for alternative GitHub hostings, GHE.com, GitHub Enterprise Server
* * (less common) 'microsoft-sovereign-cloud' - for alternative Microsoft clouds
*
* @param providerId The id of the provider to use
* @param scopeListOrRequest A scope list of permissions requested or a WWW-Authenticate request. These are dependent on the authentication provider.
* @param options The {@link AuthenticationGetSessionOptions} to use
* @returns A thenable that resolves to an authentication session or undefined if a silent flow was used and no session was found
*/
export function getSession(providerId: string, scopeListOrRequest: ReadonlyArray<string> | AuthenticationWwwAuthenticateRequest, options?: AuthenticationGetSessionOptions): Thenable<AuthenticationSession | undefined>;
}

// https://github.com/microsoft/vscode/issues/267992
// and historically: https://github.com/microsoft/vscode/issues/260156

/**********
* "Extension providing auth" API
Expand Down
Loading