Main Content

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 が自動的に実装する認証スキームを確認するには、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) は 1 つ以上の名前と値のペアの引数で指定された追加のプロパティを使用して、HTTP 資格情報を作成します。Name はプロパティ名で、Value は対応する値です。Name1,Value1,...,NameN,ValueN のように、複数の名前と値のペアの引数を任意の順番で指定できます。未指定のプロパティは既定値に設定されます。

引数を指定せずにこのコンストラクターを呼び出した場合、Credentials オブジェクトが適用され、すべての URI とすべての認証スキームに認証が許可されます。ただし、このオブジェクトは、ユーザー名前またはパスワードを必要としないスキームでのみ機能します。たとえば、Windows 上では、オブジェクトはログインしたユーザーの資格情報を使用して、NTLM および Kerberos の認証を有効にします。

プロパティ

すべて展開する

資格情報の認証スキーム。matlab.net.http.AuthenticationScheme オブジェクトのベクトルとして指定します。プラットフォームごとのサポートされるスキームの完全な一覧については、AuthenticationScheme を参照してください。

Scheme が空 (既定) の場合、資格情報はすべての定義された認証スキームに適用されます。

認証の詳細については、サーバー認証とプロキシ サーバー認証を参照してください。

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 オブジェクトのベクトル、string または文字ベクトルとして指定します。string は URI コンストラクターで受け入れ可能なもの、または host/path/... の形式でなければなりません。

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

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

属性:

GetAccess
public
SetAccess
public

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

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

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

属性:

GetAccess
public
SetAccess
public

認証スキームのユーザー名。string または文字ベクトルとして指定します。このプロパティは、明示的な Username と Password を要求するスキームにのみ適用され、システムから資格情報を取得するスキームには適用されません。

Username プロパティおよび Password プロパティを任意の string (空の string も含む) に設定すると、GetCredentialsFcn が指定されない限り、これらの資格情報が適用される要求への認証で Username が使用されます。このプロパティを [] に設定する場合、GetCredentialsFcn を指定しなければなりません。そうしないと、認証が行われません。

コードにユーザー名を組み込まない場合は、このプロパティを空のままにして、GetCredentialsFcn を指定してユーザーに名前を求めるプロンプトを表示するか、別のソースから取得します。

属性:

GetAccess
public
SetAccess
public

認証スキームのパスワード。string または文字ベクトルとして指定します。このプロパティは、明示的な Username と Password を要求するスキームにのみ適用され、システムから資格情報を取得するスキームには適用されません。

Username プロパティおよび Password プロパティを任意の string (空の string も含む) に設定すると、GetCredentialsFcn が指定されない限り、これらの資格情報が適用される要求への認証で Password が使用されます。このプロパティを [] に設定し、かつ 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 (オプション) — これらの資格情報を一致させるために MATLAB が選択する AuthenticateField.convert メソッドによって返される AuthInfo オブジェクトのベクトル内の 1 つの要素。この配列の各オブジェクトには Scheme と少なくとも 1 つの Realm パラメーターがあります。

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

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

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

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

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

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

GetCredentialsFcn がユーザー名に空の配列 [] (空の string '' ではない) を返した場合、認証は拒否されており、MATLAB は RequestMessage.send の呼び出し側への応答メッセージにサーバー認証の失敗を返します。これは、ユーザー プロンプトが実装されているときにユーザーがプロンプトで [キャンセル] をクリックした場合の適切な動作です。prevUsername と prevPasswd が、返す名前およびパスワードと同一の場合、名前とパスワードをプログラムで提供するときに [] を返さなければなりません。この値は、資格情報が受け入れられず、代替方法がないことを示します。そうしないと、関数 GetCredentaislFcn を繰り返し呼び出す無限ループが発生する場合があります。

属性:

GetAccess
public
SetAccess
public

データ型: function_handle

例

すべて折りたたむ

適切なサーバーにのみ送信される資格情報を作成します。

パスワードを格納する MATLAB Vault にシークレットを作成します。詳細については、Keep Sensitive Information Out of Codeを参照してください。

setSecret("JohnPassword")

資格情報を作成し、Vault からパスワードを取得します。

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);
...

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

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 で導入

参考

| | |

トピック