Azure DevOps OAuth 2.0 を使用して Web アプリを作成する

Azure DevOps Services

Azure DevOps は、OAuth 2.0 アプリの ID プロバイダーです。 OAuth 2.0 の実装により、開発者はユーザーのアプリを承認し、Azure DevOps リソースのアクセス トークンを取得できます。

Azure DevOps OAuth の概要

1. アプリを登録する

1. https://app.vsaex.visualstudio.com/app/registerに移動してアプリを登録します。

2. アプリケーションに必要な スコープ を選択し、アプリの認証を するときに同じスコープを使用します。 プレビュー API を使用してアプリを登録した場合は、使用したスコープが非推奨になったため、再登録します。

3. アプリケーションの作成を選択します。

   アプリケーション設定ページが表示されます。

   

   • Azure DevOps Services は、承認承認ページをユーザーに提示するときに、会社名、アプリ名、説明を使用します。 また、会社の Web サイト、アプリ Web サイト、サービス利用規約とプライバシーに関する声明の URL も使用します。

     

   • Azure DevOps Services がユーザーの承認を要求し、ユーザーがそれを許可すると、ユーザーのブラウザーは承認コードを含む承認コールバック URL にリダイレクトされます。 コールバック URL は、コードをアプリに転送し、アプリに登録されている URL と正確に一致するセキュリティで保護された接続 (https) である必要があります。 そうでない場合は、アプリに承認を付与するようにユーザーに求めるページではなく、400 エラー ページが表示されます。

4. 組織にアクセスするアプリをユーザーに承認させる場合は、承認 URL を呼び出し、アプリ ID と承認されたスコープを渡します。 Azure DevOps Services REST API を呼び出すアクセス トークンを取得する場合は、アクセス トークン URL を呼び出します。

登録する各アプリの設定は、プロファイル https://app.vssps.visualstudio.com/profile/viewから入手できます。

2. アプリを承認する

1. ユーザーが組織にアクセスするアプリを承認していない場合は、承認 URL を呼び出します。 ユーザーが承認を承認すると、承認コードを使用して呼び出されます。

https://app.vssps.visualstudio.com/oauth2/authorize
        ?client_id={app ID}
        &response_type={Assertion}
        &state={state}
        &scope={scope}
        &redirect_uri={callback URL}

2. ユーザーを Azure DevOps Services 承認エンドポイントに移動するリンクまたはボタンをサイトに追加します。

https://app.vssps.visualstudio.com/oauth2/authorize
        ?client_id=00001111-aaaa-2222-bbbb-3333cccc4444
        &response_type=Assertion
        &state=User1
        &scope=vso.work%20vso.code_write
        &redirect_uri=https://fabrikam.azurewebsites.net/myapp/oauth-callback

Azure DevOps Services は、アプリの承認をユーザーに求めます。

ユーザーが同意すると、Azure DevOps Services は、有効期間の短い承認コードと承認 URL に指定された状態値を含む、ユーザーのブラウザーをコールバック URL にリダイレクトします。

https://fabrikam.azurewebsites.net/myapp/oauth-callback
        ?code={authorization code}
        &state=User1

3. ユーザーのアクセス トークンと更新トークンを取得する

承認コードを使用して、ユーザーのアクセス トークン (および更新トークン) を要求します。 サービスは、Azure DevOps Services に対してサービス間 HTTP 要求を行う必要があります。

URL - アプリを承認する

POST https://app.vssps.visualstudio.com/oauth2/token

HTTP 要求ヘッダー - アプリを承認する

Content-Type: application/x-www-form-urlencoded

HTTP 要求本文 - アプリを承認する

client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={1}&redirect_uri={2}

前のサンプル要求本文のプレースホルダー値を置き換えます。

• {0}: アプリの登録時に取得された URL でエンコードされたクライアント シークレット
• {1}: code クエリ パラメーターを介してコールバック URL に提供される URL エンコードされた "コード"
• {2}: アプリに登録されているコールバック URL

要求本文を形成する C# の例 - アプリを承認する

public string GenerateRequestPostData(string appSecret, string authCode, string callbackUrl)
{
   return String.Format("client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={1}&redirect_uri={2}",
               HttpUtility.UrlEncode(appSecret),
               HttpUtility.UrlEncode(authCode),
               callbackUrl
        );
}

応答 - アプリを承認する

{
    "access_token": { access token for the user },
    "token_type": { type of token },
    "expires_in": { time in seconds that the token remains valid },
    "refresh_token": { refresh token to use to acquire a new access token }
}

4. アクセス トークンを使用する

アクセス トークンを使用するには、HTTP 要求の Authorization ヘッダーにベアラー トークンとして含めます。

Authorization: Bearer {access_token}

たとえば、プロジェクトの最近のビルドをする HTTP 要求は次のとおりです。

GET https://dev.azure.com/myaccount/myproject/_apis/build-release/builds?api-version=3.0
Authorization: Bearer {access_token}

5. 期限切れのアクセス トークンを更新する

ユーザーのアクセス トークンの有効期限が切れた場合は、承認フローで取得した更新トークンを使用して、新しいアクセス トークンを取得できます。 これは、アクセストークンと更新トークンの承認コードを交換するための元のプロセスのようなものです。

URL - 更新トークン

POST https://app.vssps.visualstudio.com/oauth2/token

HTTP 要求ヘッダー - 更新トークン

Content-Type: application/x-www-form-urlencoded
Content-Length: 1654

HTTP 要求本文 - 更新トークン

client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=refresh_token&assertion={1}&redirect_uri={2}

前のサンプル要求本文のプレースホルダー値を置き換えます。

• {0}: アプリの登録時に取得された URL でエンコードされたクライアント シークレット
• {1}: ユーザーの URL エンコードされた更新トークン
• {2}: アプリに登録されているコールバック URL

応答 - 更新トークン

{
    "access_token": { access token for this user },
    "token_type": { type of token },
    "expires_in": { time in seconds that the token remains valid },
    "refresh_token": { new refresh token to use when the token has timed out }
}

サンプル

OAuth を実装して Azure DevOps Services REST API を呼び出す C# サンプルは、 C# OAuth GitHub サンプルにあります。

クライアント シークレットを再生成する

5 年ごとに、アプリケーション シークレットの有効期限が切れます。 アプリ シークレットを再生成して、引き続きアクセス トークンと更新トークンを作成して使用します。 これを行うには、[シークレットの再生成] を選択し、このアクションを完了することを確認します。

再生成することを確認すると、以前のアプリ シークレットは機能しなくなり、このシークレットで作成された以前のすべてのトークンも機能しなくなります。 顧客のダウンタイムを最小限に抑えるために、このクライアント シークレットのローテーションを十分に行ってください。

アプリを削除する

アプリが不要になった場合は、プロファイルから削除します。

1. プロファイルに移動します: https://app.vssps.visualstudio.com/profile/view。

2. サイドバーの自分の名前の下にあるドロップダウン メニューから選択して、正しいテナントのページに表示されていることを確認します。

3. 左側のサイドバーの Applications と services ヘッダーでアプリを見つけます。

4. アプリケーション登録ページで [削除] を選択します。 削除を確認するモーダルが表示されます。

   

5. アプリの登録を削除すると、アプリが中断され、新しいトークンの作成や、このアプリのミントトークンの受け入れは停止されます。

よく寄せられる質問 (FAQ)

Q: 携帯電話アプリで OAuth を使用できますか?

A: いいえ。 Azure DevOps Services は Web サーバー フローのみをサポートしているため、アプリ シークレットを安全に格納できないため、OAuth を実装する方法はありません。

Q: コードで処理する必要があるエラーや特別な条件は何ですか?

A: 次の条件を処理していることを確認します。

• ユーザーがアプリのアクセスを拒否した場合、承認コードは返されません。 拒否を確認せずに承認コードを使用しないでください。
• ユーザーがアプリの承認を取り消した場合、アクセス トークンは無効になります。 アプリがトークンを使用してデータにアクセスすると、401 エラーが返されます。 もう一度承認を要求します。

Q: Web アプリをローカルでデバッグする必要があります。 アプリを登録するときにコールバック URL に localhost を使用できますか?

回答: はい。 Azure DevOps Services では、コールバック URL で localhost が許可されるようになりました。 アプリを登録するときに、コールバック URL の先頭として https://localhost を使用していることを確認します。

Q: アクセス トークンを取得しようとすると、HTTP 400 エラーが発生します。 何が間違っている可能性がありますか?

A: 要求ヘッダーでコンテンツ タイプを application/x-www-form-urlencoded に設定していることを確認します。

Q: OAuth ベースのアクセス トークンを使用すると HTTP 401 エラーが発生しますが、スコープが同じ PAT でも問題ありません。 なぜですか?

A: 組織の管理者が、https://dev.azure.com/{your-org-name}/_settings/organizationPolicyで OAuth 経由で Third-party アプリケーション アクセスを無効にしていないことを確認します。 このシナリオでは、アプリを承認し、アクセス トークンを生成するフローが機能しますが、すべての REST API は、次のようなエラーのみを返します TF400813: The user "<GUID>" is not authorized to access this resource.

関連記事

• 適切な認証方法の選択
• Microsoft Entra ID OAuth を使用する
• Azure DevOps の既定のアクセス許可とアクセス
• 承認の管理