[Azure] Create OAuth Token

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

Azure Repository

From Authorize access to REST APIs with OAuth 2.0

Detailed OAuth 2.0 Steps

You will be required to create an Azure App to obtain a client ID and secret. These will be used to generate your auth code, and subsequently your OAuth access token.

(These directions are summarized from the linked Microsoft documentation above)

Step 1: Azure - register your application

1. Register a new application in Azure DevOps
   • https://app.vsaex.visualstudio.com/app/register
   • *Scopes: vso.code (you only need read-only access for the purpose of this utility).
     • In the Authorization callback URL, use https://oauth.pstmn.io/v1/browser-callback. Take note of the Callback URL you use for this app, you will need it later on.
     • In the Authorized Scopes section of your app's registration page, select Code (read).
2. Click the Create Application button at the bottom.

*This is the minimum scope required in order to read schema files from your selected repository. Adding or removing any scopes for any 3rd party app is the responsibility of the developer and/or team that is developing the integration.

Step 2: Azure - build your authorization flow

1. Review your registered app once registered. Go to https://app.vssps.visualstudio.com/profile/view and on the left navigation menu, under Applications and services, click the name of your application. You will be able to view the application settings on this page that you will need for the next step.
2. Generate an authorization code in your client (web browser) by going to the following URL: https://app.vssps.visualstudio.com/oauth2/authorize?client_id={app ID}&response_type={Assertion}&scope={scope}&redirect_uri={callback URL}.
   1. You will need to fill in the contents within the curly braces above.
      1. Make sure to remove the curly braces around these values before navigating to this URL in your browser.
   2. See AUTHORIZATION CODE URL PARAMETERS table below (referencing the linked Microsoft documentation above).

Example Authorization Code request (in browser)

https://app.vssps.visualstudio.com/oauth2/authorize?client_id=12345678-0123-1234-1234-123456789123&response_type=Assertion&scope=vso.code&redirect_uri=https://oauth.pstmn.io/v1/browser-callback

AUTHORIZATION CODE URL PARAMETERS

1. After you navigate to this URL, you should be prompted to authorize the application in your browser.
   1. If you don't see an authorization prompt, ensure popups are allowed.
2. After you authorize the app flow, you will be redirected to your specified URL from the Callback URL value.
   1. There is a returned code in the URL - copy and store this value in a text editor of your choice to reference later.
   2. Ex: https://www.example.com/?code=ey0943oqiwjsdf0j39-2iijaod.fjeoijojr2qejfje[...]

Step 3: Create your OAuth token

1. In Qodex, send a new POST request to Azure's token endpoint in order to create your OAuth access token with the information you've generated from. the previous two steps.
   1. REQUEST: POST https://app.vssps.visualstudio.com/oauth2/token
   2. HEADER: Content-Type application/x-www-form-urlencoded
   3. PAYLOAD (see TOKEN CREATION PAYLOAD table in the Body tab section below)

Create OAuth Token

This POST request contains a payload that you send to Azure's /oauth2/token endpoint:

• client_assertion_type
• client_assertion
• grant_type
• assertion
• redirect_uri

After passing in the correct information, you should receive the following JSON object back:

{
    "access_token": "TOKEN_VALUE",
    "token_type": "jwt-bearer",
    "expires_in": "3599",
    "refresh_token": "REFRESH_TOKEN_VALUE",
    "scope": "vso.code vso.authorization_grant"
}

When this request it successful, it also sets the value of the `azureToken` Collection Variable which is used in either Azure Git Repo request ([Azure] JSON & [Azure] YAML). This is passed through in the following header for either request:

Authorization: Bearer {{ azureToken }}

Overview

Headers

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

Body tab

TOKEN CREATION PAYLOAD

Tests tab

1. Checks for 200 HTTP response.
2. Sets the value of azureToken Collection Variable
   1. This variable is used for authenticating to Azure DevOps REST APIs.

Request Body

[{"name"=>"client_assertion_type", "value"=>"{{azureClientAssertionType}}", "datatype"=>"string"}, {"name"=>"client_assertion", "value"=>"{{azureClientAssertionSecretValue}}", "datatype"=>"string"}, {"name"=>"grant_type", "value"=>"{{azureClientGrantType}}", "datatype"=>"string"}, {"name"=>"assertion", "value"=>"{{azureClientAssertionCodeValue}}", "datatype"=>"string"}, {"name"=>"redirect_uri", "value"=>"{{azureClientRedirectURI}}", "datatype"=>"string"}]

HEADERS