From 79e897cd58d6312ae864238e3c9dbd0a7a78d1a5 Mon Sep 17 00:00:00 2001 From: Sean Grove Date: Thu, 5 Aug 2021 13:57:24 -0700 Subject: [PATCH 1/6] chore: Add provisional docs for auth usage Adds documentation to the README on how to use Netlify Integration Auth in functions. --- README.md | 102 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) diff --git a/README.md b/README.md index d97a97d4..febbea57 100644 --- a/README.md +++ b/README.md @@ -74,6 +74,108 @@ The following types are exported: - `HandlerEvent` - `HandlerResponse` + +## Netlify Integration Auth Management + +To make building on and interacting with third-party APIs as simple and powerful as possible, Netlify provides API secret provisioning and management, powered by OneGraph. It’s enabled on a per-site basis under the [Netlify labs](https://app.netlify.com/user/labs) tab, where you can visually select which services you want to make available for your functions or site builds, and which scopes you need access to. + +### Usage + +After you’ve enabled one or more services, you can access the relevant API tokens and secrets in your functions with the `getSecrets` function exported from this package: + +> `getSecrets` is fully typed, so you’ll have in-editor autocomplete to explore everything that’s available, and to be confident that you’re handling all of the edge cases + + ```js + import { getSecrets } from "@netlify/functions"; + + export const handler = async (event) => { + // Handle all fetching, refreshing, rotating, etc. of tokens + const secrets = await getSecrets(); + + // Check if the GitHub auth has been enabled for the site + if (!secrets.gitHub?.bearerToken) { + return { + statusCode: 412, + body: JSON.stringify({ + error: "You must enable the GitHub auth in your Netlify dashboard", + }), + headers: { + "Content-Type": "application/json", + }, + }; + } + + // If so, we can make calls to the GitHub API - REST or GraphQL! + const MyOctokit = Octokit.plugin(restEndpointMethods); + const octokit = new MyOctokit({ auth: secrets.gitHub.bearerToken }); + + // We'll list all open issues on the netlify/functions repository + const result = await octokit.rest.issues.list({ + owner: "netlify", + repo: "functions", + state: "open", + }); + + return { + statusCode: 200, + body: JSON.stringify(result), + headers: { + "Content-Type": "application/json", + }, + }; + }; + ``` + +### Checking additional metadata about auths in your functions + +Netlify Integration Auth Management also tracks metadata for the installed auth tokens. If you would like to verify that an auth has been installed with the correct scopes before calling into an API (say, for example, to give a better error message in the developer logs): + + ```js + import { getSecrets } from "@netlify/functions"; + + export const handler = async (event) => { + // Handle all fetching, refreshing, rotating, etc. of tokens + const secrets = await getSecrets(); + + // We know that we need either "public_repo" or "repo" scopes granted + // in order to run this function properly + const sufficientScopes = ["public_repo", "repo"]; + + // Secrets have an optional `grantedScopes` field that has details + // on what the auth is allowed to do + const tokenHasScope = secrets.gitHub.grantedScopes?.some((grantedScope) => + sufficientScopes.includes(grantedScope.scope) + ); + + // Notice how we can leave a great error message that tells us exactly what + // we need to do to fix things. + if (!tokenHasScope) { + return { + statusCode: 412, + body: JSON.stringify({ + error: `You have enabled GitHub auth in your Netlify Auth dashboard, but it's missing a required scope. The auth must have one (or both) of the scopes: ${sufficientScopes.join(", ")}`, + }), + headers: { + "Content-Type": "application/json", + }, + }; + } + + // ... + } + ``` + +### Accessing integration auth during development + +When running your site under `netlify dev`, the environmental variables that power the auth management will be synced, and you can transparently develop against the third party APIs - no additional configuration necessary! + + +### Updating or removing auth from your site + +At any time you can revisit the Netlify Integration Auth Management tab for your site to see the installed auth. From there, you can select new scopes for already-installed auth and then run through the browser-based auth flow again, and the new scopes will be available to all your existing, deployed functions instantly. + +You can also install new services, or remove currently-installed services you’re no longer using. + ## Contributors Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for instructions on how to set up and work on this repository. Thanks From 525eb2667f338f3fef5da82922fe901568848fe8 Mon Sep 17 00:00:00 2001 From: Sean Grove Date: Mon, 9 Aug 2021 22:30:16 -0700 Subject: [PATCH 2/6] Update README.md Co-authored-by: Rachael Stavchansky --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index febbea57..a5e071e5 100644 --- a/README.md +++ b/README.md @@ -81,7 +81,7 @@ To make building on and interacting with third-party APIs as simple and powerful ### Usage -After you’ve enabled one or more services, you can access the relevant API tokens and secrets in your functions with the `getSecrets` function exported from this package: +After you’ve enabled one or more services, you can access the relevant API tokens and secrets in your serverless functions with the `getSecrets` function exported from the `@netlify/functions` package. > `getSecrets` is fully typed, so you’ll have in-editor autocomplete to explore everything that’s available, and to be confident that you’re handling all of the edge cases From a2ee2f9d562f5f4621fc5075e4af67ecf2ebd341 Mon Sep 17 00:00:00 2001 From: Sean Grove Date: Mon, 9 Aug 2021 22:30:23 -0700 Subject: [PATCH 3/6] Update README.md Co-authored-by: Rachael Stavchansky --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a5e071e5..6d432e61 100644 --- a/README.md +++ b/README.md @@ -128,7 +128,7 @@ After you’ve enabled one or more services, you can access the relevant API tok ### Checking additional metadata about auths in your functions -Netlify Integration Auth Management also tracks metadata for the installed auth tokens. If you would like to verify that an auth has been installed with the correct scopes before calling into an API (say, for example, to give a better error message in the developer logs): +Netlify Integration Auth Management also tracks metadata for installed auth tokens. You can verify that an auth has been installed with the correct scopes before calling into an API (say, for example, to give a better error message in the developer logs). Here's an example: ```js import { getSecrets } from "@netlify/functions"; From ac2c88465067dbb0f18e0508f0898248bcb68bc0 Mon Sep 17 00:00:00 2001 From: Sean Grove Date: Mon, 9 Aug 2021 22:30:32 -0700 Subject: [PATCH 4/6] Update README.md Co-authored-by: Rachael Stavchansky --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6d432e61..70ab6b18 100644 --- a/README.md +++ b/README.md @@ -174,7 +174,7 @@ When running your site under `netlify dev`, the environmental variables that pow At any time you can revisit the Netlify Integration Auth Management tab for your site to see the installed auth. From there, you can select new scopes for already-installed auth and then run through the browser-based auth flow again, and the new scopes will be available to all your existing, deployed functions instantly. -You can also install new services, or remove currently-installed services you’re no longer using. +You can also install new services or remove currently-installed services you’re no longer using. ## Contributors From bfd0973ceade8639c294ac8946c64cfeb7114aac Mon Sep 17 00:00:00 2001 From: Sean Grove Date: Wed, 11 Aug 2021 10:30:42 -0700 Subject: [PATCH 5/6] Incorporate copy feedback --- README.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 70ab6b18..32c149be 100644 --- a/README.md +++ b/README.md @@ -75,9 +75,11 @@ The following types are exported: - `HandlerResponse` -## Netlify Integration Auth Management +## {feature_name} -To make building on and interacting with third-party APIs as simple and powerful as possible, Netlify provides API secret provisioning and management, powered by OneGraph. It’s enabled on a per-site basis under the [Netlify labs](https://app.netlify.com/user/labs) tab, where you can visually select which services you want to make available for your functions or site builds, and which scopes you need access to. +**Note: This feature is currently in beta under Netlify Labs** + +To make building on and interacting with third-party APIs as simple and powerful as possible, Netlify provides API secret provisioning and management, powered by [OneGraph](https://www.onegraph.com). It’s enabled on a per-site basis under [Netlify labs](https://app.netlify.com/user/labs) tab, where you can use the Netlify UI to select which services you want to make available for your functions or site builds, and which scopes you need access to. ### Usage @@ -126,9 +128,9 @@ After you’ve enabled one or more services, you can access the relevant API tok }; ``` -### Checking additional metadata about auths in your functions +### Checking additional metadata about auth token in your functions and site builds -Netlify Integration Auth Management also tracks metadata for installed auth tokens. You can verify that an auth has been installed with the correct scopes before calling into an API (say, for example, to give a better error message in the developer logs). Here's an example: +{feature_name} also tracks metadata for installed auth tokens. You can verify that an auth has been installed with the correct scopes before calling into an API (say, for example, to give a better error message in the developer logs). Here's an example: ```js import { getSecrets } from "@netlify/functions"; @@ -165,14 +167,13 @@ Netlify Integration Auth Management also tracks metadata for installed auth toke } ``` -### Accessing integration auth during development +### Accessing integration auth tokens during development When running your site under `netlify dev`, the environmental variables that power the auth management will be synced, and you can transparently develop against the third party APIs - no additional configuration necessary! +### Updating or removing auth tokens from your site -### Updating or removing auth from your site - -At any time you can revisit the Netlify Integration Auth Management tab for your site to see the installed auth. From there, you can select new scopes for already-installed auth and then run through the browser-based auth flow again, and the new scopes will be available to all your existing, deployed functions instantly. +At any time you can revisit the {feature_name} tab for your site in [Netlify Labs](https://app.netlify.com/user/labs) (select your profile avatar, then Netlify Labs) to see the installed auth. From there, you can select new scopes for already-installed auth and then run through the browser-based auth flow again, and the new scopes will be available to all your existing, deployed functions and site builds _instantly_. You can also install new services or remove currently-installed services you’re no longer using. From da37759e11b14b002b97420383ccc210eb080345 Mon Sep 17 00:00:00 2001 From: Tiffany Le-Nguyen Date: Thu, 9 Sep 2021 10:17:56 -0400 Subject: [PATCH 6/6] Update README.md --- README.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 32c149be..ba255d9f 100644 --- a/README.md +++ b/README.md @@ -75,11 +75,11 @@ The following types are exported: - `HandlerResponse` -## {feature_name} +## Auth Management **Note: This feature is currently in beta under Netlify Labs** -To make building on and interacting with third-party APIs as simple and powerful as possible, Netlify provides API secret provisioning and management, powered by [OneGraph](https://www.onegraph.com). It’s enabled on a per-site basis under [Netlify labs](https://app.netlify.com/user/labs) tab, where you can use the Netlify UI to select which services you want to make available for your functions or site builds, and which scopes you need access to. +To make building on and interacting with third-party APIs as simple and powerful as possible, Netlify provides API secret provisioning and management, powered by [OneGraph](https://www.onegraph.com). It’s enabled on a per-site basis under [Netlify labs](https://app.netlify.com/user/labs) tab, where you can use the Netlify UI to select which services you want to make available for your functions or site builds, and which scopes you need access to. ### Usage @@ -129,8 +129,7 @@ After you’ve enabled one or more services, you can access the relevant API tok ``` ### Checking additional metadata about auth token in your functions and site builds - -{feature_name} also tracks metadata for installed auth tokens. You can verify that an auth has been installed with the correct scopes before calling into an API (say, for example, to give a better error message in the developer logs). Here's an example: +Auth Management also tracks metadata for installed auth tokens. You can verify that an auth has been installed with the correct scopes before calling into an API (say, for example, to give a better error message in the developer logs). Here's an example: ```js import { getSecrets } from "@netlify/functions"; @@ -173,7 +172,7 @@ When running your site under `netlify dev`, the environmental variables that pow ### Updating or removing auth tokens from your site -At any time you can revisit the {feature_name} tab for your site in [Netlify Labs](https://app.netlify.com/user/labs) (select your profile avatar, then Netlify Labs) to see the installed auth. From there, you can select new scopes for already-installed auth and then run through the browser-based auth flow again, and the new scopes will be available to all your existing, deployed functions and site builds _instantly_. +At any time you can revisit the Auth Management tab for your site in [Netlify Labs](https://app.netlify.com/user/labs) (select your profile avatar, then Netlify Labs) to see the installed auth. From there, you can select new scopes for already-installed auth and then run through the browser-based auth flow again, and the new scopes will be available to all your existing, deployed functions and site builds _instantly_. You can also install new services or remove currently-installed services you’re no longer using.