■Workspace ONE UEM API Explorerについて

この投稿は、vExperts Advent Calendar 2019 - Adventar の 12日目の記事です。

今年初めて vExperts Advent Calendar に参加させていただきます。どうぞ宜しくお願い致します。

今回の記事のテーマは、「Workspace ONE UEM(以下UEM)の持つREST APIの動作確認をしてみること」です。

VMware製品の持つAPIの多くは、以下のページでどのようなものがあるかを確認することが可能です。


ただ、UEMのAPIについては上記ページに記載はなく、UEMホストそのものに同様のページが設けられています。具体的には各UEMホストの、以下のURLに準備されています。

  • https://<UEMのFQDN>/api/help/#!/apis

※2020/9/25追記：確認する範囲では<UEMのFQDN>でもAPI Explorerにはアクセス可能ですが、多くのSaaS共有環境では、API のURLは普段管理コンソールとして利用するcnXXX.awmdm.comの先頭二文字のcnをasに入れ替えた値となります(API ExplorerのFQDNも本来はこちらになります)。
UAGなどでTunnelやContent Gatewayなどの構成要件としてAPIとの通信が必要な場合は、<UEMのFQDN>ではなく、asXXX.awmdm.comなどのような、API用URLをご確認の上、通信を許可してください。なお管理者権限にもよりますが、API用URLについてはSaaS共有環境であれば[グループと設定]＞[すべての設定]＞[システム]＞[高度な設定]＞[サイトURL]で確認可能です(2020/9/25時点)。

  

REST API用のURLの確認画面。
※画像はConsole Administrator権限で確認した際のもの

上記URLにアクセスすると、Workspace ONE UEM API Explorerが表示されます。
REST APIの動作確認というと、postmanなどのREST Clientをインストールしたり、FireFoxやChromeにREST Clientのプラグインを追加したりする方が多いかと思います。
UEMがバージョン8.xのころは私も上記の方法でREST APIの動作確認を行っていましたが、バージョン9.2ごろから、このWorkspace ONE UEM API ExplorerからREST APIの動作を確認することができるようになりました。
今回は一例として、「UEMに登録されているユーザーアカウントをREST APIで取得」したいと思います。

今回は、ハンズオンラボ環境を使用するので、以下のホストのREST APIにアクセスしています。
※アクセスしてページを表示するだけならいつでもできますが、実際にAPIを利用するには、ハンズオンラボコース（HOL-2051-09-UEM）の登録と開始が必要です。

  • hol.awmdm.com

上記ページにアクセスすると、以下のような画面が表示されます。

このエントリを記述した2019年12月12日時点で筆者が確認する限り、
この画面はどのUEMホストにおいても日本語化されていないようです。

上記の画面から、画面左上のAPIsをクリックすると、APIを用途ごとに分類したページが表示されます。


今回はユーザをREST APIで取得するため、右上の検索欄にuserと入力します。
userと入力すると検索条件に合致するAPIがリストされていきます。


今回は、/users/searchというAPIを利用するので、画面をスクロールダウンして探し出し、API名をクリックします。


クリックすると、API検索画面の最上部が表示されます。この画面をスクロールダウンすると/users/searchのパラメータ入力画面があるのですが、いったんここでは[AUTHORIZE]ボタンをクリックします。


[AUTHORIZE]ボタンをクリックすると、UEMに対してREST APIでGETやPOSTを行う権限を持つユーザーのログイン情報や、使用しているUEMのテナント情報などを投入する画面がポップアップ表示されます。

オレンジ色の枠内で示したエリアで、必要な情報を入力します。
全部表示されない場合は、オレンジ枠内右側のスクロールバーを
スクロールダウンし、適宜必要な項目を表示/入力します。

今回は、以下3つの情報を入力します。
  1. ユーザー認証情報(ユーザー名/パスワード)
  2. REST APIキー
  3. 組織グループID
それぞれの情報を集めてみましょう。
まずはユーザー認証情報です。これは単純に、UEM管理コンソールの管理者ユーザー名とパスワードです。

usernameとpassword欄に入力し、
[Authorize]ボタンをクリックします。

次に、REST APIキーです。これは、UEM管理コンソール上にログイン後、グループと設定＞すべての設定＞システム＞高度な設定＞API＞REST APIで閲覧できます。デフォルト状態ではコピーすることができませんが、[オーバーライド]することでコピー可能になります。

管理コンソールにログインして。。
[グループと設定]（画面左下）→[すべての設定]をクリック
ポップアップ表示されたら、
[システム]→[高度な設定]→[API]→[REST API]と進み、
[オーバーライド]をクリック。
オーバーライド後、画面に表示されたAPIキーの中から、
アカウントタイプが「管理者」のAPIキーをコピー

ここまで来たら、あとはAPIの画面に戻り、aw-tenant-code欄にAPIキーをペーストします。

ユーザー名/パスワードを入力した後に[AUTHORIZE]用の
ポップアップ画面が閉じるため、再度画面右上の
[AUTHORIZE]ボタンをクリックして、
aw-tenant-code欄にAPIキーをペーストし、
ポップアップ画面内の[Authorize]ボタンをクリックします。

最後に組織グループIDです。これはUEM管理コンソールログイン後、画面左上のタブにマウスオーバーした際に表示される「グループID」です。

画像は『■ HOL-1957-01-UEM(5)：組織グループってなんだ？ - その１ 』から。
※今回使用する値とは異なります

グループIDをコピーし(または控え)たら、先ほどと同様APIの画面に戻り、aw-groupid欄にペーストします。

画面右上の[AUTHORIZE]ボタンをクリックして、
aw-groupid欄に組織グループIDをペーストし、
ポップアップ画面内の[Authorize]ボタンをクリックします。

それではテスト用に作成したユーザー情報を取得してみます。
認証情報等を入力した画面が閉じたら、画面をスクロールダウンし、/users/searchのクエリ入力画面にてfirstname欄にtestと入力します(※この環境では事前にtestというファーストネームを持つユーザーを3つ作成しています)。正常にAPIが動作すれば、3つのユーザーの情報を取得してくれるはずです。


クエリを入力したら、[Try it out!]をクリックし、リクエストを実行します。


実行すると、[Try it out!]ボタンの下に、CurlでこのREST APIをたたく場合のオプション付きの実行例が表示されます。UEMにアクセス可能なLinuxでこのコマンドを使用することでも、同様の結果が得られます。


そしてさらにスクロールダウンすると、レスポンスが出力されています。


今回はユーザー情報の取得を実施しましたが、ほかにも様々なAPIが用意されています。
普段からUEMを利用される方は、ご利用中のUEMコンソールのAPIをのぞいてみると、今の管理操作をちょっと楽にしてくれる、思わぬAPIを見つけられるかもしれませんね。

明日の vExperts Advent Calendar 2019 - Adventar は masotsuka さんです。
どうぞ宜しくお願い致します。

このブログの人気の投稿

●久々にESXiのカスタムISOをつくってみた

ブログのタイトルに仮想化という言葉がはいっているのですが、ここ2-3年ESXiなどにちゃんと触れていないことに気づき、後ろめたい気持ちがあったので、久々に仮想化について記載いたします。 今回は自作PCをくみ上げ、ESXi 6.7をインストールしてみました。 ※7じゃなくて6.7な理由は、自作パソコンをくみ上げた後にオンボードnicがRealtekさんだったことに気づいたためです。 ESXi 6.7までは有志の方が作ったRealtekのドライバを使うことができたようなのですが、7では使えないらしく、泣く泣くこの選択になりました。。。 参考： Homelab considerations for vSphere 7 そのため、インストールではなく、カスタムイメージの作成から始まります。 ※というかインストールはいろんな人がすでにブログで書いており、現状ほぼ自分も迷わないので、忘備録としてカスタムISOの作成だけを記載します。。汗 普段Workspace ONEに触れている私は、ESXiのカスタムイメージを作成する機会が滅多になく、作成のたびに2時間程度調べて格闘しなければいけなかったので、この機会に忘備録として記載してしまいます。。 なお、必要なイメージやVIBなどは以下を利用しました。 Net55-r8168 - V-Front VIBSDepot Wiki VMware vSphere Hypervisor (ESXi) 6.7U3b(オフラインバンドル) 手順は主に以下を参考にしました。 Using vSphere ESXi Image Builder to create an installable ISO that is not vulnerable to Heartbleed Using the vSphere ESXi Image Builder CLI ●ESXiのカスタムイメージ作成をやる前に、概念をぼんやり思い出そう 今回のESXiカスタムイメージ作成では、以下二つの概念が出てきます。 ソフトウェアデポ これはVIBなどのソフトウェアモジュールをプールしたモノのようです。ESXiのオフラインバンドルや拡張VIBモジュールのzipを入手したら、Add-EsxSoftwareDepotコマンドレットを使用して、とりあえずソフトウェアデポに追加していきます...
Read more »

Microsoft Graph PowerShellモジュールでMicrosoft 365の認証をWorkspace ONE Accessにフェデレーションする

イメージ
耐寒マツバギク(2024/5/18撮影) タンポポに似て、円形に細い花弁を持っていることや、その名前からキクの仲間と思ったところ、調べてみると違う植物の仲間だそうです。 マツバギクという名称なのでなんとなくアジア原産かと思っていたら、南アフリカ原産でした。 New-MgDomainFederationConfiguration コマンドというコマンドがあるそうです。 以下URLを見てみると、 前回のブログエントリ で使用した Set-MsolDomainAuthentication コマンドの後継コマンドだそうです。どうやら、Microsoftは将来的にSet-MsolDomainAuthenticationをはじめとしたコマンドの一式を非サポートとするようです。 Find Azure AD PowerShell and MSOnline cmdlets in Microsoft Graph PowerShell 今回私は、近い将来来る変化に備えて、New-MgDomainFederationConfiguration コマンドを使用してMicrosoft 365の認証をWorkspace ONE Accessに委任する方式を試してみました。 本ブログエントリは2024年5月18日時点で筆者が確認できた情報をもとに作成しております。本ブログエントリを参考に同様の手順を実行する場合、その時々の各製品、サービスの提供元の公式情報をご確認ください。 【2024年12月15日更新： このMicrosoft日本チームのブログ記事 を見ると、2025年3月30日をもってMSOLコマンドのサポートが完全に提供されなくなるようです】 ■目次 Microsoft.Graph.Identity.DirectoryManagement モジュールのインストール Microsoft 365に接続 Microsoft 365に存在するドメインのリスト表示 New-MgDomainFederationConfiguration コマンドによるフェデレーション設定 ログイン確認 その他躓いたこと ①Microsoft.Graph.Identity.DirectoryManagement モジュールのインストール Set-MsolDomainAuthentication コマンドは MSOnlin...
Read more »