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.
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. |
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. |
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. |