253 lines
17 KiB
HTML
253 lines
17 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<title>JSDoc: Tutorial: server-secrets</title>
|
|
|
|
<script src="scripts/prettify/prettify.js"> </script>
|
|
<script src="scripts/prettify/lang-css.js"> </script>
|
|
<!--[if lt IE 9]>
|
|
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
|
|
<![endif]-->
|
|
<link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
|
|
<link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<div id="main">
|
|
|
|
<h1 class="page-title">Tutorial: server-secrets</h1>
|
|
|
|
<section>
|
|
|
|
<header>
|
|
|
|
|
|
<h2>server-secrets</h2>
|
|
</header>
|
|
|
|
<article>
|
|
<h1>Server Secrets</h1>
|
|
<p>It is possible to provide a token or credentials for a number of external
|
|
services. These may be used to lift a rate limit or provide access to
|
|
private resources from a self-hosted instance.</p>
|
|
<p>There are two ways of setting secrets:</p>
|
|
<ol>
|
|
<li>Via environment variables. This is a good way to set them in a PaaS
|
|
environment.</li>
|
|
</ol>
|
|
<pre class="prettyprint source lang-sh"><code>DRONE_TOKEN=...
|
|
DRONE_ORIGINS="https://drone.example.com"
|
|
</code></pre>
|
|
<ol start="2">
|
|
<li>Via checked-in <code>config/local.yml</code>:</li>
|
|
</ol>
|
|
<pre class="prettyprint source lang-yml"><code>public:
|
|
services:
|
|
drone:
|
|
authorizedOrigins: ['https://drone.example.com']
|
|
private:
|
|
drone_token: '...'
|
|
</code></pre>
|
|
<p>For more complex scenarios, configuration files can cascade. See the <a href="https://github.com/lorenwest/node-config/wiki/Configuration-Files">node-config documentation</a>
|
|
for details.</p>
|
|
<h2>Authorized origins</h2>
|
|
<p>Several of the badges provided by Shields allow users to specify the target
|
|
URL/server of the upstream instance to use via a query parameter in the badge URL
|
|
(e.g. https://img.shields.io/nexus/s/com.google.guava/guava?server=https%3A%2F%2Foss.sonatype.org).
|
|
This supports scenarios where your users may need badges from multiple upstream
|
|
targets, for example if you have more than one Nexus server.</p>
|
|
<p>Accordingly, if you configure credentials for one of these services with your
|
|
self-hosted Shields instance, you must also specifically authorize the hosts
|
|
to which the credentials are allowed to be sent. If your self-hosted Shields
|
|
instance then receives a badge request for a target that does not match any
|
|
of the authorized origins, one of two things will happen:</p>
|
|
<ul>
|
|
<li>if credentials are required for the targeted service, Shields will render
|
|
an error badge.</li>
|
|
<li>if credentials are optional for the targeted service, Shields will attempt
|
|
the request, but without sending any credentials.</li>
|
|
</ul>
|
|
<p>When setting authorized origins through an environment variable, use a space
|
|
to separate multiple origins. Note that failing to define authorized origins
|
|
for a service will default to an empty list, i.e. no authorized origins.</p>
|
|
<p>It is highly recommended to use <code>https</code> origins with valid SSL, to avoid the
|
|
possibility of exposing your credentials, for example through DNS-based attacks.</p>
|
|
<p>It is also recommended to use tokens for a service account having
|
|
<a href="https://en.wikipedia.org/wiki/Principle_of_least_privilege">the fewest privileges needed</a> for fetching the relevant status
|
|
information.</p>
|
|
<h2>Services</h2>
|
|
<h3>Azure DevOps</h3>
|
|
<ul>
|
|
<li><code>AZURE_DEVOPS_TOKEN</code> (yml: <code>private.azure_devops_token</code>)</li>
|
|
</ul>
|
|
<p>An Azure DevOps Token (PAT) is required for accessing <a href="https://docs.microsoft.com/en-us/azure/devops/organizations/public/about-public-projects?view=vsts">private Azure DevOps projects</a>.</p>
|
|
<p><a href="https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=vsts#create-personal-access-tokens-to-authenticate-access">Create a PAT</a> using an account that has access to your target Azure DevOps projects. Your PAT only needs the following <a href="https://docs.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/oauth?view=vsts#scopes">scopes:</a></p>
|
|
<ul>
|
|
<li><code>Build (read)</code></li>
|
|
<li><code>Release (read)</code></li>
|
|
<li><code>Test Management (read)</code></li>
|
|
</ul>
|
|
<h3>Bintray</h3>
|
|
<ul>
|
|
<li><code>BINTRAY_USER</code> (yml: <code>private.bintray_user</code>)</li>
|
|
<li><code>BINTRAY_API_KEY</code> (yml: <code>private.bintray_apikey</code>)</li>
|
|
</ul>
|
|
<p>The bintray API <a href="https://bintray.com/docs/api/#_authentication">requires authentication</a>
|
|
Create an account and obtain a token from the user profile page.</p>
|
|
<h3>Bitbucket (Cloud)</h3>
|
|
<ul>
|
|
<li><code>BITBUCKET_USER</code> (yml: <code>private.bitbucket_username</code>)</li>
|
|
<li><code>BITBUCKET_PASS</code> (yml: <code>private.bitbucket_password</code>)</li>
|
|
</ul>
|
|
<p>Bitbucket badges use basic auth. Provide a username and password to give your
|
|
self-hosted Shields installation access to private repositories hosted on bitbucket.org.</p>
|
|
<h3>Bitbucket Server</h3>
|
|
<ul>
|
|
<li><code>BITBUCKET_SERVER_ORIGINS</code> (yml: <code>public.services.bitbucketServer.authorizedOrigins</code>)</li>
|
|
<li><code>BITBUCKET_SERVER_USER</code> (yml: <code>private.bitbucket_server_username</code>)</li>
|
|
<li><code>BITBUCKET_SERVER_PASS</code> (yml: <code>private.bitbucket_server_password</code>)</li>
|
|
</ul>
|
|
<p>Bitbucket badges use basic auth. Provide a username and password to give your
|
|
self-hosted Shields installation access to a private Bitbucket Server instance.</p>
|
|
<h3>Discord</h3>
|
|
<p>Using a token for Dicsord is optional but will allow higher API rates.</p>
|
|
<ul>
|
|
<li><code>DISCORD_BOT_TOKEN</code> (yml: <code>discord_bot_token</code>)</li>
|
|
</ul>
|
|
<p>Register an application in the <a href="https://discord.com/developers">Discord developer console</a>.
|
|
To obtain a token, simply create a bot for your application.</p>
|
|
<h3>Drone</h3>
|
|
<ul>
|
|
<li><code>DRONE_ORIGINS</code> (yml: <code>public.services.drone.authorizedOrigins</code>)</li>
|
|
<li><code>DRONE_TOKEN</code> (yml: <code>private.drone_token</code>)</li>
|
|
</ul>
|
|
<p>The self-hosted Drone API <a href="https://0-8-0.docs.drone.io/api-authentication/">requires authentication</a>. Log in to your
|
|
Drone instance and obtain a token from the user profile page.</p>
|
|
<h3>GitHub</h3>
|
|
<ul>
|
|
<li><code>GITHUB_URL</code> (yml: <code>public.services.github.baseUri</code>)</li>
|
|
<li><code>GH_TOKEN</code> (yml: <code>private.gh_token</code>)</li>
|
|
</ul>
|
|
<p>Because of Github rate limits, you will need to provide a token, or else badges
|
|
will stop working once you hit 60 requests per hour, the
|
|
<a href="https://developer.github.com/v3/#rate-limiting">unauthenticated rate limit</a>.</p>
|
|
<p>You can <a href="https://github.com/settings/tokens">create a personal access token</a> through the
|
|
Github website. When you create the token, you can choose to give read access
|
|
to your repositories. If you do that, your self-hosted Shields installation
|
|
will have access to your private repositories.</p>
|
|
<p>When a <code>gh_token</code> is specified, it is used in place of the Shields token
|
|
rotation logic.</p>
|
|
<p><code>GITHUB_URL</code> can be used to optionally send all the GitHub requests to a
|
|
GitHub Enterprise server. This can be done in conjunction with setting a
|
|
token, though it's not required.</p>
|
|
<ul>
|
|
<li><code>GH_CLIENT_ID</code> (yml: <code>private.gh_client_id</code>)</li>
|
|
<li><code>GH_CLIENT_SECRET</code> (yml: <code>private.gh_client_secret</code>)</li>
|
|
</ul>
|
|
<p>These settings are used by shields.io for GitHub OAuth app authorization
|
|
but will not be necessary for most self-hosted installations. See
|
|
<a href="./production-hosting.md">production-hosting.md</a>.</p>
|
|
<h3>Jenkins CI</h3>
|
|
<ul>
|
|
<li><code>JENKINS_ORIGINS</code> (yml: <code>public.services.jenkins.authorizedOrigins</code>)</li>
|
|
<li><code>JENKINS_USER</code> (yml: <code>private.jenkins_user</code>)</li>
|
|
<li><code>JENKINS_PASS</code> (yml: <code>private.jenkins_pass</code>)</li>
|
|
</ul>
|
|
<p>Provide a username and password to give your self-hosted Shields installation
|
|
access to a private Jenkins CI instance.</p>
|
|
<h3>Jira</h3>
|
|
<ul>
|
|
<li><code>JIRA_ORIGINS</code> (yml: <code>public.services.jira.authorizedOrigins</code>)</li>
|
|
<li><code>JIRA_USER</code> (yml: <code>private.jira_user</code>)</li>
|
|
<li><code>JIRA_PASS</code> (yml: <code>private.jira_pass</code>)</li>
|
|
</ul>
|
|
<p>Provide a username and password to give your self-hosted Shields installation
|
|
access to a private JIRA instance.</p>
|
|
<h3>Nexus</h3>
|
|
<ul>
|
|
<li><code>NEXUS_ORIGINS</code> (yml: <code>public.services.nexus.authorizedOrigins</code>)</li>
|
|
<li><code>NEXUS_USER</code> (yml: <code>private.nexus_user</code>)</li>
|
|
<li><code>NEXUS_PASS</code> (yml: <code>private.nexus_pass</code>)</li>
|
|
</ul>
|
|
<p>Provide a username and password to give your self-hosted Shields installation
|
|
access to your private nexus repositories.</p>
|
|
<h3>npm</h3>
|
|
<ul>
|
|
<li><code>NPM_ORIGINS</code> (yml: <code>public.services.npm.authorizedOrigins</code>)</li>
|
|
<li><code>NPM_TOKEN</code> (yml: <code>private.npm_token</code>)</li>
|
|
</ul>
|
|
<p><a href="https://docs.npmjs.com/getting-started/working_with_tokens">Generate an npm token</a> to give your self-hosted Shields
|
|
installation access to private npm packages</p>
|
|
<h3>SymfonyInsight (formerly Sensiolabs)</h3>
|
|
<ul>
|
|
<li><code>SL_INSIGHT_USER_UUID</code> (yml: <code>private.sl_insight_userUuid</code>)</li>
|
|
<li><code>SL_INSIGHT_API_TOKEN</code> (yml: <code>private.sl_insight_apiToken</code>)</li>
|
|
</ul>
|
|
<p>The SymfonyInsight API requires authentication. To obtain a token,
|
|
Create an account, sign in and obtain a uuid and token from your
|
|
<a href="https://insight.sensiolabs.com/account">account page</a>.</p>
|
|
<h3>SonarQube</h3>
|
|
<ul>
|
|
<li><code>SONAR_ORIGINS</code> (yml: <code>public.services.sonar.authorizedOrigins</code>)</li>
|
|
<li><code>SONARQUBE_TOKEN</code> (yml: <code>private.sonarqube_token</code>)</li>
|
|
</ul>
|
|
<p><a href="https://docs.sonarqube.org/latest/user-guide/user-token/">Generate a token</a>
|
|
to give your self-hosted Shields installation access to a
|
|
private SonarQube instance or private project on a public instance.</p>
|
|
<h3>TeamCity</h3>
|
|
<ul>
|
|
<li><code>TEAMCITY_ORIGINS</code> (yml: <code>public.services.teamcity.authorizedOrigins</code>)</li>
|
|
<li><code>TEAMCITY_USER</code> (yml: <code>private.teamcity_user</code>)</li>
|
|
<li><code>TEAMCITY_PASS</code> (yml: <code>private.teamcity_pass</code>)</li>
|
|
</ul>
|
|
<p>Provide a username and password to give your self-hosted Shields installation
|
|
access to your private nexus repositories.</p>
|
|
<h3>Twitch</h3>
|
|
<ul>
|
|
<li><code>TWITCH_CLIENT_ID</code> (yml: <code>twitch_client_id</code>)</li>
|
|
<li><code>TWITCH_CLIENT_SECRET</code> (yml: <code>twitch_client_secret</code>)</li>
|
|
</ul>
|
|
<p>Register an application in the <a href="https://dev.twitch.tv/console">Twitch developer console</a>
|
|
in order to obtain a client id and a client secret for making Twitch API calls.</p>
|
|
<h3>Wheelmap</h3>
|
|
<ul>
|
|
<li><code>WHEELMAP_TOKEN</code> (yml: <code>private.wheelmap_token</code>)</li>
|
|
</ul>
|
|
<p>The wheelmap API requires authentication. To obtain a token,
|
|
Create an account, <a href="http://classic.wheelmap.org/en/users/sign_in">sign in</a> and use the <em>Authentication Token</em>
|
|
displayed on your profile page.</p>
|
|
<h3>YouTube</h3>
|
|
<ul>
|
|
<li><code>YOUTUBE_API_KEY</code> (yml: <code>private.youtube_api_key</code>)</li>
|
|
</ul>
|
|
<p>The YouTube API requires authentication. To obtain an API key,
|
|
log in to a Google account, go to the <a href="https://console.developers.google.com/apis/credentials">credentials page</a>,
|
|
and create an API key for the YouTube Data API v3.</p>
|
|
<h2>Error reporting</h2>
|
|
<ul>
|
|
<li><code>SENTRY_DSN</code> (yml: <code>private.sentry_dsn</code>)</li>
|
|
</ul>
|
|
<p>A <a href="https://docs.sentry.io/error-reporting/quickstart/?platform=javascript#configure-the-dsn">Sentry DSN</a> may be used to send error reports from your installation to
|
|
<a href="http://sentry.io/">Sentry.io</a>. For more info, see the <a href="https://github.com/badges/shields/blob/master/doc/self-hosting.md#sentry">self hosting docs</a>.</p>
|
|
</article>
|
|
|
|
</section>
|
|
|
|
</div>
|
|
|
|
<nav>
|
|
<h2><a href="index.html">Home</a></h2><h3>Modules</h3><ul><li><a href="module-badge-maker.html">badge-maker</a></li><li><a href="module-core_base-service_base.html">core/base-service/base</a></li><li><a href="module-core_base-service_base-graphql.html">core/base-service/base-graphql</a></li><li><a href="module-core_base-service_base-json.html">core/base-service/base-json</a></li><li><a href="module-core_base-service_base-svg-scraping.html">core/base-service/base-svg-scraping</a></li><li><a href="module-core_base-service_base-xml.html">core/base-service/base-xml</a></li><li><a href="module-core_base-service_base-yaml.html">core/base-service/base-yaml</a></li><li><a href="module-core_base-service_errors.html">core/base-service/errors</a></li><li><a href="module-core_base-service_graphql.html">core/base-service/graphql</a></li><li><a href="module-core_server_server.html">core/server/server</a></li><li><a href="module-core_service-test-runner_create-service-tester.html">core/service-test-runner/create-service-tester</a></li><li><a href="module-core_service-test-runner_icedfrisby-shields.html">core/service-test-runner/icedfrisby-shields</a></li><li><a href="module-core_service-test-runner_infer-pull-request.html">core/service-test-runner/infer-pull-request</a></li><li><a href="module-core_service-test-runner_runner.html">core/service-test-runner/runner</a></li><li><a href="module-core_service-test-runner_service-tester.html">core/service-test-runner/service-tester</a></li><li><a href="module-core_service-test-runner_services-for-title.html">core/service-test-runner/services-for-title</a></li><li><a href="module-core_token-pooling_token-pool.html">core/token-pooling/token-pool</a></li><li><a href="module-services_dynamic_json-path.html">services/dynamic/json-path</a></li><li><a href="module-services_steam_steam-base.html">services/steam/steam-base</a></li></ul><h3>Classes</h3><ul><li><a href="module.exports.html">exports</a></li><li><a href="module-core_base-service_base-graphql-BaseGraphqlService.html">BaseGraphqlService</a></li><li><a href="module-core_base-service_base-json-BaseJsonService.html">BaseJsonService</a></li><li><a href="module-core_base-service_base-svg-scraping-BaseSvgScrapingService.html">BaseSvgScrapingService</a></li><li><a href="module-core_base-service_base-xml-BaseXmlService.html">BaseXmlService</a></li><li><a href="module-core_base-service_base-yaml-BaseYamlService.html">BaseYamlService</a></li><li><a href="module-core_base-service_base-BaseService.html">BaseService</a></li><li><a href="module-core_base-service_errors-Deprecated.html">Deprecated</a></li><li><a href="module-core_base-service_errors-ImproperlyConfigured.html">ImproperlyConfigured</a></li><li><a href="module-core_base-service_errors-Inaccessible.html">Inaccessible</a></li><li><a href="module-core_base-service_errors-InvalidParameter.html">InvalidParameter</a></li><li><a href="module-core_base-service_errors-InvalidResponse.html">InvalidResponse</a></li><li><a href="module-core_base-service_errors-NotFound.html">NotFound</a></li><li><a href="module-core_base-service_errors-ShieldsRuntimeError.html">ShieldsRuntimeError</a></li><li><a href="module-core_server_server-Server.html">Server</a></li><li><a href="module-core_service-test-runner_runner-Runner.html">Runner</a></li><li><a href="module-core_service-test-runner_service-tester-ServiceTester.html">ServiceTester</a></li><li><a href="module-core_token-pooling_token-pool-Token.html">Token</a></li><li><a href="module-core_token-pooling_token-pool-TokenPool.html">TokenPool</a></li><li><a href="module-services_steam_steam-base-BaseSteamAPI.html">BaseSteamAPI</a></li></ul><h3>Tutorials</h3><ul><li><a href="tutorial-TUTORIAL.html">TUTORIAL</a></li><li><a href="tutorial-badge-urls.html">badge-urls</a></li><li><a href="tutorial-code-walkthrough.html">code-walkthrough</a></li><li><a href="tutorial-deprecating-badges.html">deprecating-badges</a></li><li><a href="tutorial-input-validation.html">input-validation</a></li><li><a href="tutorial-json-format.html">json-format</a></li><li><a href="tutorial-logos.html">logos</a></li><li><a href="tutorial-performance-testing.html">performance-testing</a></li><li><a href="tutorial-production-hosting.html">production-hosting</a></li><li><a href="tutorial-rewriting-services.html">rewriting-services</a></li><li><a href="tutorial-self-hosting.html">self-hosting</a></li><li><a href="tutorial-server-secrets.html">server-secrets</a></li><li><a href="tutorial-service-tests.html">service-tests</a></li><li><a href="tutorial-users.html">users</a></li></ul><h3>Global</h3><ul><li><a href="global.html#validateAffiliations">validateAffiliations</a></li></ul>
|
|
</nav>
|
|
|
|
<br class="clear">
|
|
|
|
<footer>
|
|
Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.6</a> on Fri Jan 22 2021 18:09:16 GMT+0000 (Coordinated Universal Time)
|
|
</footer>
|
|
|
|
<script> prettyPrint(); </script>
|
|
<script src="scripts/linenumber.js"> </script>
|
|
</body>
|
|
</html> |