認証コード

規格への参照

詳細については、OAuth パブリッククライアントによるコード交換の証明キー(英語)を参照してください。

前提条件

クライアント。

認証コード付与タイプは、機密クライアント向けに最適化されています。これはリダイレクトベースのフローであるため、クライアントはリソース所有者のユーザーエージェント（通常は Web ブラウザー）と対話でき、承認サーバーからの受信要求を（リダイレクトを使用して）受信できる必要があります。

クライアント service_ID

Hub のクライアントに関連付けられているサービスの ID。

クライアント service_secret

Hub のクライアントに関連付けられているサービスの秘密。

範囲

リソースサーバーに関連付けられた Hub サービスに登録されている ID のスペース区切りのリスト。例: クライアントが YouTrack の課題にアクセスしたい場合は、Hub の YouTrack サービスの ID を見つける必要があります。クライアントは、単一のアクセストークンで複数のリソースサーバーにアクセスできます。

クライアントの redirect_URI

承認サーバーからの応答を処理できるクライアントアプリケーションの URI。

code_verifier

最小長 43 文字、最大長 128 文字の、予約されていない文字 [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~" を使用する高エントロピー暗号化ランダム文字列。

クライアントは、OAuth 2.0 認証リクエストごとにコードベリファイアを作成します。

適切な乱数ジェネレーターの出力を使用して、32 オクテットのシーケンスを作成することをお勧めします。次に、オクテットシーケンスが base64url でエンコードされ、コードベリファイアとして使用する 43 オクテットの URL セーフ文字列が生成されます。詳細については、RFS7636 のセクション 4.1(英語) を参照してください。

code_challenge

コードチャレンジは、plain または S256 変換を使用して、クライアントによってコードベリファイアから導出されます。

plain :
code_challenge = code_verifier
S256 :
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

詳細は、RFS7636 のセクション 4.2(英語) を参照してください。

code_challenge_method

このパラメーターは、code_challenge の作成に使用される変換の型（plain または S256）を定義します。

詳細は、RFS7636 のセクション 4.2(英語) を参照してください。

Hub URL

Hub サーバーの URL。

状態

現在のアプリケーション状態の識別子。例: クライアントサービス内の現在のユーザーの場所に関する情報を含むローカルストレージオブジェクトのキーにすることができます。

request_credentials

ログインフォームをユーザーに表示するかどうかを制御するパラメーター。次の値が有効です。

skip — クライアントサービスが一般的に匿名アクセスを許可する場合は、このオプションを使用します。これは次のように機能します。
- ユーザーがすでに Hub にログインしている場合は、クライアントサービスへのアクセスを許可します。
- ユーザーが Hub にログインしておらず、ゲストアカウントが禁止されていない場合は、ゲストにクライアントサービスを許可します。
- ユーザーが Hub にログインしておらず、ゲストアカウントが禁止されている場合は、ログインフォームに移動します。
silent — skip と同じですが、戻ってきます。ゲストアカウントが禁止されている場合、このオプションは認証エラーでクライアントサービスに戻ります。
required — ユーザーをログアウトし、ログインフォームを表示します。このオプションは、クライアントサービスからログアウトするための応答として使用します。
default — クライアントサービスが匿名アクセスを許可しない場合は、このオプションを使用します。これは次のように機能します。
- ユーザーがすでに Hub にログインしている場合は、クライアントサービスへのアクセスを許可します。
- ユーザーが Hub にログインしていない場合は、ログインフォームに移動します。

access_type

ユーザーがオンラインでないときに、アプリケーションが Hub へのアクセスを必要とするかどうかを示します。許可される値: online （デフォルトで使用）および offline ユーザーがオンラインでないときにアプリケーションがアクセストークンのリフレッシュを必要とする場合は、offline 値を使用します。この場合、Hub は、ユーザーの認証コードを初めて交換するときに、アプリケーションのリフレッシュトークンを発行します。詳細については、リフレッシュトークンページを参照してください。

ユーザーを認証サーバーに送信する (Hub)

認証を開始するには、コードを次の形式で URL へのリダイレクト応答をブラウザーに送信する必要があります。

        ${Hub Service URL}/api/rest/oauth2/auth?response_type=code&state=${State}&redirect_uri=${Client redirect URI}&request_credentials=${Request credentials mode}&client_id=${Client service ID}&scope=${Scope}&access_type={online|offline}&code_challenge={code_challenge}&code_challenge_method={code_challenge_method}
    

このリクエストでは:

code_challenge - PKCE 拡張機能を使用する場合は必須
code_challenge_method - オプションで、リクエストに存在しない場合、デフォルトで「プレーン」になります。

例:

        https://hub.company.com/api/rest/oauth2/auth?response_type=code&state=9b8fdea0-fc3a-410c-9577-5dee1ae028da&redirect_uri=https%3A%2F%2Fmyservice.company.com%2Fauthorized&request_credentials=skip&client_id=98071167-004c-4ddf-ba37-5d4599fdf319&scope=0-0-0-0-0%2098071167-004c-4ddf-ba37-5d4599fdf319&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256
    

Hub にリフレッシュトークンを発行するように指示するには、access_type=offline パラメーターを要求に追加します。

        ${Hub Service URL}/api/rest/oauth2/auth?response_type=code&state=${State}&redirect_uri=${Client redirect URI}&request_credentials=${Request credentials mode}&client_id=${Client service ID}&scope=${Scope}&access_type=offline&code_challenge={code_challenge}&code_challenge_method={code_challenge_method}
    

承認サーバーからのリダイレクトバックの処理 (Hub)

リソース所有者がアクセス要求を許可すると、Hub は認証コードを発行し、"application/x-www-form-urlencoded" 形式を使用してリダイレクト URI のクエリコンポーネントに次のパラメーターを追加することにより、それをクライアントに配信します。

コード: 認証サーバーによって生成された認証コード。認証コードは、リークのリスクを軽減するために発行された直後に期限切れになります。クライアントは、認証コードを複数回使用してはなりません。認証コードが複数回使用されている場合、Hub は要求を拒否します。認証コードは、クライアント識別子とリダイレクト URI にバインドされています。
状態: 承認リクエストでクライアントから受け取った正確な値。

例: 認証サーバー（Hub）は、次の HTTP レスポンスを送信してユーザーエージェントをリダイレクトします。

        HTTP/1.1 302 Found
        Location: https://myservice.company.com/authorized?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz
    

クライアントは、認識されない応答パラメーターを無視する必要があります。

Hub からのエラー処理

リソース所有者がアクセス要求を拒否した場合、またはリダイレクト URI がないか無効である以外の理由で要求が失敗した場合、Hub は、「application/x-www-form-urlencoded」形式を使用してリダイレクト URI のクエリコンポーネントに次のパラメーターを追加することにより、クライアントに通知します。

エラー

以下からの単一の ASCII [USASCII] エラーコード:

invalid_request - リクエストに必要なパラメーターがない、無効なパラメーター値が含まれている、パラメーターが複数回含まれている、その他の形式が正しくない。
unauthorized_client - クライアントは、この方法を使用して認証コードを要求することを許可されていません。
access_denied - リソース所有者または Hub が要求を拒否しました。
unsupported_response_type Hub は、この方法を使用した認証コードの取得をサポートしていません。
invalid_scope 要求されたスコープが無効、不明、不正な形式です。
server_error Hub サーバーで予期しない状態が発生したため、要求を実行できませんでした。(500 Internal Server Error HTTP ステータスコードは HTTP リダイレクトを介してクライアントに返すことができないため、このエラーコードが必要です。)
temporarily_unavailable サーバーの一時的なオーバーロードまたは保守のため、許可サーバーは現在要求を処理できません。(このエラーコードが必要なのは、503 Service UnavailableHTTP ステータスコードを HTTP リダイレクト経由でクライアントに返すことができないためです。)

error_description

発生したエラーをクライアント開発者が理解するのを支援するために使用される、追加情報を提供する人間が読める ASCII [USASCII] テキスト。

error_uri

エラーに関する追加情報をクライアント開発者に提供するために使用される、エラーに関する情報を含む人間が読める Web ページを識別する URI。

状態

クライアント許可要求に「状態」パラメーターが存在する場合は必須です。クライアントから受け取った正確な値。

アクセストークンのコード交換

クライアントはコードを受信した後、それをアクセストークンと交換できます。

クライアントは、HTTP リクエストエンティティボディで UTF-8 の文字エンコードを使用して「application/x-www-form-urlencoded」形式を使用して次のパラメーターを送信することにより、Hub トークンエンドポイントにリクエストを送信します。

        POST /api/rest/oauth2/token
        Host: ${Hub Service URL}
        Accept: application/json
        Authorization: Basic ${base64(${Client service ID} + ":" + ${Client service secret})}
        Content-Type: application/x-www-form-urlencoded

        grant_type=authorization_code&code=${Code received on a previous step}&redirect_uri=${Client redirect URI}&code_verifier={code_verifier}
    

このリクエストでは:

code_verifier - PKCE 拡張機能を使用する場合は必須。
client_id - パブリッククライアント（信頼されていないサービス）に PKCE 拡張機能を使用する場合、および Auth Header が省略される場合は必須です。

例:

        POST /api/rest/oauth2/token
        Host: hub.company.com
        Accept: application/json
        Authorization: Basic OTgwNzExNjctMDA0Yy00ZGRmLWJhMzctNWQ0NTk5ZmRmMzE5OmVBVXlLZ1ZmaFNiVg0K
        Content-Type: application/x-www-form-urlencoded

        grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Fmyservice.company.com%2Fauthorized&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
    

アクセストークン応答の処理

アクセストークン要求が有効で承認されている場合、Hub はアクセストークンを発行します。要求クライアント認証が失敗したか無効である場合、Hub サーバーはエラー応答を返します。

成功した応答の例:

        HTTP/1.1 200 OK
        Content-Type: application/json;charset=UTF-8

        {
        "access_token":"1443459450185.0-0-0-0-0.98071167-004c-4ddf-ba37-5d4599fdf319.0-0-0-0-0%3B1.MCwCFC%2FYWvLjHdzOdpLleDLITJn4Mz9rAhRklCoZ2dlMkh2aCd1K5QQ89ibsxg%3D%3D
        "expires_in":3600,
        }
    

2026 年 6 月 13 日

YouTrack および Hub ヘルプの開発者ポータル