WP REST API のドキュメントの認証ページの翻訳

前回の用語集の翻訳に続きまして、認証のページも翻訳してみました。以下翻訳。

認証

このAPIにおいては、認証には2つの選択肢があり、基本的に以下のように選びましょう。

• そのサイトで有効化されたテーマやプラグインから利用する -> クッキー認証
• デスクトップアプリ、ウェブアプリ、モバイルアプリなどのサイトの外からアクセスするクライアントとして API を利用する -> OAuth 認証

クッキー認証

クッキー認証は、WordPress に含まれているベーシックな認証です。管理画面にログインするときには、この認証方法が利用されてログインする人のためのクッキーが正しく発行されます。なので、プラグインやテーマ開発者は必要とするのはログインしているユーザーのみとなります。

しかしながら、この REST API は CSRF の問題を解決するための nonce と呼ばれるテクニックを利用して、他のサイトがあなたに対して明示的に意図していない行動をとらせるということ（CSRF）を防いでいます。これがあるために、API 利用のためにちょっと特殊な操作が必要になります。

ビルトイン Javascript API を利用する開発者においては、自動的にハンドリングが行われます（ので簡単です）。プラグインやテーマによる API 利用の推奨された方法です。データモデルをカスタマイズする場合には、 wp.api.models.Base を継承することであらゆるカスタムリクエストで nonce が送信されることを保証することができます。

マニュアルで Ajax リクエストを送る場合には nonce は各リクエストで送信される必要があります。 API は nonce を wp_rest にセットされたアクションと一緒に利用します。API に nonce を渡すには、

• POST のデータとして _wpnonce 名で渡す
• GET のクエリパラメータとして、 _wpnonce 名で渡す
• X-WP-Nonce ヘッダーとして渡す

というふうにします。

重要な事は、これらの認証は WordPress のクッキーに依存しているということです。つまり、この方法が有効なのは、REST API が WordPress の内部で使われていて、かつ、ユーザーがログインしている時のみであるということです。さらに、そのログインユーザーが実行しようとしているアクションに必要な権限（Capability）を与えられているということも条件となります。

たとえば、以下は、ビルトインの Javascript クライアントが nonce を生成する方法です。

<?php 
wp_localize_script( 
 'wp-api', 
 'WP_API_Settings', 
 array( 
 'root' => esc_url_raw( rest_url() ), 
 'nonce' => wp_create_nonce( 'wp_rest' ) 
 ) 
);

で、ベースモデル(base model)の中で以下のように利用します。

options.beforeSend = function(xhr) {
  xhr.setRequestHeader('X-WP-Nonce', WP_API_Settings.nonce);

  if (beforeSend) {
    return beforeSend.apply(this, arguments);
  }
};

以下は、jQuery AJAX を使って投稿のタイトルを書き換える事例です。

$.ajax( {
  url: WP_API_Settings.root + 'wp/v2/posts/1',
  method: 'POST',
  beforeSend: function ( xhr ) {
    xhr.setRequestHeader( 'X-WP-Nonce', WP_API_Settings.nonce );
  },
  data:{
    'title' : 'Hello Moon'
  }
} ).done( function ( response ) {
  console.log( response );
} );

OAuth 認証

OAuth 認証は外部のクライアントのための認証ハンドラです。OAuth 認証では、ユーザーは通常の WordPress ログイン画面を通じてログインを行い、その後ユーザの代わりに処理を行うクライアントを認証します。クライアントには、OAuth トークンが発行され、クライアントがAPIにアクセスできるようになります。このアクセス権はユーザー側からいつでも取り消すことができます。

OAuth 認証は、OAuth 1.0a specification (published as RFC5849) を利用しており、OAuth plugin がサイトで有効化されていることが必要です（このプラグインは将来的にコアにマージされます）。

WP API と OAuth サーバー用のプラグインを有効化したら、コンシューマを作成します。コンシューマは、アプリケーションの識別子であり、サイトとリンクするために必要な key と secret からなります。

コンシューマの作成には、サーバで以下を実行します。

$ wp oauth1 add
ID: 9
Key: N6eGHfuYyI3L
Secret: rTeXmLRxxMBdhz1lntSi2PhA0KqbXtuVoQwN0r8IZnGmuoSD

ここの key と secret がそれで、これを認証プロセスで利用します。現状 UI は無いのですが、将来的に頑張ります。

これを利用するための事例としては、CLI client および、 API console がこの機能を利用しており、最初に見てみるといいでしょう。

ベーシック認証

ベーシック認証は、外部クライアントから利用できるもうひとつの認証です。OAuth 認証は複雑なので開発段階ではベーシック認証が便利です。ただし、ベーシック認証ではすべてのリクエストにおいてユーザー名とパスワードを送る必要があり、本番の環境で利用することは超非推奨です。

ベーシック認証は、 HTTP Basic Authentication (published as RFC2617) を利用しており Basic Auth plugin の有効化が必要です。

ベーシック認証の利用には、ユーザー名とパスワードを各リクエストの Authorization ヘッダーを通じて渡します。この値は、HTTP Basic 認証の仕様に従い、base64 でエンコードされるべきです。

以下は、WordPress のHTTP API を利用して、ベーシック認証による投稿の更新方法のサンプルです。

<?php 
$headers = array ( 'Authorization' => 'Basic ' . base64_encode( 'admin' . ':' . '12345' ), 
); 
$url = rest_url( 'wp/v2/posts/1' ); 

$body = array( 
 'title' => 'Hello Gaia' 
); 

$response = wp_remote_post( 
 $url, 
 array ( 
 'method' => 'POST', 
 'headers' => $headers, 
 'body' => $data 
 ) 
); 

(注: 最後の $data は $body なんじゃないか)