|
| 1 | +# Azure Mixed Reality Authentication client library for .NET |
| 2 | + |
| 3 | +Mixed Reality services, like Azure Spatial Anchors, Azure Remote Rendering, and others, use the Mixed Reality security |
| 4 | +token service (STS) for authentication. This package supports exchanging Mixed Reality account credentials for an access |
| 5 | +token from the STS that can be used to access Mixed Reality services. |
| 6 | + |
| 7 | +[Source code](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/mixedreality/Azure.MixedReality.Authentication) | NuGet |
| 8 | + |
| 9 | + |
| 10 | + |
| 11 | +- [Azure Mixed Reality Authentication client library for .NET](#azure-mixed-reality-authentication-client-library-for-net) |
| 12 | + - [Getting started](#getting-started) |
| 13 | + - [Install the package](#install-the-package) |
| 14 | + - [Prerequisites](#prerequisites) |
| 15 | + - [Authenticate the client](#authenticate-the-client) |
| 16 | + - [Authentication examples](#authentication-examples) |
| 17 | + - [Authenticating with account key authentication](#authenticating-with-account-key-authentication) |
| 18 | + - [Authenticating with an AAD client secret](#authenticating-with-an-aad-client-secret) |
| 19 | + - [Authenticating a user using device code authentication](#authenticating-a-user-using-device-code-authentication) |
| 20 | + - [Interactive authentication with DefaultAzureCredential](#interactive-authentication-with-defaultazurecredential) |
| 21 | + - [Key concepts](#key-concepts) |
| 22 | + - [MixedRealityStsClient](#mixedrealitystsclient) |
| 23 | + - [Examples](#examples) |
| 24 | + - [Retrieve an access token](#retrieve-an-access-token) |
| 25 | + - [Troubleshooting](#troubleshooting) |
| 26 | + - [Next steps](#next-steps) |
| 27 | + - [Client libraries supporting authentication with Mixed Reality Authentication](#client-libraries-supporting-authentication-with-mixed-reality-authentication) |
| 28 | + - [Contributing](#contributing) |
| 29 | + |
| 30 | +## Getting started |
| 31 | + |
| 32 | +### Install the package |
| 33 | + |
| 34 | +Install the Azure Mixed Reality Authentication client library for .NET using one of the following methods. |
| 35 | + |
| 36 | +From Visual Studio Package Manager: |
| 37 | + |
| 38 | +```powershell |
| 39 | +Install-Package Azure.MixedReality.Authentication |
| 40 | +``` |
| 41 | + |
| 42 | +From .NET CLI |
| 43 | + |
| 44 | +```dotnetcli |
| 45 | +dotnet add package Azure.MixedReality.Authentication |
| 46 | +``` |
| 47 | + |
| 48 | +Add a package reference: |
| 49 | + |
| 50 | +```xml |
| 51 | +<PackageReference Include="Azure.MixedReality.Authentication" Version="1.0.0-preview.1" /> |
| 52 | +``` |
| 53 | + |
| 54 | +### Prerequisites |
| 55 | + |
| 56 | +- You must have an [Azure subscription](https://azure.microsoft.com/free/). |
| 57 | +- You must have an account with an [Azure Mixed Reality service](https://azure.microsoft.com/topic/mixed-reality/): |
| 58 | + - [Azure Remote Rendering](https://docs.microsoft.com/azure/remote-rendering/) |
| 59 | + - [Azure Spatial Anchors](https://docs.microsoft.com/azure/spatial-anchors/) |
| 60 | +- Familiarity with the authentication and credential concepts from [Azure.Identity](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/identity/Azure.Identity/README.md). |
| 61 | + |
| 62 | +### Authenticate the client |
| 63 | + |
| 64 | +Mixed Reality services support a few different forms of authentication: |
| 65 | + |
| 66 | +- Account Key authentication |
| 67 | + - Account keys enable you to get started quickly with using Mixed Reality services. But before you deploy your application |
| 68 | + to production, we recommend that you update your app to use Azure AD authentication. |
| 69 | +- Azure Active Directory (AD) token authentication |
| 70 | + - If you're building an enterprise application and your company is using Azure AD as its identity system, you can use |
| 71 | + user-based Azure AD authentication in your app. You then grant access to your Mixed Reality accounts by using your |
| 72 | + existing Azure AD security groups. You can also grant access directly to users in your organization. |
| 73 | + - Otherwise, we recommend that you obtain Azure AD tokens from a web service that supports your app. We recommend this |
| 74 | + method for production applications because it allows you to avoid embedding the credentials for access to a Mixed |
| 75 | + Reality service in your client application. |
| 76 | + |
| 77 | +See [here](https://docs.microsoft.com/azure/spatial-anchors/concepts/authentication) for detailed instructions and information. |
| 78 | + |
| 79 | +#### Authentication examples |
| 80 | + |
| 81 | +Below are some examples of some common authentication scenarios, but more examples and information can be found at |
| 82 | +[Azure.Identity](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/identity/Azure.Identity/README.md). |
| 83 | + |
| 84 | +##### Authenticating with account key authentication |
| 85 | + |
| 86 | +Use the `MixedRealityStsClient` constructor overload accepting an `AzureKeyCredential` to configure account key |
| 87 | +authentication with the Mixed Reality STS: |
| 88 | + |
| 89 | +```csharp |
| 90 | +AzureKeyCredential keyCredential = new AzureKeyCredential(accountKey); |
| 91 | +MixedRealityStsClient client = new MixedRealityStsClient(accountId, accountDomain, keyCredential); |
| 92 | +``` |
| 93 | + |
| 94 | +> Note: Account key authentication is **not recommended** for production applications. |
| 95 | +
|
| 96 | +##### Authenticating with an AAD client secret |
| 97 | + |
| 98 | +```csharp |
| 99 | +TokenCredential aadCredential = new ClientSecretCredential(tenantId, clientId, clientSecret, new TokenCredentialOptions |
| 100 | +{ |
| 101 | + AuthorityHost = new Uri($"https://login.microsoftonline.com/{tenantId}") |
| 102 | +}); |
| 103 | + |
| 104 | +MixedRealityStsClient client = new MixedRealityStsClient(accountId, accountDomain, aadCredential); |
| 105 | +``` |
| 106 | + |
| 107 | +##### Authenticating a user using device code authentication |
| 108 | + |
| 109 | +```csharp |
| 110 | +Task deviceCodeCallback(DeviceCodeInfo deviceCodeInfo, CancellationToken cancellationToken) |
| 111 | +{ |
| 112 | + Debug.WriteLine(deviceCodeInfo.Message); |
| 113 | + Console.WriteLine(deviceCodeInfo.Message); |
| 114 | + return Task.FromResult(0); |
| 115 | +} |
| 116 | + |
| 117 | +TokenCredential deviceCodeCredential = new DeviceCodeCredential(deviceCodeCallback, tenantId, clientId, new TokenCredentialOptions |
| 118 | +{ |
| 119 | + AuthorityHost = new Uri($"https://login.microsoftonline.com/{tenantId}"), |
| 120 | +}); |
| 121 | + |
| 122 | +MixedRealityStsClient client = new MixedRealityStsClient(accountId, accountDomain, deviceCodeCredential); |
| 123 | + |
| 124 | +AccessToken token = await client.GetTokenAsync(accountId); |
| 125 | +``` |
| 126 | + |
| 127 | +See [here](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/Device-Code-Flow) for more |
| 128 | +information about using device code authentication flow. |
| 129 | + |
| 130 | +##### Interactive authentication with DefaultAzureCredential |
| 131 | + |
| 132 | +Use the `DefaultAzureCredential` object with `includeInteractiveCredentials: true` to use default interactive authentication |
| 133 | +flow: |
| 134 | + |
| 135 | +```csharp |
| 136 | +TokenCredential credential = new DefaultAzureCredential(includeInteractiveCredentials: true); |
| 137 | + |
| 138 | +MixedRealityStsClient client = new MixedRealityStsClient(accountId, accountDomain, credential); |
| 139 | +``` |
| 140 | + |
| 141 | +## Key concepts |
| 142 | + |
| 143 | +### MixedRealityStsClient |
| 144 | + |
| 145 | +The `MixedRealityStsClient` is the client library used to access the Mixed Reality STS to get an access token. |
| 146 | + |
| 147 | +Tokens obtained from the Mixed Reality STS have a lifetime of **24 hours**. |
| 148 | + |
| 149 | +## Examples |
| 150 | + |
| 151 | +### Retrieve an access token |
| 152 | + |
| 153 | +```csharp |
| 154 | +AzureKeyCredential keyCredential = new AzureKeyCredential(accountKey); |
| 155 | +MixedRealityStsClient client = new MixedRealityStsClient(accountId, accountDomain, keyCredential); |
| 156 | + |
| 157 | +AccessToken token = await client.GetTokenAsync(accountId); |
| 158 | +``` |
| 159 | + |
| 160 | +See the authentication examples [above](#authenticate-the-client) for more complex authentication scenarios. |
| 161 | + |
| 162 | +## Troubleshooting |
| 163 | + |
| 164 | +- See [Error Handling](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/identity/Azure.Identity/README.md#error-handling) for Azure.Identity. |
| 165 | +- See [Logging](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/identity/Azure.Identity/README.md#logging) for Azure.Identity. |
| 166 | + |
| 167 | +## Next steps |
| 168 | + |
| 169 | +### Client libraries supporting authentication with Mixed Reality Authentication |
| 170 | + |
| 171 | +Libraries supporting the Mixed Reality Authentication are coming soon. |
| 172 | + |
| 173 | +## Contributing |
| 174 | + |
| 175 | +This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License |
| 176 | +Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. |
| 177 | +For details, visit [https://cla.microsoft.com](https://cla.microsoft.com). |
| 178 | + |
| 179 | +When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the |
| 180 | +PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this |
| 181 | +once across all repos using our CLA. |
| 182 | + |
| 183 | +This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). |
| 184 | +For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact |
| 185 | +[opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. |
0 commit comments