Appconfiguration: App Configuration fails when used in a browser due to the `x-ms-command-name` not being in the accept headers

[richardpark-msft]

When we use App Configuration in a browser-based app the SDK currently sends the x-ms-command-name header since the User-Agent header is generally not modifiable.

The AppConfig service does not list this header Access-Control-Allow-Headers (CORS checking) so requests will end up failing.

This is currently the cause of this issue: https://github.com/Azure/azure-sdk-for-js/issues/5810

[zhenlan]

@richardpark-msft just make sure I understand, the JS/TS SDK sends user-agent string using x-ms-command-name. Is this only when User-Agent cannot be modified or always the case?

@MSGaryWang @drago-draganov is this something that makes sense to add?

[richardpark-msft]

@zhenlan - we only send this header in the browser case, otherwise we use the User-Agent header.

[zhenlan]

@richardpark-msft got it. Thanks. Is using x-ms-command-name as an alternative header for user-agent a common practice in the JS SDKs for other Azure services as well?

[richardpark-msft]

@zhenlan - it's a standard header in the JS SDK when we're running in a browser - it's baked into the underlying library that we use for HTTP requests.

BTW, I did a preflight request against appconfig and it looks like there are already some x-ms headers that are whitelisted:

Access-Control-Allow-Headers: x-ms-client-request-id, x-ms-content-sha256, x-ms-date, host, x-ms-return-client-request-id, x-ms-retry-after, x-ms-request-id ```

(other non-x-ms headers elided)

[bterlson]

Given that we can't control UA string in browsers, services need to support another header that lets us include that information. Does appconfig have such a header? If not, probably just allow-listing this header would be best from my perspective.

[zhenlan]

Thanks for the information. We will add x-ms-command-name to the allow-list of CORS.

[richardpark-msft]

@zhenlan - do you have an ETA that you're okay with giving me?

[zhenlan]

We are trying to get the fix included in the deployment of this week.

[richardpark-msft]

CC: @kaerm, who should be kept informed about this for telemetry/usage purposes.

[kaerm]

List: @kaerm @loarabia @kyle-patterson

[johanste]

The x-ms-command-name was originally introduced as a means for applications (primarily command line applications - e.g. azure cli and powershell) to indicate which command triggered the request. Services are expected to include this information in their telemetry stores when appropriate. I don't recall any discussions as to why the user agent was not used for this. I don't believe our SDKs need to explicitly expose the header. It is custom enough that I would expect a client application that needs to provide the value can do so by injecting the appropriate policy or similar.

[bterlson]

@johanste the issue is that browsers can't change the UA string so we have to put the information elsewhere. x-ms-command-name seems to already be used for this purpose. Is there a better alternative you can suggest?

[zhenlan]

@johanste thanks for sharing the background. We are thinking about using x-ms-command-name as user-agent when it's sent by a request for metrics. According to what you said, the x-ms-command-name could be used for something else like azure CLI command name as well. This made it hard for us to detect whether x-ms-command-name is actually a user agent string or something else. Do you think if it would make sense for the SDK to pick another header that is more dedicated to alternative user-agent header, for example, x-ms-user-agent? This will make it simpler for other Azure services that are interested in this information as well.

[johanste]

Relevant guidance:

https://azure.github.io/azure-sdk/general_azurecore.html#azurecore-http-telemetry-dynamic
https://azure.github.io/azure-sdk/general_azurecore.html#azurecore-http-telemetry-x-ms-useragent

[bterlson]

@johanste thanks for the pointer! I looks like we'd prefer x-ms-useragent over x-ms-command-name for this usage. Do you think that's true? If so, @zhenlan, is it too late to add x-ms-useragent to the allow list as well?

@richardpark-msft assuming we can add x-ms-useragent to the allow list, you can pass { userAgentHeaderName: 'x-ms-useragent' } in ServiceClientOptions to use this header.

@daviwil @johanste the userAgentPolicy defaults to x-ms-command-name in browsers. I wonder if it should default to x-ms-useragent instead?

[johanste]

@daviwil @johanste the userAgentPolicy defaults to x-ms-command-name in browsers. I wonder if it should default to x-ms-user-agent instead?

That would be my assumption.

[daviwil]

@bterlson I'm not sure why x-ms-command-name was ever used for this purpose, but seems like x-ms-user-agent is the appropriate header to use these days so I'm :+1: for it.

[bterlson]

My guess is was driven by management plane things, and that changing the default now is hard. @daviwil maybe we get this on the list of things to fix for the next major?

@zhenlan if you can confirm whether you can add x-ms-useragent header to the allow list, let's go with that instead. Let's not change core's default header name unless @daviwil really wants to make that change now 😀.

[zhenlan]

We can add the new user-agent header to the CORS allow-list. It will miss the deployment of this week, but we should be able to include it in the first deployment of the new year (early Jan). So I think we should go ahead and make the change in the JS SDK.

According to the link @johanste shared, the header should be x-ms-useragent. Please confirm which header the JS SDK is going to use.

[bterlson]

@zhenlan good catch, should be x-ms-useragent. Edited my comments above to prevent any confusion (hopefully).

[richardpark-msft]

(removing comment about casing of the header - I'll go with x-ms-useragent, lower-cased).

[johanste]

I would go with lower-cased, but technically, it shouldn't matter since http header field names are case insensitive.

[bterlson]

+1 for getting type for headers from the lower case. The upper case is hard to reach anyway.

[richardpark-msft]

@zhenlan - I've committed this PR to start sending the x-ms-useragent header in the next release of JS AppConfig.

https://github.com/Azure/azure-sdk-for-js/pull/6528

[zhenlan]

@richardpark-msft excellent. We will add x-ms-useragent to the service CORS allow-list too. Deployment ETA early January.

BTW, the previous change of x-ms-command-name is already deployed to WestCentralUS and EastUS. This should enable the existing JS SDK to work in case you want to validate there is no surprise.

[richardpark-msft]

Thank you @zhenlan , our browser SDK users appreciate it :)

[jimmyca15]

@zhenlan Correct me if I'm wrong. We are adding only x-ms-useragent through CORS. x-ms-command-name will not be available through CORS. It's just currently available in WCUS and EUS for SDK verification.

[zhenlan]

Correct, x-ms-command-name will be removed. Only x-ms-useragent will be added to the CORS allow-list.

[richardpark-msft]

@zhenlan - do you know when the deployment for this is scheduled to go?

[zhenlan]

We will start the mid-next week and will take a week to go to all regions.

[zhenlan]

The fix (adding x-ms-useragent to CORS allow-list) has been deployed to all regions. Please let me know if you see any issues.