Azure Mixed Reality client library for Java - version 1.2.21

  • Article

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.

Source code | Package (Maven) | API reference documentation | Product documentation

Mixed Reality service authentication diagram

Getting started

Prerequisites

Include the package

Include the BOM file

Please include the azure-sdk-bom to your project to take dependency on the General Availability (GA) version of the library. In the following snippet, replace the {bom_version_to_target} placeholder with the version number. To learn more about the BOM, see the AZURE SDK BOM README.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

and then include the direct dependency in the dependencies section without the version tag as shown below.

<dependencies>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-mixedreality-authentication</artifactId>
    </dependency>
</dependencies>

Include direct dependency

If you want to take dependency on a particular version of the library that is not present in the BOM, add the direct dependency to your project as follows.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-mixedreality-authentication</artifactId>
    <version>1.2.21</version>
</dependency>

Authenticate the client

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 for detailed instructions and information.

Key concepts

MixedRealityStsClient

The MixedRealityStsClient is the client library used to access the Mixed Reality STS to get an access token.

Tokens obtained from the Mixed Reality STS have a lifetime of 24 hours.

Examples

Create the client

For a synchronous client:

AzureKeyCredential keyCredential = new AzureKeyCredential(accountKey);
MixedRealityStsClient client = new MixedRealityStsClientBuilder()
    .accountDomain(accountDomain)
    .accountId(accountId)
    .credential(keyCredential)
    .buildClient();

For an asynchronous client (note the call to buildAsyncClient instead of buildClient):

AzureKeyCredential keyCredential = new AzureKeyCredential(accountKey);
MixedRealityStsAsyncClient client = new MixedRealityStsClientBuilder()
    .accountDomain(accountDomain)
    .accountId(accountId)
    .credential(keyCredential)
    .buildAsyncClient();

Retrieve an access token

AzureKeyCredential keyCredential = new AzureKeyCredential(accountKey);
MixedRealityStsClient client = new MixedRealityStsClientBuilder()
    .accountDomain(accountDomain)
    .accountId(accountId)
    .credential(keyCredential)
    .buildClient();

AccessToken token = client.getToken();

See the authentication examples above for more complex authentication scenarios.

Using the access token in a Mixed Reality client library

Some Mixed Reality client libraries might accept an access token in place of a credential. For example:

// getMixedRealityAccessTokenFromWebService is a hypothetical method that retrieves
// a Mixed Reality access token from a web service. The web service would use the
// MixedRealityStsClient and credentials to obtain an access token to be returned
// to the client.
AccessToken accessToken = getMixedRealityAccessTokenFromWebService();

SpatialAnchorsAccount account = new SpatialAnchorsAccount(accountId, accountDomain);
SpatialAnchorsClient client = new SpatialAnchorsClient(account, accessToken);

Note: The SpatialAnchorsClient usage above is hypothetical and may not reflect the actual library. Consult the documentation for the client library you're using to determine if and how this might be supported.

Troubleshooting

Describe common errors and exceptions, how to "unpack" them if necessary, and include guidance for graceful handling and recovery.

Provide information to help developers avoid throttling or other service-enforced errors they might encounter. For example, provide guidance and examples for using retry or connection policies in the API.

If the package or a related package supports it, include tips for logging or enabling instrumentation to help them debug their code.

Next steps

Client libraries supporting authentication with Mixed Reality Authentication

Libraries supporting the Mixed Reality Authentication are 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. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Impressions