スキップしてメイン コンテンツに移動

Workspace ONE UEM APIs Collectionの使い方

 

Workspace ONE UEMでは、デバイス情報の照会やコマンドの実行、プロファイルなどのリソースの設定など、さまざまな操作を実行するためのAPIが提供されています。

APIの使い方を確認したり、テストを実行したりするにはAPI Explorerを使うこともできますが、今回は下記のページでも紹介されている、Postmanで公開されているWorkspace ONE UEM API Collectionを使用して、より簡単にAPIを使用する方法を紹介します。

大まかな流れは以下の通りです。
    1．PostmanでWorkspace ONE UEM API Collectionを作成
    2．Collectionのセットアップ
    3．APIコールの実行と結果の確認


1．Postman で Workspace ONE UEM API Collection を作成

まずは、Postmanアプリを開き、検索ボックスに 「Workspace ONE UEM APIs」と入力し、検索結果に表示される「Workspace ONE UEM APIs」を選択します。


Postmanの左ペインにコレクションが表示されたら、コレクション名の右側にある3つの点をクリック後、「Create a fork」をクリックします。


「Fork label」に任意の値を入力し、「Workspace」で任意のワークスペースを選択後、「Fork Collection」をクリックします。


これで、自分のワークスペースでWorkspace ONE UEM APIコレクションを使用できるようになりました。



2．Collectionのセットアップ

APIコールを実行する前に、いくつかの前提となる設定をする必要があります。
このセクションでは、APIコールを実行するために必要な設定の方法を紹介します。

2.1. Global variablesの設定
フォーク処理が完了したら、コンソール右上の 「Environment quick look」アイコンをクリックし、「Globals」の右側にある 「Add」をクリックします。」


「Variable」列に「aw-tenant-code」と「Access Token」を入力し、それぞれの「Type」列を「secret」に設定後、右上の「Save」をクリックします。



2.2. BaseUrlの設定
BaseUrlを設定するには、UEMの「REST API URL」を取得する必要があります。
UEMコンソールにログインし、「GROUPS & SETTINGS」>「すべての設定」>「システム」 > 「高度な設定」>「サイトURL」に移動し、「REST API URL」の値を取得します。


Postmanコンソールに戻ります。
コレクション名をクリックし、「Variables」タブをクリックし、目的のAPIエンドポイントの行を確認し、「Initial value」と 「Current value」の両方で、「YOUR_API_SERVER」を「REST API URL」のUEM環境のホスト名の値に置き換えます。
例えば、UEMのREST API URLが先ほどのスクリーンショットのようにhttps://as802.awmdm.com/APIの場合、「YOUR_API_SERVER」を「as802」に置き換えます。
そして「Save」をクリックします。


2.3. 認証情報の設定
APIコールを実行するには管理者認証が必要です。
このブログでは、OAuth 2.0を認証方法として使用します。

以下のドキュメントから UEM 環境の「Token URL」を取得します。
リージョンが異なるとToken URLも異なる場合があるので、環境ごとに確認します。


UEMコンソールで、「GPOUPS & SETTINGS」>「Configurations」に移動し、「OAuth Client Management」 をクリックします。


OAuthクライアント管理 画面で、「追加」をクリックします。


以下の設定を入力し、「SAVE」をクリックします。
　A) Name： OAuthクライアントの任意の名前
　B) 説明：このOAuthクライアントの説明
　C) 組織グループ： UEMの組織グループを選択
　D) 役割： このOAuthクライアントに設定されている管理者ロールを選択
　E) ステータス：有効


「Client ID」と「Client Secret」の値をコピーし、「CLOSE」をクリックします。
【補足】「Client Secret」の値はこの画面にしか表示されませんので、コピーし忘れた場合は再度作成する必要があります。


Postmanコンソールに戻り、新しいリクエストを作成し、リクエストメソッドを「POST」に設定し、URLボックスに 「Token URL」の値を入力します。
「Body」タブを以下のように設定します。
　-grant_type：client_credentials
　-client_id：UEMで生成された「クライアント ID」の値
　-client_secret：UEMで生成された「クライアントシークレット」の値


設定後「Send」をクリックし、レスポンスから「access_token」の値をコピーします。


Workspace ONE UEM API Collectionに戻り、「access_token」の値を「Access Token」変数の「Current Value」 に入力します。


Access Tokenの値を設定した後、Authorizationタブに移動し、以下の画像のように「Available Tokens」の下のフィールドに「{{Access Token}}」を追加します


2.4. aw-tenant-codeの設定
「aw-tenant-code」は、Workspace ONE UEMのテナントを一意に識別するコードで、APIを実行するための必須パラメータです。ここでは、その取得方法を紹介します。

UEMコンソールにログインし、「GROUPS & SETTINGS」>「すべての設定」>「System」>「Advanced」>「API」>「REST API」に移動し、「AirWatchAPI」行の 「API Key」列の値を取得します。


Postmanコンソールに戻り、変数 「aw-tenant-code」の 「Initial value」と 「Current value」にAPIキーの値を入力し、「Save」をクリックします。



3．APIコールの実行と結果の確認

Collectionには多くのAPIサンプルが用意されています。
このブログでは、例として、Windowsデバイス関連のトラブルシューティングに有用なデバッグログを指定したデバイスから収集することができるコマンドである「Request Device Log」をAPIで実行してみます。


Collectionから目的のAPIリクエストを検索します。
このシナリオでは、「New - Executes device log request command for device matching the filter criteria.」 を検索してクリックします。
これは、UEM コンソールの 「Request Device Log」 アクションに相当します。

APIリクエストを実行するために必要な値を入力します。
このシナリオでは、シリアル番号でデバイスを検索するため、「searchby」キーの値の列に 「Serialnumber」を入力し、「id」キーの値の列に対象となるデバイスのシリアル番号の文字列を入力します


リクエストの詳細をすべて設定した後、「Send」をクリックし、レスポンスとして 「202 Accepted」が表示されることを確認します。


UEMコンソールでは、API実行の結果として、指定したデバイスの「Troubleshooting」タブの「Commands」タブに「Request Logs」コマンドがキューイングされており、API経由でログのリクエストが実行できていることが確認できます。



前述の手順の「1.」と「2.」については、SaaS環境側のバージョンアップなどが無い限りは、基本的に一度セットアップしてしまえば以降は実施する必要はありません。

実行したい内容に応じて「3.」で実施したように目的の操作を実行するAPIを探して実行するだけというイメージです。

APIの利用は、日常業務で実行されるタスクの自動化や削減を検討する際に大きな助けとなると思います。
あるタスクがAPIで実行できるかどうかを調査し、それが動作するかどうかを検証し、最終的にAPIを使用するというステップは難しいプロセスになりがちですが、このプリセットのPostmanコレクションを使用すれば、ユーザーは簡単にUEM APIを活用できるのではないかと思います。


コメント

コメントを投稿

このブログの人気の投稿

Workspace ONE Accessに証明書認証でログイン

Workspace ONE AccessではSaaSなどのサービスへのアクセス管理ができますが、クライアント証明書認証の機能も備わっています。 ここでは、Workspace ONE UEMから配信した証明書を使用して、Workspace ONE Accessに証明書認証でログインする、ということをやってみます。 まずは、Workspace ONE UEMコンソールでの作業です。 すべての設定＞システム＞エンタープライズ統合＞Workspace ONE Access＞構成 へ移動し、「 エクスポート 」をクリックしてAirWatch認証局のルート証明書をエクスポートします。 次に、Windows向けにWorkspace ONE Access認証用証明書プロファイルを作成してデバイスに対して配信します。 SCEPペイロードを選択し、「 資格情報ソース 」は「 AirWatch認証局 」を選択します。証明書テンプレートは「 証明書（クラウド展開） 」です。 【補足】 上記のプロファイルで配信した証明書は 秘密キーのエクスポートができない ようになっているため、使い回しを防ぐことができます。つまり、私用のデバイスにインポートし直してログインしてしまおう...ということはできない仕組みになっているワケですね。 次はWorkspace ONE Accessの管理コンソールでの作業です。 IDとアクセス管理＞管理＞認証方法をクリックし、「 証明書（クラウドデプロイ） 」の設定を変更します。（UEMのプロファイルで選択した証明書テンプレートと同じ名前ですね。若干の誤差はありますが...） 始めに、「 証明書アダプタを有効にする 」にチェックを入れ、「 ルートおよび中間CA証明書 」のところには先ほどWorkspace ONE UEMからエクスポートした証明書をアップロードし、「 証明書の失効を有効にする 」にもチェックを入れておきます。 【補足】 公的認証局であっても、ここでルート証明書をアップロードしない限り証明書認証はできないので、今回の例では Workspace ONE UEM内部の認証局から発行されている証明書以外では認証できない 構成にすることができます。 少し下にスクロールして「 OCSPの失効を有効にする 」にチェックを入れ、「 OCSPレスポンダの署名証明書 」には...
コメントを投稿
続きを読む

Workspace ONE AccessでOpenID Connect連携

Workspace ONE Accessはその名の通りSaaSなどへのアクセス管理をすることができる製品ですが、Identity Providerの役割を果たすことも可能で、以下のフェデレーションプロトコルに対応しています。 　－WS-Federation 　－SAML 　－OpenID Connect WS-FederationはOffice365と連携する際などに利用したりするヤツですね。 個人的な感覚では、クラウドサービスはSAML認証に対応しているものが多いのでWorkspace ONE Accessと認証連携する場合、SAMLを利用するケースが一番多い気がします。 また、設定ガイド( SAML ベース SSO 統合のドキュメント センター )なんかも公開されており、連携のハードルは比較的低いと思います。 一方で、OpenID Connectの利用に関してはかなり情報が少ない気がしてます... ただ、OpenID Connectも認証連携の仕組みとしては代表的なものの一つではありますので、今回はOpenID Connectを使用してWorkspace ONE Accessと認証連携をしてみたいと思います。（連携先のサービスにはRedmineを使用します。） まずはWorkspace ONE Accessの管理コンソールでの作業です。 カタログ＞Webアプリケーション とクリックして、Workspace ONE Accessのアプリカタログに載せるWebアプリの一覧を開き、「 新規 」をクリックします。 「 名前 」に入力した値はそのままユーザーのアプリカタログに表示されるので、わかりやすい名称にします。入力したら次に進みます。 【補足】 いくつかのサービスは連携用のテンプレートがあり、「 またはカタログから参照 」をクリックすることで利用が可能です。今回使用するRedmineについても、SAML連携であればテンプレートがあるので比較的カンタンに設定できると思います。 まずは、「認証タイプ」で「 OpenID 接続 」を選びます。（おそらくOpenID Connectが訳されているのでしょうが、何か違うような...） すると、OpenID Connect連携用の設定項目が現れるので、各設定を入れていきます。 「 クライアントID 」と「 クライアント シークレ...
コメントを投稿
続きを読む

Workspace ONE AccessからServiceNowにシングルサインオン(SAML)

以前、Workspace ONEと他システム間で、 OpenID Connect で連携する内容をポストしましたが、今回は SAML を利用したシングルサインオンの構成を検証してみました。 ServiceNow と SAML連携 して、WS1のポータルからシングルサインオンする構成を試してみます。 大枠の流れとしては以下の通りです。      1．ServiceNow(SP)のSAML認証設定          1.1． WS1 AccessからSAML連携に必要な情報を取得           1.2．SAML認証設定      2．WS1 Access(IDP)でSAML認証設定      3．動作確認 1.ServiceNow側(SP)でSAML認証設定 まずは、今回の構成ではSP(Service Provider)となるServiceNow側でSAMLによるシングルサインオンを可能とするように構成します。 1.1．WS1 Accessから S AML連携に必要な情報を取得 まずは、WS1 AccessのIDPメタデータのURLを取得します。 [カタログ]>[Webアプリケーション]をクリック後、[設定]をクリックします。 左ペインから[SAMLメタデータ]をクリック後、IDPメタデータの[URLをコピー]をクリックします。 クリップボードにコピーされるので、テキストエディタにでも貼り付けておきます。 次に、WS1 AccessのIDP署名証明書を取得します。 左ペインから、[SAMLメタデータ]をクリック後、署名証明書の[ダウンロード]をクリックします。 こんなファイルがダウンロードされます。 1.2．SAML認証設定 続いて、ServiceNow側のSAML認証設定を行います。 ServiceNowの管理コンソールにログインし、検索バーに[saml]と入力後、[SAML2 Single Sign-On]配下の[Certificate]をクリックします。 後で、使用するため先ほどダウンロードした、[signingCertificate.cer]をテキストエデ...
コメントを投稿
続きを読む