이 문서에서는 웹 및 모바일 기반 앱이 Fleet Engine 데이터에 액세스할 수 있도록 하는 과정에서 JSON 웹 토큰을 발급하는 방법을 설명합니다. 아직 하지 않았다면 Fleet Engine의 보안 섹션에서 JSON 웹 토큰을 읽어보세요. Fleet Engine 서비스를 사용하면 다음 방법 중 하나로 JWT를 발급할 수 있습니다.
- 승인 라이브러리 사용: 코드베이스가 Java로 작성된 경우 이 접근 방식을 사용하는 것이 좋습니다. 이 라이브러리는 서비스에 필요할 수 있는 모든 사용 사례 시나리오의 JWT 발급을 처리하며 구현을 크게 간소화합니다.
- 자체 JWT 만들기: Google의 JWT 라이브러리를 사용할 수 없는 경우 자체 코드베이스에 빌드해야 합니다. 이 섹션에서는 각 시나리오에 관한 JWT의 다양한 예시를 제공합니다.
JWT 작동 방식
휴대전화 및 웹브라우저와 같이 신뢰할 수 없는 환경의 경우 백엔드 서버가 다음과 같이 작동하는 JWT를 발급합니다.
신뢰도가 낮은 환경에서 실행되는 클라이언트 코드는 완전히 신뢰할 수 있는 환경에서 실행되는 서버 코드를 호출하여 Fleet Engine에 전달할 적절한 JWT를 요청합니다.
JWT는 서비스 계정과 연결되므로 Fleet Engine으로 전송된 요청은 JWT에 서명한 서비스 계정과 암시적으로 연결됩니다.
JWT 클레임은 특정 차량, 이동, 작업 등 클라이언트가 작동할 수 있는 리소스를 추가로 제한합니다.
Java용 승인 라이브러리 사용
Java용 Fleet Engine 승인 라이브러리를 사용하려면 GitHub 저장소를 방문하세요. 이 라이브러리는 Fleet Engine JWT의 생성을 간소화하고 안전하게 서명합니다. 이 API는 다음과 같은 기능을 제공합니다.
- 프로젝트 종속 항목 선언
- 주문형 이동 또는 예약된 작업에 대한 모든 서비스 계정 역할의 전체 목록
- 사용자 인증 정보 파일을 사용하는 것 이외의 토큰 서명 메커니즘(예: 서비스 계정 명의 도용)
- 서명된 토큰을 gRPC 스텁 또는 Google API Codegen (GAPIC) 클라이언트 라이브러리에서 생성한 아웃바운드 요청에 연결합니다.
- 서명자를 Fleet Engine 클라이언트 라이브러리와 통합하는 방법에 대한 안내입니다.
코드에서 JWT를 발행하는 경우
Java용 승인 라이브러리를 사용할 수 없는 경우, 자체 코드베이스에 JWT를 구현해야 합니다. 이 섹션에서는 자체 토큰을 만들기 위한 몇 가지 가이드라인을 제공합니다. JWT 필드 및 클레임 목록은 Fleet Engine의 보안 섹션에 있는 JSON 웹 토큰을 참고하세요. Fleet Engine에서 사용하는 서비스 계정 역할은 서비스 계정 역할을 참고하세요. 주문형 이동 또는 예약된 태스크에 대한 JWT 예시 목록은 다음 섹션을 참조하세요.
일반 가이드라인
- 적절한 서비스 계정 및 역할을 사용합니다. 서비스 계정과 연결된 역할은 토큰을 요청하는 사용자가 토큰이 액세스 권한을 부여하는 정보를 볼 수 있는 권한이 있는지 확인합니다. 구체적으로는 다음과 같습니다.
- 휴대기기에 전달할 JWT에 서명하는 경우 드라이버 또는 소비자 SDK 역할의 서비스 계정을 사용합니다. 그러지 않으면 휴대기기가 액세스해서는 안 되는 데이터를 변경하고 액세스할 수 있습니다.
- 권한 있는 호출에 사용할 JWT에 서명하는 경우 ADC 또는 JWT를 사용할 때는 올바른 Fleet Engine 관리자 역할로 서비스 계정을 사용하세요. 그렇지 않으면 작업이 실패합니다.
- 생성된 토큰만 공유합니다. 토큰을 만드는 데 사용된 사용자 인증 정보를 공유하지 마세요.
- gRPC 호출의 경우 토큰을 연결하는 메커니즘은 호출하는 데 사용된 언어와 프레임워크에 따라 다릅니다. HTTP 호출에 토큰을 지정하는 메커니즘은 값이 토큰인 Bearer 토큰이 있는
Authorization헤더를 포함하는 것입니다. - 만료 시간을 반환합니다. 서버는 일반적으로 초 단위로 토큰의 만료 시간을 반환해야 합니다.
- OAuth 2.0 액세스 토큰을 사용하는 대신 JSON을 토큰 소유자로 직접 생성하고 서명해야 하는 경우, ID 개발자 문서에서 OAuth 없이 서비스 계정 승인에 관한 안내를 참고하세요.
주문형 이동의 경우
- JWT 페이로드를 만들 때 호출이 이루어지는 차량 ID 또는 이동 ID의 값으로 키
vehicleid또는tripid를 설정하여 승인 섹션에 클레임을 추가합니다.
예약된 작업
- 서버가 다른 API를 호출할 때 토큰에는 적절한 클레임도 포함되어야 합니다. 이를 위해 다음을 수행할 수 있습니다.
- 각 키의 값을
*로 설정합니다. - 사용자에게 모든
taskids및deliveryvehicleids에 대한 액세스 권한을 부여합니다. 이렇게 하려면 승인 섹션에 키taskid및deliveryvehicleid를 사용하여 추가 클레임을 추가합니다. taskids클레임에서 별표 (*)를 사용할 때는 이 요소가 배열의 유일한 요소여야 합니다.
- 각 키의 값을
주문형 이동을 위한 JWT 예시
이 섹션에서는 주문형 이동을 사용하는 경우 일반적인 시나리오에 관한 JWT 예시를 제공합니다.
운전자 앱 작업의 토큰 예시
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_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": {
"vehicleid": "driver_12345"
}
}
소비자 앱 작업의 토큰 예시
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_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": {
"tripid": "trip_54321"
}
}
예약된 작업을 위한 JWT 예시
이 섹션에서는 예약 태스크를 사용하는 경우의 일반적인 시나리오에 대한 JWT 예시를 제공합니다.
드라이버 앱의 토큰 예
{
"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"
}
}
소비자 앱의 토큰 예시
{
"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"
}
}
Fleet 작업을 위한 JWT 예시
이 섹션에서는 차량 운영의 일반적인 시나리오에 관한 JWT 예시를 제공합니다.
Fleet의 모든 태스크 및 차량을 추적하는 토큰 예시
다음 예는 운영자가 사용하는 웹 기반 앱에서 Fleet에 있는 모든 태스크 및 차량을 추적하는 토큰입니다. 이러한 작업에 필요한 권한은 클라이언트 애플리케이션에 필요한 권한보다 많습니다. 이 토큰을 사용하는 클라이언트 측 구현은 JavaScript Fleet 추적 라이브러리 설정을 참고하세요.
Fleet Engine Delivery Fleet ReaderCloud IAM 역할을 사용하여 토큰에 서명합니다.
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_consumer_service_account"
}
.
{
"iss": "superuser@yourgcpproject.iam.gserviceaccount.com",
"sub": "superuser@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"scope": "https://www.googleapis.com/auth/xapi",
"authorization": {
"taskid": "*",
"deliveryvehicleid": "*",
}
}
백엔드 서버 작업을 위한 대체 인증 방법
ADC를 사용하여 백엔드 서버 작업을 인증하는 것이 좋습니다. ADC를 사용할 수 없고 JWT를 사용해야 하는 경우 다음 예시를 참고하세요.
주문형 백엔드 서버 작업의 예시 토큰
{ "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": { "vehicleid": "*", "tripid": "*" } }
예약된 백엔드 서버 작업의 토큰 예시
{ "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": "*" } }