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

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

인증 및 승인

이 섹션에서는 Fleet Engine과의 통합과 관련하여 인증 및 승인의 개념을 설명합니다.

Google Cloud 콘솔을 통해 라스트 마일 Fleet 솔루션에서 제공하는 기능을 구성할 수 있습니다. Fleet Engine SDK를 사용하려면 적절한 서비스 계정으로 서명된 JSON 웹 토큰 (JWT)을 사용해야 합니다.

개요

Fleet Engine에서 인증 및 승인하는 고객 백엔드는 표준 애플리케이션 기본 사용자 인증 정보 메커니즘을 사용해야 합니다.

Fleet Engine은 또한 스마트폰 및 브라우저와 같은 신뢰도가 낮은 환경에서 발생한 호출을 수신합니다. 신뢰할 수 있는 환경에만 적합한 서비스 계정 보안 비밀 키를 보호하려면 고객의 백엔드는 Fleet Engine과 관련된 추가 클레임으로 서명된 JSON 웹 토큰 (JWT)을 생성해야 합니다. 그러면 이 클레임이 휴대전화와 같이 신뢰할 수 없는 환경에 발급될 수 있습니다.

인증 설계 원칙

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

IAM 역할은 주 구성원에게 허용되는 리소스에 대한 권한 집합을 정의합니다. 예를 들어 Admin 역할은 애플리케이션 기본 사용자 인증 정보로 모든 작업을 할 수 있는 반면, Untrusted Driver* 역할은 차량 위치를 업데이트하는 데만 허용되고 인증 및 승인을 위한 JWT 사용으로 제한됩니다.
신뢰할 수 없는 환경의 경우 JWT 클레임은 호출자가 작업할 수 있는 항목을 추가로 제한합니다. 특정 작업 또는 배송 수단일 수 있습니다.
신뢰도가 낮은 환경에서 실행되는 코드는 먼저 신뢰할 수 있는 환경에서 실행되는 코드를 호출하여 JWT를 발급해야 합니다.
Fleet Engine은 리소스의 API 호출에 다음 보안 검사를 수행합니다.
1. 호출하는 주 구성원에게 역할 할당을 통해 리소스에 대한 작업에 대한 적절한 권한이 있습니다.
2. 비관리자 역할의 경우 요청에서 전달된 JWT 클레임은 리소스에 필요한 권한을 제공합니다.

인증 흐름

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

Fleet 관리자가 서비스 계정을 만듭니다.
Fleet 관리자가 서비스 계정에 특정 IAM 역할을 할당합니다.
Fleet 관리자가 서비스 계정 및 애플리케이션 기본 사용자 인증 정보로 백엔드를 구성합니다.
클라이언트 앱이 고객 백엔드에서 JWT를 요청합니다. 요청자는 드라이버 앱, 소비자 앱 또는 모니터링 앱일 수 있습니다.
고객 백엔드에서 각 서비스 계정에 대해 JWT를 서명하고 발급합니다. 클라이언트 앱이 JWT를 수신합니다.
클라이언트 앱은 설정 단계에서 할당된 IAM 역할에 따라 JWT를 사용하여 Fleet Engine에 연결하여 데이터를 읽거나 수정합니다.

인증 시퀀스 다이어그램

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.deliveryAdmin`	게재 리소스에 대한 읽기 및 쓰기 권한을 부여합니다. 이 역할이 있는 주 구성원은 JWT를 사용할 필요가 없으며 대신 애플리케이션 기본 사용자 인증 정보를 사용해야 합니다. 커스텀 JWT 클레임은 무시됩니다. 이 역할은 신뢰할 수 있는 환경 (고객 백엔드)으로 제한해야 합니다.
~~Fleet Engine Delivery 수퍼유저~~ (지원 중단됨) `roles/fleetengine.deliverySuperUser`	모든 배송 차량 및 태스크 API에 대한 권한을 부여합니다. 이 역할을 가진 서비스 계정에서 발급된 토큰은 일반적으로 백엔드 서버에서 사용됩니다.
Fleet Engine Delivery Fleet 리더 `roles/fleetengine.deliveryFleetReader`	배송 차량 및 작업을 읽고 추적 ID를 사용하여 작업을 검색할 수 있는 권한을 부여합니다. 이 역할을 가진 서비스 계정에서 발급된 토큰은 일반적으로 배송 Fleet 운영자의 웹브라우저에서 사용됩니다.

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

BYOD(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 Engine 토큰을 만드는 프로세스를 간소화합니다.
사용자 인증 정보 파일 사용 이외의 토큰 서명 메커니즘 (예: 서비스 계정 가장)을 제공합니다.

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

Fleet Engine 인증 라이브러리를 사용하지 않는 경우 코드베이스 내에서 직접 JWT를 작성해야 합니다. 이를 위해서는 JWT와 Fleet Engine과의 관계에 대한 이해가 필요합니다. 따라서 Fleet Engine 인증 라이브러리를 활용할 것을 적극 권장합니다.

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

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

필드	설명
`alg`	사용할 알고리즘입니다. `RS256`
`typ`	토큰 유형입니다. `JWT`입니다.
`kid`	서비스 계정의 비공개 키 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시간을 넘으면 요청이 실패합니다.
`authorization`	사용 사례에 따라 `deliveryvehicleid`, `trackingid`, `taskid` 또는 `taskids`를 포함할 수 있습니다.

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

JWT 클레임

라스트 마일 플릿 솔루션은 비공개 클레임을 사용합니다. 비공개 클레임을 사용하면 승인된 클라이언트만 자체 데이터에 액세스할 수 있습니다. 예를 들어 백엔드가 배달 기사의 휴대기기에 관한 JSON 웹 토큰을 발급하는 경우 이 토큰에는 배달 기사의 배달 차량 ID 값과 함께 deliveryvehicleid 클레임이 포함되어야 합니다. 그런 다음 운전자 역할에 따라 토큰은 특정 배송 차량 ID에만 액세스를 사용 설정하고 다른 임의의 차량 ID에는 액세스하지 않습니다.

라스트 마일 플릿 솔루션은 다음과 같은 비공개 클레임을 사용합니다.

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

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

OAuth 2.0 액세스 토큰을 사용하는 대신 토큰 Bearer로 JSON을 직접 만들고 서명하려면 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입니다.

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