Main Content

matlab.net.http.Credentials 클래스

네임스페이스: matlab.net.http
슈퍼클래스: handle

HTTP 요청 인증에 사용할 자격 증명

설명

Credentials 클래스는 요청 메시지를 보내는 데 사용할 인증 자격 증명을 지정합니다. HTTPOptions 객체에 Credentials 객체를 지정합니다.

RequestMessage.send 메서드는 자격 증명을 사용하여 서버나 프록시의 인증 질문에 응답합니다. 인증 질문은 AuthenticateField 헤더 필드에 있으며 서버나 프록시가 요청을 충족하기 위해 허용하는 하나 이상의 인증 체계를 지정합니다.

동작은 인증 체계에 따라 달라집니다. 일반적으로, MATLAB®은 요청 URI에 적용되고 지정된 인증 체계를 지원하는 Credentials 객체의 벡터를 검색합니다. 그런 다음 MATLAB은 AuthorizationField 헤더에 적절한 자격 증명을 포함시켜 원래 요청을 다시 보냅니다. 여러 자격 증명이 적용되는 경우 MATLAB은 가장 강력한 체계에 가장 적합한 Credentials 객체를 사용합니다. 중복된 Credentials 객체가 존재할 경우 MATLAB은 첫 번째 객체를 사용합니다.

MATLAB에서 자동으로 구현하는 인증 체계를 확인하려면 AuthenticationScheme을 참조하십시오. 서버가 다른 체계를 요청하거나 사용자가 요청된 체계에 맞는 자격 증명을 제공하지 않는 경우 인증 응답 메시지는 StatusCode 401 또는 407을 반환합니다. 이 경우, 적합한 응답을 직접 구현해야 합니다.

Windows®상의 NTLM 같이 Username 속성과 Password 속성이 필요하지 않은 체계의 경우 디폴트 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와 모든 인증 체계에 적용되기 때문에 모든 URI와 모든 인증 체계에 대한 인증을 허용합니다. 그러나 이 객체는 사용자 이름 또는 비밀번호가 필요하지 않은 체계에서만 사용 가능합니다. 예를 들어 Windows에서 이 객체를 사용할 경우, 로그인한 사용자의 자격 증명을 이용한 NTLM 및 Kerberos 인증이 가능합니다.

속성

모두 확장

자격 증명에 대한 인증 체계로, matlab.net.http.AuthenticationScheme 객체의 벡터로 지정됩니다. 플랫폼별로 지원되는 체계에 대한 전체 목록을 보려면 AuthenticationScheme 항목을 참조하십시오.

Scheme이 비어 있는 경우(디폴트 값) 자격 증명이 정의된 모든 인증 체계에 적용됩니다.

인증에 대한 더 자세한 내용은 서버 인증프록시 서버 인증 항목을 참조하십시오.

SchemeBasic 전용으로 설정된 경우 이 자격 증명은 서버가 인증을 요청하는지 여부에 상관없이 요청에 적용될 수 있습니다. Basic 전용 체계는 인증 질문에 대한 추가적인 왕복 응답을 방지합니다. 그러나, 서버에 Basic 인증이 필요 없는 경우 이 체계는 불필요하게 Username 속성과 Password 속성을 서버에 노출시킵니다.

이 속성에 Basic 외에 다른 체계가 포함되어 있거나 Scheme이 비어 있는 경우(즉, 모든 체계를 허용하는 경우) MATLAB은 첫 번째 메시지에 자격 증명이 적용되는 어떠한 승인 정보도 전송하지 않습니다. MATLAB은 서버가 WWW-Authenticate 필드 같은 질문에 응답할 때까지 기다립니다. 그 응답을 통해 MATLAB은 서버에서 허용하는 인증 체계를 알 수 있습니다. 그러면 MATLAB은 지정한 Scope 속성과 Realm 속성(있는 경우)과도 일치하는 Credentials 중에서 가장 강력한 체계를 선택합니다. 이후 동일한 Scope를 사용하여 동일한 서버에 보내는 메시지에는 인증 질문을 먼저 요구하지 않아도 올바른 승인 정보가 포함됩니다.

특성:

GetAccess
public
SetAccess
public

자격 증명이 적용되는 URI로, matlab.net.URI 객체의 벡터, string형 또는 문자형 벡터로 지정됩니다. 문자열은 URI 생성자로 허용 가능하거나 host/path/... 형식이어야 합니다.

Scope 값이나 이 벡터의 빈 Host 또는 Path는 모든 Host 속성 또는 Path 속성과 일치합니다. SchemeBasic 전용으로 설정된 경우, 사용자가 신뢰할 수 있는 서버에만 액세스하는 것이 아니라면 Scope을 빈 상태로 두지 마십시오. 이러한 설정 조합은 이들 Credentials를 포함하는 HTTPOptions를 사용하여 액세스하는 모든 서버에 UsernamePassword를 전송합니다.

MATLAB은 Scope의 값을 요청 메시지 URI와 비교하여 이러한 자격 증명이 적용되는지 여부를 확인합니다. 요청 URI가 이 Scope에 포함된 URI 중 하나와 같은 수준이거나 그보다 깊은 수준의 경로에 있는 동일한 호스트를 참조하는 경우 자격 증명이 적용됩니다. 경로 없이 호스트를 명명하는 URI를 포함하는 Scope은 해당 호스트의 모든 경로에 적용됩니다.

예를 들어, Scopemathworks.com 호스트 이름은 www.mathworks.comanything.mathworks.com에 대한 요청과 일치합니다. mathworks.com/products/stateflow URI는 www.mathworks.com/products/stateflow/features에 대한 요청과 일치하지만, www.mathworks.com/products에 대한 요청과는 일치하지 않습니다. /products 경로는 /products/stateflow와 같은 수준이거나 그보다 깊은 수준이 아닙니다.

Scope URI의 Host, Port, Path 속성만 사용됩니다. 일반적으로 www.mathworks.com과 같은 Host 이름만 지정합니다. 자격 증명이 호스트 내의 일부 경로에 대해서만 필요한 경우 Path나 경로의 일부를 추가하십시오.

특성:

GetAccess
public
SetAccess
public

자격 증명에 대한 인증 영역으로, 자격 증명에 대한 영역을 규정하는 정규 표현식을 포함하는 string형 배열, 문자형 벡터 또는 문자형 벡터로 구성된 셀형 배열로 지정됩니다. 디폴트 값은 모든 영역과 일치하는 빈 값입니다. 이 벡터의 값이 빈 문자열이면 빈 값 또는 지정되지 않은 Realm과만 일치합니다. 정규 표현식을 인증 Realm 문자열의 시작이나 끝에 고정하려면 ^ 문자나 $ 문자를 적절하게 포함시키십시오.

Realm에는 사용자가 어떤 이름과 비밀번호를 입력해야 하는지 알 수 있도록 표시되는 텍스트가 포함되어 있습니다. 서버는 ResponseMessageAuthenticateFieldRealm을 지정합니다. 일반적으로는 이 속성을 빈 값으로 두십시오. 서버가 URI마다 다른 로그인 값을 필요로 하고, 동일한 서버에서 영역마다 다른 자격 증명을 프로그래밍 방식으로 지정하려면 Realm을 사용하십시오. 이름과 비밀번호를 요청하는 경우 이 속성을 설정하지 마십시오. 대신, 사용자가 어떤 자격 증명을 입력해야 하는지 알 수 있도록 프롬프트에 AuthenticateFieldRealm 속성을 표시하십시오.

MATLAB은 Realm의 표현식을 AuthenticateField의 인증 Realm과 비교하여 이러한 자격 증명이 적용되는지 여부를 확인합니다. 이러한 realm 중 하나를 사용하여 MATLAB에서 성공적인 인증이 수행되고 나면 MATLAB은 Credentials에서 인증에 대한 정보를 캐시합니다. 이러한 Credentials에 적용되는 호스트 및 경로에 대한 후속 요청은 인증을 위해 이 캐시된 정보를 사용합니다. 따라서 인증 질문이나 GetCredentialsFcn 함수 호출에 대한 오버헤드가 방지됩니다.

특성:

GetAccess
public
SetAccess
public

인증 체계에 대한 사용자 이름으로, string형이나 문자형 벡터로 지정됩니다. 이 속성은 명시적 UsernamePassword가 필요한 체계에만 적용되고, 시스템에서 자격 증명을 가져오는 체계에는 적용되지 않습니다.

Username 속성과 Password 속성을 문자열(빈 문자열 포함)로 설정한 경우 GetCredentialsFcn이 지정되지 않았으면 이러한 자격 증명이 적용되는 요청에 대한 인증에 Username이 사용됩니다. 이 속성을 []로 설정한 경우 GetCredentialsFcn도 지정해야 하며, 그러지 않으면 인증이 시도되지 않습니다.

코드에 사용자 이름을 넣지 않고자 하는 경우, 이 속성을 빈 값으로 두고 GetCredentialsFcn을 지정하십시오. 그러면 사용자에게 이름을 묻는 메시지가 표시되거나 다른 소스에서 사용자 이름을 가져옵니다.

특성:

GetAccess
public
SetAccess
public

인증 체계에 대한 비밀번호로, string형이나 문자형 벡터로 지정됩니다. 이 속성은 명시적 UsernamePassword가 필요한 체계에만 적용되고, 시스템에서 자격 증명을 가져오는 체계에는 적용되지 않습니다.

Username 속성과 Password 속성을 문자열(빈 문자열 포함)로 설정한 경우 GetCredentialsFcn이 지정되지 않았으면 이러한 자격 증명이 적용되는 요청에 대한 인증에 Password가 사용됩니다. 이 속성이 []로 설정되고 GetCredentialsFcn 속성이 없는 경우 비밀번호가 제공되지 않습니다.

코드에 비밀번호를 넣지 않고자 하는 경우, 이 속성을 빈 값으로 두고 GetCredentialsFcn을 지정하십시오. 그러면 사용자에게 비밀번호를 묻는 메시지가 표시되거나 다른 소스에서 비밀번호를 가져옵니다.

특성:

GetAccess
public
SetAccess
public

인증에 사용할 UsernamePassword를 반환하는 함수로, 함수 핸들로 지정됩니다. 이 속성은 사용자 이름과 비밀번호를 지정하도록 요구하는 체계에만 적용됩니다.

MATLAB은 GetCredentialsFcn 함수를 호출하여 인증 응답에 사용할 이름과 비밀번호를 가져옵니다. MATLAB은 CredentialsUsername 속성이나 Password 속성을 무시합니다.

GetCredentialsFcn의 함수 시그니처는 다음과 같습니다.

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

여기서 인수는 다음 중 하나로 지정됩니다.

  • cred — 이 Credentials 객체에 대한 핸들

  • req — 이 인증 질문을 유발한 마지막으로 전송된 요청 메시지.

  • respAuthenticateField를 포함하여, 서버에서 반환하는 응답 메시지. cred.Scheme 속성이 Basic으로만 설정된 경우 resp 인수가 비어 있을 수 있습니다.

  • authInfo(선택 사항) — MATLAB이 이러한 자격 증명을 일치시키기 위해 선택하는 AuthenticateField.convert 메서드에서 반환되는 AuthInfo 객체의 벡터에 포함된 하나의 요소. 이 배열의 각 객체에는 Scheme 파라미터와 적어도 하나의 Realm 파라미터가 있습니다.

  • prevUsername, prevPasswd(선택 사항) — 처음에는 빈 인수입니다. 비어 있지 않은 경우, 이러한 인수는 이전 호출에서 GetCredentialsFcn 함수가 반환했으나 서버가 거부한 값입니다. 자격 증명을 요청하지 않는 경우 반환하려는 값과 이러한 값을 비교합니다. 값이 동일하면 인증이 다시 실패할 가능성이 높습니다. MATLAB에서 인증 오류를 반환하도록 username[]로 설정하십시오. 사용자에게 자격 증명을 요청하는 경우 이러한 인수를 지정할 필요가 없습니다. 사용자는 같은 자격 증명 또는 다른 자격 증명을 다시 입력할 수 있습니다.

  • username — 사용할 사용자 이름. 서버가 사용자 이름이 아니라 비밀번호만 필요로 하는 경우, username을 빈 문자열('')로 설정하십시오. username 값이 []이면 인증이 실패한 것입니다.

  • password — 사용할 비밀번호.

GetCredentialsFcn 함수를 구현하고 CredentialsUsername 속성 및/또는 Password 속성을 빈 상태로 두면, 프로그램에 해당 값을 내포하지 않고도 프롬프트를 구현하여 사용자로부터 이 값을 가져올 수 있습니다. 프롬프트에 요청 URI나 authInfo.Realm 파라미터를 표시합니다. 또 다른 간편한 패턴은 Username 속성을 설정하고 비밀번호만 요청하는 것입니다. 프롬프트는 기존 Username이나 prevUsername(설정된 경우)을 표시할 수 있으며, 사용자에게 이를 변경할 수 있는 옵션을 제공할 수 있습니다.

GetCredentialsFcn 함수는 cred 인수와 요청 메시지 및 응답 메시지의 헤더 필드에 포함된 자격 증명을 검토하여 어떤 리소스에 액세스되는지 확인할 수 있습니다. 이런 식으로, 이 함수는 사용자에게 올바른 자격 증명을 요청할 수 있습니다. 일반적으로, 이 프롬프트는 사용자가 인증 컨텍스트를 알 수 있도록 authInfo.Realm을 표시해야 합니다.

Credentials는 핸들 클래스이기 때문에 GetCredentialsFcn 함수는 사용자 이름과 비밀번호를 cred 인수에 저장합니다. 향후 요청 시 함수를 다시 호출하지 않고 해당 객체를 사용할 수 있습니다. MATLAB은 향후 요청에 적용할 수 있도록 사용자 이름과 비밀번호를 내부에 저장합니다. 그러나, MATLAB이 이러한 자격 증명을 사용하는 여러 요청에 동일한 사용자 이름과 비밀번호가 적용되는지 여부를 확인할 수 없는 경우도 있습니다.

GetCredentialsFcn이 사용자 이름에 대해 빈 배열 [](빈 문자열 '' 아님)을 반환하는 경우 인증이 거부되고 MATLAB은 RequestMessage.send의 호출자에게 응답 메시지에 서버 인증 실패를 반환합니다. 이 동작은 사용자 프롬프트가 구현된 후 사용자가 프롬프트에서 취소를 클릭하는 경우에 적합합니다. prevUsernameprevPasswd가 반환하려는 이름 및 비밀번호와 동일하면 이름과 비밀번호를 프로그래밍 방식으로 제공할 때 []을 반환해야 합니다. 이 값은 자격 증명이 수락되지 않았으며 다른 대안이 없음을 나타냅니다. 그렇게 하지 않을 경우 GetCredentaislFcn 함수를 반복적으로 호출하는 무한 루프가 발생할 수 있습니다.

특성:

GetAccess
public
SetAccess
public

데이터형: function_handle

예제

모두 축소

적절한 서버에만 전송되는 자격 증명을 생성합니다.

import matlab.net.http.Credentials
scope = URI('http://my.server.com');
creds = Credentials('Username','John','Password','secret','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:" "Password:"];
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 = 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에 개발됨