JavaScript용 Azure Mixed Reality 인증 클라이언트 라이브러리 - 버전 1.0.0-beta.1

  • 아티클

Azure Spatial Anchors, Azure Remote Rendering 등의 Mixed Reality 서비스는 인증에 Mixed Reality STS(보안 토큰 서비스)를 사용합니다. 이 패키지는 Mixed Reality 서비스에 액세스하는 데 사용할 수 있는 STS에서 액세스 토큰에 대한 Mixed Reality 계정 자격 증명 교환을 지원합니다.

주요 링크:

Mixed Reality 서비스 인증 다이어그램

시작

현재 지원되는 환경

필수 구성 요소

@azure/mixed-reality-authentication 패키지를 설치합니다.

를 사용하여 JavaScript용 Azure Mixed Reality 인증 클라이언트 라이브러리를 npm설치합니다.

npm install @azure/mixed-reality-authentication

MixedRealityStsClient 만들기 및 인증

Mixed Reality 서비스에 대한 액세스 토큰을 요청하는 클라이언트 개체를 만들려면 Mixed Reality 서비스 리소스 및 의 및 account domain 가 credential필요합니다account identifier.

Mixed Reality 서비스는 다음과 같은 몇 가지 유형의 인증을 지원합니다.

  • 계정 키 인증
    • 계정 키를 사용하면 Mixed Reality 서비스를 사용하여 빠르게 시작할 수 있습니다. 하지만 애플리케이션을 프로덕션 환경에 배포하기 전에 Azure AD 인증을 사용하도록 앱을 업데이트하는 것이 좋습니다.
  • Azure AD(Active Directory) 토큰 인증
    • 엔터프라이즈 애플리케이션을 빌드하고 회사가 Azure AD를 ID 시스템으로 사용하는 경우 앱에서 사용자 기반 Azure AD 인증을 사용할 수 있습니다. 그런 다음 기존 Azure AD 보안 그룹을 사용하여 Mixed Reality 계정에 대한 액세스 권한을 부여합니다. 조직의 사용자에게 직접 액세스 권한을 부여할 수도 있습니다.
    • 그렇지 않은 경우에는 앱을 지원하는 웹 서비스에서 Azure AD 토큰을 가져오는 것이 좋습니다. 클라이언트 애플리케이션에서 Mixed Reality 서비스에 액세스하기 위해 자격 증명을 포함하지 않도록 하므로 프로덕션 애플리케이션에 이 방법을 사용하는 것이 좋습니다.

자세한 지침 및 정보는 여기 를 참조하세요.

계정 키 인증 사용

Azure Portal을 사용하여 Mixed Reality 서비스 리소스를 찾아 를 검색합니다account key.

계정 키가 있으면 클래스를 AzureKeyCredential 사용하여 다음과 같이 클라이언트를 인증할 수 있습니다.

const { AzureKeyCredential } = require("@azure/core-auth");

const { MixedRealityStsClient } = require("@azure/mixed-reality-authentication");

const accountId = "<ACCOUNTD ID>";
const accountDomain = "<ACCOUNT_DOMAIN>";
const accountKey = "<ACCOUNT_KEY>";

const client = new MixedRealityStsClient(
  accountId,
  accountDomain,
  new AzureKeyCredential(accountKey)
);

참고: 프로덕션 애플리케이션에는 계정 키 인증을 사용하지 않는 것이 좋습니다 .

Azure Active Directory 자격 증명 사용

계정 키 인증은 대부분의 예제에서 사용되지만 Azure ID 라이브러리를 사용하여 Azure Active Directory로 인증할 수도 있습니다. 프로덕션 애플리케이션에 권장되는 방법입니다. 아래에 표시된 DefaultAzureCredential 공급자 또는 Azure SDK와 함께 제공되는 다른 자격 증명 공급자를 사용하려면 패키지를 설치 @azure/identity 하세요.

npm install @azure/identity

또한 서비스 주체에 Mixed Reality 서비스에 대한 적절한 역할을 할당하여 새 AAD 애플리케이션을 등록하고 Mixed Reality 리소스에 대한 액세스 권한을 부여해야 합니다.

AAD 애플리케이션의 클라이언트 ID, 테넌트 ID 및 클라이언트 암호 값을 환경 변수로 설정합니다. AZURE_CLIENT_ID, , AZURE_TENANT_IDAZURE_CLIENT_SECRET.

const { MixedRealityStsClient } = require("@azure/mixed-reality-authentication");
const { DefaultAzureCredential } = require("@azure/identity");

const client = new MixedRealityStsClient(accountId, accountDomain, new DefaultAzureCredential());

주요 개념

MixedRealityStsClient

는 MixedRealityStsClient 액세스 토큰을 가져오기 위해 Mixed Reality STS에 액세스하는 데 사용되는 클라이언트 라이브러리입니다.

Mixed Reality STS에서 가져온 토큰의 수명은 24시간입니다.

반환 값

에 대한 성공적인 호출 getToken 의 반환 값은 GetTokenResponse@azure/core-http의 입니다AccessToken.

예

액세스 토큰 검색

const { AzureKeyCredential } = require("@azure/core-auth");

const { MixedRealityStsClient } = require("@azure/mixed-reality-authentication");

const accountId = "<ACCOUNTD ID>";
const accountDomain = "<ACCOUNT_DOMAIN>";
const accountKey = "<ACCOUNT_KEY>";

const client = new MixedRealityStsClient(
  accountId,
  accountDomain,
  new AzureKeyCredential(accountKey)
);

const token = await client.getToken();

더 복잡한 인증 시나리오는 위의 인증 예제 또는 Azure ID 를 참조하세요.

Mixed Reality 클라이언트 라이브러리에서 액세스 토큰 사용

일부 Mixed Reality 클라이언트 라이브러리는 자격 증명 대신 액세스 토큰을 수락할 수 있습니다. 예를 들어:

// 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.
const accessToken = await GetMixedRealityAccessTokenFromWebService();

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

참고: 위의 사용법은 SpatialAnchorsClient 가상이며 실제 라이브러리를 반영하지 않을 수 있습니다. 사용 중인 클라이언트 라이브러리에 대한 설명서를 참조하여 지원되는지 여부와 방법을 확인합니다.

문제 해결

로깅

로깅을 사용하도록 설정하면 실패에 대한 유용한 정보를 파악하는 데 도움이 될 수 있습니다. HTTP 요청 및 응답 로그를 보려면 AZURE_LOG_LEVEL 환경 변수를 info로 설정합니다. 또는 @azure/logger에서 setLogLevel을 호출하여 런타임에 로깅을 사용하도록 설정할 수 있습니다.

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

로그를 사용하는 방법에 대한 자세한 내용은 @azure/logger package docs를 참조하세요.

다음 단계

이 라이브러리를 사용하는 방법에 대한 자세한 예제는 샘플 디렉터리를 참조하세요.

참여

이 프로젝트에 대한 기여와 제안을 환영합니다. 대부분의 경우 기여하려면 권한을 부여하며 실제로 기여를 사용할 권한을 당사에 부여한다고 선언하는 CLA(기여자 라이선스 계약)에 동의해야 합니다. 자세한 내용은 https://cla.microsoft.com 을 참조하세요.

끌어오기 요청을 제출하면 CLA-bot은 CLA를 제공하고 PR을 적절하게 데코레이팅해야 하는지 여부를 자동으로 결정합니다(예: 레이블, 설명). 봇에서 제공하는 지침을 따르기만 하면 됩니다. 이 작업은 CLA를 사용하여 모든 리포지토리에서 한 번만 수행하면 됩니다.

이 프로젝트에는 Microsoft Open Source Code of Conduct(Microsoft 오픈 소스 준수 사항)가 적용됩니다. 자세한 내용은 Code of Conduct FAQ(규정 FAQ)를 참조하세요. 또는 추가 질문이나 의견은 opencode@microsoft.com으로 문의하세요.

이 라이브러리에 기여하려면 기여 가이드 를 참조하여 코드를 빌드하고 테스트하는 방법에 대해 자세히 알아보세요.

Impressions