本页翻译不是最新的。点击此处可查看最新英文版本。

matlab.net.http.Credentials 类

R2024b

命名空间: matlab.net.http
超类: handle

用于对 HTTP 请求进行身份验证的凭据

全页展开

描述

Credentials 类指定用于发送请求消息的身份验证凭据。在 HTTPOptions 对象中指定 Credentials 对象。

RequestMessage.send 方法使用凭据响应来自服务器或代理的身份验证质询。身份验证质询位于 AuthenticateField 标头字段中，它指定一个或多个身份验证方案供服务器或代理接受以满足请求。

具体行为取决于身份验证方案。通常，MATLAB® 会在 Credentials 对象向量中搜索应用于请求 URI 并且支持指定的身份验证方案的对象。MATLAB 然后在 AuthorizationField 标头中重新发送具有正确凭据的原始请求。如果有多个适用的凭据，MATLAB 将使用最具体的 Credentials 对象，以支持最强的身份验证方法。如果存在重复的 Credentials 对象，MATLAB 将使用第一个。

要查看 MATLAB 自动实现的身份验证方案，请参阅 AuthenticationScheme。如果服务器需要其他方案，或者您没有为所需的方案提供凭据，身份验证响应消息将返回 StatusCode 401 或 407。在此情况下，您必须自行实现适当的响应。

对于不需要 Username 和 Password 属性的方案，例如 Windows® 上的 NTLM，您可以使用默认的 Credentials 对象。默认的 Credentials 对象具有默认或空属性，并适用于所有受支持的方案和 URI。您的授权凭据来自登录时存储在系统中的信息，如 Kerberos 票证。要限制使用特定方案的条件，您可以指定其他属性，例如 Scope 和 Realm。例如，将这些值设置为对某些 URL 使用 NTLM，对其他 URL 使用 Kerberos，并拒绝那些从不匹配这些 URL 和方案的服务器发出的身份验证请求。

对于需要 Username 和 Password 属性的方案，如果 MATLAB 使用 Credentials 对象进行身份验证，则 MATLAB 会将结果保存在此对象中。MATLAB 可以在后续请求中应用这些凭据，而无需等待来自服务器的身份验证质询。要利用此捷径，请对同一或其他 HTTPOptions 对象中的后续请求提供相同的 Credentials 对象。

Credentials 对象是句柄对象，会在内部收集以前成功完成身份验证的信息。因此，您可以在后续消息中重用这些信息。如果您将此对象插入到多个 HTTPOptions 对象中，则每次使用时都可能会更新 Credentials 对象。如果您使用 copy 方法复制 Credentials，则 MATLAB 只复制您设置的可见属性，而不复制内部状态。

matlab.net.http.Credentials 类是一个 handle 类。

类属性

Sealed
true

有关类属性的信息，请参阅类属性。

创建对象

描述

obj = matlab.net.http.Credentials(Name,Value) 创建 HTTP 凭据并由一个或多个名称-值对组参量指定其他属性。Name 是属性名称，Value 是对应的值。您可采用任意顺序指定多个名称-值对组参量，例如 Name1,Value1,...,NameN,ValueN。未指定的属性设置为默认值。

如果不带参量地调用此构造函数，则 Credentials 对象适用于所有 URI 和所有身份验证方案，因此允许相应的身份验证。但是，该对象仅适用于不需要用户名或密码的方案。例如，在 Windows 上，该对象支持使用登录用户凭据的 NTLM 和 Kerberos 身份验证。

示例

属性

全部展开

凭据的身份验证方案，指定为 matlab.net.http.AuthenticationScheme 对象的向量。有关各个平台所支持方案的完整列表，请参阅 AuthenticationScheme。

如果 Scheme 为空（默认值），则凭据适用于所有已定义的身份验证方案。

有关身份验证的详细信息，请参阅Server Authentication和代理服务器身份验证。

如果 Scheme 设置为仅进行 Basic 身份验证，则这些凭据可能会应用于请求，而不管服务器是否要求进行身份验证。设置为仅进行 Basic 身份验证这种方案可避免对身份验证质询进行一轮额外的响应。但是，如果服务器没有要求进行 Basic 身份验证，则这种方案不必要地向服务器暴露了 Username 和 Password 属性。

如果此属性包含任何 Basic 以外的方案，或如果 Scheme 为空（表示允许所有方案），则 MATLAB 不会在应用这些凭据的第一条消息中发送任何授权信息。MATLAB 等待服务器以质询（如 WWW-Authenticate 字段）作出响应。该响应告诉 MATLAB 服务器接受什么身份验证方案。然后，MATLAB 选择 Credentials 中列出的最强方案，该方案也匹配您指定的 Scope 和 Realm 属性（如果有）。随后发送到同一服务器的具有相同 Scope 的消息也会包含适当的授权信息，而无需事先要求质询。

属性：

GetAccess
public
SetAccess
public

应用凭据的 URI，指定为 matlab.net.URI 对象的向量或者字符串或字符向量。字符串必须能够被 URI 构造函数所接受，或者采用 host/path/... 的形式。

空 Scope 值或者此向量中的空 Host 或 Path 与所有 Host 或 Path 属性匹配。如果 Scheme 设置为仅进行 Basic 身份验证，请勿将 Scope 保留为空，除非您只访问可靠的服务器。这种设置组合可将 Username 和 Password 发送给您使用包含这些 Credentials 的 HTTPOptions 访问的任何服务器。

MATLAB 将 Scope 中的值与请求消息 URI 进行比较，以确定是否应用这些凭据。如果请求 URI 指向的主机所在的路径与此 Scope 中的某个 URI 所在的路径相同或比其更深，则应用这些凭据。如果 Scope 包含的 URI 只指定了主机，而没有包含路径，则会将凭据应用于该主机上的所有路径。

例如，Scope 中的主机名称 mathworks.com 匹配的是对 www.mathworks.com 和 anything.mathworks.com 的请求。URI mathworks.com/products/stateflow 匹配的是对 www.mathworks.com/products/stateflow/features 的请求，而不是对 www.mathworks.com/products 的请求。/products 路径与 /products/stateflow 既不在同一级别，也不在比它更深的级别。

仅使用了 Scope URI 的 Host、Port 和 Path 属性。通常您只指定 Host 名称，例如 www.mathworks.com。如果您知道一台主机上只有某些路径需要凭据，则可以添加一个 Path 或路径的一部分。

属性：

GetAccess
public
SetAccess
public

凭据的身份验证范围，指定为字符串数组、字符向量或字符向量元胞数组，其中包含说明凭据范围的正则表达式。默认值为空，即匹配所有范围。如果此向量中的任一值为空字符串，则只匹配空或未指定的 Realm。要将正则表达式定位到身份验证 Realm 字符串的开头或末尾，请根据需要包括 ^ 或 $ 字符。

Realm 包含要显示的文本，以告知用户要输入的用户名和密码。服务器在 ResponseMessage 的 AuthenticateField 中指定 Realm。通常，将此属性留空。如果一台服务器要求为不同的 URI 使用不同的登录值，并且您希望以编程方式为同一台服务器上的不同范围指定不同的凭据，则可以使用 Realm。如果您要提示用户输入用户名和密码，则无需设置此属性。而可以在您的提示中显示 AuthenticateField 中的 Realm 属性，从而告诉用户应输入哪些凭据。

MATLAB 将 Realm 中的表达式与 AuthenticateField 中的身份验证 Realm 进行比较，以确定这些凭据是否适用。一旦 MATLAB 使用其中一个范围成功完成身份验证，MATLAB 就会将有关身份验证的信息缓存在 Credentials 中。应用这些 Credentials 对主机和路径进行的后续请求将使用这些缓存的信息进行身份验证。这样可以避免身份验证质询或调用 GetCredentialsFcn 函数的开销。

属性：

GetAccess
public
SetAccess
public

身份验证方案的用户名，指定为字符串或字符向量。此属性仅适用于需要显式 Username 和 Password 的方案，不适用于从系统获取凭据的方案。

如果您将 Username 和 Password 属性设置为任意字符串（包括空字符串），将使用 Username 对这些凭据所应用的任何请求进行身份验证，除非指定了 GetCredentialsFcn。如果您将此属性设置为 []，则您必须指定 GetCredentialsFcn，否则不会尝试进行身份验证。

如果不想在代码中嵌入用户名，请将此属性留空，并指定 GetCredentialsFcn，它提示用户输入用户名，或从其他来源获取用户名。

属性：

GetAccess
public
SetAccess
public

身份验证方案的密码，指定为字符串或字符向量。此属性仅适用于需要显式 Username 和 Password 的方案，不适用于从系统获取凭据的方案。

如果您将 Username 和 Password 属性设置为任意字符串（包括空字符串），将使用 Password 对这些凭据所应用的任何请求进行身份验证，除非指定了 GetCredentialsFcn。如果您将此属性设置为 [] 且没有 GetCredentialsFcn 属性，则不提供密码。

如果不想在代码中嵌入密码，请将此属性留空，并指定 GetCredentialsFcn，它提示用户输入密码，或从其他来源获取密码。

属性：

GetAccess
public
SetAccess
public

返回用来进行身份验证的 Username 和 Password 的函数，指定为函数句柄。此属性仅适用于要求您指定用户名和密码的方案。

MATLAB 调用 GetCredentialsFcn 函数来获取用于身份验证响应的用户名和密码。这种情况下 MATLAB 会忽略 Credentials 中的 Username 或 Password 属性。

GetCredentialsFcn 的函数签名为：

[username,password] = GetCredentialsFcn(cred,req,resp,authInfo,prevUsername,prevPasswd)

其中的参量按如下方式进行指定：

  • cred - 此 Credentials 对象的句柄

  • req - 上次发送的、引发此身份验证质询的请求消息。

  • resp - 来自服务器的、包含 AuthenticateField 的响应消息。如果 cred.Scheme 属性设置为 Basic 作为唯一选项，则 resp 参量可能为空。

  • authInfo（可选）- AuthenticateField.convert 方法返回的 AuthInfo 对象向量中的一个元素，由 MATLAB 选择用来与这些凭据进行匹配。此数组中的每个对象都有 Scheme 和至少一个 Realm 参数。

  • prevUsername、prevPasswd（可选）- 最初为空参量。如果非空，则这些参量是在上一次调用中返回的 GetCredentialsFcn 函数的值，但服务器拒绝了这些值。如果您不打算提示用户输入凭据，请将这些值与您计划返回的值进行比较。如果它们相同，则身份验证很可能再次失败。将 username 设置为 [] 以便 MATLAB 返回身份验证失败。如果您打算提示用户输入凭据，则不需要指定这些参量。用户可以选择重新输入相同或不同凭据。

  • username - 要使用的用户名。如果服务器只要求输入密码，不要求输入用户名，请将 username 设置为空字符串 ('')。如果 username 的值为 []，则表示身份验证失败。

  • password - 要使用的密码。

通过实现 GetCredentialsFcn 函数，并将 Credentials 中的 Username 和/或 Password 属性保留为空，您可以实现一条提示，以便从用户那里获取这些值，而不用将它们嵌入到您的程序中。在您的提示中，显示请求 URI 或 authInfo.Realm 参数。另一种便捷的方式是设置好 Username 属性，只提示用户输入密码。您的提示可以显示现有 Username 或 prevUsername（如果已设置），并为用户提供更改选项。

GetCredentialsFcn 函数可以检查 cred 参量以及请求和响应消息的标头字段中的凭据，以确定要访问哪些资源。因此，该函数可以提示用户输入正确的凭据。一般情况下，提示应显示 authInfo.Realm，以便告诉用户身份验证的范围。

由于 Credentials 是句柄类，GetCredentialsFcn 函数将用户名和密码存储在 cred 参量中。您可以在将来的请求中使用该对象，而不用再次调用该函数。MATLAB 会在内部保存成功的用户名和密码，以用于将来的请求。但是，MATLAB 可能并不总是能够确定是否将同样的用户名和密码应用于使用这些凭据的不同请求。

如果 GetCredentialsFcn 为用户名返回空数组 []（而不是空字符串 ''），则身份验证被拒绝，MATLAB 将在给 RequestMessage.send 的调用方的响应消息中返回服务器身份验证失败。如果您实现一个用户提示，而用户点击了提示中的取消，则会出现这种行为。如果 prevUsername 和 prevPasswd 与您要返回的用户名和密码完全相同，则当您以编程方式提供该用户名和密码时，您必须返回 []。此值表示未接受您的凭据，而您也没有其他选择。否则，可能会发生反复调用 GetCredentaislFcn 函数的无限循环。

属性：

GetAccess
public
SetAccess
public

数据类型: function_handle

示例

全部折叠

创建只发送给正确服务器的凭据。

在您的 MATLAB 保管库中创建一个包含您的密码的机密。有关详细信息，请参阅 Keep Sensitive Information Out of Code。

setSecret("JohnPassword")

创建凭据，从您的保管库中获取密码。

import matlab.net.http.Credentials
scope = URI('http://my.server.com');
creds = Credentials('Username','John','Password',getSecret("JohnPassword"),'Scope',scope);
options = HTTPOptions('Credentials',creds);

发送消息。如果服务器要求进行身份验证，则该事务处理涉及到多个消息的交换。

resp = RequestMessage().send(scope,options);
...

然后，再次使用包含相同凭据的选项。由于该凭据已成功使用过，所以此事务处理只需要一条消息。

resp = RequestMessage().send(scope,options)

创建一个提示输入凭据的函数，使用 Credentials 对象的 Username 属性作为默认值。MATLAB 将调用此函数，以获取用于身份验证响应的用户名和密码。

创建 getMyCredentials 函数。

function [u,p] = getMyCredentials(cred,req,resp,authInfo)
prompt = ["Username:" "PasswordKey:"];
username = cred.Username;
if(isempty(username))
    username = "";
end
defAns = [username ""];
title = "Credentials needed for " + getParameter(authInfo,'realm');
answer = inputdlg(prompt, title, [1, 60], defAns, 'on');
if isempty(answer)
    u = [];
    p = [];
else
    u = answer{1};
    p = getSecret(answer{2});
end
end

创建请求消息。

cred = matlab.net.http.Credentials('GetCredentialsFcn',@getMyCredentials);
options = matlab.net.http.HTTPOptions('Credentials',cred);
req = matlab.net.http.RequestMessage;

将该消息发送给 httpbin.org。

uri = 'httpbin.org/basic-auth/user/passwd';
resp = req.send(uri,options)

输入任意文本。要退出，请选择取消。

版本历史记录

在 R2016b 中推出

另请参阅

| | |

主题