docs(dpg): consolidate contents regarding authentication (#28416)

* docs(dpg): consolidate contents regarding authentication

- add a section `Authentication` to host all knowledge regarding authentication
- add missing `-securityHeaderName` description
- fix some issues in generation scripts:
  - fix type error of `$readme` in `Invoke-DataPlaneGenerateSDKPackage.ps1`
  - fix missing `$inputfile` value in `GenerateAndBuildLib.ps1`

part of #27612

doc/DataPlaneCodeGeneration/AzureSDKCodeGeneration_DataPlane_Quickstart.md

@@ -20,6 +20,12 @@ This tutorial has following sections:
     - [Changelog](#changelog)
     - [Add Convenience APIs](#add-convenience-apis)
     - [APIView](#apiview)
+  - [Background Knowledge](#background-knowledge)
+    - [Authentication](#authentication)
+      - [Supported Authentication](#supported-authentication)
+      - [Parameters To Create Starter Package](#parameters-to-create-starter-package)
+      - [Authentication Configuration In `autorest.md`](#authentication-configuration-in-autorestmd)
+      - [More Read On Authentication](#more-read-on-authentication)
 
 <!-- /TOC -->
 
@@ -74,7 +80,8 @@ pwsh /home/azure-sdk-for-net/eng/scripts/automation/Invoke-DataPlaneGenerateSDKP
 - For `- namespace`, please use one of the pre-approved namespace groups on the [.NET Azure SDK Guidelines Approved Namespaces list](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-namespaces-approved-list). This value will also provide the name for the shipped package, and should be of the form `Azure.<group>.<service>`.
 - `-inputfiles` takes the address of the Open API spec files,  separated by semicolon if there is more than one file.  The Open API spec file can be local file, e.g. ./swagger/compute.json, or the web address of the file in the `azure-rest-api-specs` repo.  When pointing to a file in the `azure-rest-api-specs` repo, make sure to include the commit id in the URI, i.e. `https://github.com/Azure/azure-rest-api-specs/blob/73a0fa453a93bdbe8885f87b9e4e9fef4f0452d0/specification/webpubsub/data-plane/WebPubSub/stable/2021-10-01/webpubsub.json`.  This ensures that you can choose the time to upgrade to new swagger file versions.
 - `-readme` takes the address of the readme configuration file. The configuration can be local file, e.g. ./swagger/readme.md or the web address of the file in the `azure-rest-api-specs` repo, i.e. `https://github.com/Azure/azure-rest-api-specs/blob/23dc68e5b20a0e49dd3443a4ab177d9f2fcc4c2b/specification/deviceupdate/data-plane/readme.md`
-- `-securityScope` designates the authentication scope your library will use if it supports token credential authentication.  Both Azure Active Directory and Azure Key Credential authentication are supported. **AzureKey authentication** is specific to each service, but generally it is documented by that service. e.g [AzureKey authentication of Azure Storage](https://docs.microsoft.com/azure/storage/blobs/authorize-data-operations-portal#use-the-account-access-key). **AADToken** is for any service that supports [TokenCredential authentication](https://docs.microsoft.com/dotnet/api/azure.core.tokencredential?view=azure-dotnet). If your service supports AADToken, just set the parameter **securityScope**(the security scope), and if your service supports AzureKey authentication, set parameter **securityHeaderName**( the security header name). You also can provide both if your service supports two methods of authentication.
+- `-securityScope` designates the authentication scope to use if your library supports **Token Credential** authentication.
+- `-securityHeaderName` designates the key to use if your library supports **Azure Key Credential** authentication.
 
 When you run the `eng\scripts\automation\Invoke-DataPlaneGenerateSDKPackage.ps1` script, it will:
 
@@ -158,4 +165,52 @@ Once you've done all above requirements, you will need to upload public API to [
 
 Here are the steps:
 - Create the artifact: Run `dotnet pack` under `sdk\<service>\Azure.<group>.<service>` directory. The artifact will be generated to the directory `artifacts\packages\Debug\Azure.<group>.<service>`
-- Upload the artifact to [APIView Website](https://apiview.dev/) to create APIView of the service.
+- Upload the artifact to [APIView Website](https://apiview.dev/) to create APIView of the service.
+
+## Background Knowledge
+
+### Authentication
+
+#### Supported Authentication
+
+Data plane clients support two types of authentication: Azure Key Credential(`AzureKey`) and Token credential(`AADToken`).
+
+- **Azure Key Credential** is specific to each service, but generally it is documented by that service. e.g [AzureKey authentication of Azure Storage](https://docs.microsoft.com/azure/storage/blobs/authorize-data-operations-portal#use-the-account-access-key).
+- **Token Credential** is for any service that supports [Token Credential authentication](https://docs.microsoft.com/dotnet/api/azure.core.tokencredential?view=azure-dotnet).
+
+#### Parameters To Create Starter Package
+
+- If your service supports AzureKey authentication, set parameter `-securityHeaderName`( the security header name).
+- If your service supports AADToken, just set the parameter `-securityScope`(the security scope).
+- You can set **both parameters** if your service supports both authentication.
+- You can set **neither** if your service doesn't require authentication(rare cases).
+
+#### Authentication Configuration In `autorest.md`
+
+In the `autorest.md`,
+
+- Support Azure Key Credential(e.g. `-securityHeaderName` is specified):
+
+```yaml
+security: AzureKey
+security-header-name: Your-Subscription-Key
+```
+
+- Support Token Credential(e.g. `-securityScope` is specified):
+
+```yaml
+security: AADToken
+security-scopes: https://yourendpoint.azure.com/.default
+```
+
+- Support both credentials(e.g. `-securityHeaderName` and `--securityScope` are specified):
+
+```yaml
+security: AADToken;AzureKey
+security-header-name: Your-Subscription-Key
+security-scopes: https://yourendpoint.azure.com/.default
+```
+
+#### More Read On Authentication
+
+- [Autorest: Authentication in generated SDKs](https://github.com/Azure/autorest/blob/main/docs/generate/authentication.md)

eng/scripts/automation/GenerateAndBuildLib.ps1

@@ -152,7 +152,7 @@ function New-DataPlanePackageFolder() {
     Invoke-Expression $dotnetNewCmd
 
     $file = (Join-Path $projectFolder "src" $AUTOREST_CONFIG_FILE)
-    Update-AutorestConfigFile -autorestFilePath $file -inputfile -readme $readme
+    Update-AutorestConfigFile -autorestFilePath $file -inputfile $inputfile -readme $readme
     # dotnet sln
     dotnet sln remove src\$namespace.csproj
     dotnet sln add src\$namespace.csproj

eng/scripts/automation/Invoke-DataPlaneGenerateSDKPackage.ps1

@@ -4,7 +4,7 @@ param (
   [string]$namespace,
   [string]$sdkPath,
   [string]$inputfiles="", #input files, separated by semicolon if more than one
-  [stirng]$readme = "",
+  [string]$readme = "",
   [string]$securityScope="",
   [string]$securityHeaderName="",
   [string]$AUTOREST_CONFIG_FILE = "autorest.md"