matlab-secure-credentials

MATLAB での認証情報の安全な管理

API キー、トークン、パスワード、パスフレーズは、ハードコードするのではなく、MATLAB に組み込まれた暗号化ストアである MATLAB Vault で管理します。このスキルでは、認証情報の保存、取得、認証が必要なサービスへの接続時の受け渡しについて説明します。

使用する場面

• MATLAB から認証が必要なサービスや接続を利用する場合。REST API、データベース、クラウドストレージ、SFTP/FTP サーバー、メッセージキューなどが該当します。
• API キー、ベアラートークン、パスワード、SSH キーのパスフレーズを扱うコードを作成する場合。
• 認証情報が必要な、ユーザーが不在の CI／バッチ／スケジュール実行用 MATLAB コードを作成する場合。
• 認証情報を扱うコードをリファクタリングする場合や、シークレットを含む設定を永続化する場合。
• 「認証情報をコードに含めない」「シークレットをコミットしない」「安全な方法で実行する」といった依頼を受けた場合。

使用しない場面

• 認証情報を使わずに接続／クエリ／転送の処理自体を作成する場合（例：公開 API やローカルファイル）、またはデータがテーブルや timetable に入った後のクリーニング／変換／集計を行う場合は、該当するデータインポートスキル（例：matlab-analyze-data、matlab-use-database）を使用します。
• サードパーティのシークレットマネージャー（HashiCorp Vault、AWS Secrets Manager、Azure Key Vault）との統合は対象外です。
• OS レベルまたは MATLAB 以外でのキー管理。

選択ガイド：使用する方法

習慣ではなく、認証情報の受け渡し方法に基づいて選択します。

状況	使用するもの	使用しないもの
認証情報をセッションをまたいで保存し、再利用する	setSecret を一度実行し、使用時に getSecret を実行	ハードコード、独自に作成した設定ファイル
一連の認証情報をまとめて読み込む必要がある（対話型セットアップ、または非対話型／CI／ヘッドレス／スケジュール実行）	importSecrets でシークレットファイルから Vault に登録してから getSecret を実行。CI では、ランナーから渡された値に getenv を使用	ヘッドレスジョブでの setSecret — 対話型でのみサポートされています
関数が呼び出し元から認証情報を受け取る	secretID（シークレットの値ではなく参照）	値を構造体のフィールドや引数に保存する
認証情報が実際にプロセス環境変数である（CI から渡されるシークレットや、AWS_ACCESS_KEY_ID のようなクラウド SDK の規約など）	getenv — これが適切です	理由なく Vault に重複して登録する

ルールは「シークレットをハードコードしない」であり、「環境変数を決して使わない」ではありません。シークレットがすでにプロセスの環境変数である場合は getenv が適切です。自分で保存する認証情報には Vault を標準的に使用します。

ワークフロー

1. 上記の選択ガイドを使って方法を決めます。
2. 認証情報を保存または登録します。
   • 単一のシークレットを対話形式で登録する場合：setSecret("MyApiToken") を実行します（MATLAB が値の入力を求めます。値を引数として渡してはいけません。引数に指定できるのは名前のみです）。
   • 複数のシークレットをまとめて登録する場合：importSecrets("secrets.env") は、プロンプトを表示せずに名前と値を Vault に読み込みます。対話型セットアップにも、非対話型／CI にも便利です。
3. 使用時に getSecret("MyApiToken") で取得するか、secretID("MyApiToken") を受け付ける API に渡します（呼び出し時に値が解決されるため、値が変数に保持されることはありません）。
4. 接続に組み込みます — 以下のパターンを参照してください。
5. 読み取りまたは削除の前に isSecret("MyApiToken") で確認し、スクリプト、ログ、保存ファイルのいずれにもシークレットの値が含まれていないことを確認します。

主な機能

機能	目的	利用可能なバージョン
setSecret	シークレットをボールトに追加します。対話型で、値の入力を求めます。名前のみを指定します（更新するには Overwrite=true を指定します）	R2024a
getSecret	シークレットの値を取得します（文字列スカラーを返します）	R2024a
isSecret	名前を指定したシークレットが存在するか確認します	R2024a
listSecrets	保存されているシークレットの名前を一覧表示します	R2024a
removeSecret	シークレットをボールトから削除します（deleteSecret はありません）	R2024a
setSecretMetadata	シークレットにメタデータ（有効期限や所有者など）を関連付けます	R2024a
getSecretMetadata	シークレットのメタデータを辞書として読み取ります	R2024a
secretID	シークレットの値ではなく名前を保持する参照オブジェクトです。weboptions および matlab.net.http.Credentials で使用できます	R2025a
importSecrets	ファイルから一連のシークレットをボールトに読み込みます（プロンプトは表示されません）	R2026a

使用パターン

一度保存し、使用時に取得する

% One-time, at the MATLAB prompt (prompts for the value — do NOT type the secret in code):
setSecret("MyApiToken");

% In your script, read it only where needed:
token = getSecret("MyApiToken");

有効期限などのメタデータを記録しておくと、呼び出し元が使用前に有効性を確認できます。

% Metadata values are stored in a dictionary; wrap each value in a cell:
setSecretMetadata("MyApiToken", dictionary("Expires", {datetime(2026,12,31)}));

md = getSecretMetadata("MyApiToken");
expiry = md{"Expires"};            % {} indexing returns the stored value
if expiry < datetime("today")
    error("MyApiToken expired on %s — rotate it with setSecret(...,Overwrite=true).", expiry);
end
token = getSecret("MyApiToken");

シークレットをローテーションまたは更新する

setSecret(...,Overwrite=true) は、既存のシークレットの値を置き換えます。これは認証情報をローテーションする通常の方法です（定期的に、または有効期限後などに新しい値に置き換えます）。Overwrite を指定しない場合、すでに存在する名前に対して setSecret を実行するとエラーになります。

setSecret("MyApiToken", Overwrite=true);   % prompts for the new value

ベアラートークンを使用した REST 呼び出し

ボールトからトークンを取得し、Authorization ヘッダーに設定します。

token = getSecret("MyApiToken");
opts = weboptions( ...
    HeaderFields = ["Authorization", "Bearer " + token], ...
    ContentType  = "json");
data = webread("https://api.example.com/v1/data", opts);

基本認証では、weboptions に secretID を渡すことで、リクエスト時に値が解決され、変数に保持されることはありません。

username = getenv("API_USER");   % REPLACE: your service-account user name
opts = weboptions(Username=username, Password=secretID("MyApiPassword"));
data = webread("https://api.example.com/v1/data", opts);

より低レベルのリクエストでは、matlab.net.http.Credentials も secretID を受け付けます。

cred = matlab.net.http.Credentials(Password=secretID("MyApiPassword"));

パスフレーズで保護された鍵を使用した SFTP

keyFile = fullfile(userpath, "id_rsa");   % REPLACE: path to your private key
s = sftp("sftp.example.com", "reportuser", ...
    PrivateKeyFile       = keyFile, ...
    PrivateKeyPassphrase = getSecret("SftpKeyPassphrase"));
c = onCleanup(@() close(s));
localPaths  = mget(s, "/reports/nightly.csv", tempdir);
reportTable = readtable(localPaths{1});

鍵の代わりにパスワード認証を使用する場合：

s = sftp("sftp.example.com", "reportuser", Password=getSecret("SftpPassword"));

データベース接続

パスワードをボールトに保存し、接続時に読み取ります。ホスト、ポート、データベースはコードに記述し、認証情報はコードに含めないでください。

conn = postgresql("svc-account", getSecret("PgPassword"), ...
    Server       = "db-prod-01", ...
    PortNumber   = 5432, ...
    DatabaseName = "analytics");
c = onCleanup(@() close(conn));
tables = sqlfind(conn, "");

再利用や共有が可能な設定にするには、データソースを一度保存し（Database Explorer アプリ、または databaseConnectionOptions と saveAsDataSource を使用）、名前を指定して接続し、パスワードをボールトから渡します。

conn = postgresql("analyticsDataSource", "svc-account", getSecret("PgPassword"));

クラウドストレージ（S3 / Azure Blob / GCS）

MATLAB のファイル I/O（readtable、datastore など）はクラウド URI を直接読み取り、SDK の環境変数から認証情報を取得します。明示的なキーを使用する場合は、ボールトから取得して SDK が想定する環境変数に設定します。クラウドインフラストラクチャで実行する場合は、アタッチされた IAM ロールを優先し、何も設定しないでください。

% Explicit keys held in the vault -> set the SDK env vars from getSecret:
setenv("AWS_ACCESS_KEY_ID",     getSecret("AwsAccessKeyId"));
setenv("AWS_SECRET_ACCESS_KEY", getSecret("AwsSecretAccessKey"));
setenv("AWS_DEFAULT_REGION",    "us-east-1");   % REPLACE: bucket region
T = readtable("s3://acme-data/prices/latest.csv");

コードを EC2 インスタンス、またはロールが有効な環境で実行する場合は、キーを一切使用しません。IAM ロールから認証情報が提供されるため、シークレットをどこにも保存する必要はありません。

関数に認証情報を渡す

関数が呼び出し元から認証情報を受け取る場合は、値ではなく参照である secretID を渡します。シークレットが解決されるのは、getSecret が呼び出された場所だけです。

設定を作成します。ここに保持されるのはトークンではなく参照です。

config = struct( ...
    "BaseUrl", "https://api.example.com/v1", ...
    "Token",   secretID("MyApiToken"));

関数内で設定を使用します。シークレットを解決するのは、使用する時点だけです。

function report = fetchReport(config)
    arguments
        config (1,1) struct
    end
    token = getSecret(config.Token.Name);
    opts  = weboptions(HeaderFields = ["Authorization", "Bearer " + token]);
    report = webread(config.BaseUrl + "/report", opts);
end

一連のシークレットをまとめて読み込む（セットアップまたは CI）

importSecrets は、プロンプトを表示せずにシークレットファイルから名前と値をボールトに読み込みます。対話型の初回セットアップにも、setSecret を使用できないヘッドレスジョブ（対話型でのみ使用可能なため）にも便利です。

% secrets.env — a dotenv file (e.g. from CI secret storage), never committed — with lines like:
%   MyApiToken=abc123
%   PgPassword=hunter2
importSecrets("secrets.env");     % FileType="auto" (default) detects the dotenv format
token = getSecret("MyApiToken");

ランナーがファイルではなく、プロセスの環境変数として認証情報を直接注入する場合は、getenv("MY_TOKEN") で読み取ります。ボールトは必要ありません。

規約

• 必ず：保存する認証情報には、デフォルトでボールト（setSecret／getSecret）を使用してください。removeSecret は isSecret で確認してから実行してください。
• 必ず：複数のシークレットを一度に読み込む場合、またはヘッドレス／CI 環境では、setSecret ではなく importSecrets を使用してください。
• 禁止：.m ファイルにシークレットをハードコードしたり、シークレットの 値 を構造体やログに書き込んだりしないでください。代わりに secretID の参照を渡してください。
• 推奨：API が参照を受け付ける場合は、getSecret で値を実体化するよりも、secretID(...) を weboptions／Credentials に渡してください。
• 認証情報がプロセス環境変数である場合（CI シークレット、クラウド SDK の規約など）は、環境変数を使用して問題ありません。利点がないのにボールトへ無理に移行する必要はありません。

よくある間違い

間違い	問題である理由	正しい方法
.m ファイルにトークン／パスワードをハードコードする	バージョン管理に漏えいし、ローテーションも困難になります	ボールトから getSecret("Name") で取得する
シークレットの 値 を、関数が受け渡しする構造体のフィールドや引数に書き込む	シークレットの平文がボールトの外に出ます	secretID の参照を保持し、使用時に getSecret で解決する
CI／バッチ／スケジュールジョブで setSecret を呼び出す	対話形式でのみサポートされており、値を入力できません	importSecrets を使って、非対話形式でボールトに登録する
deleteSecret を呼び出す	そのような関数は存在しません	isSecret で確認してから removeSecret("Name") を呼び出す
save() で認証情報を .mat ファイルに保存し、load() で読み戻す	シークレットの平文が暗号化されずにディスクへ書き込まれ、多くの場合コミットされます	値はボールトに保持し、secretID の参照のみを保存して、使用時に getSecret で解決する

エラーとその意味

エラー識別子	発生する状況	対処方法
MATLAB:authnz:secretapis:KeyAlreadyExists — "A secret named 'X' already exists. Set 'Overwrite' to true…"	X がすでにボールトにある状態で setSecret("X") を呼び出した場合	ローテーション／更新するには setSecret("X", Overwrite=true) を呼び出してください。それ以外の場合は、新しい名前を選んでください
MATLAB:authnz:secretapis:SecretValueNotFound — "No secret value found for secret name 'X'…"	保存されていない X に対して getSecret("X") を呼び出した場合（または名前の誤記、大文字・小文字の間違いがある場合）	先に保存してください（setSecret／importSecrets）。isSecret("X") で読み取り前に確認してください。シークレット名は大文字と小文字が区別されます
MATLAB:authnz:secretapis:RemoveSecretFailed — "…No secret found for secret name 'X'."	X がボールトにない状態で removeSecret("X") を呼び出した場合	if isSecret("X"); removeSecret("X"); end で確認してください

---

著作権 2026 The MathWorks, Inc.

---