diff --git a/docs/manage-projects/oauth.md b/docs/manage-projects/oauth.md new file mode 100644 index 00000000000..3000a33fc52 --- /dev/null +++ b/docs/manage-projects/oauth.md @@ -0,0 +1,160 @@ +--- +title: OAuth Authentication +sidebar_label: OAuth Authentication +slug: /oauth +--- + +Some applications require OAuth as an authentication method for connecting with +third party applications making requests via their APIs. This guide walks you +through how to set up and manage OAuth clients. + +### OAuth Authentication + +Some applications require [OAuth](https://oauth.net/2/) as an authentication +method for connecting with third-party applications and making requests via +their APIs. OpenFn allows you to connect with applications using their OAuth +authentication. To use this feature in your OpenFn workflows, you need to set up +OAuth clients and credentials for your instances or projects. This guide walks +you through the management of OAuth clients and credentials. + +### Setting up an OAuth client + +#### What is an OAuth client and when do I need it? + +By setting up OAuth for an application, you authorize OpenFn to connect and +interact with this application within a set of scopes defined by you. For +example, you might set up an OAuth authorization for OpenFn to connect to your +Google Sheets account to read and track changes on your behalf. In this example, +you need to set up an OpenFn client that will represent an instance of OpenFn on +Google and will hold all the permissions OpenFn needs on your behalf. All API +requests and responses are managed through the OpenFn client and authorized by +an authorization token stored by the client. + +In most cases, one client setup might be sufficient for one application but +depending on the project requirements and organization policy, several clients +might be set up for one application. These clients might be owned by the same or +different OpenFn users and accessible to different projects. + +For every application you need to connect to OpenFn, you need to set up at least +one client for your project(s). + +Oauth clients can be set up either on the +[project credentials page](../manage-projects/manage-credentials.md) or the +[user credentials page](../manage-users/user-credentials.md). + +### Creating an OAuth client (Super Users) + +:::note + Currently only users with +[super user privileges](https://docs.openfn.org/documentation/manage-projects/user-roles-permissions#super-user-privileges) +can create and manage OAuth clients. If you're using the OpenFn cloud-hosted platform SaaS, +contact [support@openfn.org](mailto://support@openfn.org) for assistance adding a new Oauth client. +::: + +If you have not created a client before or a superuser has not created a client +for the projects/users in the deployment, you will see an empty block with a +button prompting you to create a client as shown below. + +![New client](/img/create_new_oauth_client.png) + +Alternatively, you will see the list of existing OAuth clients you have access +to. In this case click on the `New credential` button and select +`OAuth client [Advanced]` in the dropdown. + +![OAuth dropdown](/img/oauth_dropdown.png) + +:::note + Make sure you add https://app.openfn.org/authenticate/callback as the +callback URL for the application when enabling OAuth authentication for the +third party application. +::: + +### Sharing OAuth Clients + +A super user has the privilege to share OAuth clients with projects in two ways: + +1. Making a client global +2. Sharing with specific projects + +They can do this in the OAuth client configuration modal either when creating +the client, or via editing it. + +![OAuth edit](/img/oauth_client_edit.png) + +#### Making OAuth clients global + +When an OAuth client is global, users in the instance can have access to it and +can create credentials from it. + +To make a client global, scroll down to `Manage Project Access` section in the +OAuth client configuration modal and select the checkbox +`Make client global (allow any project in this instance to use this client)` and +save changes. All projects on the instance can now access the client and users +with owner, admin and editor rights on these projects can now create credentials +from the client. + +![OAuth project access](/img/manage_project_access.png) + +#### Sharing OAuth clients with projects + +To share an OAuth client with specific projects, scroll down to +`Manage Project Access` section in the OAuth client configuration modal. Select +the project dropdown and select a project and click the add button to grant the +project access to the client. + +![Share OAuth client](/img/share_oauth_client.png) + +### Creating a credential from an OAuth client + +Every client requires an authentication token to authenticate requests made to +the application on behalf of the user. On OpenFn, these tokens are created as +credentials and are associated with clients. + +1. To create a credential from an Oauth client, click on create a new credential + or click on the button as show below: + +![Create new cred](/img/create_new_cred.png) + +![New credential](/img/new_cred.png) + +:::tip +Unlike for OAuth clients, project owners or admins can also create +credentials, not only super users. +::: + +2. Then, in the credential type modal, find and select the Oauth client to use + for creating the OAuth credential. This will open a new modal for you to + configure the credential by providing the name, scopes/permissions required + and API version. +3. When you’ve filled the form, click on the + `Sign in with [your OAuth Client name]` button to authorize the Oauth client. + Clicking this button will open a new tab for you to grant OpenFn an + authorization token to authenticate your requests. + +:::note + When you have siged in, you will be required to grant OpenFn access by +clicking `Allow` on the permissions modal. Please note that this might look +different for different applications but the intent is to grant OpenFn +perimission to carry out certain actions to the application on your behalf. The +user authenticating OAuth clients should have the required permissions in the +application. +::: + +### Deleting Clients and Credentials + +To delete a credential/client, simply click `Delete`. + +![OAuth edit](/img/oauth_client_edit.png) + +A confirmation message pops up to confirm your action. + +As soon as you confirm that you want to delete a credential, you will receive an +email to notify you that the credential has been scheduled for deletion. + +The scheduled deletion date is set by a grace period configured by your instance +administrator. On the [OpenFn hosted instance](https://app.openfn.org/), it will be permanently deleted after 7 days. + +### More on Managing Credentials +Go to the docs on [managing user credentials](../manage-users/user-credentials.md) to learn more +about credential management for the applications you are integrating with on OpenFn. + diff --git a/sidebars-main.js b/sidebars-main.js index 5b9cb01baad..b40d7a68db4 100644 --- a/sidebars-main.js +++ b/sidebars-main.js @@ -94,6 +94,8 @@ module.exports = { 'manage-projects/webhook-auth', 'manage-projects/workflow-dashboard', 'manage-projects/collaboration', + 'manage-projects/oauth', + ], }, { diff --git a/static/img/create_new_cred.png b/static/img/create_new_cred.png new file mode 100644 index 00000000000..292a6739fd9 Binary files /dev/null and b/static/img/create_new_cred.png differ diff --git a/static/img/create_new_oauth_client.png b/static/img/create_new_oauth_client.png new file mode 100644 index 00000000000..88a068da144 Binary files /dev/null and b/static/img/create_new_oauth_client.png differ diff --git a/static/img/manage_project_access.png b/static/img/manage_project_access.png new file mode 100644 index 00000000000..107c56c1795 Binary files /dev/null and b/static/img/manage_project_access.png differ diff --git a/static/img/new_cred.png b/static/img/new_cred.png new file mode 100644 index 00000000000..09308f6a053 Binary files /dev/null and b/static/img/new_cred.png differ diff --git a/static/img/oauth_client_edit.png b/static/img/oauth_client_edit.png new file mode 100644 index 00000000000..6ffa0e21a42 Binary files /dev/null and b/static/img/oauth_client_edit.png differ diff --git a/static/img/oauth_dropdown.png b/static/img/oauth_dropdown.png new file mode 100644 index 00000000000..cbed685fff2 Binary files /dev/null and b/static/img/oauth_dropdown.png differ diff --git a/static/img/share_oauth_client.png b/static/img/share_oauth_client.png new file mode 100644 index 00000000000..59d2cc10b60 Binary files /dev/null and b/static/img/share_oauth_client.png differ