認証と認可

ユーザーの認証はサイボウズ Live のアカウントのみ有効です。OpenID のようなサードパーティのアカウントで認証することはできません。 認可には OAuth を使います。OAuth については RFC 5849 を確認してください。 必要に応じて コミュニティの仕様 も確認してください。 インストールして利用する種類のクライアントアプリケーションでは、認可に xAuth も使えます。

この文書では次の三つの用語を確認してください。

  • サービスプロバイダー : サイボウズ Live のことです。認可のステップにおいて次の三つのエンドポイントを提供します。
    • https://api.cybozulive.com/oauth/initiate : 一時トークンを取得するためのエンドポイントです。
    • https://api.cybozulive.com/oauth/authorize : リソースオーナーに認可を要求する画面を表示するエンドポイントです。
    • https://api.cybozulive.com/oauth/token : リソースオーナーのアクセストークンを取得するためのエンドポイントです。
  • コンシューマー : 作成するアプリケーションです。

  • リソースオーナー : アカウントを持つユーザーのことです。リソースとはスケジュールの各イベントや、個別のチャットのことです。

OAuth の場合

OAuth ではコンシューマーの認証とリソースオーナーからの認可がありますので、いくつかのステップを経ることになります。 リソースオーナーの認証情報であるアクセストークンを取得することが目標となります。 いずれのステップでもシークレットを外部に送り出さないでください。当サービスからこれらの情報を問い合わせることもありません。

なお、アプリケーションの認証情報をコンシューマートークン、ユーザーの認証情報をアクセストークンと呼びます。 トークンはキーとシークレットのペアからなります。通常の認証で使うアカウント名とパスワードのペアのようなものです。 例えば次のような文字列です。

項目名 データの例
コンシューマートークン・キー 908830ad3b5ab839682dd6a667939ece9ece60
コンシューマートークン・シークレット 1ff82e592c3179701757883669871ebce9b8d75
アクセストークン・キー d34ffc83f9ceda30a147589c6bd963e5
アクセストークン・シークレット 1378ee668adfd78c52700d564edbe585

コンシューマーがリソースオーナーの認可を経てアクセストークンを取得するまでのステップは次のようになります。

  1. コンシューマーはコンシューマートークンに署名して、一時トークンを取得するためのエンドポイントにリクエストを発行します。

    データが有効である場合には一時トークンのキーとシークレットのペアが返されます。無効の場合にはエラーメッセージが返されますので確認してください。 一時トークンの有効期限は 10分間 です。この時間内に認可のプロセスが最後まで終了しなかった場合は、初めからもう一度やり直してください。 なお、サービスプロバイダーで利用可能な署名形式は HMAC-SHA1 のみです。署名方法の詳細は OAuth の仕様を参照してください。

  2. 一時トークンを使用して認可を要求するページへリソースオーナーをリダイレクトさせます。

    リソースオーナーがコンシューマーからのアクセスを許可すると、サービスプロバイダーは指定されたコールバック URL へリソースオーナーを転送します。 転送時に確認コードも送信します。 コールバック URL が設定されていない場合は確認コードを表示しますので、リソースオーナーが手動でコンシューマーにそのコードを入力します。

  3. コンシューマーはコンシューマートークン、一時トークン、確認コードに署名して、アクセストークンを取得するためのエンドポイントにリクエストを発行します。

    データが有効である場合にはアクセストークンのキーとシークレットのペアが返されます。 今のところ、アクセストークンに有効期限はありません。リソースオーナーが明示的にコンシューマーを無効化しない限り、アクセストークンは有効です。 外部に漏えいしないように注意してください。

データ API を利用するためにはコンシューマートークンとアクセストークンを使います。 消失しないようにトークンはコンシューマーが保管してください。

xAuth の場合

ユーザーが明示的に端末にインストールして使うアプリケーションの場合は、xAuth を使って認証ステップを省略できます。 アクセストークンを取得するためのエンドポイント (https://api.cybozulive.com/oauth/token) に、OAuth で必要な署名情報と 以下のパラメータを POST してください。ユーザーのパスワードを送信しますので、プロトコルは必ず https:// を使ってください。

  • x_auth_username : サイボウズ Live のユーザー名です
  • x_auth_password : サイボウズ Live のパスワードです
  • x_auth_mode : 値は client_auth のみ有効です。

認証に成功するとアクセストークンが返されます。アクセストークンはコンシューマーが保管してください。

エラーコード

レスポンスの形式は全てパーセント・エンコードで返します。XML 形式などの拡張レスポンスには対応していません。 エラーを識別する文字列は oauth_problem に 設定されています。HTTP ステータスコードは 400 番台と 500 番台を使います。

oauth_problem Status Code 状態および対応策
version_rejected 400 バージョン情報が不正です。”1.0” のみ有効です。
parameter_absent 400 パラメータが不足しています。不足しているパラメータを補ってから再度レスポンスを発行してください。
parameter_rejected 400 パラメータが拒否されました。メッセージ内容を再確認してください。
timestamp_refused 400 時刻の指定が不正です。コンピュータの時刻を確認してください。
nonce_used 400 NONCE が使用済みです。適当な文字列を再度生成してください。
signature_method_rejected 400 署名方法が拒否されました。”HMAC-SHA1” のみ有効です。
signature_invalid 401 署名の値が不正です。エラーメッセージの内容を確認して、再度生成してください。
consumer_key_unknown 401 コンシューマートークン・キーが未登録です。初めにコンシューマーを登録してください。
consumer_key_rejected 401 コンシューマートークン・キーが不正です。エラーメッセージの内容を確認してください。
token_used 401 一時トークンが使用済みです。認証ステップを初めからやり直してください。
token_expired 401 一時トークンが期限切れです。認証ステップを初めからやり直してください。
token_revoked 401 トークンが不正です。エラーメッセージの内容を確認してください。
token_rejected 401 トークンが拒否されました。エラーメッセージの内容を確認してください。
additional_authorization_required 401 追加の認証情報が必要です。メッセージ内容を再確認してください。
permission_unknown 401 権限情報が見つかりません。エラーメッセージの内容を確認してください。
permission_denied 401 権限情報が拒否されました。エラーメッセージの内容を確認してください。
invalid_account 401 ユーザー名もしくはパスワードが間違っています。
locked_account 401 アカウントがロックされています。ロック解除URLにアクセスするか、時間をおいてから実施してください。
consumer_key_refused 503 コンシューマートークン・キーが不正です。エラーメッセージの内容を確認してください。
user_refused 503 ユーザーが拒否されました。エラーメッセージの内容を確認してください。

その他、アプリケーションが使用停止状態になっている場合はリクエストを拒否します。 レスポンスの oauth_problem_advice に “application_is_not_active” や “application_is_stopped” が設定されている場合には注意してください。