Azure API Management で提供している認証系機能の整理

Azure API Management (以下「APIM」)は、バックエンドの Web API とクライアントアプリの間に挟むことで、もろもろの便利な機能を提供する API プロキシサービスだ。 認証関連の機能も提供しているのだが、ドキュメントを読んでも初見だとちょっと紛らわしいところがあるので、簡単に解説する。

というのも、APIM 上で「認証」と名の付く機能は、以下のようにたくさんあり、適当なキーワードでググると、どれがどの用途なのか一見わかりづらい(と思う)。

# 機能の内容 認証される対象 サポートする形式 (参考)ドキュメント
1 アプリ開発者が、APIM の提供する管理画面にログインするための認証 APIM を使ってアプリ開発する開発者 Azure AD, APIM 独自認証 https://docs.microsoft.com/ja-jp/azure/api-management/api-management-howto-aad
2 アプリ開発者が、APIM の提供する開発者用画面で、バックエンド API にテストリクエストを送信するためにトークンを取得する機能 APIM を使ってアプリ開発する開発者 OAuth2.0, OpenID Connect https://docs.microsoft.com/ja-jp/azure/api-management/api-management-howto-oauth2
3 APIM が、APIM の裏にあるバックエンド API から認証してもらうための機能 APIM の管理者(≒1 の開発者の場合もある) Basic 認証、クライアント証明書 https://docs.microsoft.com/ja-jp/azure/api-management/api-management-authentication-policies
4 アプリ利用者が送ってきたリクエストに付いた JWT Token (*1) を検証する機能 APIM を使って作られたアプリのエンドユーザ OAuth2.0, OpenID Connect 等 https://docs.microsoft.com/ja-jp/azure/api-management/api-management-access-restriction-policies#ValidateJWT

(*1) JWT Token(読みは「じょっと とーくん」)とは、JSON 形式のクレーム情報を base64エンコードしたもので、OpenID Connect 等での認証に利用される。以下の記事が詳しい。

qiita.com

個人的には、API プロキシの提供する認証機能と聞いて期待するのは「クライアントアプリからのリクエストに正しい認証トークンが付いているかチェックしてくれる機能」だと思うが、それは上記の表だと 4 にあたる。

なお、最初よくわからなかったのが 2 なのだが、結局この機能は、APIM の開発者向け画面からテストリクエストを送ってみる際にしか使えない開発用機能なので要注意。

validate-jwt ポリシーの使い方

さて、1~3については、表中に示したドキュメントを見てもらうとして、肝心の 4 の使い方について簡単に説明しておく。

4 の機能は、validate-jwt というポリシーとして提供されている。 ポリシーというのは、API Management の API で受けたリクエストやレスポンスを、パイプラインのXMLな感じで加工したり、追加処理をしたりできる機能のことで、適用したいポリシーを XML で記述して利用する。

では validate-jwt ポリシーがどのような処理を行ってくれるかというと、リクエストのヘッダ(通常であれば Authorization ヘッダ)に含まれる JWT Token を復号化し、任意の条件を満たしているかチェックして、リクエストを通過させたり、拒否したりできるものだ。

Azure ポータルで APIM を開き、以下の画面でポリシーを編集する。

f:id:nosunosu:20180705125830p:plain

以下のポリシーを <inbound /> に追加すると、Azure AD の特定のテナントとアプリで認証されたユーザをすべて許可するルールとなる。

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">  
    <!-- 利用する認証基盤の OpenID 構成エンドポイントを指定 -->
    <!-- e.g.) Facebook の場合は https://facebook.com/.well-known/openid-configuration -->
    <openid-config url="https://login.microsoftonline.com/contoso.onmicrosoft.com/.well-known/openid-configuration" /> 

    <!-- 認証時に指定した Resource 名 --> 
    <audiences>
        <audience>https://graph.microsoft.com</audience>
    </audiences>
</validate-jwt>  

Azure AD で特定のグループに所属していることをチェックして、簡易的な認可を行うこともできる。

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">  
    <openid-config url="https://login.microsoftonline.com/contoso.onmicrosoft.com/.well-known/openid-configuration" /> 
    <audiences>
        <audience>https://graph.microsoft.com</audience>
    </audiences>

    <required-claims>
        <claim name="groups" match="any">
            <!-- 許可するグループの ID を指定 -->
            <value>xxxx-xxxx-xxxx-xxxxxxxxx</value>
        </claim>
    </required-claims>
</validate-jwt>  

なお、デフォルトでは JWT Token にグループの情報は含まれないため、事前に Azure AD のアプリ登録画面のマニフェストで、"groupMembershipClaims": "SecurityGroup" などに変更しておく必要がある。

stackoverflow.com

以下のドキュメントにも validate-jwt を使ったポリシーのサンプルが記載されているので、利用する際には目を通してみると良い。

docs.microsoft.com

docs.microsoft.com