Skip to content

Commit

Permalink
Added the Azure.MixedReality.Authentication library (#16714)
Browse files Browse the repository at this point in the history
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)
  • Loading branch information
craigktreasure authored Feb 23, 2021
1 parent a286861 commit 1a60ae0
Showing 66 changed files with 2,411 additions and 0 deletions.
1 change: 1 addition & 0 deletions eng/.docsettings.yml
Original file line number Diff line number Diff line change
@@ -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']
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Release History

## 1.0.0b1 (Unreleased)

- Initial release.
21 changes: 21 additions & 0 deletions sdk/mixedreality/azure-mixedreality-authentication/LICENSE.txt
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
@@ -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
199 changes: 199 additions & 0 deletions sdk/mixedreality/azure-mixedreality-authentication/README.md
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
@@ -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']
Original file line number Diff line number Diff line change
@@ -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
Loading

0 comments on commit 1a60ae0

Please sign in to comment.