Added the Azure.MixedReality.Authentication library (#16714)

This change adds an authentication library for Mixed Reality services, which all currently utilize a custom STS for authentication. Upcoming Mixed Reality client libraries will depend on this library to perform authentication using identities from Azure.Identity. See the added README.md for more information about the library.

[ApiView link](https://apiview.dev/Assemblies/Review/986545855b9c499faeff72b25115ab96)

Author: craigktreasure

eng/.docsettings.yml

@@ -124,6 +124,7 @@ known_content_issues:
   - ['sdk/core/azure-mgmt-nspkg/README.rst', 'nspkg and common']
   - ['sdk/core/azure-nspkg/README.rst', 'nspkg and common']
   - ['sdk/keyvault/azure-keyvault-nspkg/README.md', 'nspkg and common']
+  - ['sdk/mixedreality/azure-mixedreality-nspkg/README.md', 'nspkg and common']
   - ['sdk/search/azure-search-nspkg/README.md', 'nspkg and common']
   - ['sdk/storage/azure-storage-blob/samples/README.md', 'nspkg and common']
   - ['sdk/storage/azure-storage-file-datalake/samples/README.md', 'nspkg and common']

sdk/mixedreality/azure-mixedreality-authentication/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Release History
+
+## 1.0.0b1 (Unreleased)
+
+- Initial release.

sdk/mixedreality/azure-mixedreality-authentication/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Microsoft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sdk/mixedreality/azure-mixedreality-authentication/MANIFEST.in

@@ -0,0 +1,6 @@
+include *.md
+include azure/__init__.py
+include azure/mixedreality/__init__.py
+include LICENSE.txt
+recursive-include tests *.py
+recursive-include samples *.py *.md

sdk/mixedreality/azure-mixedreality-authentication/README.md

@@ -0,0 +1,199 @@
+[![Build Status](https://dev.azure.com/azure-sdk/public/_apis/build/status/azure-sdk-for-python.client?branchName=master)](https://dev.azure.com/azure-sdk/public/_build/latest?definitionId=46?branchName=master)
+
+# Azure Mixed Reality Authentication Package client library for Python
+
+Mixed Reality services, like Azure Spatial Anchors, Azure Remote Rendering, and others, use the Mixed Reality security
+token service (STS) for authentication. This package supports exchanging Mixed Reality account credentials for an access
+token from the STS that can be used to access Mixed Reality services.
+
+![Mixed Reality service authentication diagram](https://docs.microsoft.com/azure/spatial-anchors/concepts/media/spatial-anchors-authentication-overview.png)
+
+# Getting started
+
+## Currently supported environments
+
+This package has been tested with Python 2.7, 3.5, 3.6, 3.7, 3.8, and 3.9.
+
+## Prerequisites
+
+- An [Azure subscription][azure_sub].
+- You must have an account with an [Azure Mixed Reality service](https://azure.microsoft.com/topic/mixed-reality/):
+  - [Azure Remote Rendering](https://docs.microsoft.com/azure/remote-rendering/)
+  - [Azure Spatial Anchors](https://docs.microsoft.com/azure/spatial-anchors/)
+- Familiarity with the authentication and credential concepts from the [Azure Identity library][azure_identity].
+- Python 2.7, or 3.5 or later is required to use this package.
+
+## Install the package
+
+Install the Azure Mixed Reality Authentication SDK.
+
+```bash
+pip install --pre azure-mixedreality-authentication
+```
+
+## Create and authenticate a `MixedRealityStsClient`
+
+To create a client object to request an access token for a Mixed Reality service, you will need the `account identifier`
+and `account domain` of your Mixed Reality service resource and a `credential`.
+
+Mixed Reality services support a few different forms of authentication:
+
+- Account Key authentication
+  - Account keys enable you to get started quickly with using Mixed Reality services. But before you deploy your application
+    to production, we recommend that you update your app to use Azure AD authentication.
+- Azure Active Directory (AD) token authentication
+  - If you're building an enterprise application and your company is using Azure AD as its identity system, you can use
+    user-based Azure AD authentication in your app. You then grant access to your Mixed Reality accounts by using your
+    existing Azure AD security groups. You can also grant access directly to users in your organization.
+  - Otherwise, we recommend that you obtain Azure AD tokens from a web service that supports your app. We recommend this
+    method for production applications because it allows you to avoid embedding the credentials for access to a Mixed
+    Reality service in your client application.
+
+See [here][register_aad_app] for detailed instructions and information.
+
+### Using account key authentication
+
+Use the [Azure Portal][azure_portal] to browse to your Mixed Reality service resource and retrieve an `account key`.
+
+Once you have an account key, you can use the `AzureKeyCredential` class to authenticate the client as follows:
+
+```python
+from azure.core.credentials import AzureKeyCredential
+from azure.mixedreality.authentication import MixedRealityStsClient
+
+account_id = "<ACCOUNTD ID>"
+account_domain = "<ACCOUNT_DOMAIN>"
+account_key = "<ACCOUNT_KEY>"
+key_credential = AzureKeyCredential(account_key)
+
+client = MixedRealityStsClient(account_id, account_domain, key_credential)
+```
+
+> Note: Account key authentication is **not recommended** for production applications.
+
+### Using an Azure Active Directory Credential
+
+Account key authentication is used in most of the examples, but you can also authenticate with Azure Active Directory
+using the [Azure Identity library][azure_identity]. This is the recommended method for production applications. To use
+the [DefaultAzureCredential][defaultazurecredential] provider shown below, or other credential providers provided with
+the Azure SDK, please install the `@azure/identity` package:
+
+You will also need to [register a new AAD application][register_aad_app] and grant access to your Mixed Reality resource
+by assigning the appropriate role for your Mixed Reality service to your service principal.
+
+```python
+from azure.identity import DefaultAzureCredential
+from azure.mixedreality.authentication import MixedRealityStsClient
+
+account_id = "<ACCOUNTD ID>"
+account_domain = "<ACCOUNT_DOMAIN>"
+default_credential = DefaultAzureCredential()
+
+client = MixedRealityStsClient(account_id, account_domain, default_credential)
+```
+
+# Key concepts
+
+## MixedRealityStsClient
+
+The `MixedRealityStsClient` is the client library used to access the Mixed Reality STS to get an access token. An access
+token can be retrieved by calling `get_token()` on an `MixedRealityStsClient` instance.
+
+Tokens obtained from the Mixed Reality STS have a lifetime of **24 hours**.
+
+### Token result value
+
+The return value for a successful call to `get_token` is an `azure.core.credentials.AccessToken`.
+
+See the authentication examples [above](#authenticate-the-client) or [Azure Identity][azure_identity] for more complex
+authentication scenarios.
+
+## Retrieve an access token synchronously
+
+```python
+from azure.core.credentials import AzureKeyCredential
+from azure.mixedreality.authentication import MixedRealityStsClient
+
+account_id = "<ACCOUNTD ID>"
+account_domain = "<ACCOUNT_DOMAIN>"
+account_key = "<ACCOUNT_KEY>"
+key_credential = AzureKeyCredential(account_key)
+
+client = MixedRealityStsClient(account_id, account_domain, key_credential)
+
+token = client.get_token()
+```
+
+## Retrieve an access token asynchronously
+
+```python
+from azure.core.credentials import AzureKeyCredential
+from azure.mixedreality.authentication.aio import MixedRealityStsClient
+
+account_id = "<ACCOUNTD ID>"
+account_domain = "<ACCOUNT_DOMAIN>"
+account_key = "<ACCOUNT_KEY>"
+key_credential = AzureKeyCredential(account_key)
+
+client = MixedRealityStsClient(account_id, account_domain, key_credential)
+
+token = await client.get_token()
+```
+
+# Examples
+
+These are code samples that show common scenario operations with the Azure Mixed Reality Authentication client library.
+The async versions of the samples (the python sample files appended with `_async`) show asynchronous operations,
+and require Python 3.5 or later.
+Before running the sample code, refer to Prerequisites
+<!-- [Prerequisites](#Prerequisites) -->
+to create a resource, then set some Environment Variables
+
+```bash
+set MIXEDREALITY_ACCOUNT_DOMAIN="<the Mixed Reality account domain>"
+set MIXEDREALITY_ACCOUNT_ID="<the Mixed Reality account identifier>"
+set MIXEDREALITY_ACCOUNT_KEY="<the Mixed Reality account primary or secondary key>"
+
+pip install azure-mixedreality-authentication
+
+python samples\client_sample.py
+python samples\client_sample_async.py
+```
+
+# Troubleshooting
+
+The [troubleshooting](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/identity/azure-identity#troubleshooting)
+section for Azure Identity can be helpful when troubleshooting authentication issues.
+
+# Next steps
+
+## Mixed Reality client libraries
+
+- Coming soon
+
+## Contributing
+
+This project welcomes contributions and suggestions. Most contributions require you to agree to a
+Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
+the rights to use your contribution. For details, visit https://cla.microsoft.com.
+
+When you submit a pull request, a CLA-bot will automatically determine whether you need to provide
+a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions
+provided by the bot. You will only need to do this once across all repos using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
+contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
+
+If you'd like to contribute to this library, please read the
+[contributing guide](https://github.com/Azure/azure-sdk-for-python/blob/master/CONTRIBUTING.md) to learn more about how to
+build and test the code.
+
+![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-python%2Fsdk%2Ftemplate%2Fazure-template%2FREADME.png)
+
+[azure_cli]: https://docs.microsoft.com/cli/azure
+[azure_sub]: https://azure.microsoft.com/free/
+[azure_portal]: https://portal.azure.com
+[azure_identity]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/identity/azure-identity
+[register_aad_app]: https://docs.microsoft.com/azure/spatial-anchors/concepts/authentication
+[defaultazurecredential]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/identity/azure-identity#defaultazurecredential

sdk/mixedreality/azure-mixedreality-authentication/azure/__init__.py

@@ -0,0 +1,7 @@
+# --------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+
+__path__ = __import__('pkgutil').extend_path(__path__, __name__) # type: ignore

sdk/mixedreality/azure-mixedreality-authentication/azure/mixedreality/__init__.py

@@ -0,0 +1,7 @@
+# --------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+
+__path__ = __import__('pkgutil').extend_path(__path__, __name__) # type: ignore

sdk/mixedreality/azure-mixedreality-authentication/azure/mixedreality/authentication/__init__.py

@@ -0,0 +1,11 @@
+# --------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+
+from ._version import VERSION
+from ._client import MixedRealityStsClient
+
+__version__ = VERSION
+__all__ = ['MixedRealityStsClient']

sdk/mixedreality/azure-mixedreality-authentication/azure/mixedreality/authentication/_client.py

@@ -0,0 +1,113 @@
+# --------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+from typing import TYPE_CHECKING
+
+try:
+    from urllib.parse import urlparse
+except ImportError:
+    from urlparse import urlparse # type: ignore
+
+from azure.core.credentials import AzureKeyCredential
+from azure.core.tracing.decorator import distributed_trace
+from azure.core.pipeline.policies import BearerTokenCredentialPolicy
+
+from ._generated import MixedRealityStsRestClient
+from ._generated.models import TokenRequestOptions
+from ._version import SDK_MONIKER
+from ._shared.authentication_endpoint import construct_endpoint_url
+from ._shared.mixedreality_account_key_credential import MixedRealityAccountKeyCredential
+from ._utils import convert_to_access_token, generate_cv_base
+
+if TYPE_CHECKING:
+    # pylint: disable=unused-import,ungrouped-imports
+    from typing import Any, Union
+    from azure.core.credentials import TokenCredential
+    from azure.core.credentials import AccessToken
+
+
+class MixedRealityStsClient(object):
+    """ A client to interact with the Mixed Reality STS service.
+
+    :param str account_id:
+        The Mixed Reality service account identifier.
+    :param str account_domain:
+        The Mixed Reality service account domain.
+    :param Union[TokenCredential, AzureKeyCredential] credential:
+        The credential used to access the Mixed Reality service.
+    :keyword str custom_endpoint_url:
+        Override the Mixed Reality STS service endpoint.
+    """
+
+    def __init__(self, account_id, account_domain, credential, **kwargs):
+        # type: (str, str, Union[TokenCredential, AzureKeyCredential], Any) -> None
+        if not account_id:
+            raise ValueError("account_id must be a non-empty string.")
+
+        if not account_domain:
+            raise ValueError("account_domain must be a non-empty string.")
+
+        if not credential:
+            raise ValueError("credential can not be None.")
+
+        self._account_id = account_id
+        self._account_domain = account_domain
+
+        if isinstance(credential, AzureKeyCredential):
+            credential = MixedRealityAccountKeyCredential(account_id, credential)
+
+        self._credential = credential
+
+        endpoint_url = kwargs.pop('custom_endpoint_url', construct_endpoint_url(account_domain))
+
+        try:
+            if not endpoint_url.lower().startswith('http'):
+                endpoint_url = "https://" + endpoint_url
+        except AttributeError:
+            raise ValueError("Host URL must be a string.")
+
+        parsed_url = urlparse(endpoint_url.rstrip('/'))
+        if not parsed_url.netloc:
+            raise ValueError("Invalid URL: {}".format(endpoint_url))
+
+        self._endpoint_url = endpoint_url
+
+        authentication_policy = BearerTokenCredentialPolicy(credential, endpoint_url + '/.default')
+
+        self._client = MixedRealityStsRestClient(
+            base_url=endpoint_url,
+            authentication_policy=authentication_policy,
+            sdk_moniker=SDK_MONIKER,
+            **kwargs)
+
+    @distributed_trace
+    def get_token(self, **kwargs):
+        # type: (Any) -> AccessToken
+        """
+        Retrieve a token from the STS service for the specified account identifier asynchronously.
+        :return: Instance of azure.core.credentials.AccessToken - token and expiry date of it
+        :rtype: ~azure.core.credentials.AccessToken
+        """
+        token_request_options = TokenRequestOptions()
+        token_request_options.client_request_id = generate_cv_base()
+
+        response = self._client.get_token(
+            self._account_id,
+            token_request_options=token_request_options,
+            **kwargs)
+        return convert_to_access_token(response)
+
+    def close(self):
+        # type: () -> None
+        self._client.close()
+
+    def __enter__(self):
+        # type: () -> MixedRealityStsClient
+        self._client.__enter__()  # pylint:disable=no-member
+        return self
+
+    def __exit__(self, *args):
+        # type: (*Any) -> None
+        self._client.__exit__(*args)  # pylint:disable=no-member