Microsoft 認証ライブラリを使用して API へのアクセスを承認する

5 分

会社のユーザーを Web アプリケーションにサインインさせることができるようになりました。次に、従業員のプロファイルから役職や仕事用メールアドレスなどの情報をページに表示する必要があります。ユーザー関連のデータには、Microsoft Graph API を使用してアクセスできます。

このユニットでは、Microsoft Graph API などの Microsoft サービスへの認可済みアクセスを取得するために MSAL がどのように役に立つのかを学習します。

API のアクセス許可とスコープ

Microsoft Entra ID によってセキュリティ保護された Web サービスで定義されているアクセス許可のセットを使うことで、そのサービスが公開する API 機能とデータにアクセスできます。アプリケーションでユーザーや管理者にこれらのアクセス許可を要求することができ、ユーザーや管理者が要求を承認してからでないと、アプリケーションはデータにアクセスしたり、ユーザーの代理として動作したりできません。たとえば、Microsoft Graph では、特に次のタスクを実行するアクセス許可が定義されています。

ユーザーの予定表の読み取り
ユーザーの予定表への書き込み
ユーザーとしてのメールの送信

ユーザーや管理者は、アプリケーションでアクセスできるデータを制御したり把握したりできます。 Microsoft によってセキュリティ保護された API にアプリケーションでアクセスするには、その前に、アクションを実行するためのアクセス許可をアプリケーションに付与する必要があります。

Microsoft Entra ID では、委任されたアクセス許可とアプリケーションのアクセス許可という 2 種類のアクセス許可がサポートされています。

委任されたアクセス許可は、サインインしているユーザーが存在するアプリで使用されます。これらのアプリでは、アプリが要求するアクセス許可にユーザーまたは管理者が同意します。アプリは、ターゲット API への呼び出しを行うときに、サインインしているユーザーとして動作するためのアクセス許可を委任されます。一部の高い特権のアクセス許可には、管理者の同意が必要です。
アプリケーションのアクセス許可は、サインインしているユーザーが存在しない状態で実行されるアプリ (バックグラウンドサービスまたはデーモンとして実行されるアプリなど) で使用されます。アプリケーションのアクセス許可に同意できるのは管理者だけです。

これらの API アクセス許可は、Azure portal でアプリの登録に割り当ることができます。

スコープ

Microsoft Entra ID に実装されている OAuth 2.0 認可プロトコルをアプリケーションで使用することにより、Web でホストされるリソースにユーザーに代わってアクセスできます。

OAuth 2.0 では、これらの種類のアクセス許可セットは "スコープ" と呼ばれます。アプリケーションで Microsoft Entra ID に対する認可要求を行うときは、要求の scope クエリパラメーターでアクセス許可を指定することにより、必要なアクセス許可を要求します。たとえば、Microsoft Graph でユーザーの予定表を読み取るためのアクセス許可を要求するには、スコープ値 https://graph.microsoft.com/Calendars.Read を使用します。

MSAL でアクセストークンを取得する

クライアントアプリケーションでアクセストークンを使用することにより、Microsoft Entra ID でセキュリティ保護された Web API を安全に呼び出すことができます。 Microsoft 認証ライブラリ (MSAL) を使用してアクセストークンを取得するには、複数の方法があります。一般に、トークンを取得するために使用される方法は、アプリケーションがパブリッククライアントアプリケーション (デスクトップアプリまたはモバイルアプリ) か、機密クライアントアプリケーション (Web アプリ、Web API、またはデーモンアプリケーション) かによって異なります。

MSAL のトークン取得メソッドのいくつかは、scopes パラメーターが必要です。これは、必要なアクセス許可と要求するリソースが宣言されている文字列の一覧です。

Web アプリに推奨される呼び出しパターン

MSAL では、トークンは取得された後でキャッシュされます。 OpenID Connect 承認コードフローが使用される Web アプリケーションの場合、コントローラーで推奨されるパターンは次のとおりです。

他の手段でトークンの取得を試みる前に、まず、キャッシュからのトークンの自動取得を試みる必要があります。次のコードは、AuthHelper クラスの acquireTokenSilently メソッドの実装からの抜粋です。

final SilentParameters parameters = SilentParameters
                                        .builder(Collections.singleton(Config.SCOPES), context.getAccount())
                                        .build();

final ConfidentialClientApplication client = getConfidentialClientInstance();

client.tokenCache().deserialize(context.getTokenCache());

final IAuthenticationResult result = client.acquireTokenSilently(parameters).get();

キャッシュ内にトークンがなく、サイレントでのトークン要求によるトークンの取得が失敗した場合は、認可コードフローを使ってトークンを取得できます。

final AuthorizationCodeParameters authParams = AuthorizationCodeParameters
                                                    .builder(authCode, new URI(Config.REDIRECT_URI)).scopes(Collections.singleton(Config.SCOPES))
                                                    .build();

final IAuthenticationResult result = app.acquireToken(authParams).get();

また、期限切れが近いトークンを MSAL で更新することもできます (トークンキャッシュには更新トークンも含まれるため)。

認証の結果

クライアントがアクセストークンを要求すると、Microsoft Entra ID はアクセストークンに関するメタデータを含む認証結果も返します。このデータを使用すると、アプリはアクセストークン自体を解析しなくても、そのアクセストークンのインテリジェントなキャッシュを実行できます。 AuthenticationResult MSAL からは次のものが返されます。

Web API のアクセストークン。
ユーザーの ID トークン (JWT)。
トークンの有効期限。トークンの有効期限が切れる日付と時刻を示します。
テナント ID には、ユーザーが見つかったテナントが含まれています。
トークンが発行されたスコープ。
ユーザーの一意の ID。

Microsoft Graph の概要

Microsoft Graph API の単一のエンドポイント https://graph.microsoft.com により、Microsoft クラウド内の豊富なユーザー中心のデータと分析情報へのアクセスが提供されます。 REST API または SDK を使用してエンドポイントにアクセスし、生産性、コラボレーション、教育、人と職場のインテリジェンスなどを対象とする Microsoft 365 のシナリオをサポートするアプリをビルドできます。 Microsoft Graph には、ユーザーとデバイスの ID を管理する強力なサービスのセットも含まれています。

たとえば、https://graph.microsoft.com/v1.0/me エンドポイントにアクセスすることで、サインインしているユーザーのプロパティを読み取ることができます。