IoT Central REST API 호출을 인증하고 권한을 부여하는 방법

아티클
03/01/2024

IoT Central REST API를 사용하면 IoT Central 애플리케이션과 통합되는 클라이언트 애플리케이션을 개발할 수 있습니다. REST API를 사용하여 디바이스 템플릿, 디바이스, 작업, 사용자, 역할과 같은 IoT Central 애플리케이션에서 리소스 작업을 수행할 수 있습니다.

모든 IoT Central REST API 호출에는 IoT Central이 호출자의 ID를 확인하는 데 사용하는 권한 부여 헤더와 애플리케이션 내에서 호출자에게 부여되는 사용 권한이 필요합니다.

이 문서에서는 권한 부여 헤더에서 사용할 수 있는 토큰 유형과 이를 가져오는 방법에 대해 설명합니다. 서비스 주체는 IoT Central REST API 액세스 관리에 권장되는 방법입니다.

토큰 형식

REST API를 사용하여 IoT Central 애플리케이션에 액세스하려면 다음을 사용하면 됩니다.

Microsoft Entra 전달자 토큰. 전달자 토큰은 Microsoft Entra 사용자 계정 또는 서비스 주체와 연결됩니다. 토큰은 사용자나 서비스 주체가 IoT Central 애플리케이션에서 가진 사용 권한과 동일한 권한을 호출자에게 부여합니다.
IoT Central API 토큰. API 토큰은 IoT Central 애플리케이션의 역할과 연결됩니다.

REST API를 사용하는 자동화 및 스크립트를 개발하고 테스트하는 동안 사용자 계정과 연결된 전달자 토큰을 사용합니다. 프로덕션 자동화 및 스크립트에 서비스 주체와 연결된 전달자 토큰을 사용합니다. API 토큰에 대한 기본 설정으로 전달자 토큰을 사용하여 토큰이 만료될 때 누출 및 문제의 위험을 줄입니다.

IoT Central의 사용자 및 역할에 대해 자세히 알아보려면 IoT Central 애플리케이션에서 사용자 및 역할 관리를 참조하세요.

전달자 토큰 가져오기

Microsoft Entra 사용자 계정에 대한 전달자 토큰을 가져오려면 다음 Azure CLI 명령을 사용합니다.

az login
az account get-access-token --resource https://apps.azureiotcentral.com

Important

az login 명령은 Cloud Shell를 사용하는 경우에도 필요합니다.

이전 명령의 JSON 출력은 다음 예제와 같습니다.

{
  "accessToken": "eyJ0eX...fNQ",
  "expiresOn": "2021-03-22 11:11:16.072222",
  "subscription": "{your subscription id}",
  "tenant": "{your tenant id}",
  "tokenType": "Bearer"
}

전달자 토큰은 약 1시간 동안 유효하며, 그 후에는 새로 만들어야 합니다.

서비스 주체용 전달자 토큰을 가져오려면 서비스 주체 인증을 참조하세요.

API 토큰 가져오기

API 토큰을 가져오려면 IoT Central UI 또는 REST API 호출을 사용하면 됩니다. 루트 조직과 연결된 관리자 및 올바른 역할에 할당된 사용자는 API 토큰을 만들 수 있습니다.

팁

API 토큰에 대한 만들기 및 삭제 작업은 감사 로그에 기록됩니다.

IoT Central UI 사용:

권한 > API 토큰으로 이동합니다.
+ 새로 만들기 또는 API 토큰 만들기를 선택합니다.
토큰의 이름을 입력하고 역할 및 조직을 선택합니다.
생성을 선택합니다.
IoT Central에 다음 예제와 같은 토큰이 표시됩니다.

SharedAccessSignature sr=5782ed70...&sig=dvZZE...&skn=operator-token&se=1647948035850

이 화면은 API 토큰을 볼 수 있는 유일한 시간입니다. 분실한 경우 새로 생성해야 합니다.

API 토큰은 약 1년 동안 유효합니다. IoT Central 애플리케이션에서 기본 제공 역할과 사용자 지정 역할 모두에 대한 토큰을 생성할 수 있습니다. API 토큰을 만들 때 선택하는 조직은 API가 액세스할 수 있는 디바이스를 결정합니다. 애플리케이션에 조직을 추가하기 전에 만든 모든 API 토큰은 루트 조직과 연결됩니다.

액세스를 취소해야 하는 경우 IoT Central UI에서 API 토큰을 삭제할 수 있습니다.

REST API 사용:

REST API를 사용하여 애플리케이션에서 역할 ID 목록을 검색합니다.

GET https://{your app subdomain}.azureiotcentral.com/api/roles?api-version=2022-07-31

이 요청에 대한 응답은 다음 예제와 같습니다.

{
  "value": [
    {
      "displayName": "Administrator",
      "id": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"
    },
    {
      "displayName": "Operator",
      "id": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    },
    {
      "displayName": "Builder",
      "id": "344138e9-8de4-4497-8c54-5237e96d6aaf"
    }
  ]
}

REST API를 사용하여 역할에 대한 API 토큰을 만듭니다. 예를 들어 연산자 역할에 대해 operator-token이라는 API 토큰을 만들려면 다음을 사용합니다.

PUT https://{your app subdomain}.azureiotcentral.com/api/apiToken/operator-token?api-version=2022-07-31

요청 본문.:

{
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ]
}

이전 명령에 대한 응답은 다음 JSON과 같습니다.

{
  "expiry": "2022-03-22T12:01:27.889Z",
  "id": "operator-token",
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ],
  "token": "SharedAccessSignature sr=e8a...&sig=jKY8W...&skn=operator-token&se=1647950487889"
}

이 응답은 API 토큰에 액세스할 수 있는 유일한 시간입니다. 분실한 경우 새로 생성해야 합니다.

REST API를 사용하여 애플리케이션에서 API 토큰을 나열하고 삭제할 수 있습니다.

전달자 토큰 사용

REST API를 호출할 때 전달자 토큰을 사용하려면 권한 부여 헤더가 다음 예제와 같습니다.

Authorization: Bearer eyJ0eX...fNQ

API 토큰 사용

REST API를 호출할 때 API 토큰을 사용하려면 권한 부여 헤더가 다음 예제와 같습니다.

Authorization: SharedAccessSignature sr=e8a...&sig=jKY8W...&skn=operator-token&se=1647950487889