본문으로 건너뛰기

기계 간: Logto로 인증 (Authentication)

노트:

이 가이드는 Admin Console에서 "Machine-to-machine" 유형의 애플리케이션을 생성했다고 가정합니다.

소개​

기계 간 (M2M)은 앱 (사용자가 아닌)이 리소스와 직접 통신해야 할 때 일반적으로 사용하는 인증 방법입니다 (일반적으로 M2M 앱은 사용자 상호작용이 필요 없으므로 UI가 없습니다). 예를 들어, Logto에서 사용자의 맞춤 데이터를 업데이트하는 API 서비스, 일일 주문을 가져오는 통계 서비스 등이 있습니다.

Logto는 역할 기반 접근 제어 (RBAC)를 접근 제어 정책으로 사용하므로, M2M 앱에 M2M 역할을 할당하여 직접 서비스 통신이 필요한 API를 보호하는 것이 필요합니다.

정보:

현재 RBAC 및 사용자 역할과 M2M 역할의 차이에 대해 알아보려면, 역할 구성을 참조하세요.

Logto에서 기계 간 앱을 사용하는 두 가지 일반적인 사용 사례가 있습니다:

  1. Logto Management API에 접근하기: 이 경우, 내장된 Logto Management API에서 all 권한을 포함하는 M2M 역할을 M2M 앱에 할당해야 합니다.
  2. 자신의 API 리소스에 접근하기: 이 경우, 자신의 API 리소스에서 권한을 포함하는 M2M 역할을 M2M 앱에 할당해야 합니다.

M2M 앱 생성 과정에서, 애플리케이션에 M2M 역할을 할당할 수 있는 페이지로 안내됩니다:

Assign M2M roles modal

또는 이미 M2M 앱이 생성된 경우, M2M 앱 상세 페이지에서 이러한 역할을 할당할 수도 있습니다:

Assign M2M roles page

이제 전체 과정을 살펴보겠습니다. 명확성을 위해 Logto Management API와 다른 API 리소스에 접근하는 단계를 분리하겠습니다. 그리고 Logto에서 이미 M2M 앱을 생성했다고 가정합니다.

액세스 토큰 가져오기​

액세스 토큰 요청의 기본 사항​

M2M 앱은 HTTP 요청 엔티티 본문에 application/x-www-form-urlencoded 형식으로 다음 매개변수를 추가하여 토큰 엔드포인트에 액세스 토큰을 가져오기 위해 POST 요청을 합니다:

  • grant_type: client_credentials로 설정해야 합니다
  • resource: 액세스하려는 리소스
  • scope: 액세스 요청의 스코프

또한, 토큰 엔드포인트가 M2M 앱을 인증할 수 있도록 요청 헤더에 M2M 앱의 자격 증명을 포함해야 합니다.

이는 요청 Authorization 헤더에 기본 인증 (Basic authentication) 형식으로 앱의 자격 증명을 포함하여 달성됩니다. 여기서 사용자 이름은 App ID이고, 비밀번호는 App Secret입니다.

M2M 앱의 세부 정보 페이지에서 App ID와 App Secret을 찾을 수 있습니다:

App ID and App Secret

액세스 토큰 요청의 예는 다음과 같습니다:

POST /oidc/token HTTP/1.1
Host: your.logto.endpoint
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&resource=https://shopping.api
&scope=read:products write:products

액세스 토큰 요청하기​

노트:

다음 시연에서는 https://your.logto.endpoint를 목표로 하는 Logto 엔드포인트로 교체하세요. Logto Cloud의 경우, https://{your-tenant-id}.logto.app가 됩니다.

Logto는 내장된 "Logto Management API" 리소스를 제공합니다. 이는 Logto Management API에 접근하기 위한 all 권한을 가진 읽기 전용 리소스이며, API 리소스 목록에서 확인할 수 있습니다. 리소스 API 지표는 https://{your-tenant-id}.logto.app/api 형식으로 되어 있으며, 이는 액세스 토큰 요청 본문에서 사용되는 리소스 값이 됩니다.

Logto Management API 세부사항

Logto Management API에 접근하기 전에, M2M 앱이 이 내장된 "Logto Management API" 리소스에서 all 권한을 포함하는 M2M 역할이 할당되었는지 확인하세요.

정보:

Logto는 새로 생성된 테넌트에 대해 사전 구성된 "Logto Management API 접근" M2M 역할도 제공합니다. 이 역할에는 Logto Management API 리소스의 모든 권한이 이미 할당되어 있습니다. 수동으로 권한을 설정하지 않고 직접 사용할 수 있습니다. 이 사전 구성된 역할은 필요에 따라 편집 및 삭제할 수도 있습니다.

이제 모든 것을 조합하여 요청을 보내세요:

const logtoEndpoint = 'https://your.logto.endpoint'; // Logto 엔드포인트로 교체하세요
const tokenEndpoint = `${logtoEndpoint}/oidc/token`;
const applicationId = 'your-application-id';
const applicationSecret = 'your-application-secret';
const tenantId = 'your-tenant-id';

const fetchAccessToken = async () => {
  return await fetch(tokenEndpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Authorization: `Basic ${Buffer.from(`${applicationId}:${applicationSecret}`).toString(
        'base64'
      )}`,
    },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      resource: `https://${tenantId}.logto.app/api`,
      scope: 'all',
    }).toString(),
  });
};
주의:

Logto Cloud 사용자에게: Logto Management API와 상호작용할 때는 사용자 정의 도메인을 사용할 수 없으며, 기본 Logto 엔드포인트 https://{your_tenant_id}.logto.app/oidc/token을 사용하여 액세스 토큰을 부여받아야 합니다.

액세스 토큰 응답​

성공적인 액세스 응답 본문은 다음과 같습니다:

{
  "access_token": "eyJhbG...2g", // Logto Management API에 접근하기 위한 이 토큰을 사용하세요
  "expires_in": 3600, // 토큰 만료 시간 (초 단위)
  "token_type": "Bearer", // 액세스 토큰을 사용할 때 요청의 인증 유형
  "scope": "all" // Logto Management API의 스코프 `all`
}
노트:

Logto는 현재 M2M 앱이 사용자를 나타내는 것을 지원하지 않습니다. 액세스 토큰 페이로드의 sub는 앱 ID가 됩니다.

액세스 토큰을 사용하여 리소스에 접근하기​

토큰 응답에 token_type 필드가 있으며, 이는 Bearer로 고정되어 있음을 알 수 있습니다.

따라서 API 리소스 서버와 상호작용할 때 액세스 토큰을 Bearer 형식 (Bearer YOUR_TOKEN)으로 HTTP 헤더의 Authorization 필드에 넣어야 합니다.

Logto의 모든 애플리케이션을 가져오기 위해 내장된 Logto Management API 리소스 https://[your-tenant-id].logto.app/api와 함께 요청된 액세스 토큰 (Access token)을 사용하세요:

const logtoEndpoint = 'https://your.logto.endpoint'; // Logto 엔드포인트로 교체하세요
const accessToken = 'eyJhb...2g'; // 액세스 토큰

const fetchLogtoApplications = async () => {
  return await fetch(`${logtoEndpoint}/api/applications`, {
    method: 'GET',
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  });
};

인증 (Authentication)​

Logto Management API 외의 자신의 API 리소스를 보호하는 경우, 리소스에 대한 인증을 구현해야 합니다. 자세한 내용은 API 보호하기를 참조하세요.