라스트 마일 Fleet 솔루션은 현재 일부 고객에게만 제공됩니다. 자세한 내용은 영업팀에 문의하세요.

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

인증 및 승인

이 섹션에서는 Fleet Engine 구현과 관련된 인증 및 승인 개념을 설명합니다. Fleet Engine 함수 호출을 보호하기 위해 수행해야 하는 절차를 자세히 설명합니다.

Google Cloud Console을 통해 Last Mile Fleet 솔루션에서 제공하는 기능을 구성할 수 있습니다. 이러한 API와 SDK는 Cloud Console에서 생성된 서비스 계정을 사용하여 서명된 JSON 웹 토큰 (JWT)을 사용해야 합니다.

개요

승인 메커니즘의 일부로 Fleet Engine은 신뢰할 수 없는 환경에서 발생한 호출로부터 추가 보안을 제공합니다. 신뢰할 수 없는 환경에는 스마트폰과 브라우저가 포함됩니다. 또한 Fleet Engine은 최소 권한 원칙을 채택하여 작업을 완료하는 데 필요한 권한만 호출에 부여해야 합니다.

신뢰할 수 없는 환경에서 발생하는 함수 호출을 보호하기 위해 Google은 코드가 완전히 신뢰할 수 있는 환경인 백엔드 서버에서 토큰을 만드는 메커니즘을 설계했습니다. 각 호출은 완전한 보안 설명을 전달하며, 이 설명은 모든 환경에서 호출 시 전달되는 JWT로 암호화됩니다.

인증 설계 원칙

Fleet Engine의 인증 흐름에는 다음 설계 원칙이 적용됩니다.

IAM 역할은 호출자에게 허용되는 활동 범위를 정의합니다. 예를 들어 SuperUser 역할은 모든 작업을 할 수 있는 반면 신뢰할 수 없는 드라이버 역할은 최소한의 위치 업데이트만 수행할 수 있습니다.
IAM 역할은 서비스 계정과 연결됩니다.
JWT 클레임은 호출자가 작업할 수 있는 항목을 추가로 제한합니다. 이는 특정 작업 또는 배달 수단일 수 있습니다.
Fleet Engine으로 전송되는 요청에는 항상 JWT가 포함됩니다.
- JWT는 서비스 계정과 연결되므로 Fleet Engine으로 전송되는 요청은 JWT와 연결된 서비스 계정과 암시적으로 연결됩니다.
그런 다음 Fleet Engine에 전달할 수 있는 적절한 JWT를 요청하려면 먼저 신뢰할 수 있는 환경에서 실행되는 코드가 완전히 신뢰할 수 있는 환경에서 실행되는 코드를 호출해야 합니다.
Fleet Engine은 다음 보안 검사를 수행합니다.
1. 서비스 계정과 연결된 IAM 역할은 호출자에게 API 호출을 실행할 수 있는 올바른 권한을 제공합니다.
2. 요청에서 전달된 JWT 클레임은 호출자가 항목에 대해 작업할 수 있도록 올바른 승인을 제공합니다.

인증 흐름

다음 시퀀스 다이어그램은 이러한 인증 흐름 세부정보를 보여줍니다.

Fleet 관리자가 서비스 계정을 만듭니다.
Fleet 관리자가 특정 IAM 역할을 서비스 계정에 할당합니다.
Fleet 관리자는 서비스 계정으로 백엔드를 구성합니다.
클라이언트 앱이 파트너의 백엔드에서 JWT를 요청합니다. 요청자는 드라이버 앱, 소비자 앱 또는 모니터링 앱일 수 있습니다.
Fleet Engine이 각 서비스 계정에 대한 JWT를 발급합니다. 클라이언트 앱이 JWT를 수신합니다.
클라이언트 앱은 JWT를 사용하여 Fleet Engine에 연결하여 설정 단계에서 할당된 IAM 역할에 따라 데이터를 읽거나 수정합니다.

인증 시퀀스 다이어그램

Cloud 프로젝트 설정

클라우드 프로젝트를 설정하려면 먼저 프로젝트를 만든 후 서비스 계정을 만드세요.

Google Cloud 프로젝트를 만들려면 다음 안내를 따르세요.

Google Cloud 콘솔을 사용하여 Google Cloud 프로젝트를 만듭니다.
API 및 서비스 대시보드를 사용하여 Local Rides and Deliveries API를 사용 설정합니다.

서비스 계정 및 IAM 역할

서비스 계정은 사람이 아닌 애플리케이션에서 사용하는 특별한 종류의 계정입니다. 일반적으로 서비스 계정은 역할에 따라 서로 다른 권한 집합을 부여하는 JWT를 발급하는 데 사용됩니다. 악용 가능성을 줄이기 위해 각각 필요한 최소한의 역할이 포함된 서비스 계정을 여러 개 만들 수 있습니다.

라스트 마일 Fleet 솔루션은 다음 역할을 사용합니다.

역할	설명
Fleet Engine Delivery 신뢰할 수 있는 드라이버 사용자 `roles/fleetengine.deliveryTrustedDriver`	배송 차량 위치와 작업 상태 또는 결과 업데이트를 포함하여 배송 차량과 작업을 만들고 업데이트할 수 있는 권한을 부여합니다. 이 역할을 가진 서비스 계정으로 발급된 토큰은 일반적으로 배달 기사의 휴대기기 또는 백엔드 서버에서 사용됩니다.
Fleet Engine Delivery를 신뢰할 수 없는 드라이버 사용자 `roles/fleetengine.deliveryUntrustedDriver`	배송 차량 위치를 업데이트할 권한을 부여합니다. 이 역할을 가진 서비스 계정으로 발급된 토큰은 일반적으로 배달 기사의 휴대기기에서 사용됩니다.
Fleet Engine Delivery 소비자 사용자 `roles/fleetengine.deliveryConsumer`	추적 ID를 사용하여 태스크를 검색하고 태스크 정보를 읽을 수 있지만 업데이트하지 않을 권한을 부여합니다. 이 역할을 가진 서비스 계정으로 발급된 토큰은 일반적으로 게재 소비자의 웹브라우저에서 사용됩니다.
Fleet Engine Delivery 수퍼유저 `roles/fleetengine.deliverySuperUser`	모든 배달 차량 및 작업 API에 대한 권한을 부여합니다. 이 역할을 가진 서비스 계정으로 발급된 토큰은 일반적으로 백엔드 서버에서 사용됩니다.
Fleet Engine Delivery Fleet 리더 `roles/fleetengine.deliveryFleetReader`	배송 차량 및 작업을 읽고 추적 ID를 사용하여 작업을 검색할 수 있는 권한을 부여합니다. 이 역할을 가진 서비스 계정으로 발급된 토큰은 일반적으로 배송 Fleet 운영자의 웹브라우저에서 사용됩니다.

회사 IT에서 관리하는 기기를 배송 기사에게 제공하는 조직은 Fleet Engine 신뢰할 수 있는 운전자 사용자 역할이 제공하는 유연성을 활용하고 Fleet Engine 상호작용의 일부 또는 전체를 모바일 앱에 통합할 수 있습니다.

Bring Your Own Device(자체 기기 사용) 정책을 지원하는 조직은 Fleet Engine 신뢰할 수 없는 운전자 사용자 역할의 안전을 선택하고 모바일 앱만 사용하여 차량 위치 업데이트를 Fleet Engine에 전송해야 합니다. 다른 모든 상호작용은 고객 백엔드 서버에서 시작되어야 합니다.

드라이버 및 소비자 SDK는 이러한 표준 역할을 중심으로 빌드됩니다. 그러나 임의의 권한 집합을 번들로 묶을 수 있는 커스텀 역할을 만들 수도 있습니다. 필요한 권한이 없으면 드라이버 및 소비자 SDK에 오류 메시지가 표시됩니다. 따라서 커스텀 역할 대신 위에 설명된 표준 역할 집합을 사용하는 것이 좋습니다.

서비스 계정 만들기

Google Cloud Console의 IAM & Admin > Service Accounts 탭을 사용하여 서비스 계정을 만들 수 있습니다. 역할 드롭다운 목록에서 Fleet Engine을 선택하고 역할 중 하나를 서비스 계정에 할당합니다. 각 역할과 연결된 계정을 지정하는 것이 좋습니다. 예를 들어 서비스 계정에 의미 있는 이름을 지정합니다.

편의상 신뢰할 수 없는 클라이언트의 JWT를 발급해야 하는 경우 서비스 계정 토큰 생성자 역할에 사용자를 추가하면 gcloud 명령줄 도구로 토큰을 발급할 수 있습니다.

gcloud projects add-iam-policy-binding project-id \
       --member=user:my-user@example.com \
       --role=roles/iam.serviceAccountTokenCreator

여기서 my-user@example.com은 gcloud (gcloud auth list --format='value(account)')로 인증하는 데 사용되는 이메일입니다.

Fleet Engine 인증 라이브러리

Fleet Engine은 JWT를 사용하여 Fleet Engine API에 대한 액세스를 제한합니다. GitHub에서 제공되는 새로운 Fleet Engine 인증 라이브러리를 사용하면 Fleet Engine JWT의 구성을 간소화하고 안전하게 서명할 수 있습니다.

라이브러리는 다음과 같은 이점을 제공합니다.

Fleet 엔진 토큰 생성 프로세스가 간소화됩니다.
사용자 인증 정보 파일 사용 이외의 토큰 서명 메커니즘 (예: 서비스 계정 가장)을 제공합니다.
gRPC 스텁 또는 GAIC 클라이언트에서 작성된 아웃바운드 요청에 서명된 토큰을 연결합니다.

승인을 위한 JSON 웹 토큰 (JWT) 만들기

Fleet Engine 인증 라이브러리를 사용하지 않는 경우 코드베이스에서 직접 JWT를 만들어야 합니다. 이를 위해서는 JWT와 JWT가 Fleet Engine과 어떤 관련이 있는지에 대해 깊이 이해하고 있어야 합니다. 이러한 이유로 Fleet Engine 인증 라이브러리를 활용하는 것이 좋습니다.

Fleet Engine 내에서 JWT는 단기 인증을 제공하며 기기가 승인된 차량 또는 작업만 수정할 수 있도록 합니다. JWT에는 헤더와 클레임 섹션이 포함됩니다. 헤더 섹션에는 사용할 비공개 키 (서비스 계정에서 가져옴) 및 암호화 알고리즘과 같은 정보가 포함됩니다. 클레임 섹션에는 토큰의 생성 시간, 토큰의 TTL(수명), 토큰의 액세스 권한을 요청하는 서비스, 액세스 범위를 줄이기 위한 기타 승인 정보(예: 배달 차량 ID)가 포함됩니다.

JWT 헤더 섹션에는 다음 필드가 포함됩니다.

필드	설명
alg	사용할 알고리즘입니다. `RS256`.
typ	토큰 유형입니다. `JWT`.
어린이	서비스 계정의 비공개 키 ID 이 값은 서비스 계정 JSON 파일의 `private_key_id` 필드에서 찾을 수 있습니다. 올바른 수준의 권한으로 서비스 계정의 키를 사용해야 합니다.

JWT 클레임 섹션에는 다음 필드가 포함되어 있습니다.

필드	설명
iss	서비스 계정의 이메일 주소입니다.
sub	서비스 계정의 이메일 주소입니다.
aud	서비스 계정의 SERVICE_NAME(이 경우 https://fleetengine.googleapis.com/)
iat	토큰이 생성된 타임스탬프로, 1970년 1월 1일 00:00:00 UTC 이후 경과된 초 단위로 지정됩니다. 편향이 발생할 수 있도록 10분간 기다립니다. 타임스탬프가 너무 먼 과거 또는 미래인 경우 서버에서 오류를 보고할 수 있습니다.
exp	토큰 만료 시점의 타임스탬프로, 1970년 1월 1일 00:00:00 UTC 이후 경과된 초로 지정됩니다. 타임스탬프가 1시간을 넘으면 요청이 실패합니다.
승인	사용 사례에 따라 `deliveryvehicleid`, `trackingid`, `taskid` 또는 `taskids`를 포함할 수 있습니다.

JWT 토큰 발급이란 서명을 의미합니다. JWT를 만들고 서명하는 안내와 코드 샘플은 OAuth 없이 서비스 계정 승인을 참조하세요. 그런 다음 발행된 토큰을 gRPC 호출 또는 Fleet Engine에 액세스하는 데 사용되는 다른 메서드에 연결할 수 있습니다.

JWT 클레임

Last Mile Fleet 솔루션이 비공개 소유권 주장을 사용합니다. 비공개 클레임을 사용하면 승인된 클라이언트만 자체 데이터에 액세스할 수 있습니다. 예를 들어 백엔드에서 배달 기사의 휴대기기에 JSON 웹 토큰을 발행하면 토큰에는 해당 운전자의 배달 차량 ID 값이 있는 deliveryvehicleid 클레임이 포함되어야 합니다. 그런 다음 운전자 역할에 따라 토큰은 임의의 다른 차량 ID가 아닌 특정 배달 차량 ID에만 액세스를 사용 설정합니다.

Last Mile Fleet 솔루션은 다음과 같은 비공개 클레임을 사용합니다.

deliveryvehicleid - 운송 차량별 API를 호출할 때 사용합니다.
taskid - 태스크별 API를 호출할 때 사용합니다.
taskids - BatchCreateTasksAPI를 호출할 때 사용합니다. 이 클레임은 배열 형식이어야 하며 배열에 요청을 완료하는 데 필요한 모든 작업 ID가 포함되어야 합니다. delivervehicleid, trackingid 또는 taskid 클레임을 포함하지 마세요.
trackingid - SearchTasksAPI를 호출할 때 사용합니다. 소유권 주장은 요청의 추적 ID와 일치해야 합니다. delivervehicleid, taskid 또는 taskids 클레임을 포함하지 마세요.

또한 백엔드 서버에서 API를 호출할 때는 토큰에 적절한 클레임이 포함되어 있어야 하지만 deliveryvehicleid, taskid, trackingid 클레임에 별표('*')의 특수 값을 사용할 수 있습니다. taskids 클레임에도 별표('*')를 사용할 수 있지만 배열에서 유일한 요소여야 합니다.

OAuth 2.0 액세스 토큰을 사용하는 대신 JSON을 토큰 Bearer로 직접 만들고 서명하려면 ID 개발자 문서에서 OAuth를 사용하지 않는 서비스 계정 승인 안내를 참조하세요.

토큰을 gRPC 호출에 연결하는 메커니즘은 호출을 수행하는 데 사용된 언어와 프레임워크에 따라 다릅니다. HTTP 호출에 토큰을 지정하는 메커니즘은 개별 배송 추적 또는 Fleet 성능 사용 사례에 대한 승인 메모에 명시된 것처럼 값이 토큰인 Bearer 토큰과 함께 승인 헤더를 포함하는 것입니다.

다음 예시에서는 백엔드 서버의 태스크별 작업 토큰을 보여줍니다.

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_provider_service_account"
    }
    .
    {
      "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
      "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "taskid": "*"
       }
    }

다음 예시는 백엔드 서버에서의 일괄 작업 만들기 작업의 토큰을 보여줍니다.

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_provider_service_account"
    }
    .
    {
      "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
      "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "taskids": ["*"]
       }
    }

다음 예시는 백엔드 서버의 배송 차량별 작업의 토큰을 보여줍니다.

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_provider_service_account"
    }
    .
    {
      "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
      "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "deliveryvehicleid": "*"
       }
    }

다음 예시는 최종 사용자 고객용 토큰을 보여줍니다.

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_delivery_consumer_service_account"
    }
    .
    {
      "iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
      "sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "trackingid": "shipment_12345"
       }
    }

다음 예는 드라이버 앱의 토큰을 보여줍니다.

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_delivery_driver_service_account"
    }
    .
    {
      "iss": "driver@yourgcpproject.iam.gserviceaccount.com",
      "sub": "driver@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "deliveryvehicleid": "driver_12345"
       }
    }

헤더의 kid 필드에 서비스 계정의 비공개 키 ID를 지정합니다. 이 값은 서비스 계정 JSON 파일의 private_key_id 필드에서 찾을 수 있습니다.
iss 및 sub 필드에 서비스 계정의 이메일 주소를 지정합니다. 이 값은 서비스 계정 JSON 파일의 client_email 필드에서 찾을 수 있습니다.
aud 필드에 https://SERVICE_NAME/을 지정합니다.
iat 필드에는 토큰이 생성된 시점의 타임스탬프를 1970년 1월 1일 00:00:00 UTC 이후 경과된 초 단위로 지정합니다. 편향은 10분간 기다리세요. 타임스탬프가 너무 먼 과거 또는 미래인 경우 서버에서 오류를 보고할 수 있습니다.
exp 필드에는 토큰이 만료되는 시점의 타임스탬프를 1970년 1월 1일 00:00:00 UTC 이후의 초 단위로 지정합니다. 권장 값은 iat + 3600입니다.

휴대기기 또는 최종 사용자에게 전달할 토큰에 서명할 때는 배달 드라이버 또는 소비자 역할의 사용자 인증 정보 파일을 사용해야 합니다. 그렇지 않으면 휴대기기 또는 최종 사용자가 액세스해서는 안 되는 정보를 변경하거나 볼 수 있습니다.