Soft deprecate WithAuthority on request level

[bgavrilMS]

Fixes #3716

Changes proposed in this request
Hide WithAuthority methods.

Testing

Performance impact

Documentation

• All relevant documentation is updated.

[jmprieur]

LGTM
Thanks @bgavrilMS

do we want to add an obsolete(false) attribute?

[pmaytak]

What about:

• microsoft-authentication-library-for-dotnet/src/client/Microsoft.Identity.Client/ApiConfig/AbstractAcquireTokenParameterBuilder.cs

  Line 260 in 9af5689

  public T WithAuthority(AzureCloudInstance azureCloudInstance, AadAuthorityAudience authorityAudience, bool validateAuthority = true)

• microsoft-authentication-library-for-dotnet/src/client/Microsoft.Identity.Client/ApiConfig/AbstractAcquireTokenParameterBuilder.cs

  Line 360 in 9af5689

  public T WithAdfsAuthority(string authorityUri, bool validateAuthority = true)

[bgavrilMS]

LGTM Thanks @bgavrilMS

do we want to add an obsolete(false) attribute?

I had a long conversation with Azure SDK folks about this and they advise against it. This is because of diamond dependencies again, which can cause warnings. I think the sceanrio is like this:

• App references MSAL 4.40, uses an API which is not obsolete
• App also references Azure.Identiy, which references MSAL 4.48, where API is obsolete
• App now gets a warning (and many apps use "report warnings as errors", which breaks the build)

So they recommend just hiding obsolete APIs.

CC: @pmaytak @neha-bhargava @SameerK-MSFT @trwalke @gladjohn