Need a way to support "challenges"

[TylerLeonhardt]

On the Microsoft side, this is on the horizon:
https://azure.microsoft.com/en-us/blog/announcing-mandatory-multi-factor-authentication-for-azure-sign-in/
https://learn.microsoft.com/en-us/entra/identity/authentication/concept-mandatory-multifactor-authentication?tabs=dotnet

This is going to break us Sept 15th... because of these steps:

• Ask for auth with scope X -> get a token
• Use token at API -> it 401s with WWW-Authenticate saying it needs more claims
• 🐛 we have no way to pass that down to the Microsoft auth provider, we can only have it force re-creation of a token

Implementing this in a generic fashion... we could introduce a new challenges array to getSession:

const challenges = // literally the array of WWW-Authenticate header values
vscode.authentication.getSession('microsoft', scopes, { createIfNone: true, challenges }

And then in the auth provider we could make this a concrete object that contains some well-known properties like claims, scopes, etc:

• https://www.rfc-editor.org/rfc/rfc6750.html#section-3
• https://datatracker.ietf.org/doc/html/rfc9470#name-authentication-requirements
• https://datatracker.ietf.org/doc/html/rfc9728#name-use-of-www-authenticate-for
• https://datatracker.ietf.org/doc/html/rfc2617#section-3.2.1

while also supporting any other key.

At this point the auth provider can do what it wants with that... which in Microsoft's case will pass the claims value into MSAL.

Alternative getSession API

Making the 2nd parameter more about influencing the shape of the token and less about the UI, we could do this:

const challenges = // literally the array of WWW-Authenticate header values
vscode.authentication.getSession('microsoft', { scopes, challenges }, { createIfNone: true }

which could then be expanded further if we want to support resource, another thing that would influence the token shape.

[TylerLeonhardt]

https://learn.microsoft.com/en-us/entra/identity-platform/claims-challenge?tabs=dotnet#claims-challenge-header-format
https://learn.microsoft.com/en-us/entra/msal/dotnet/advanced/extract-authentication-parameters

[TylerLeonhardt]

See if MSAL has an equivalent: https://learn.microsoft.com/en-us/dotnet/api/microsoft.identity.client.wwwauthenticateparameters?view=msal-dotnet-latest

[TylerLeonhardt]

Here's what a WWW-Authenticate header looks like from the very real Azure situation:

WWW-Authenticate: Bearer
    realm="",
    authorization_uri="https://login.microsoftonline.com/common/oauth2/authorize",
    error="insufficient_claims",
    claims="eyJhY2Nlc3NfdG9rZW4iOnsiYWNycyI6eyJlc3NlbnRpYWwiOnRydWUsInZhbHVlcyI6WyJwMSJdfX19"

Note: put on newlines for readibility

This generically looks like this:

WWW-Authenticate: <challenge>
// or
WWW-Authenticate: <challenge1>,..., <challengeN>

A challenge looks like this:

challenge = <auth-scheme> <auth-param>, …, <auth-paramN>

Where:

• auth-scheme is a case-insensitive string
• auth-param is key=value where key and value are strings (key is unique within the challenge)

which in TypeScript could translate to:

interface AuthenticationChallenge {
  scheme: string
  params: Record<string, string>
}

which... we could type further for specific types of challenges where we know the kinds of params they have like Bearer:

interface BearerAuthenticationChallengeParams: {
  realm?: string;
  scope?: string;
  claims?: string;
  [key: string]: string;
}

interface BearerAuthenticationChallenge {
  scheme: 'bearer'
  params: BearerAuthenticationChallengeParams
}

Regardless of all of that, I think the API for "extension that wants auth" should be as simple as possible... and simply passing the WWW-Authenticate value into the Auth API is a good strategy so the extension doesn't have to be in the business of parsing this complex string.

With that in mind, you may have noticed in the Bearer challenge above that scope is a parameter option... this is used when the server expects more scopes than it was given... but if it's not used, then that signals that the scopes sent were fine, but something else is wrong.

This means that there are scenarios where:

• An AuthenticationSession needs to be re-created (like if there are claims in the challenge (aka metadata inside of the token that arent scopes)
• A completely new session needs to be created because more scopes are required. (ex: MCP will use this when you use a tool that needs more permissions than what the token can do

So that leads me to believe that the new API for the "extension that wants auth" to consume should look like this:

AuthenticationSessionChallenge {
  scopes?: string[];
  challenge: string;
}

declare module 'vscode' {
  export namespace authentication {
    export function getSession(providerId: string, challenge: AuthenticationSessionChallenge, options?: AuthenticationGetSessionOptions): Thenable<AuthenticationSession | undefined>;
  }
}

The challenge becomes the star, and since the auth extension is stateless, it will need to know the scopes so the option to provide them is there if needed.

Alternative

Our API has been so locked in to scopes but another component is resource which could be used:

• instead of scopes
• in conjunction with scopes

So:

AuthenticationSessionChallenge {
  scopes?: string[];
  challenge: string;
}

could be

AuthenticationSessionParameters {
  scopes?: string[];
  challenge?: string;
}

To future proof us a bit better if we ever add a resource:

AuthenticationSessionParameters {
  scopes?: string[];
  challenge?: string;
  resource?: string;
}

That said, since this is just an "input" API, we could also add ^ that later since it would not be a breaking change.

extension supplying auth perspective

From the "extension supplying auth perspective" we don't really need to dive deep just yet. I'll keep it proposed for a little bit... but I'm thinking:

AuthProvider implements two new functions:

interface AuthenticationChallenge {
  scheme: string
  params: Record<string, string>
}

interface BearerAuthenticationChallengeParams: {
  realm?: string;
  scope?: string;
  claims?: string;
  [key: string]: string;
}

interface BearerAuthenticationChallenge {
  scheme: 'bearer'
  params: BearerAuthenticationChallengeParams
}

interface AuthenticationProvider {
		getSessionsFromChallenges(challenges: readonly AuthenticationChallenge[], options: AuthenticationProviderSessionOptions): Thenable<AuthenticationSession[]>;

		createSessionFromChallenges(challenges: readonly AuthenticationChallenge[], options: AuthenticationProviderSessionOptions): Thenable<AuthenticationSession>;
}

Where challenges could be turned into a BearerAuthenticationChallenge with a scheme check.

[TylerLeonhardt]

Feedback from API sync:

• Turn getSession(providerId: string, challenge: AuthenticationSessionChallenge ... into getSession(providerId: string, scopeListOrChallenge: ScopeList | AuthenticationSessionChallenge ... (scopeListOrChallenge final name still pending)
• Try to enforce the implementation of an auth provider that supports challenges at compile time AuthenticationProviderWithChallenges

[TylerLeonhardt]

Notes for implementation:

• Add a new proposed API file that includes the new getSession and the new *SessionFromChallenges functions on an AuthenticationProvider
• plumb that challenge all the way down, implementing similar changes from scopes: string[] to scopeListOrChallenge: ScopeList | AuthenticationSessionChallenge as needed.
• When the AuthenticationService is ready to call the auth provider, check if the provider supports the Challenge functions and call those instead
• plumb those calls down to the auth provider
• Only implement the new functions in the Microsoft Authentication extension's auth providers
• Find the bearer scheme'd challenge and get the claims challenge out of it
• pass that down to MSAL