Google Apps の Directory API にてWebブラウザを介さずに認証する

こんにちは、伊藤です。
この記事は TECHSCORE Advent Calendar 2015 の 12日目の記事です。

Google Appsでユーザやグループといった情報をソフトウェアから操作したいときは、Google Admin SDK の Directory API を使います。昔はこのような用途のために Provisioning API なるものが提供されていたのですが、Google Admin SDKの提供とともに非推奨となり、今年の4月に正式に Provisioning API をはじめとする古いAPIは廃止されました（参照 → Apps アップデートブログ: 廃止予定の Google Apps 管理 API は 2015 年 4 月にサポート終了）。

そして、これら古いAPIの終了とともに、認証方式はOAuth2.0に統一されることになりました。今、ネット上でDirectory APIを使ったサンプルを軽く検索してみると、Webブラウザを介してOAuth認証してAPIを利用する例がいろいろと出てきます。

もちろん、これはこれでいいのですが、Google Appsの情報を扱うちょっと凝ったシステムを作ろうとすると、システムを利用するユーザの権限をベースにWebブラウザを介して都度認証を行うこの方式では足りないケースが出てきます。たとえば、一般ユーザの操作をきっかけにバックグラウンドでメーリングリストを更新するといった機能を作ろうとしたときに。

ところが、ちょっとニーズが少なそうなことをやるために調べだすと途端に日本語の情報が少なかったり古かったりするというのは「Google技術あるある」だと個人的には思っているのですが、このDirectory APIでの認証の話もまさにそれで、バックグラウンドでの自動処理等で認証するにはどうしたらいいのかという課題を解決するのに思いのほか手間取ってしまいました。

まぁ、どうやればいいかは英語の公式ドキュメントの中にずばり書いてあるので、ちゃんとドキュメント読めよという結論になってしまうのですが、世の中、日本語と遜色ないレベルで英語が読めるエンジニアばかりではないんです（逆ギレ）。というわけで、私と同じニーズと課題を抱えている人向けに（いるのか？）、ポイントを書いておこうと思います。

いきなりですがこれが正解

どうすればいいかは、公式ドキュメントの「Perform Google Apps Domain-Wide Delegation of Authority」というページに書いてあります。このページおよびそこからのリンク先の情報で、ほぼ問題なく目的を果たせるでしょう。

なお、手っ取り早くサンプルコードを手に入れようと QuickStarts(Java) を見に行ったり、勘違いしてJavaのクライアントライブラリの Batch の項目を見に行ったりすると、認証時にWebブラウザが立ち上がるコードを手に入れてしまうことになりますのでご注意ください。

ちなみに、API Client Library for Javaのドキュメントの中には、権限のあるユーザのIDとパスワードを使って認証する ClientLoginに関する記述が残っていますが、この認証方式はもう利用できなくなっていて使えませんのでお気を付けください。もちろん、仮に利用できたとしても、システムのコード内にアカウントのIDとパスワードを持つというのはデメリットが大きいですしね。

話はここで終わりともいえるのですが、念のため、ここから先の手順の要点だけを記載しておきます。

Google Developers Consoleにて事前準備

まず、Google Developers Consoleにアクセスして、既存の適切なProjectを選択するか、新たにProjectを作成します。

次に、そのプロジェクトのAPI管理画面でAdmin SDKのAPIを有効にします。

最後に、プロジェクトの認証情報の画面からサービスアカウント（およびそのキー）を追加します。ここで生成されるキーや情報が後で必要になります。

Google Apps Admin Consoleにて事前準備

前節で作ったサービスアカウントに対し、操作対象となるGoogle Appsの権限を付与します。

具体的には、まず、Google Apps Admin Consoleにアクセスし、セキュリティの画面からAPIアクセスを有効にします。

次に、セキュリティ内の認証の欄から「API クライアントアクセスを管理する」を選択し、そこで表示されるページで、先ほど作ったサービスアカウントとそのサービスアカウントに許可する権限を登録します。

ここまで来たら、事前準備完了です。

Google APIs client libraryを使ってAPIを呼ぶ

あとは、使う言語に合わせたGoogle APIs Client Libraryを使って、必要なAPIを呼ぶコードを書けばいいです。このとき、サービスアカウントとそのキーが必要となります。以下は、新規にグループを作るJavaのサンプルコードの抜粋です。

HttpTransport httpTransport = new UrlFetchTransport();
JacksonFactory jsonFactory = new JacksonFactory();
GoogleCredential credential =
    new GoogleCredential.Builder()
        .setTransport(httpTransport)
        .setJsonFactory(jsonFactory)
        .setServiceAccountId(SERVICE_ACCOUNT_EMAIL)
        .setServiceAccountScopes(
            Arrays.asList(
                new String[] {
                    DirectoryScopes.ADMIN_DIRECTORY_GROUP,
                    DirectoryScopes.ADMIN_DIRECTORY_GROUP_MEMBER }))
        .setServiceAccountUser(SERVICE_ACCOUNT_USER)
        .setServiceAccountPrivateKeyFromP12File(
            new java.io.File(SERVICE_ACCOUNT_KEY_PATH))
        .build();
Directory directory =
    new Directory.Builder(httpTransport, jsonFactory, null)
        .setApplicationName(APPLICATION_NAME)
        .setHttpRequestInitializer(credential)
        .build();

Group group = new Group();
group.setEmail("test@example.com").setName("testGroup").setDescription("TEST Group.");
directory.groups().insert(group).execute();

HttpTransport httpTransport = new UrlFetchTransport();

JacksonFactory jsonFactory = new JacksonFactory();

GoogleCredential credential =

new GoogleCredential.Builder()

.setTransport(httpTransport)

.setJsonFactory(jsonFactory)

.setServiceAccountId(SERVICE_ACCOUNT_EMAIL)

.setServiceAccountScopes(

Arrays.asList(

new String[] {

DirectoryScopes.ADMIN_DIRECTORY_GROUP,

DirectoryScopes.ADMIN_DIRECTORY_GROUP_MEMBER }))

.setServiceAccountUser(SERVICE_ACCOUNT_USER)

.setServiceAccountPrivateKeyFromP12File(

new java.io.File(SERVICE_ACCOUNT_KEY_PATH))

.build();

Directory directory =

new Directory.Builder(httpTransport, jsonFactory, null)

.setApplicationName(APPLICATION_NAME)

.setHttpRequestInitializer(credential)

.build();

Group group = new Group();

group.setEmail("[email protected]").setName("testGroup").setDescription("TEST Group.");

directory.groups().insert(group).execute();

おわりに

というわけで、知ってしまえばなんてこともない話ですが、急いでいるときに限って回り道してしまうこともあるものです。日本のどこかにいるかも知れない、同じように困っている人の助けになれば幸いです。