Kiota should have a developer-friendly way of providing auth information in the VS Code extension

[maisarissi]

As part of calling authenticated APIs, one can provide auth information as part of the plugin manifest so Copilot can know how to call the API. Kiota should identify the auth information from the OpenAPI description and create the right thing (https://github.com/microsoft/kiota/issues/5070).

Things to consider: 1 - Not all OpenAPI descriptions have security information 2 - Some APIs do not need authentication (either for some endpoints or all endpoints) 3 - Providing auth information in the plugin manifest is not required (because of the 2nd point mentioned above)

So, Kiota VS Code extension should have a developer-friendly way of adding/providing the auth info different from adding the information editing the manifest file manually.

Acceptance Criteria:

1. Kiota VS Code extension will offer a new action (CTRL+SHIFT+P) "Add authentication registration info"
2. When user triggers the new action, we do open in the quick picker 2 questions: "What's the auth type" and "What's the reference-id"
3. Once the user confirmed the input for both questions, new auth object will be generated in the plugin manifest, following the structure as defined in #5070.
4. If the user triggers the action for a plugin manifest which already contains the auth object, it will be overwritten with the new values.

[baywet]

@maisarissi Can you please provide more information?

[maisarissi]

@baywet I thought I had added descriptions for all new issues. This is fixed now. Not sure though how to give developers a way of adding the auto info from the extension in a way that relates to their journey. Any thoughts?

[sebastienlevert]

Kiota needs to understand the auth scheme of all APIs, anyways. In the future, we will want to auto-gen and scaffold some level of auth code. So this would be useful in larger scenarios.

Now, for Copilot specifically, there are requirements (reference ids, types, etc.) that will be required. If we start adding tons of switches, I feel we are going backwards and are not respecting our goal of being as simple as possible.

Any thoughts @baywet @andrueastman?

[maisarissi]

Hey @sebastienlevert , this is about the extension. The CLI discussion is over here: https://github.com/microsoft/kiota/issues/5072

[baywet]

Overall I'm not clear on the experience to start with, and this is why I have asked a bunch of questions to attempt clarifying it in #5072. I don't think we want to be in the business of "storing additional information that's missing in the OAS description". And that's regardless of whether we're talking about Auth information, the AI OAS extensions, etc... We talked about overlays for that. People can also create a copy of the description and locally edit it in the meantime etc...

Here is the main reason why I don't want us to be building those kind of experiences. Imagine that we built a fancy user experience to set your token endpoint, your consent endpoint, and all the other information that's required for an OAuth2 flow. Now we will additionally need to build user experiences to tie that information to any specific operation so we can later on identify the given operation needs that information to be exported for the plugin. And even if you built all that additional user experience we now need to reflect it in the CLI which will be complex and convoluted and we also need to store that information somewhere so we can retrieve it during updates and other scenarios like those. Not only this represents a ton of user experience to build but it also does not Denver agreed user experience at the end of the day especially in the CLI context.

[maisarissi]

My fault @baywet . I wasn't too clear around what I meant here. We are not getting into the business of providing auth registration. This is TDP responsibility. Kiota should only provide a way for folks to provide the type and the reference-id in both CLI and VS Code extension. My only concern is how we should do it in the VS Code extension since this information is not required.

I think we shouldn't have block users of creating plugins for OpenAPI descriptions with no auth requirements and we should let them provide the auth type and reference-id to be automatically added to the plugin manifest rather than adding the "none" default version and requiring users to manually edit the json file.

[baywet]

No worries, I'm just trying to make sure we have a common understanding and enough information to implement things properly here. Have you thought about additional questions in the generate copilot plugin sequence? If we don't detect any authentication configuration for the operation, we don't ask them. If we do, we prompt the user. If we're refreshing an existing plugin, and the questions have already been answered, we skip them as well I guess? Are there default placeholders we could use?

Or do we need to ask any of that at all since we're already established in #5070 that we can compute that information from the description?

[maisarissi]

Thanks for seeking all clarity needed before doing the work!

So, I thought about asking additional question, here are my thoughts:

• When the auth info is provided in the OpenAPI description, we shouldn't ask them any additional questions
• When there is no auth in the OpenAPI description we have 2 scenarios:

1. The OpenAPI doesn't require authentication (so generating the auth None is what we should do)
2. The OpenAPI description is missing the auth info but authenticating is necessary. In the second option above, we would like to give users a way of providing the type and reference-id, so we can create the right thing automatically for them, rather than asking them to go and edit the json file manually.

Adding a new action (CTRL+SHIFT+P) is something one would be used to do it to add something like that? Having a new Kiota: add authentication registration info (or something like that)

And by doing that, we do open in the quick picker 2 questions like "What's the auth type" and "What's the reference-id"?

[baywet]

How would people know they need to do this at this point? is the editing experience of the plugin something we could leave to TTK instead? I'm a bit worried this will lead to a disjoint experience, but not strictly opposed to it.

[maisarissi]

We definitely want to provide a good editing experience in Kiota. Kiota helps one to maintain their plugin by editing paths, re-generating, or in this case, providing a nice way to adding auth when the OpenAPI description doesn't have the info.

The only reason I said we might want to add a new action is that we don't want to bother people by asking auth info when the API they are creating a plugin for, don't require authentication. In the CLI, we can easily fix that by providing 2 switchers where one can provide the info. In VS Code, we need to be careful to not add unnecessary friction and asking more 2 questions (type and reference-id).

We can provide that info through docs, saying that one might manually edit the json file or use the "action". I'm also open to other ideas on how we can make this experience better.

[petrhollayms]

@maisarissi Agree with the AC as defined above?

[maisarissi]

@petrhollayms yes, agree. My only concern is to know to which plugin manifest the auth object should be applied to. Today, there is a constraint that there is only 1 plugin per app, however, this will be worked out. So when there is more than 1 plugin manifest, how can we ensure they are applying to the right thing?

Should we ask them to select the plugin manifest? Is there a way for us to list in the quick pick all plugin manifest available in the workspace?

[petrhollayms]

@thewahome Can we ask the user a question about the manifest to use if there is more than one, with the list of all manifests in the workspace? See ^^^

[garethj-msft]

In the new plan, we will generate the AUTH info from the plugin description in TypeSpec either into the OpenAPI file or into the workspace.json (or both if necessary), so a GUI experience should be unnecessary in the plugin.

Consequently I propose we close this.

[baywet]

@garethj-msft we could repurpose this to implement those changes: reading from the description or the workspace. I'm in favour of reading it from the description since this is where most of the other information comes from. The workspace is simply a "storage unit" for the user provided information. Do you have more details on which fields/extensions TypeSpec would be emitting auth information to?

[garethj-msft]

TypeSpec is only going to completely replace files, not edit them. If we can do the auth solely by putting it in the OpenAPI file, I'm in favor of that as TypeSpec natively has syntax for that in its OAS31 emitter, then all we need in the workspace file is the simple list with paths, which is pretty trivial for us to emit.

[maisarissi]

So, today one needs to either create an auth registration in TDP and provide the key, or add a auth register task in teamsapp.yml so TTK helps with the auth registration in TDP.

Are we saying that using TypeSpec we will have a similar experience? Either way, Kiota would need to have access to the key that points to the auth registration in TDP to add as part of the plugin.

[darrelmiller]

@maisarissi Only TTK is going to be calling TDP to get the referenceId. If that gets written into workspace.json then it makes it problematic for TypeSpec to generate the workspace.json.

If the user/TTK writes the referenceId and the desired authType into TypeSpec, then TypeSpec can emit a complete workspace.json that Kiota can use.

[maisarissi]

Sure. For Kiota, we need to have the info to create the right API Plugin. If TypeSpec adds the info into the workspace.json, this works for us! Now, in a world where the user doesn't use TypeSpec, I still believe that adding a new action to the Kiota extension is still a valid scenario.

[baywet]

@maisarissi is this still relevant since we've moved to the TypeSpec strategy?

[sebastienlevert]

Let's pause, learn from TypeSpec and then go back to this is it's really what we need.