Markdown Scanner Accounts configuration file

To enable automated testing for predefined service accounts with Markdown Scanner you can confirm an accounts.json file as part of your documentation repo.

Inside the accounts.json file, you can define the parameters for various OAuth2 compatible accounts that will be used to generate access tokens for check-service functionality.

The format of the file is as follows:

{
  "checkServiceEnabledBranches": ["master", "release"],
  "accounts": [
    {
      "name": "AccountFriendlyName",
      "oauthMode": "RefreshToken",
      "enabled": true,
      "clientId": "",
      "clientSecret": "",
      "tokenService": "http://login.live.com/oauth2_token.srf",
      "redirectUri": "appuri://redirect_from_auth",
      "refreshToken": "cached-refresh-token",
      "serviceUrl": "https://api.onedrive.com/v1.0",
      "scopes": ["scope1", "scope2"]

    }
  ]
}

You can define as many account objects within the accounts array as you need. Each enabled account is processed sequentially when running the check-service method. You can also specify a specific account to run using the --account <name> command line parameter.

Types of Accounts

OAuth 2 Refresh Token Accounts

In this scenario, a refresh token generated by an application is stored along with the information about the application that generated the refresh token.

These details are used to call the OAuth2 token service specified and redeem the cached refresh token for a new access token. This method works great for services where the refresh token does not expire.

The following account fields are used for refresh token accounts:

Field Name	Type	Description
name	string	Friendly name of the account
oauthMode	string	Set to RefreshToken
enabled	boolean	Determines if the account is enabled for running automatically with check-service method.
clientId	string	Client ID for the application that generated the refresh token
clientSecret	string	Optional value. Client secret for the application that generated the refresh token.
tokenService	string	The token service endpoint used to redeem the refresh token
redirectUri	string	The refresh URI for the application that generated the refresh token.
refreshToken	string	The cached value of a refresh token.
serviceUrl	string	The base URL for the service that should be tested for this account.

OAuth 2 Username and Password Account

In this scenario, an access token is generated using the password grant flow which redeems a username and password for an OAuth access token for the service.

Field Name	Type	Description
name	string	Friendly name of the account
oauthMode	string	Set to UserPassword
enabled	boolean	Determines if the account is enabled for running automatically with check-service method.
clientId	string	Client ID for the application that generated the refresh token
tokenService	string	Specify the AAD authority URL. Usually https://login.microsoftonline.com/common.
serviceUrl	string	The base URL for the service that should be tested for this account.
username	string	The username to use when requesting access.
password	string	The user's password to use when requesting access.

Other Account parameters

The following additional parameters are valid for all account types, but are optional.

Field Name	Type	Description
additionalHeaders	Array of Strings	An array of string values that are appended to all request headers verbatim.
type	string	Specify the type of the account, if your documentation has some methods that are only valid for certain account types
scopes	Array of Strings	Specify the scopes provided by this account configuration, so only tests that require these scopes are executed.