ドキュメンテーション

最新のリリースでは、このページがまだ翻訳されていません。 このページの最新版は英語でご覧になれます。

matlab.net.http.Credentials クラス

パッケージ: matlab.net.http
スーパークラス: handle

HTTP 要求を認証するための資格情報

説明

Credentials クラスは、要求メッセージを送信するための認証資格情報を指定します。Credentials オブジェクトを HTTPOptions オブジェクト内で指定します。

RequestMessage.send メソッドは、資格情報を使用してサーバーまたはプロキシからの認証チャレンジに応答します。認証チャレンジは AuthenticateField ヘッダー フィールド内にあり、サーバーまたはプロキシが要求を満たすために受け入れる 1 つ以上の認証スキームを指定します。

動作は認証スキームによって異なります。一般に MATLAB® は、要求 URI に適用される、指定された認証スキームをサポートする資格情報を Credentials オブジェクトのベクトルで検索します。その後 MATLAB は適切な資格情報を AuthorizationField ヘッダーに入れて元の要求を再送信します。適用される資格情報が複数ある場合、MATLAB は最も強力なスキーム用の最も特定的な Credentials オブジェクトを使用します。重複する Credentials オブジェクトが存在する場合、MATLAB は最初のオブジェクトを使用します。

MATLAB は Basic および Digest 認証スキームのみを実装します。サーバーによって他のスキームが要求される場合、または要求されたスキームの資格情報を提供しない場合、認証応答メッセージは 401 または 407 の StatusCode オブジェクトを返します。その場合、適切な応答を自分で実装しなければなりません。

正常に認証されると、MATLAB は情報を Credentials オブジェクトに保存します。これらの資格情報を同じサーバーへの今後の要求に適用すると、MATLAB はサーバーからの認証チャレンジを待ちません。資格情報を適用するには、各要求に対して同じ Credentials オブジェクトを指定します。

Credentials オブジェクトはハンドル オブジェクトで、以前に成功した認証に関する情報を内部に蓄積します。したがって、後続のメッセージでその情報を再使用することができます。このオブジェクトを複数の HTTPOptions オブジェクトに挿入する場合、Credentials オブジェクトは使用するたびに更新される可能性があります。copy メソッドを使って Credentials をコピーすると、MATLAB は設定した可視のプロパティのみをコピーし、内部状態はコピーしません。

matlab.net.http.Credentials クラスは handle クラスです。

クラスの属性

Sealed
true

クラス属性の詳細については、クラスの属性を参照してください。

作成

説明

obj = matlab.net.http.Credentials(Name,Value) は 1 つ以上の名前と値のペアの引数で指定された追加のプロパティを使用して、HTTP 資格情報を作成します。Name はプロパティ名で、Value は対応する値です。Name1,Value1,...,NameN,ValueN のように、複数の名前と値のペアの引数を任意の順番で指定できます。未指定のプロパティは既定値に設定されます。

プロパティ

すべて展開する

資格情報の認証スキーム。matlab.net.http.AuthenticationScheme オブジェクトのベクトルとして指定します。既定値は AuthenticationScheme.Basic および AuthenticationScheme.Digest です。Scheme が空の場合、資格情報はすべての認証スキームに適用されます。

SchemeBasic のみに設定されている場合、サーバーが認証を要求するかどうかにかかわらず、これらの資格情報が要求に適用されることがあります。Basic のみのスキームでは、認証チャレンジへの応答の余分なやり取りが回避されます。ただし、サーバーが Basic 認証を要求しない場合、このスキームは Username プロパティおよび Password プロパティをサーバーに不必要に提示することになります。

オプションのいずれかが Digest である場合、または Scheme が空の場合、これらの資格情報が適用される可能性のある最初のメッセージが Authorization ヘッダー フィールドなしで送信されます。メッセージは Scope プロパティおよび要求 URI に基づいて選択されます。これらの Credentials は、サーバーがチャレンジで応答した後、かつ Scope プロパティと Realm プロパティが URI とサーバー チャレンジに一致した場合にのみ使用されます。

属性:

GetAccess
public
SetAccess
public

資格情報が適用される URI。matlab.net.URI オブジェクトのベクトル、string または文字ベクトルとして指定します。string は URI コンストラクターで受け入れ可能なもの、または host/path/... の形式でなければなりません。

空の Scope 値、またはこのベクトルの空の Host または Path は、すべての Host プロパティまたは Path プロパティに一致します。信頼されているサーバーのみにアクセスする場合を除き、SchemeBasic に設定されている場合は Scope を空のままにしないでください。この設定の組み合わせにより、これらの Credentials を含む HTTPOptions を使用してアクセスする任意のサーバーに、UsernamePassword が送信されます。

MATLAB は Scope の値と要求メッセージ URI を比較して、これらの資格情報が適用されるかどうかを判別します。要求 URI がこの Scope のいずれかの URI と同じレベルまたはそれより深いレベルのパスにある同じホストを参照する場合、資格情報が適用されます。パスなしでホストを指定した URI を含む Scope は、このホスト上のすべてのパスに適用されます。

たとえば、Scope のホスト名 mathworks.com は、www.mathworks.com および anything.mathworks.com への要求に一致します。mathworks.com/products/stateflow URI は www.mathworks.com/products/stateflow/features への要求に一致しますが、www.mathworks.com/products への要求には一致しません。/products パスは /products/stateflow と同じレベルまたはそれより深いレベルにありません。

Scope URI の HostPort および Path プロパティのみが使用されます。通常、www.mathworks.com などのように Host 名のみを指定します。資格情報がホスト内のいくつかのパスでのみ必要なことがわかっている場合は、Path またはパスの一部を追加します。

属性:

GetAccess
public
SetAccess
public

資格情報の認証レルム。資格情報のレルムを記述する正規表現を含む string 配列、文字ベクトルまたは文字ベクトルの cell 配列として指定します。既定値は空 ([]) で、すべてのレルムに一致します。値が空の string の場合、空または未指定の Realm とのみ一致します。正規表現を認証 Realm 文字列の先頭または末尾に一致させるには、^ 文字または $ 文字を適宜含めます。

Realm には表示するテキストが含まれるので、ユーザーは入力する名前とパスワードを知ることができます。サーバーは RealmAuthenticateField で指定します。サーバーが異なる URI に対して異なるログイン値を要求し、同じサーバー上の異なるレルムに対して異なる資格情報をプログラムで指定する場合、Realm を使用します。名前とパスワードを求めるプロンプトを表示する場合は、このプロパティを設定しないでください。代わりに、プロンプトの AuthenticateField から Realm プロパティを表示して、ユーザーに入力する資格情報を知らせます。

MATLAB は Realm の表現を AuthenticateField の認証 Realm と比較して、これらの資格情報が適用されるかどうかを判別します。これらのいずれかのレルムを使用して MATLAB で認証が正しく実行されると、MATLAB は認証情報を Credentials にキャッシュします。これらの Credentials が適用されるこれ以降のホストとパスへの要求では、このキャッシュされた情報が認証に使用されます。これにより、認証チャレンジのオーバーヘッドや関数 GetCredentialsFcn の呼び出しが回避されます。

属性:

GetAccess
public
SetAccess
public

Basic 認証スキームまたは Digest 認証スキームに対するユーザー名。string または文字ベクトルとして指定します。Username プロパティおよび Password プロパティを任意の string (空の string も含む) に設定すると、GetCredentialsFcn が指定されない限り、これらの資格情報が適用される要求への認証で Username が使用されます。このプロパティを [] に設定する場合、GetCredentialsFcn を指定しなければなりません。そうしないと、認証が行われません。

属性:

GetAccess
public
SetAccess
public

Basic 認証スキームまたは Digest 認証スキームに対するパスワード。string または文字ベクトルとして指定します。GetCredentialsFcn プロパティを指定しない限り、これらの資格情報が適用される要求の認証には Password プロパティを使用します。Password 値が [] の場合、パスワードは提供されません。

属性:

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 オブジェクトのベクトル内の 1 つの要素。この配列の各オブジェクトには Scheme フィールドと Realm フィールドがあります。

  • prevUsername, prevPasswd (オプション) — 最初は空の引数。引数が設定されている場合は、サーバーで受け入れられなかった、前の呼び出しで返された関数 GetCredentialsFcn の値です。資格情報を求めるプロンプトを表示しない場合、これらの値を、返す予定の値と比較します。それらが同じ場合、username[] に設定して認証の失敗を示します。ユーザーに資格情報を求めるプロンプトを表示する場合は、これらの引数を指定する必要はありません。

  • username — 使用するユーザー名。サーバーがパスワードのみを要求し、ユーザー名を要求しない場合、username を空の string ('') に設定します。username の値が [] の場合、認証が失敗したことを示します。

  • password — 使用するパスワード。

関数 GetCredentialsFcn を実装して CredentialsUsername プロパティと Password プロパティの一方または両方を空にすれば、これらの値をプログラムに組み込まずにプロンプトを実装してユーザーから値を取得できます。プロンプトには、要求 URI または authInfo.Realm プロパティを表示します。Username プロパティを設定してパスワードのみを要求するのが便利な方法です。プロンプトには、既存の Username または prevUsername が設定されていればこれを表示し、ユーザーが変更できるようにします。

関数 GetCredentialsFcncred 引数と要求メッセージおよび応答メッセージのヘッダー フィールドで資格情報を確認して、どのリソースがアクセス中であるかを判別できます。これにより、関数はユーザーに対して正しい資格情報を求めるプロンプトを表示できます。一般に、ユーザーに認証のコンテキストを知らせるため、プロンプトでは authInfo.Realm が表示されなければなりません。

cred 引数はハンドルであるため、関数 GetCredentialsFcn はユーザー名とパスワードをオブジェクトに格納します。以降の要求では関数を再度呼び出すことなく、このオブジェクトを使用できます。MATLAB は以降の要求に適用するために、名前とパスワードを内部で保存します。ただし、MATLAB はこれらの資格情報を使用する異なる要求に対して同じユーザー名とパスワードが適用されるかどうかを常に判別できるとは限りません。

認証が拒否された場合、GetCredentialsFcn はユーザー名として空の配列 [] (空の string、'' ではない) を返します。MATLAB はサーバー認証の失敗を応答メッセージで返します。これは、ユーザー プロンプトが実装されているときにユーザーがプロンプトで [キャンセル] をクリックした場合の適切な動作です。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);
...

次に、同じ資格情報を含むオプションを再利用します。資格情報は既に正常に使用されているため、このトランザクションでは 1 つのメッセージが必要になります。

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

既定値として Credentials オブジェクトの Username プロパティを使用して、資格情報を求めるプロンプトを表示する関数を作成します。MATLAB はこの関数を呼び出して認証応答に使用する名前とパスワードを取得します。

関数 getMyCredentials を作成します。

function [u,p] = getMyCredentials(cred,req,resp,authInfo)
    u = cred.Username;
    prompt{1} = 'Username:';
    prompt{2} = 'Password:';
    defAns = {char(u), ''};
    title = ['Credentials needed for ' char(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 で導入