Docs Menu
Docs Home
/ / /
Node.js 드라이버
/ /

엔터프라이즈 인증 메커니즘

이 페이지의 내용

  • Kerberos (GSSAPI/SSPI)
  • LDAP (PLAIN)
  • MONGODB-OIDC
  • API 문서

이 가이드에서는 MongoDB Enterprise Edition에서 사용할 수 있는 각 인증 메커니즘을 사용하여 MongoDB에 연결하기 위한 샘플 코드를 찾을 수 있습니다: Kerberos (GSSAPI/SSPI), LDAP (PLAIN)MONGODB-OIDC.

참고

Node.js 드라이버는 UNIX에서는 MIT Kerberos 라이브러리를 사용하고 Windows에서는 SSPI API를 사용하여 Kerberos를 지원합니다.

GSSAPI 인증 메커니즘은 사용자 주체를 사용하여 Kerberos 서비스에 인증합니다.

연결 string 에 옵션을 지정하는 동안 다음 작업을 수행하여 이 인증 메커니즘을 지정할 수 있습니다.

  • authMechanism 매개 변수를 GSSAPI 로 설정합니다.

  • mongodb 이외의 값을 사용하는 경우 authMechanismProperties 매개 변수에서 SERVICE_NAME 값을 설정합니다.

  • 사용자 지정 서비스 영역이 필요한 경우 authMechanismProperties 매개 변수에 SERVICE_REALM 값을 지정합니다.

  • 호스트 이름을 정규화해야 하는 경우 authMechanismProperties 매개변수에 CANONICALIZE_HOST_NAME 값을 지정하세요. 이 속성은 다음 값을 사용할 수 있습니다.

    • none: (기본값) 호스트 이름 정규화를 수행하지 않습니다.

    • forward: 호스트 이름을 정규화하기 위해 정방향 DNS 조회를 수행합니다.

    • forwardAndReverse: 정방향 DNS 조회를 수행한 다음 해당 값을 역방향 조회하여 호스트 이름을 정규화합니다.

중요

gssapiServiceName 매개변수는 더 이상 사용되지 않으며 향후 드라이버 버전에서 제거될 수 있습니다. 대신 연결 URI에 authMechanismProperties=SERVICE_NAME:<your service name> 을(를) 사용하세요. 자세한 내용은 authMechanismProperties 매개변수 문서를 참조하세요.

다음 코드 샘플은 GSSAPI 을 사용하여 UNIX용 Kerberos에 인증합니다.

중요

항상 encodeURIComponent 메서드를 사용하여 주체를 URI로 인코딩 하여 올바르게 구문 분석되도록 합니다.

const { MongoClient } = require("mongodb");
// specify the placeholder values for your environment in the following lines
const clusterUrl = "<MongoDB cluster URL>";
const principal = encodeURIComponent("<Kerberos principal and realm>");
const serviceRealm = "<Kerberos service realm>";
const canonicalizationSetting = "<canonicalization setting>";
const authMechanismProperties = `SERVICE_REALM:${serviceRealm},CANONICALIZE_HOST_NAME:${canonicalizationSetting}`;
const authMechanism = "GSSAPI";
// Connection URI
const uri = `mongodb+srv://${principal}@${clusterUrl}/?authMechanism=${authMechanism}&authMechanismProperties=${authMechanismProperties}`;
const client = new MongoClient(uri);
// Function to connect to the server
async function run() {
try {
// Establish and verify connection
await client.db("admin").command({ ping: 1 });
console.log("Connected successfully to server");
} finally {
// Ensures that the client will close when you finish/error
await client.close();
}
}
run().catch(console.dir);

참고

드라이버가 GSSAPI RFC-4652 를 통해 인증하기 때문에 이 메서드는 대신 인증 GSSAPI Kerberos 메커니즘을 참조합니다. , SASL 메커니즘.

PLAIN 인증 메커니즘은 사용자 이름과 비밀번호를 사용하여 경량 디렉토리 액세스 프로토콜(LDAP) 서버에 인증합니다.

다음 샘플 코드와 authMechanism 같이 매개 변수를 로 설정하고 PLAIN LDAP 연결 에 string 사용자 이름 및 비밀번호를 포함하여 이 인증 메커니즘을 지정할 수 있습니다.

const { MongoClient } = require("mongodb");
// specify the placeholder values for your environment in the following lines
const clusterUrl = "<MongoDB cluster URL>";
const ldapUsername = "<LDAP username>";
const ldapPassword = "<LDAP password>";
const authMechanism = "PLAIN";
// Connection URI
const uri = `mongodb+srv://${ldapUsername}:${ldapPassword}@${clusterUrl}/?authMechanism=${authMechanism}`;
const client = new MongoClient(uri);
// Function to connect to the server
async function run() {
try {
// Establish and verify connection
await client.db("admin").command({ ping: 1 });
console.log("Connected successfully to server");
} finally {
// Ensures that the client will close when you finish/error
await client.close();
}
}
run().catch(console.dir);

참고

인증 메커니즘의 이름 PLAINLDAP RFC- 에 정의된 PLAIN 단순 인증 및 보안 계층(SASL) 을4616 사용하여 인증하기 때문에 대신 로 지정됩니다. .

중요

MONGODB-OIDC 인증 메커니즘을 사용하려면 Linux 플랫폼에서 실행되는 MongoDB Server v7.0 이상이 필요합니다.

다음 섹션에서는 MONGODB-OIDC 인증 메커니즘을 사용하여 다양한 플랫폼에서 인증하는 방법을 설명합니다.

MONGODB-OIDC 인증 메커니즘에 대한 자세한 내용은 MongoDB Server 매뉴얼의 OpenID Connect 인증MongoDB Server 매개변수 를 참조하세요.

애플리케이션이 Azure VM에서 실행되거나 Azure 인스턴스 메타데이터 서비스 를 사용하는 경우 (IMDS)를 사용하는 경우 Node.js 드라이버의 기본 제공 Azure 지원을 사용하여 MongoDB에 인증할 수 있습니다.

Azure IMDS OIDC를 인증 메커니즘으로 지정하려면 연결 문자열에서 다음 옵션을 설정합니다.

  • username: Azure 관리 ID를 사용하는 경우 이를 관리 ID의 클라이언트 ID로 설정합니다. 서비스 주체를 사용하여 엔터프라이즈 애플리케이션을 나타내는 경우 이를 서비스 주체의 애플리케이션 ID로 설정합니다. 그렇지 않으면 이 옵션을 생략합니다.

  • authMechanism: MONGODB-OIDC 로 설정합니다.

  • authMechanismProperties: ENVIRONMENT:azure,TOKEN_RESOURCE:<audience> 로 설정합니다. <audience> 자리 표시자를 MongoDB 배포에 구성된 audience 매개 변수의 값으로 바꿉니다.

다음 코드 예제에서는 앞의 연결 옵션을 설정하는 방법을 보여줍니다.

const { MongoClient } = require("mongodb");
const uri = "mongodb+srv://<username>@<hostname>:<port>/?authMechanism=MONGODB-OIDC"
+ "&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:<audience>";
const client = new MongoClient(uri);

애플리케이션이 Google Compute Engine VM에서 실행되거나 GCP 인스턴스 메타데이터 서비스 를 사용하는 경우 Node.js 드라이버의 기본 제공 GCP 지원을 사용하여 MongoDB에 인증할 수 있습니다.

GCP IMDS OIDC를 인증 메커니즘으로 지정하려면 연결 문자열에서 다음 옵션을 설정합니다.

  • authMechanism: MONGODB-OIDC 로 설정합니다.

  • authMechanismProperties: ENVIRONMENT:gcp,TOKEN_RESOURCE:<audience> 로 설정합니다. <audience> 자리 표시자를 MongoDB 배포에 구성된 audience 매개 변수의 값으로 바꿉니다.

다음 코드 예제에서는 앞의 연결 옵션을 설정하는 방법을 보여줍니다.

const { MongoClient } = require("mongodb");
const uri = "mongodb+srv://<host>:<port>/?authMechanism=MONGODB-OIDC"
+ "&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:<audience>";
const client = new MongoClient(uri);

Node.js 드라이버는 Azure Functions 및 Azure Kubernetes Service(AKS)를 포함한 모든 플랫폼에 대한 기본 지원을 제공하지 않습니다. 대신 OIDC를 사용하여 이러한 플랫폼에서 인증하려면 사용자 지정 콜백을 정의해야 합니다.

먼저, OIDC 인증에 사용할 액세스 토큰을 검색하는 함수를 정의합니다. 이 함수에는 다음 서명이 있어야 합니다.

const myCallback = (params: OIDCCallbackParams): Promise<OIDCResponse> => { }

OIDCCallbackParams 매개변수에는 함수 내에서 액세스할 수 있는 다음 속성이 포함되어 있습니다.

속성
timeoutContext
30 초 후에 인증 워크플로를 중단하는 AbortSignal
version
현재 OIDC API 버전
idpInfo
서버에서 반환된 ID 제공자 정보
username
연결 문자열에 포함된 사용자 이름(있는 경우)
refreshToken
발급자에게 새 액세스 토큰을 요청하는 새로 고침 토큰(있는 경우)

콜백 함수는 OIDCResponse 객체를 반환해야 합니다. 이 객체에는 다음과 같은 속성이 포함되어 있습니다.

속성
accessToken
인증에 사용할 액세스 토큰입니다.
expiresInSeconds
선택 사항. 액세스 토큰이 만료될 때까지의 시간(초)입니다.
refreshToken
선택 사항. 발급자에게 새 액세스 토큰을 요청하기 위한 새로 고침 토큰입니다.

다음 예제에서는 로컬 파일 시스템의 access-token.dat 파일에서 OIDC 액세스 토큰을 검색하는 콜백 함수를 보여줍니다.

const fs = require("node:fs");
const myCallback = (params: OIDCCallbackParams): Promise<OIDCResponse> => {
const token = fs.readFileSync("access-token.dat", "utf8");
return {
accessToken: token,
expiresInSeconds: 300,
refreshToken: token
};
}

콜백 함수를 정의한 후 이를 authMechanismProperties 매개변수의 일부로 MongoClient 생성자에 전달합니다. Node.js 드라이버는 다음 인증 패턴을 지원합니다.

  • 기계 인증: 사람의 상호 작용이 필요하지 않은 웹 서비스 및 기타 애플리케이션에서 사용됩니다. 이 구문의 예를 보려면 Machine Callback 탭을 선택합니다.

  • 인간 인증: 데이터베이스 도구, 명령줄 유틸리티 및 인간의 직접적인 상호 작용과 관련된 기타 애플리케이션에서 사용됩니다. 이 구문의 예를 보려면 Human Callback 탭을 선택합니다.

머신 인증의 경우 다음 예시와 같이 콜백 함수를 authMechanismProperties.OIDC_CALLBACK 속성에 할당합니다.

const { MongoClient } = require("mongodb");
const uri = "mongodb+srv://<host>:<port>/?authMechanism=MONGODB-OIDC";
const client = new MongoClient(uri, {
authMechanismProperties: {
OIDC_CALLBACK: myCallback
}
});

인간 인증의 경우 다음 예시와 같이 콜백 함수를 authMechanismProperties.OIDC_HUMAN_CALLBACK 속성에 할당합니다.

const { MongoClient } = require("mongodb");
const uri = "mongodb+srv://<host>:<port>/?authMechanism=MONGODB-OIDC";
const client = new MongoClient(uri, {
authMechanismProperties: {
OIDC_HUMAN_CALLBACK: myCallback
}
});

이 가이드에서 설명하는 메서드 및 유형에 대해 자세히 알아보려면 다음 API 문서를 참조하세요.

돌아가기

인증 메커니즘.