Skip to content

Latest commit

 

History

History
88 lines (69 loc) · 5.18 KB

account-configuration.md

File metadata and controls

88 lines (69 loc) · 5.18 KB
Raw

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.