OneGateのAPI機能を使ってみよう

はじめに

2025年7月からSoliton OneGateにて「OneGate API Suite」機能が利用できるようになりました。

OneGate API SuiteはREST APIとして提供しており、APIを介してOneGateの複数の機能にアクセスしてデータの取得や処理機能を呼び出して外部システムとの自動連携を行うといったことが可能です。

非常に便利なAPI機能ですが、「動作のイメージがなかなかつかめない」という方や、「試してみたいけどやり方がわからないし動作確認するのにハードルが高いと感じる」という方もいらっしゃるかもしれません。

そこで本記事では「OneGateのAPI機能を簡単に試してみたい」という方のために、下記3つの処理をPowerShellを使ってAPIで実施する方法をご紹介します。

1.「利用者ログインログ」をエクスポートする
2.「利用者」をインポートする
3.「招待コード」を一括発行する

※OneGate API Suiteは、Soliton OneGateのBasicまたはStandardプランをご契約のお客様でご利用可能です。
※API仕様はセキュリティや運用上の理由で随時変更・拡張される場合があります。
※API機能の利用には利用規約への同意が必要です。

API利用時の留意点

APIキーの保管について

APIキーはパスワードと同様に、厳重に管理し外部に漏洩しないようにご注意ください。

APIのURLについて

OneGateのAPIエンドポイントについて、どの機能を利用するかによってURLが異なります。後述のコマンド例にある「APIエンドポイントの指定」は、<中略>部分を含め、実際の環境に合わせて「Soliton OneGate API仕様書」に記載されているパスに置き換えてください。

API実行時のクライアント証明書認証について

OneGate管理ページにアクセスする際、クライアント証明書認証が求められる環境では、APIエンドポイントのURLに含まれるOneGateのFQDN部分について、下記のように 「ids」の後ろに「-s」を挿入してください。

例： soliton-techテナントの場合
https://soliton-tech.ids-s.soliton-ods.jp/<中略>/…

事前準備

前提条件

利用するPowerShellについて

今回はPowerShell 7を使ってOneGateのAPI機能を試します。PowerShell 7のインストール方法についてはMicrosoft社の記事などをご参考にしてください。
Windows への PowerShell のインストール - PowerShell | Microsoft Learn

実行環境

今回は下記の実行環境で動作確認を行います。

1. クライアント証明書の取得

OneGateよりクライアント証明書を取得します。証明書発行・インストール手順についてはご契約者様・ご評価者様向けに公開しているOneGateオンラインマニュアルの「Soliton OneGate利用ガイド」にございます「クライアント証明書（エージェント）発行」または「ご利用前の準備Ⅰ(証明書取得)」の項目をご確認ください。

クライアント証明書はAPIを実行する端末にインストールします。今回はWindows端末で実行するため、APIを実行するユーザーのユーザーストアに証明書をインストールします。

2. クライアント証明書の拇印確認

1. [Windows]キー+[R]キーで「ファイル名を指定して実行」を開き「certmgr.msc」と入力して「OK」をクリックします。
   
   
2. 「個人」＞「証明書」から取得したクライアント証明書が表示されていることを確認して、対象のクライアント証明書をダブルクリックします。
   
3. [詳細]タブを開いて「拇印」の項目の値をコピーしてメモ帳などに貼り付けておきます。

3. APIキーの取得

APIの呼び出しの際にAPIキーが必要になります。APIキーはOneGate側でAPIを利用可能なユーザーであるかを確認するのに用いられます。下記の手順でAPIキーを取得します。

1. OneGateの管理ページにログイン後、右上のログイン中のユーザー名をクリックして「アカウント情報」をクリックします。
   
2. 「APIアクセスキー」にある「発行」をクリックします。
   確認メッセージが表示されるので「はい」をクリックします。
   
3. 発行されたAPIキーをコピーしてメモ帳などに貼り付けておきます。このダイアログを閉じるとAPIキーを確認できなくなるためご注意ください。

以上で事前準備は完了です。
次の章からは、実際にAPIを利用するコマンドを実行して機能を試してみましょう。

1. OneGateの「利用者ログインログ」をエクスポートする

OneGateでログを保持できる日数は90日で、90日を経過すると自動的にログが削除されます。OneGateではSyslog over TLSで外部SIEM等に一部のログを転送する機能もありますが、定期的にログを取得して長期的に保管しておきたいという方もいらっしゃるかもしれません。
※OneGateのログ転送についてはこちらの記事で解説しています。

そのような場合、OneGateのAPI機能によりOneGateのログを自動で取得することが可能です。この章では、本日分のOneGate利用者ログインログをAPIでエクスポートする手順を紹介します。

1.1. PowerShellでコマンドを実行する

下記のようにPowerShellでコマンドを実行します。
コマンド実行の際は本記事の「API利用時の留意点」の項目もあわせてご確認ください。

# 今日の日付を取得
$YEAR = (Get-Date).Year
$MONTH = (Get-Date).Month
$DAY = (Get-Date).Day
$TODAY = "{0}/{1:D2}/{2:D2}" -f $YEAR, $MONTH, $DAY
 
# APIキーをセット
$API_KEY = "<コピーしたAPIキー>"
 
# URLを指定 (soliton-techテナントの場合)
$BASE_URL ="https://soliton-tech.ids-s.soliton-ods.jp/<中略>/employee/export"
 
# リクエストパラメーターで本日分のログを指定
$QUERY = "?key=log_timestamp&value=$TODAY-$TODAY"
 
# APIエンドポイント指定
$URL = "$BASE_URL$QUERY"
 
# 証明書の拇印
$CERT_THUMBPRINT = "<コピーしたクライアント証明書の拇印>"
 
# 証明書オブジェクト取得（ユーザーストアから）
$CERT = Get-ChildItem -Path Cert:\CurrentUser\My | Where-Object { $_.Thumbprint -eq $CERT_THUMBPRINT }
 
# HTTPヘッダーにAPIキーをトークンとしてセット
$HEADERS = @{
    "Authorization" = "Bearer $API_KEY"
}

# APIリクエストを実行する
Invoke-RestMethod -Uri $URL `
    -Headers $HEADERS `
    -Method Get `
    -Certificate $CERT

上記のコマンドを実行して下記のような結果が返ってくればOKです。

xml                                             　      loginLog 
---                                             　　　　--------
version="1.0" encoding="UTF-8" standalone="yes" 　　　　loginLog

1.2. 取得したログを確認する

下記のコマンドを実行します。

# 利用者ログインログのデータを格納
$RESPONSE = Invoke-RestMethod -Uri $URL -Headers $HEADERS -Method Get -Certificate $CERT

# 結果を表示
$RESPONSE.OuterXml

ログインユーザー名やログイン日時、送信元IPアドレス、認証に使用したクライアント証明書の情報などを確認することができます。

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<loginLog>
    <loginLogList>
        <loginLog>
            <operationTimestamp>YYYY/MM/DD hh:mm:ss</operationTimestamp>
            <processingDateAndTime>YYYY/MM/DD hh:mm:ss</processingDateAndTime>
            <loginName>testuser</loginName>
            <hostname></hostname>
            <sourceIPAddress><送信元IPアドレス></sourceIPAddress>
            <browserInformation>Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36 Edg/141.0.0.0</browserInformation>
            <loginResultFlag>true</loginResultFlag>
            <loginResult>Login Successful</loginResult>
            <loginType>OneGate Login</loginType>
            <countryCode>JP</countryCode>
            <countryName>Japan</countryName>
            <authenticationInformation1>
                <authType>PASSWORD</authType>
                <authTypeName>Password</authTypeName>
                <message>Authentication Successful</message>
                <messageCode><エラーコードの情報></messageCode>
                <successFlag>true</successFlag>
            </authenticationInformation1>
            <existsAdditionalAuthenticationLogFlag>false</existsAdditionalAuthenticationLogFlag>
            <icCardName></icCardName>
            <certificateType>INTERNAL_CERTIFICATES</certificateType>
            <certificateTypeName>Certificate issued by OneGate</certificateTypeName>
            <certificateSubject><証明書のサブジェクト></certificateSubject>
            <certificateSerialNumberText><証明書のシリアルナンバー></certificateSerialNumberText>
        </loginLog>

APIの実行結果はOneGate管理ページの[ログ管理]＞[管理ログ]から確認できます。

2. OneGateに「利用者」をインポートする

OneGateには利用者をCSVファイルで一括インポートする機能がありますが、頻繁にユーザーの追加、変更、削除が発生する環境では、毎度OneGateの管理ページにアクセスして手動でCSVファイルのインポートをしなければならず運用の手間になると感じるお客様もいらっしゃるかもしれません。

そのような場合に、OneGateのAPI機能を使ってユーザーを自動でインポートできれば、日々の運用業務の効率を上げられるかもしれません。例えば人事システムなどから出力したデータをAPI経由で自動でOneGateに反映させるといったことができるととても便利ですよね。

この章ではあらかじめ用意したインポート用CSVファイルをAPIを使ってインポートする手順を紹介します。

2.1. CSVファイルを作成する

OneGateにインポートするユーザーの情報を記載したCSVファイルを用意します。CSVファイルのフォーマットについては、ご契約者様・ご評価者様向けに公開しているOneGateオンラインマニュアルの「Soliton OneGate 管理ガイド」にございます「利用者情報のCSVファイルをOneGateにインポートする」の項目をご確認ください。

今回は下記内容のCSVファイル「OneGateUser.csv」を作成して試します。
作成したファイルは任意の場所に配置しておきます。今回は C:\test に配置します。

2.2. PowerShellでコマンドを実行する

下記のようにPowerShellでコマンドを実行します。
コマンド実行の際は本記事の「API利用時の留意点」の項目もあわせてご確認ください。

# APIキーをセット
$API_KEY = "<コピーしたAPIキー>"
 
# CSVファイル指定
$CSV_PATH = "C:\test\OneGateUser.csv"
 
# APIエンドポイントの指定?(soliton-techテナントの場合)
$URL = "https://soliton-tech.ids-s.soliton-ods.jp/<中略>/employee/import"
 
# 証明書の拇印
$CERT_THUMBPRINT = "<コピーしたクライアント証明書の拇印>"
 
# 証明書オブジェクト取得（ユーザーストアから）
$CERT = Get-ChildItem -Path Cert:\CurrentUser\My | Where-Object { $_.Thumbprint -eq $CERT_THUMBPRINT }
 
# CSVファイル送信
$FORM = @{
    file = Get-Item $CSV_PATH
}
 
# APIリクエスト実行
Invoke-RestMethod -Uri $URL `
    -Headers @{ "Authorization" = "Bearer $API_KEY" } `
    -Method Post `
    -Form $FORM `
    -Certificate $CERT

上記のコマンドを実行して下記の結果が返ってくればOKです。

status  responseBody errorInfo
------  ------------ ---------
success              {}

APIの実行履歴はOneGate管理ページの[ログ管理]＞[管理ログ]から確認できます。

2.3. OneGateで差分同期する

CSVファイルで追加したユーザーはOneGateの同期スケジュールが実行されたあとにOneGateの管理ページに反映されます。OneGateの管理ページにログイン後、[同期スケジュール設定]＞[差分同期スケジュール]にて同期スケジュールの確認や即時実行が可能です。

差分同期スケジュールをクリックしたときの画面今回は動作確認のため、差分同期スケジュールの「即時実行」を行い、ユーザーをOneGateに反映させます。

同期が完了すると[利用者管理]＞[利用者一覧]に対象のユーザーが表示されます。

同期処理の結果は[ログ管理]＞[同期実行ログ]から確認できます。

3. 招待コードを一括発行する

OneGateのクライアント証明書配布方法の1つとして、管理者から利用ユーザーに招待コードを発行してユーザーが発行された招待コードからクライアント証明書を取得する方法があります。

招待コードの発行はOneGateの管理ページから操作しますが、大量のユーザーに証明書を配布する必要があるとき、1ユーザーずつ画面操作して招待コードを発行していくのは時間がかかり、ミスが発生するかもしれません。

OneGateでは、管理ページからCSVファイルで招待コードの利用者をインポートすることにより招待コードの一括発行ができますが、API機能でもCSVによる招待コードの一括発行が可能です。

本章では前章でインポートしたユーザー対象に、あらかじめ用意したインポート用CSVファイルからAPI機能を使って招待コードを一括発行する手順をご紹介します。

3.1. CSVファイルを作成する

OneGateにインポートするユーザーの情報を記載したCSVファイルを用意します。CSVファイルのフォーマットについては、ご契約者様・ご評価者様向けに公開しているOneGateオンラインマニュアル「Soliton OneGate 管理ガイド」の「招待コード方式」にございます、「招待コードを発行する」項目をご確認ください。

今回は下記内容のCSVファイル「OneGateInvitation.csv」を作成して、前章でOneGateに追加したユーザーに対して招待コードを一括発行します。

※招待コード発行にあたって、事前に招待設定を作成しておく必要があります。
招待設定作成の手順は、オンラインマニュアル「Soliton OneGate 管理ガイド」の「招待設定」の項目をご確認ください。

今回は「default」の招待設定で試します。

作成したファイルは任意の場所に配置しておきます。今回は C:\test に配置します。

3.2. PowerShellでコマンドを実行する

下記のようにPowerShellでコマンドを実行します。
コマンド実行の際は本記事の「API利用時の留意点」の項目もあわせてご確認ください。

# APIキーをセット
$API_KEY = "<コピーしたAPIキー>"
 
# CSVファイル指定
$CSV_PATH = "C:\test\OneGateInvitation.csv"
 
# APIエンドポイント（soliton-techテナントの場合）
$URL = "https://soliton-tech.ids-s.soliton-ods.jp/<中略>/invitations/users/import"
 
# 証明書の拇印
$CERT_THUMBPRINT = "<コピーしたクライアント証明書の拇印>"
 
# 証明書オブジェクト取得（ユーザーストアから）
$CERT = Get-ChildItem -Path Cert:\CurrentUser\My | Where-Object { $_.Thumbprint -eq $CERT_THUMBPRINT }
 
# CSVファイル送信
$FORM = @{
    file = Get-Item $CSV_PATH
    encodingId = "30" # UTF-8の場合（Shift_JISなら"20"）
}

# APIリクエスト実行
Invoke-RestMethod -Uri $URL `
    -Headers @{ "Authorization" = "Bearer $API_KEY" } `
    -Method Post `
    -Form $FORM `
    -Certificate $CERT

上記コマンドを実行して下記の結果が返ってくればOKです。

status  responseBody               errorInfo
------  ------------               ---------
success {@{name=default; count=3}} {}

APIの実行結果はOneGate管理ページの[ログ管理]＞[管理ログ]から確認できます。

また[証明書管理]＞[招待コード管理]から、招待コードが発行されたかどうかや、ユーザーが発行された招待コードを利用してクライアント証明書を取得したかどうかを確認することができます。

招待コードが発行されると、ユーザーにメールで招待コードが通知されます。ユーザーはメールに記載のURLからSoliton KeyManagerアプリ経由でクライアント証明書を取得する流れとなります。

前章のユーザー追加のコマンドとあわせて活用すれば、利用者追加から招待コードの一括発行までの一連の作業を自動化することができるため、運用の効率化につなげられます。

応用編：「利用者ログインログ」をエクスポートしてファイルとして保存する

OneGateの利用者ログインログをエクスポートする手順をご紹介しましたが、エクスポート結果をファイルとして保存できれば、監査の対応の際などに役立てることができます。

追加で下記のコマンドを実行すると、エクスポートしたログをXMLファイルとして任意の場所に保存することができます。

# ファイルを任意の場所に保存(今回はC:\testに保存)
$FILE_NAME = "C:\test\userlog_{0}.xml" -f $TODAY.Replace('/','')
$RESPONSE.OuterXml | Out-File -FilePath $FILE_NAME -Encoding utf8

下記のようにXMLファイルがエクスポートされます。

ファイルの中身を確認すると、OneGateの利用者ログインログが記録されていることがわかります。
PowerShellのコマンドを利用してバッチファイルを作成して、タスクスケジューラーなどで1日1回深夜などのタイミングに実行するようにすれば、ログサーバーがない環境でも毎日の利用者ログインログをファイルとして長期間保存しておくことができます。

補足：よくあるエラー

1. 400 Errorが返ってくる

Invoke-RestMethod:

400 Error

400
You don't have client certificate.
No required SSL certificate was sent

© Soliton Systems K.K.

原因. 異なるCAから発行されたクライアント証明書の拇印を指定している

ユーザーストアの「個人」＞「証明書」に複数のクライアント証明書がインストールされている環境で、誤って異なるCAのクライアント証明書を指定すると400エラーが返ってきます。

コマンドのURLに含まれるOneGateテナントから発行したクライアント証明書を指定しているかご確認ください。

※OneGateの[システム設定] > [信頼する外部認証局設定]で外部CAを信頼しており、対象の外部CAからクライアント証明書を発行している場合は、信頼する外部CAから発行したクライアント証明書の拇印を正しく指定しているかご確認ください。

2. 403 Forbiddenが返ってくる

APIを実行して403エラーが返ってきてしまう場合は、下記の内容を中心に確認してみてください。

 Invoke-RestMethod:

403 Forbidden

403 Forbidden
Access denied.
(HTTP 403 : Access denied.)

Soliton OneGate, Copyright © 2025, Soliton Systems K.K., All rights reserved.

原因1. APIキーの値が間違っている

OneGateからコピーしたAPIキーの値に誤りがないかご確認ください。
1度発行したAPIキーの値を再度OneGateの管理ページから確認することはできないため、一から操作をやり直す場合には、APIを再発行してお試しください。

再発行の手順は「3. APIキーの取得」と同じです。
再発行時に下記のメッセージが表示されるので、「はい」をクリックすると新しいAPIキーが発行されます。こちらをメモ帳などに貼り付けて再度コマンド実行をお試しください。

原因2. APIエンドポイントのURLに「-s」を追記し忘れている

「-s」を付与しないと、OneGateの管理ページへのアクセスに失敗して403エラーになります。
「API実行時のクライアント証明書認証について」をご確認ください。

3. 404 Not Foundが返ってくる

Invoke-RestMethod:

404 Not Found

404 File Not Found
Page not found.
(HTTP 404 : Page not found.)

Soliton OneGate, Copyright © 2025, Soliton Systems K.K., All rights reserved.

原因. APIエンドポイントの指定を間違えている

APIエンドポイントのURLが間違っている（例：URLの一部が不足など）場合に404エラーが返ってきます。「Soliton OneGate API仕様書」で実行したい操作の「URL」の値をご確認いただき、指定している値に間違いがないかご確認ください。

おわりに

今回はOneGateのAPI機能をPowerShellを使って手軽に試す方法を紹介しました。API機能は外部システムの自動連携に使われるケースが多いですが、具体的な手順を確認することで、API機能を活用して効率的な運用管理を実現するイメージをつかんでいただけたのではないでしょうか。

今回はAPIによる3つの操作をご紹介しましたが、この他にも管理者ログ(監査ログ)のエクスポートやICカード情報の一括管理など様々な操作が可能です。

OneGateを利用しているが「効率的な運用ができていない」というお客様や、「IDaaSの導入を検討しているが運用できるか不安」といったお悩みをお持ちの方が、本記事でイメージを掴んでいただき参考になれば幸いです。

ゼロトラストを実現するIDaaS　ワンストップで選ぶならOneGate