[apps/api] feat: allow oauth for regional bots

[lilyydu]

resolves: #367

• exposed a new config option called ClientSettings thats passed into our clients from the app layer
• the tokenUrl specifies the regional token endpoint to use (e.g., europe.token.botframework)

I didn't reuse OauthSettings because
a) its associated w/ the Apps ecosystem vs ClientSettings is concerned w the API layer
b) eventually may diverge with additional params
b) would cause circular dependencies

• tested with the graph sample, works w/ global and a west-europe regional bot
• add tests

INSTRUCTIONS FOR SETTING UP
(documenting here for now, should add to docs, partial courtesy to @Benjiiim):

• in azurebot.bicep, replace all 'global' occurrences by 'westeurope'
• in aad.manifest.json, replace "https://token.botframework.com/.auth/web/redirect" by "https://europe.token.botframework.com/.auth/web/redirect"
• in index.ts, update OauthSettings to incl clientSettings

const app = new App({
oauth: {
defaultConnectionName: 'graph',
// This is an example of overriding the token URL for a specific region (e.g., Europe).
// Uncomment this block if needed.
// clientSettings: {
// tokenUrl: "https://europe.token.botframework.com",
// }
},
logger: new ConsoleLogger('@tests/auth', { level: 'debug' })
});

resources:

• https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-concept-regionalization?view=azure-bot-service-4.0
• https://learn.microsoft.com/en-us/azure/bot-service/ref-oauth-redirect-urls?view=azure-bot-service-4.0
• https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-authentication?view=azure-bot-service-4.0&tabs=multitenant%2Caadv2%2Ccsharp#prepare-the-bot-code

[Benjiiim]

Loving it 😍 Thanks a lot @lilyydu for your work on this.

I have several comments after going through the changes.

Have you considered using OAuthUrl as the setting's name instead of tokenUrl? I understand the choice for tokenUrl as it is the URL to get the token but the bot service doc talks about OAuth URL in OAuth URL support in Azure AI Bot Service for example so it might be good to be aligned.

Regarding the instructions for setting up:

• I don't think you should touch the azure.bicep file as resourceGroup().location will get the resource group location automatically + the resource group location doesn't change anything regarding the bot service resource location.
• You should document the change needed in manifest.json as well. *.botframework.com should be replaced by europe.token.botframework.com (or equivalent for other locations)
• I will be glad to have a look at the doc when time will come

Regarding the CLI templates:

• If you choose to add a comment to define the tokenURL in index.ts, you might want to do the same with the validdomain in manifest.json.
• And you might want to do that for the template applied when running config add atk.oauth to change the reply url in the aad.manifest.json file and the location in azurebot.bicep.
• Instead of comments everywhere, I'm wondering if env variables won't be better? A discussion with M365 toolkit might be useful in that case to align the templates.
• An other option would be to rely only on the documentation without touching the templates

[heyitsaamir]

camelCase?

[heyitsaamir]

NIT: Instead of making all keys optional in ClientSettings, and making DEFAULT_CLIENT_SETTINGS Required, you could make all keys required in ClientSettings, and make all parameters Partial. This way, in places you need ClientSettings, the value of the keys isn't string | undefined.
For eg, in sign-in.ts, you have:

`${this._clientSettings.OAuthUrl}/${BOT_SIGNIN_ENDPOINTS.URL}?${q}`

here OauthUrl is actually string | undefined, which is less understandable than if it was just string.

[heyitsaamir]

Also oauthUrl, or oauthBaseEndpoint? It's not really the full url. Thoughts?

[heyitsaamir]

this is copied in many places. Consider a helper method that takes in Partial<ClientSettings> and returns ClientSettings

[heyitsaamir]

why is this in "OauthSettings". this seems more general than just Oauth, right?

[heyitsaamir]

Also, each of these should have an associated environment variable that populates them through a config, if not provided