Crewcade でサインイン
クラブのメンバーは、Crewcade アカウントであなたのウェブサイトやアプリにサインインできます。Crewcade は、認可コードフローと PKCE を使う OAuth 2.1 を使います。OpenID Connect にも対応しています。
始める前に、Crewcade にアプリを追加します。連携アプリを見てください。クライアントIDが得られます。サーバーアプリにはクライアントシークレットもあります。
クラブを見つける
Section titled “クラブを見つける”クラブごとに、専用のサインインサーバーがあります。そのアドレスは Crewcade でコピーできます。
- 設定 を開き、開発者 を選びます。連携アプリ タブを開きます。
- アプリを探し、サインイン設定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 |
アドレスは、ディスカバリーの返事から読み取ります。手で組み立てないでください。
| スコープ | アプリにできること |
|---|---|
openid | IDトークンを得ます。メンバーには表示されません。 |
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 が返ります。
ステップ2: 答えを読む
Section titled “ステップ2: 答えを読む”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 です。
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トークン
Section titled “IDトークン”IDトークンは、RS256 で署名された JWT です。公開キーは jwks エンドポイントから得ます。トークンヘッダーの kid が、使うキーを示します。
| クレーム | 意味 |
|---|---|
iss | イシュアーです。 |
sub | メンバーIDです。 |
aud | あなたのクライアントIDです。 |
exp、iat | トークンが終わる時刻と始まる時刻です。 |
nonce | 送った場合の、あなたの nonce です。 |
auth_time | わかる場合の、サインインした時刻です。 |
署名、iss、aud、exp、nonce を確認してください。
メンバーとして API を呼ぶ
Section titled “メンバーとして API を呼ぶ”アクセストークンを Bearer トークンとして送ります。
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リクエストまで送れます。
ステップ4: 更新する
Section titled “ステップ4: 更新する”アクセストークンが切れたら、リフレッシュトークンを新しいトークンに交換します。
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 “サインアウト: トークンを取り消す”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_type | authorization_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ヘッダーの秒数だけ待ちます。