Microsoft Graph とアプリ専用認証を使用して Java アプリを構築する
このチュートリアルでは、Microsoft Graph API を使用してアプリ専用認証を使用してデータにアクセスする Java コンソール アプリを構築する方法について説明します。 アプリのみの認証は、組織内のすべてのユーザーのデータにアクセスする必要があるバックグラウンド サービスまたはアプリケーションに適しています。
注意
Microsoft Graph を使用してユーザーの代わりにデータにアクセスする方法については、この ユーザー (委任された) 認証チュートリアルを参照してください。
このチュートリアルの内容:
ヒント
このチュートリアルに従う代わりに、 GitHub リポジトリ をダウンロードまたは複製し、README の指示に従ってアプリケーションを登録し、プロジェクトを構成できます。
前提条件
このチュートリアルを開始する前に、 Java SE Development Kit (JDK) と Gradle が開発マシンにインストールされている必要があります。
また、グローバル管理者ロールを持つ Microsoft の職場または学校アカウントも必要です。 Microsoft 365 テナントをお持ちでない場合は、 Microsoft 365 開発者プログラムを通じてテナントの資格を得る可能性があります。詳細については、 FAQ を参照してください。 または、 1 か月間の無料試用版にサインアップするか、Microsoft 365 プランを購入することもできます。
注意
このチュートリアルは、OpenJDK バージョン 17.0.2 と Gradle 7.4.2 で記述されました。 このガイドの手順は、他のバージョンで動作する可能性がありますが、テストされていません。
ポータルでアプリを登録する
この演習では、 アプリのみの認証を有効にするために、Azure Active Directory に新しいアプリケーションを登録します。 アプリケーションは、Microsoft Entra 管理センターを使用するか、 Microsoft Graph PowerShell SDK を使用して登録できます。
アプリケーションをアプリ専用認証に登録する
このセクションでは、 クライアント資格情報フローを使用してアプリのみの認証をサポートするアプリケーションを登録します。
ブラウザーを開き、 Microsoft Entra 管理センター に移動し、グローバル管理者アカウントを使用してログインします。
左側のナビゲーションで [Microsoft Entra ID] を 選択し、[ ID] を展開し、[ アプリケーション] を展開して、[ アプリの登録] を選択します。
[新規登録] を選択します。 アプリケーションの名前 (例:
Graph App-Only Auth Tutorial
) を入力します。[ サポートされているアカウントの種類 ] を [この組織のディレクトリ内のアカウントのみ] に設定します。
[リダイレクト URI]を空のままにします。
[登録] を選択します。 アプリケーションの [概要 ] ページで、 アプリケーション (クライアント) ID と ディレクトリ (テナント) ID の値をコピーして保存します。次の手順でこれらの値が必要になります。
[管理] で、[API のアクセス許可] を選択します。
行で省略記号 (...) を選択し、[アクセス許可の削除] を選択して、[構成されたアクセス許可] の下にある既定の User.Readアクセス許可を削除します。
[ アクセス許可の追加] を選択し、[ Microsoft Graph] を選択します。
[アプリケーションのアクセス許可] を選択します。
[ User.Read.All] を選択し、[ アクセス許可の追加] を選択します。
[ 管理者の同意を付与する] を選択し、[ はい ] を選択して、選択したアクセス許可に対して管理者の同意を提供します。
[管理] で [証明書とシークレット] を選択し、[新しいクライアント シークレット] を選択します。
説明を入力し、期間を選択し、[ 追加] を選択します。
[値] 列からシークレットをコピーします。次の手順で必要になります。
重要
このクライアント シークレットは今後表示されないため、この段階で必ずコピーするようにしてください。
注意
ユーザー認証に登録する手順とは異なり、このセクションではアプリの登録に対する Microsoft Graph のアクセス許可を構成したことに注意してください。 これは、アプリのみの認証で クライアント資格情報フローが使用されるため、アプリの登録でアクセス許可を構成する必要があるためです。 詳細については 、「.default スコープ 」を参照してください。
Java コンソール アプリを作成する
このセクションでは、基本的な Java コンソール アプリを作成します。
プロジェクトを作成するディレクトリでコマンド ライン インターフェイス (CLI) を開きます。 次のコマンドを実行して、新しい Gradle プロジェクトを作成します。
gradle init --dsl groovy --test-framework junit --type java-application --project-name graphapponlytutorial --package graphapponlytutorial
プロジェクトが作成されたら、次のコマンドを実行して CLI でアプリを実行して動作することを確認します。
./gradlew --console plain run
動作する場合、アプリは
Hello World.
を出力する必要があります。
依存関係のインストール
次に進む前に、後で使用するいくつかの依存関係を追加します。
- ユーザーを認証し、アクセス トークンを取得するための Java 用の Azure Identity クライアント ライブラリ。
- Microsoft Graph SDK for Java を使用して Microsoft Graph を呼び出します。
./app/build.gradle を開きます。
dependencies
セクションを更新して、これらの依存関係を追加します。dependencies { // Use JUnit test framework. testImplementation 'junit:junit:4.13.2' // This dependency is used by the application. implementation 'com.google.guava:guava:33.2.1-jre' implementation 'com.azure:azure-identity:1.13.0' implementation 'com.microsoft.graph:microsoft-graph:6.13.0' }
./app/build.gradle の末尾に次を追加します。
run { standardInput = System.in }
次回プロジェクトをビルドするときに、Gradle はこれらの依存関係をダウンロードします。
アプリケーション設定を読み込む
このセクションでは、アプリ登録の詳細をプロジェクトに追加します。
./app/src/main/resources ディレクトリに graphapponlytutorial という名前の新しいディレクトリを作成します。
oAuth.properties という名前の ./app/src/main/resources/graphapponlytutorial ディレクトリに新しいファイルを作成し、そのファイルに次のテキストを追加します。
app.clientId=YOUR_CLIENT_ID_HERE app.clientSecret=YOUR_CLIENT_SECRET_HERE app.tenantId=YOUR_TENANT_ID_HERE
次の表に従って値を更新します。
設定 値 app.clientId
アプリ登録のクライアント ID app.tenantId
組織のテナント ID app.clientSecret
クライアント シークレット 重要
git などのソース管理を使用している場合は、誤ってアプリ ID が漏洩しないように 、ソース管理から oAuth.properties ファイルを除外することをお勧めします。
アプリを設計する
このセクションでは、簡単なコンソール ベースのメニューを作成します。
./app/src/main/java/graphapponlytutorial/App.java を開き、次の
import
ステートメントを追加します。package graphapponlytutorial; import java.io.IOException; import java.util.InputMismatchException; import java.util.Properties; import java.util.Scanner; import com.microsoft.graph.models.User;
既存の
main
関数を、以下の関数で置き換えます。public static void main(String[] args) { System.out.println("Java App-Only Graph Tutorial"); System.out.println(); final Properties oAuthProperties = new Properties(); try { oAuthProperties.load(App.class.getResourceAsStream("oAuth.properties")); } catch (IOException e) { System.out.println("Unable to read OAuth configuration. Make sure you have a properly formatted oAuth.properties file. See README for details."); return; } initializeGraph(oAuthProperties); Scanner input = new Scanner(System.in); int choice = -1; while (choice != 0) { System.out.println("Please choose one of the following options:"); System.out.println("0. Exit"); System.out.println("1. Display access token"); System.out.println("2. List users"); System.out.println("3. Make a Graph call"); try { choice = input.nextInt(); } catch (InputMismatchException ex) { // Skip over non-integer input } input.nextLine(); // Process user choice switch(choice) { case 0: // Exit the program System.out.println("Goodbye..."); break; case 1: // Display access token displayAccessToken(); break; case 2: // List users listUsers(); break; case 3: // Run any Graph code makeGraphCall(); break; default: System.out.println("Invalid choice"); } } input.close(); }
ファイルの末尾に次のプレースホルダー メソッドを追加します。 後の手順で実装します。
private static void initializeGraph(Properties properties) { // TODO } private static void displayAccessToken() { // TODO } private static void listUsers() { // TODO } private static void makeGraphCall() { // TODO }
これにより、基本的なメニューが実装され、コマンド ラインからユーザーの選択が読み取ります。
- ./app/src/test/java/graphapponlytutorial/AppTest.javaを削除します。
アプリ専用認証を追加する
このセクションでは、アプリケーションにアプリのみの認証を追加します。 これは、Microsoft Graph を呼び出すために必要な OAuth アクセス トークンを取得するために必要です。 この手順では、 Java 用 Azure Identity クライアント ライブラリ をアプリケーションに統合し、 Microsoft Graph SDK for Java の認証を構成します。
アプリ専用認証用に Graph クライアントを構成する
このセクションでは、 ClientSecretCredential
クラスを使用して、 クライアント資格情報フローを使用してアクセス トークンを要求します。
Graph.java という名前の ./app/src/main/java/graphapponlytutorial ディレクトリに新しいファイルを作成し、そのファイルに次のコードを追加します。
package graphapponlytutorial; import java.util.Properties; import com.azure.core.credential.AccessToken; import com.azure.core.credential.TokenRequestContext; import com.azure.identity.ClientSecretCredential; import com.azure.identity.ClientSecretCredentialBuilder; import com.microsoft.graph.models.UserCollectionResponse; import com.microsoft.graph.serviceclient.GraphServiceClient;
空の Graph クラス定義を追加します。
public class Graph { }
Graph クラスに次のコードを追加します。
private static Properties _properties; private static ClientSecretCredential _clientSecretCredential; private static GraphServiceClient _appClient; public static void initializeGraphForAppOnlyAuth(Properties properties) throws Exception { // Ensure properties isn't null if (properties == null) { throw new Exception("Properties cannot be null"); } _properties = properties; if (_clientSecretCredential == null) { final String clientId = _properties.getProperty("app.clientId"); final String tenantId = _properties.getProperty("app.tenantId"); final String clientSecret = _properties.getProperty("app.clientSecret"); _clientSecretCredential = new ClientSecretCredentialBuilder() .clientId(clientId) .tenantId(tenantId) .clientSecret(clientSecret) .build(); } if (_appClient == null) { _appClient = new GraphServiceClient(_clientSecretCredential, new String[] { "https://graph.microsoft.com/.default" }); } }
App.javaの空の
initializeGraph
関数 を 次のように置き換えます。private static void initializeGraph(Properties properties) { try { Graph.initializeGraphForAppOnlyAuth(properties); } catch (Exception e) { System.out.println("Error initializing Graph for user auth"); System.out.println(e.getMessage()); } }
このコードでは、 ClientSecretCredential
オブジェクトと GraphServiceClient
オブジェクトの 2 つのプライベート プロパティを宣言します。
initializeGraphForAppOnlyAuth
関数は、ClientSecretCredential
の新しいインスタンスを作成し、そのインスタンスを使用してGraphServiceClient
の新しいインスタンスを作成します。
_appClient
を介して Microsoft Graph に API 呼び出しが行われるたびに、提供された資格情報を使用してアクセス トークンを取得します。
ClientSecretCredential をテストする
次に、 ClientSecretCredential
からアクセス トークンを取得するコードを追加します。
次の関数を
Graph
クラスに追加します。public static String getAppOnlyToken() throws Exception { // Ensure credential isn't null if (_clientSecretCredential == null) { throw new Exception("Graph has not been initialized for app-only auth"); } // Request the .default scope as required by app-only auth final String[] graphScopes = new String[] {"https://graph.microsoft.com/.default"}; final TokenRequestContext context = new TokenRequestContext(); context.addScopes(graphScopes); final AccessToken token = _clientSecretCredential.getToken(context).block(); return token.getToken(); }
App.javaの空の
displayAccessToken
関数 を 次のように置き換えます。private static void displayAccessToken() { try { final String accessToken = Graph.getAppOnlyToken(); System.out.println("Access token: " + accessToken); } catch (Exception e) { System.out.println("Error getting access token"); System.out.println(e.getMessage()); } }
アプリをビルドして実行します。 オプションの入力を求められたら、「
1
」と入力します。 アプリケーションにアクセス トークンが表示されます。Java App-Only Graph Tutorial Please choose one of the following options: 0. Exit 1. Display access token 2. List users 3. Make a Graph call 1 App-only token: eyJ0eXAiOiJKV1QiLCJub25jZSI6IlVDTzRYOWtKYlNLVjVkRzJGenJqd2xvVUcwWS...
ヒント
検証とデバッグ のみを目的として、 https://jwt.msで Microsoft のオンライン トークン パーサーを使用してユーザー アクセス トークンをデコードできます (職場または学校アカウントの場合のみ)。 これは、Microsoft Graph を呼び出すときにトークン エラーが発生した場合に役立ちます。 たとえば、トークン内の
scp
要求に、想定される Microsoft Graph アクセス許可スコープが含まれていることを確認します。
ユーザーを一覧表示する
このセクションでは、アプリのみの認証を使用して、Azure Active Directory 内のすべてのユーザーを一覧表示する機能を追加します。
Graph.javaを開き、Graph クラスに次の関数を追加します。
public static UserCollectionResponse getUsers() throws Exception { // Ensure client isn't null if (_appClient == null) { throw new Exception("Graph has not been initialized for app-only auth"); } return _appClient.users().get(requestConfig -> { requestConfig.queryParameters.select = new String[] { "displayName", "id", "mail" }; requestConfig.queryParameters.top = 25; requestConfig.queryParameters.orderby = new String[] { "displayName" }; }); }
App.javaの空の
listUsers
関数 を 次のように置き換えます。private static void listUsers() { try { final UserCollectionResponse users = Graph.getUsers(); // Output each user's details for (User user: users.getValue()) { System.out.println("User: " + user.getDisplayName()); System.out.println(" ID: " + user.getId()); System.out.println(" Email: " + user.getMail()); } final Boolean moreUsersAvailable = users.getOdataNextLink() != null; System.out.println("\nMore users available? " + moreUsersAvailable); } catch (Exception e) { System.out.println("Error getting users"); System.out.println(e.getMessage()); } }
アプリを実行し、サインインし、オプション 4 を選択してユーザーを一覧表示します。
Please choose one of the following options: 0. Exit 1. Display access token 2. List users 3. Make a Graph call 2 User: Adele Vance ID: 05fb57bf-2653-4396-846d-2f210a91d9cf Email: AdeleV@contoso.com User: Alex Wilber ID: a36fe267-a437-4d24-b39e-7344774d606c Email: AlexW@contoso.com User: Allan Deyoung ID: 54cebbaa-2c56-47ec-b878-c8ff309746b0 Email: AllanD@contoso.com User: Bianca Pisani ID: 9a7dcbd0-72f0-48a9-a9fa-03cd46641d49 Email: NO EMAIL User: Brian Johnson (TAILSPIN) ID: a8989e40-be57-4c2e-bf0b-7cdc471e9cc4 Email: BrianJ@contoso.com ... More users available? True
コードの説明
getUsers
関数のコードについて考えてみましょう。
コレクションへのアクセス
このメソッドは、ユーザーのコレクションを返します。 コレクションを返す Microsoft Graph のほとんどの API では、使用可能なすべての結果が 1 つの応答で返されるわけではありません。 代わりに、 ページングを 使用して結果の一部を返しながら、クライアントが次の "ページ" を要求するメソッドを提供します。
既定のページ サイズ
ページングを使用する API では、既定のページ サイズが実装されます。 ユーザーの場合、既定値は 10 です。 クライアントは、 $top クエリ パラメーターを使用して、より多く (またはそれ以下) を要求できます。
getUsers
では、これは要求構成の top
プロパティで実現されます。
注意
top
で設定される値は、明示的な数値ではなく、上限です。 API は、指定した値 まで 多数のユーザーを返します。
後続のページを取得する
サーバーで使用可能な結果が増える場合、コレクション応答には、次のページにアクセスするための API URL を含む @odata.nextLink
プロパティが含まれます。 Java クライアント ライブラリでは、これをコレクション応答オブジェクトの getOdataNextLink
メソッドとして公開します。 このメソッドが null 以外を返す場合は、使用可能な結果が増えます。
コレクションを並べ替える
関数は、要求構成で orderBy
プロパティを使用して、ユーザーの表示名で並べ替えられた結果を要求します。 これにより、 $orderby クエリ パラメーター が API 呼び出しに追加されます。
省略可能: 独自のコードを追加する
このセクションでは、独自の Microsoft Graph 機能をアプリケーションに追加します。 これは、Microsoft Graph ドキュメント または Graph エクスプローラーのコード スニペット、または作成したコードです。 このセクションは省略可能です。
アプリを更新する
Graph.javaを開き、Graph クラスに次の関数を追加します。
public static void makeGraphCall() { // INSERT YOUR CODE HERE }
App.javaの空の
MakeGraphCallAsync
関数 を 次のように置き換えます。private static void makeGraphCall() { try { Graph.makeGraphCall(); } catch (Exception e) { System.out.println("Error making Graph call"); System.out.println(e.getMessage()); } }
API を選択する
試したい API を Microsoft Graph で見つけます。 たとえば、 Create イベント API です。 API ドキュメントの例のいずれかを使用するか、Graph Explorer で API 要求をカスタマイズし、生成されたスニペットを使用できます。
アクセス許可を構成する
選択した API のリファレンス ドキュメントの [アクセス許可] セクションを確認して、サポートされている認証方法を確認します。 たとえば、一部の API では、アプリ専用アカウントや個人用 Microsoft アカウントがサポートされていません。
- ユーザー認証を使用して API を呼び出すには (API でユーザー (委任された) 認証がサポートされている場合)、 ユーザー (委任された) 認証 のチュートリアルを参照してください。
- アプリ専用認証を使用して API を呼び出すには (API でサポートされている場合)、Azure AD 管理センターに必要なアクセス許可スコープを追加します。
コードを追加する
コードを Graph.java の makeGraphCallAsync
関数にコピーします。 ドキュメントまたは Graph Explorer からスニペットをコピーする場合は、必ず GraphServiceClient
の名前を _appClient
に変更してください。
おめでとうございます。
Java Microsoft Graph チュートリアルを完了しました。 Microsoft Graph を呼び出す作業アプリが作成されたので、新しい機能を試して追加できます。
- Microsoft Graph Java SDK で ユーザー (委任された) 認証 を使用する方法について説明します。
- Microsoft Graph でアクセスできるすべてのデータについては、 Microsoft Graph の概要 に関するページを参照してください。
Java サンプル
このセクションに問題がある場合 このセクションを改善できるよう、フィードバックをお送りください。