文档菜单
文档首页
/
语言
/
PHP
/
PHP库手册
/
安全性

身份验证机制

在本页面上

  • 概述
  • SCRAM-SHA-256
  • SCRAM-SHA-1
  • MONGODB-X509
  • MONGODB-AWS
  • MongoDB.Client凭据
  • 环境变量
  • AssumeRoleWithWebIdentity请求
  • ECS元数据
  • EC2实例元数据
  • 其他信息
  • API文档

概述

本指南描述了您可以在PHP库中使用以进行用户身份验证的机制。

重要

百分比编码

您必须百分比编码在将用户名和密码包含在MongoDB URI中之前，请对它们进行百分比编码。rawurlencode()方法可以将这些值根据RFC 3986中指定的URI语法进行编码。在将用户名或密码作为参数传递给MongoDB\Client构造函数的选项数组参数时，不要对它们进行百分比编码。

了解更多信息，请参阅以下资源

  • RFC 3986

  • rawurlencode在PHP手册中

SCRAM-SHA-256

SCRAM-SHA-256，由RFC 7677定义，是MongoDB Server v4.0或更高版本部署上的默认认证机制。

要使用此机制进行认证，请设置以下连接选项

  • username：用于认证的用户名。在将其包含在连接URI中之前，请对此值进行百分号编码。

  • password：用于认证的密码。在将其包含在连接URI中之前，请对此值进行百分号编码。

  • authSource：要认证的MongoDB数据库。默认情况下，MongoDB PHP库会在连接URI中包含数据库时对其认证。如果不包含，则对admin数据库进行认证。

  • authMechanism：设置为'SCRAM-SHA-256'。连接到MongoDB Server v4.0时，设置authMechanism是可选的。

您可以通过两种方式设置这些选项：通过将选项数组传递给MongoDB\Client构造函数或通过连接URI中的参数。

$uriOptions = [
    'username' => '<username>',
    'password' => '<password>',
    'authSource' => '<authentication database>',
    'authMechanism' => 'SCRAM-SHA-256',
];
$client = new MongoDB\Client(
    'mongodb://<hostname>:<port>',
    $uriOptions,
);
$uri = 'mongodb://<username>:<password>@<hostname>:<port>/?authSource=admin&authMechanism=SCRAM-SHA-256';
$client = new MongoDB\Client($uri);

SCRAM-SHA-1

SCRAM-SHA-1，如RFC 5802定义，是MongoDB Server v3.6版本部署上的默认身份验证机制。

注意

MongoDB PHP库v1.20停止支持MongoDB Server v3.6。当使用库的v1.20+版本时，所有支持的服务器版本默认使用SCRAM-SHA-256身份验证机制。

要使用此机制进行身份验证，请使用与SCRAM-SHA-256相同的语法，但将authMechanism选项的值更改为'SCRAM-SHA-1'。

MONGODB-X509

如果您启用TLS，MongoDB PHP库可以在TLS握手过程中向MongoDB提供X.509客户端证书以证明其身份。MONGODB-X509身份验证机制使用此证书来验证客户端。

要使用此机制进行认证，请设置以下连接选项

  • tls：设置为true。

  • tlsCertificateKeyFile：包含您的客户端证书和私钥的.pem文件的文件路径。

  • authMechanism：设置为'MONGODB-X509'。

您可以通过两种方式设置这些选项：通过将选项数组传递给MongoDB\Client构造函数或通过连接URI中的参数。

$uriOptions = [
    'tls' => true,
    'tlsCertificateKeyFile' => '<file path>',
    'authMechanism' => 'MONGODB-X509',
];
$client = new MongoDB\Client(
    'mongodb://<hostname>:<port>',
    $uriOptions,
);
$uri = 'mongodb://<hostname>:<port>/?tls=true&tlsCertificateKeyFile=<file path>&authMechanism=MONGODB-X509';
$client = new MongoDB\Client($uri);

MONGODB-AWS

重要

MONGODB-AWS身份验证机制需要MongoDB Server v4.4或更高版本。

mongodb-aws认证机制使用AWS IAM（亚马逊云服务身份和访问管理）或AWS Lambda凭据来验证您的应用程序。要使用此方法进行验证，您必须将'MONGODB-AWS'指定为authMechanism连接选项的值。

注意

MongoDB PHP库使用libmongoc对MONGODB-AWS认证机制的实现。有关使用libmongoc的此认证机制的更多信息，请参阅C驱动程序文档中的通过AWS IAM进行认证。

当您使用MONGODB-AWS机制时，驱动程序将按照以下顺序尝试从以下来源检索AWS凭据

  1. 传递给MongoDB\Client的选项，可以是连接URI的一部分或选项参数

  2. 环境变量

  3. AWS EKS AssumeRoleWithWebIdentity请求

  4. ECS容器元数据

  5. EC2实例元数据

以下部分描述了如何从这些来源检索凭据，并使用它们来验证您的PHP应用程序。

MongoDB.Client凭据

首先，驱动程序会检查您是否已将AWS凭据传递给MongoDB\Client构造函数，无论是作为连接URI的一部分还是作为$uriOptions数组参数的一部分。要将凭据传递给MongoDB\Client，设置以下连接选项

  • username：用于验证的AWS IAM访问密钥ID。在将其包含在连接URI中之前，对此值进行百分编码。

  • password：AWS IAM秘密访问密钥。在将其包含在连接URI中之前，对此值进行百分编码。

  • authMechanism：设置为'MONGODB-AWS'。

您可以通过两种方式设置这些选项：通过将选项数组传递给MongoDB\Client构造函数或通过连接URI中的参数。

$uriOptions = [
    'username' => '<AWS IAM access key ID>',
    'password' => '<AWS IAM secret access key>',
    'authMechanism' => 'MONGODB-AWS',
];
$client = new MongoDB\Client(
    'mongodb://<hostname>:<port>',
    $uriOptions,
);
$uri = 'mongodb://<AWS IAM access key ID>:<AWS IAM secret access key>@<hostname>:<port>/?authMechanism=MONGODB-AWS';
$client = new MongoDB\Client($uri);

环境变量

如果您在构建 MongoDB.Client 对象时没有提供用户名和密码，驱动程序将尝试从以下环境变量中检索 AWS 凭据

  • AWS_ACCESS_KEY_ID

  • AWS_SECRET_ACCESS_KEY

  • AWS_SESSION_TOKEN

要使用这些环境变量来验证您的应用程序，首先将它们设置为用于验证的 AWS IAM 值。您可以在您的 shell 中运行 export 命令或将变量添加到 .env 文件中，如下面的代码示例所示

export AWS_ACCESS_KEY_ID=<AWS IAM access key ID>
export AWS_SECRET_ACCESS_KEY=<AWS IAM secret access key>
export AWS_SESSION_TOKEN=<AWS session token>
AWS_ACCESS_KEY_ID=<AWS IAM access key ID>
AWS_SECRET_ACCESS_KEY=<AWS IAM secret access key>
AWS_SESSION_TOKEN=<AWS session token>

重要

不要对这些环境变量的值进行百分号编码。

设置这些环境变量后，将 authMechanism 连接选项设置为 'MONGODB-AWS'。

示例

以下示例设置了 authMechanism 连接选项。您可以通过两种方式设置此选项：通过将选项数组传递给 MongoDB.Client 构造函数或在您的连接 URI 中设置参数。

$client = new MongoDB\Client(
    'mongodb://<hostname>:<port>',
    ['authMechanism' => 'MONGODB-AWS']
);
$uri = 'mongodb://<hostname>:<port>/?authMechanism=MONGODB-AWS';
$client = new MongoDB\Client($uri);

提示

AWS Lambda

AWS Lambda 运行时可以在初始化过程中自动设置这些环境变量。有关在 AWS Lambda 环境中使用环境变量的更多信息，请参阅 AWS 文档中的 使用 Lambda 环境变量。

AssumeRoleWithWebIdentity 请求

如果您的应用程序从 OpenID Connect (OIDC) 身份提供商对您的 EKS 集群进行用户认证，则驱动程序可以发出一个 AssumeRoleWithWebIdentity 请求，以交换 OIDC 令牌以获取应用程序的临时 AWS 凭据。

为了使用由 AssumeRoleWithWebIdentity 请求返回的临时 AWS IAM 凭据进行认证，请确保您的环境中存在 AWS 配置文件并且配置正确。有关如何创建和配置 AWS 配置文件的更多信息，请参阅 AWS 文档中的 配置。

在配置好您的环境以进行 AssumeRoleWithWebIdentity 请求后，将 authMechanism 连接选项设置为 'MONGODB-AWS'。要查看设置 authMechanism 选项的示例，请参阅本页上的 authMechanism 示例。

提示

有关使用 AssumeRoleWithWebIdentity 请求对应用程序进行身份验证的更多信息，请参阅以下 AWS 文档

ECS 元数据

如果您的应用程序运行在 Elastic Container Service (ECS) 容器中，驱动程序可以自动从 ECS 端点检索临时 AWS 凭据。要这样做，请在一个名为 AWS_CONTAINER_CREDENTIALS_RELATIVE_URI 的环境变量中指定 ECS 端点的 URI。您可以通过运行 export 壳命令或将它添加到您的 .env 文件中来设置此变量，如下面的示例所示

export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=<URI of the ECS endpoint>
AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=<URI of the ECS endpoint>

设置环境变量后，将 authMechanism 连接选项设置为 'MONGODB-AWS'。要查看设置 authMechanism 选项的示例，请参阅本页上的 authMechanism 示例。

EC2 实例元数据

驱动程序可以自动从 Amazon Elastic Cloud Compute (EC2) 实例检索临时 AWS 凭据。要在 EC2 实例内部使用临时凭据，将 authMechanism 连接选项设置为 'MONGODB-AWS'。要查看设置 authMechanism 选项的示例，请参阅本页上的 authMechanism 示例。

注意

如果未设置环境变量部分中描述的环境变量，MongoDB PHP 库将从 EC2 实例中检索凭据。

更多信息

要了解更多关于在 MongoDB PHP 库中创建 MongoDB\Client 对象的信息，请参阅创建 MongoDB 客户端指南。

API 文档

要了解更多关于 MongoDB\Client 类的信息，请参阅库 API 文档中的 MongoDB\Client。

要查看可以传递给 MongoDB\Client 的完整 URI 选项列表，请参阅扩展 API 文档中的 MongoDB\Driver\Manager::__construct() Parameters。

返回

安全性

下一页

加密