コンテンツにスキップ

Crewcade でサインイン

クラブのメンバーは、Crewcade アカウントであなたのウェブサイトやアプリにサインインできます。Crewcade は、認可コードフローと PKCE を使う OAuth 2.1 を使います。OpenID Connect にも対応しています。

始める前に、Crewcade にアプリを追加します。連携アプリを見てください。クライアントIDが得られます。サーバーアプリにはクライアントシークレットもあります。

クラブごとに、専用のサインインサーバーがあります。そのアドレスは Crewcade でコピーできます。

  1. 設定 を開き、開発者 を選びます。連携アプリ タブを開きます。
  2. アプリを探し、サインイン設定URL の横の コピー をクリックします。

これがディスカバリーのアドレスです。すべてのエンドポイントが載っています。次のような形です。

https://api.crewcade.com/api/oauth/w/k3m9x2pq4r7t/.well-known/openid-configuration

イシュアーは、このアドレスから /.well-known/openid-configuration を除いたものです。

https://api.crewcade.com/api/oauth/w/k3m9x2pq4r7t

ディスカバリーの返事に、次のエンドポイントが入っています。

エンドポイント場所
認可クラブ自身のアドレスの /api/oauth/authorize
トークン{issuer}/token
取り消し{issuer}/revoke
ユーザー情報{issuer}/userinfo
署名キー{issuer}/jwks

アドレスは、ディスカバリーの返事から読み取ります。手で組み立てないでください。

スコープアプリにできること
openidIDトークンを得ます。メンバーには表示されません。
profileメンバーの名前と写真を見ます。
emailメンバーのメールアドレスを見ます。
registrationsメンバーのイベントを見ます。無料のイベントに申し込ませたり、無料の申し込みをキャンセルしたりします。
peopleメンバーが参加するイベントの参加者を見ます。

scope パラメーターに、スペースで区切って入れます。未知のスコープは invalid_scope エラーになります。

ステップ1: メンバーを Crewcade に送る

Section titled “ステップ1: メンバーを Crewcade に送る”

43文字から128文字のランダムな code_verifier を作ります。文字、数字、記号 -._~ が使えます。次に code_challenge を作ります。verifier の SHA-256 ハッシュを base64url で書いたものです。

メンバーのブラウザーで、次のアドレスを開きます。ディスカバリーの認可エンドポイントを使います。

パラメーター必須意味
response_typeはい常に code です。
client_idはいあなたのクライアントIDです。
redirect_uriはい戻り先URLの1つです。完全に一致する必要があります。
scopeはい必要なスコープです。
code_challengeはいPKCE のチャレンジです。
code_challenge_methodはい常に S256 です。plain は使えません。
stateいいえランダムな値です。Crewcade が返します。必ず確認します。
nonceいいえランダムな値です。IDトークンに入ります。
promptいいえconsent は常に画面を出します。none は画面を出しません。

各パラメーターは1回だけ送ります。未知のパラメーターは無視されます。同じパラメーターを2回送るとエラーです。

https://yourclub.crewcade.com/api/oauth/authorize?response_type=code&client_id=cca_your_client_id&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&scope=openid%20profile%20email&code_challenge=YOUR_CHALLENGE&code_challenge_method=S256&state=YOUR_STATE

メンバーはクラブのページでサインインします。パスワード、Google、LINE、6桁のメールコードが使えます。次に、アプリにできることの一覧を見ます。メンバーは 許可する または キャンセル を押します。アプリがパスワードを見ることはありません。Crewcade はメンバーの選択を覚えます。

アプリは、あとから registrations と people を求めることができます。すでにアプリを許可したメンバーには、新しい権限だけが表示されます。前の権限をもう一度許可する必要はありません。

prompt=none のとき、メンバーに画面は出ません。メンバーがまだアプリを許可していなければ、consent_required が返ります。

Crewcade はメンバーを戻り先URLに送ります。

成功すると、アドレスに code、state、iss が入ります。state が送った値と同じか確認します。iss がイシュアーか確認します。

問題があると、アドレスに error、state、iss が入ります。メンバーが キャンセル を押すと、エラーは access_denied です。

client_id が未知のとき、または redirect_uri が一致しないときは、Crewcade が自分のエラー画面を出します。メンバーはアプリに送られません。

コードの有効期間は60秒です。使えるのは1回だけです。

ステップ3: コードをトークンに交換する

Section titled “ステップ3: コードをトークンに交換する”

トークンエンドポイントに POST を送ります。形式は application/x-www-form-urlencoded です。

Terminal window
curl https://api.crewcade.com/api/oauth/w/k3m9x2pq4r7t/token \
-d grant_type=authorization_code \
-d code=THE_CODE \
-d redirect_uri=https://app.example.com/callback \
-d client_id=cca_your_client_id \
-d code_verifier=YOUR_VERIFIER

サーバーアプリは、自分が誰かも証明する必要があります。シークレットは2つの方法で送れます。

  • クライアントIDとシークレットを使う Authorization: Basic(client_secret_basic)。
  • フォーム項目の client_id と client_secret(client_secret_post)。

ウェブサイトやモバイルアプリは、シークレットを送りません。証明は code_verifier です。

返事は次のとおりです。

{
"access_token": "ccm_...",
"token_type": "Bearer",
"expires_in": 900,
"refresh_token": "ccr_...",
"scope": "openid profile email",
"id_token": "eyJ..."
}
  • アクセストークンの有効期間は15分(900秒)です。
  • リフレッシュトークンの有効期間は30日です。
  • id_token は openid を求めたときだけ返ります。
  • アクセストークンはランダムな文字列です。JWT ではありません。中身は読まないでください。

IDトークンは、RS256 で署名された JWT です。公開キーは jwks エンドポイントから得ます。トークンヘッダーの kid が、使うキーを示します。

クレーム意味
issイシュアーです。
subメンバーIDです。
audあなたのクライアントIDです。
exp、iatトークンが終わる時刻と始まる時刻です。
nonce送った場合の、あなたの nonce です。
auth_timeわかる場合の、サインインした時刻です。

署名、iss、aud、exp、nonce を確認してください。

アクセストークンを Bearer トークンとして送ります。

Terminal window
curl https://api.crewcade.com/api/v1/me \
-H "Authorization: Bearer ccm_your_access_token"

呼べるのは GET /v1/me、GET /v1/workspace、イベントのエンドポイントです。自分とクラブとイベントを見てください。registrations スコープがあれば、申し込みのエンドポイントも呼べます。people スコープがあれば、出会う人を呼べます。userinfo エンドポイントは GET /v1/me と同じデータを返します。メンバートークンでは、メンバーのエンドポイントと GET /v1/events/{id}/registrations は呼べません。

メンバーとアプリの組ごとに、1分あたり60リクエストまで送れます。

アクセストークンが切れたら、リフレッシュトークンを新しいトークンに交換します。

Terminal window
curl https://api.crewcade.com/api/oauth/w/k3m9x2pq4r7t/token \
-d grant_type=refresh_token \
-d refresh_token=ccr_your_refresh_token \
-d client_id=cca_your_client_id

更新のたびに、新しいリフレッシュトークンが返ります。古いものは使えなくなります。必ず新しいものを保存してください。

古いリフレッシュトークンをもう一度使うと、Crewcade はそのメンバーを、あなたのアプリのすべての場所からログアウトします。メンバーはもう一度サインインします。トークンが漏れたときに、メンバーを守るためです。

更新のときは、スコープを減らして求めることもできます。増やすことはできません。

サインアウト: トークンを取り消す

Section titled “サインアウト: トークンを取り消す”
Terminal window
curl https://api.crewcade.com/api/oauth/w/k3m9x2pq4r7t/revoke \
-d token=ccr_your_refresh_token \
-d client_id=cca_your_client_id

返事は常に 200 です。リフレッシュトークンを取り消すと、一緒に出たトークンも終わります。

メンバーがアクセスを失うとき

Section titled “メンバーがアクセスを失うとき”

次のときは、すぐにアクセスが止まります。

  • メンバーがあなたのアプリの接続を解除したとき。
  • メンバーが停止されたとき、またはクラブを退会したとき。
  • メンバーのアカウントが削除されたとき、またはブロックされたとき。
  • アプリをオフにしたとき、または削除したとき。
  • クライアントシークレットを入れ替えたとき。

ブラウザーアプリとサーバーアプリ

Section titled “ブラウザーアプリとサーバーアプリ”
  • ウェブサイトまたはモバイルアプリ は、パブリッククライアントです。シークレットはありません。PKCE が守ります。
  • サーバーアプリ は、機密クライアントです。シークレットをサーバーに置きます。

ブラウザーアプリは、戻り先URLのオリジンから、トークンエンドポイントと /v1 を呼べます。これらの呼び出しでクッキーは送られません。

トークンのエラーは RFC 6749 に従います。返事は error と error_description を持つ JSON です。

エラー意味
invalid_requestパラメーターがないか、間違っています。
invalid_clientクライアントIDかシークレットが間違っています。サーバーアプリは必ずシークレットを送ります。
invalid_grantコードかリフレッシュトークンが間違い、使用済み、期限切れ、または取り消し済みです。verifier か redirect_uri が一致しません。
unsupported_grant_typeauthorization_code か refresh_token だけを使います。
invalid_scopeスコープが未知です。またはメンバーが許可した以上を求めています。
temporarily_unavailable今はサインインできません。後でもう一度試してください。

コードを2回使うと、Crewcade は拒否します。1回目で出たトークンも取り消します。

不正なトークンで /v1 を呼ぶと、401 と invalid_token が返ります。スコープが足りないと、403 と insufficient_scope が返ります。

  • トークンエンドポイントは、クライアントごとに1分あたり120リクエストまでです。
  • トークンエンドポイントは、IPアドレスごとに1分あたり30リクエストまでです。
  • 速すぎると 429 が返ります。Retry-After ヘッダーの秒数だけ待ちます。