Cf pats oauth admin setup

_data/home-content.yml

@@ -118,7 +118,7 @@
     localurl: /docs/administration/add-users/
   - title: Single Sign-On
     localurl: /docs/administration/single-sign-on/
-  - title: Set up OAuth2 authentication
+  - title: Set up OAuth2 authentication for Git providers
     localurl: /docs/administration/oauth-setup/  
   - title: User settings
     localurl: /docs/administration/user-settings/

_data/nav.yml

@@ -141,7 +141,7 @@
       url: "/add-users"
     - title: User settings
       url: "/user-settings"
-    - title: Set up OAuth2 authentication
+    - title: Set up OAuth2 authentication for Git providers
       url: "/oauth-setup"
     - title: Authorize access to organizations/projects
       url: "/hosted-authorize-orgs"  

_docs/administration/oauth-setup.md

@@ -1,30 +1,42 @@
 ---
-title: "Set up OAuth2 authentication"
+title: "Set up OAuth2 authentication for Git providers"
 description: ""
 group: administration
 toc: true
 ---
 
-Easily Connect Codefresh to your Git provider using OAuth2. 
-Codefresh integrates with Git to sync repositories to your clusters, implementing Git-based operations when creating resources such as Delivery Pipelines, and to enrich Images with valuable information.
+Codefresh integrates with the Git provider defined for your runtime account to sync repositories to your clusters, implementing Git-based operations when creating resources such as Delivery Pipelines, applications, and enriching images with valuable information.  
 
+As the account administrator, you can select the authentication method for a runtime account. Users in Codefresh will then authorize access to the Git providers through the defined mechanism.  
 
-Codefresh supports OAuth2 or Personal Access Tokens (PATs) for authentication:
-
-* OAuth2 with Codefresh OAuth Application or custom OAuth2 Application
+{% include 
+   image.html 
+   lightbox="true" 
+   file="/images/authentication/authentication-list.png" 
+   url="/images/authentication/authentication-list.png" 
+   alt="Git provider authentication accounts" 
+   caption="Git provider authentication accounts"
+   max-width="80%" 
+   %}
 
-  OAuth2 is the preferred authentication mechanism, currently supported for GitHub. You have the option to use the default pre-defined Codefresh OAuth Application, or your own Oauth2 Application in your Git account. 
-  To use your own Oauth2 GitHub Application, create a secret on your K8s cluster and configure it in Authentication > Settings. See [Create a custom OAuth2 provider account](#create-a-custom-oauth2-provider-account) in this article.
-
+Codefresh supports OAuth2 or personal access tokens (PATs) for authentication:  
 
-  > A runtime can have only one active account for authentication. 
+* OAuth2 with Codefresh OAuth Application or custom OAuth2 Application  
+  OAuth2 is the preferred authentication mechanism, supported for popular Git providers such as GitHub, GitHub Enterprise, GitLab Cloud and Server, and Bitbucket Cloud and Server.  
+  You have the option to use the default predefined Codefresh OAuth Application, or a custom Oauth2 Application for Codefresh in your Git provider account.  
+  Hosted runtime accounts automatically use Codefresh's predefined OAuth Application.  
+  To use a custom Oauth2 Application for Codefresh, first create the application in your Git provider account, then create a secret on your K8s cluster, and finally configure OAuth2 access for the custom application in Authentication > Settings. See [Create a custom OAuth2 Application for Git provider](#create-a-custom-oauth2-provider-account) in this article.
 
 * Token-based authentication using PAT  
-  With token-based authentication, users must enter their personal access tokens when prompted to authorize access. Token-based authentication for users is described in [Managing Git personal access tokens]({{site.baseurl}}/docs/administration/user-settings/).
+  With token-based authentication, users must generate personal access tokens from their Git providers with the required scopes and enter their personal access tokens when prompted to authorize access. See [Authorize Git access in Codefresh]({{site.baseurl}}/docs/administration/user-settings/#authorize-git-access-in-codefresh).
+
+
 
+### Authentication for Git providers and runtime accounts
+The [Authentication](https://g.codefresh.io/2.0/account-settings/authentication?providerName=github){:target="\_blank"} page displays the accounts by Git provider and the authentication method selected for the same.  
 
-### Authentication provider accounts
-The authentication accounts created for a provider are displayed in the [Authentication](https://g.codefresh.io/2.0/account-settings/authentication?providerName=github){:target="\_blank"}.  
+Authentication accounts are organized by Runtimes. A runtime can have a single authentication account.   
+The Type column identifies the authentication for the provider account as either Codefresh, Custom, or PAT (personal access token). 
 
 {% include 
    image.html 
@@ -33,42 +45,71 @@ The authentication accounts created for a provider are displayed in the [Authent
    url="/images/authentication/authentication-list.png" 
    alt="Git provider authentication accounts" 
    caption="Git provider authentication accounts"
-   max-width="60%" 
+   max-width="80%" 
    %}
-The authentication accounts are organized by Runtimes. Every runtime can have a single authentication account.   
-The Type column identifies the provider account type as either Codefresh or Custom. You can change the provider type to Codefresh or Custom or select manual token entry as the authentication.  
+
+As the account administrator, you can change the authentication method for an account at any time to either Codefresh or Custom, or manual token entry. See [Select authentication mechanism for runtime](#select-authentication-mechanism-for-runtime).
 
+### Create a custom OAuth2 Application for Git provider 
+Create a custom OAuth2 Application for Codefresh in your Git provider accounts with the correct scopes, and set up authentication for the same within Codefresh. Users in Codefresh can then authorize access to the Git provider using OAuth2, instead of a personal access token.  
 
-### Create a custom OAuth2 provider account 
-Codefresh account administrators can create an OAuth2 Application in GitHub, and set up authentication within Codefresh. Users in Codefresh can then authorize access to GitHub using OAuth2, instead of generating a personal access token to perform Git-based actions.  
+Supported Git providers:
+* GitHub and GitHub Enterprise
+* GitLab Cloud and GitLab Server
+* Bitbucket Cloud (hosted) and Bitbucket Server (hybrid)
 
-To set up OAuth2 authorization for GitHub in Codefresh, you must:
-* Create a GitHub OAuth2 Application for Codefresh 
-* Create a K8s `secret` in the runtime cluster with OAuth2 Application credentials
-* Configure OAuth2 settings in Codefresh to create a K8s `ConfigMap` that references the secret
+{::nomarkdown}
+<br>
+{:/}
 
-#### Step 1: Create GitHub OAuth2 Application
+To set up OAuth2 authorization in Codefresh, you must:
+1. [Create Custom OAuth2 Application in Git](#step-1-create-a-custom-oauth2-application-in-git) 
+1. [Create a K8s `secret` in the runtime cluster](#step-2-create-a-k8s-secret-resource-in-the-runtime-cluster)
+1. [Configure OAuth2 settings for Custom Application in Codefresh](#step-3-configure-oauth2-settings-for-custom-application-in-codefresh)
+
+{::nomarkdown}
+<br>
+{:/}
+
+#### Step 1: Create a custom OAuth2 Application in Git
 Create and register an OAuth App under your organization to authorize Codefresh.  
 
-> Make sure your OAuth app has `repo` scope with write access to code. For more information, see [Scopes for OAuth apps](https://docs.github.com/en/developers/apps/building-oauth-apps/scopes-for-oauth-apps){:target="\_blank"}.   
+1. Follow the step-by-step instructions for your Git provider:   
+
+  * [GitHub](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app){:target="\_blank"}:      
+    * For **Authorization callback URL**, enter this value:  
+       `<ingressHost>/app-proxy/api/git-auth/github/callback`  
+       where:  
+       `<ingressHost>` is the IP address or URL of the ingress host in the runtime cluster.
+    * Make sure **Enable Device Flow** is _not_ selected. 
+    * Select **Register application**. 
+       The client ID is automatically generated, and you are prompted to generate the client secret.
+    * Select **Generate a new client secret**, and copy the generated secret.  
+
+  * [GitLab Cloud and Server](https://docs.gitlab.com/ee/integration/oauth_provider.html#user-owned-applications){:target="\_blank"}:   
+    * For **Redirect URI**, enter this value:   
+      `<ingressHost>/app-proxy/api/git-auth/gitlab/callback`  
+      where:  
+      `<ingressHost>` is the IP address or URL of the ingress host in the runtime cluster.  
+
+  * [Bitbucket Server](https://confluence.atlassian.com/adminjiraserver0902/configure-an-outgoing-link-1168853925.html){:target="\_blank"}:      
+    * For **Callback URL**, enter this value:  
+      `<ingressHost>/app-proxy/api/git-auth/bitbucket-server/callback`  
+      where:  
+      `<ingressHost>` is the IP address or URL of the ingress host in the runtime cluster.
 
-1. Follow the step-by-step instructions in [GitHub](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app){:target="\_blank"}.   
-  For the `Authorization callback URL`, enter this value:  
-    `<ingressHost>/app-proxy/api/git-auth/github/callback`  
-    where:  
-    `<ingressHost>` is the IP address or URL of the ingress host in the runtime cluster. 
-1. Make sure **Enable Device Flow** is _not_ selected. 
-1. Select **Register application**. 
-   The client ID is automatically generated, and you are prompted to generate the client secret.
-1. Select **Generate a new client secret**, and copy the generated secret. 
-1. Note down the following:
-  * Application ID from the URL
-  * Client ID and the client secret  
+{:start="2"}
+1. Note down the following, as you will need them to create the K8s secret for the Git OAuth2 application:
+  * GitHub: Application ID from the URL, Client ID, and the client secret  
+  * GitLab Cloud and Server: Application ID and Secret
+  * Bitbucket Server: Key and Secret
 
-You need them to create the K8s secret for the GitHub OAuth2 application.
+{::nomarkdown}
+<br>
+{:/}
 
 #### Step 2: Create a K8s secret resource in the runtime cluster 
-Create a K8s secret in the runtime cluster, using the example below as a guideline. You must define the application ID (`appId`), client ID (`clientId`) and the client secret (`clientSecret`) from the GitHub OAuth2 Application you created, and the GitHub URL (`url`).  
+Create a K8s secret in the runtime cluster, using the example below as a guideline. You must define the application ID (`appId`), client ID (`clientId`) and the client secret (`clientSecret`) from the OAuth2 Application you created in your Git provider, and the Git URL (`url`).  
 
 > All fields in the secret _must be_ encoded in `base64`.  
   To encode, use this command: `echo -n VALUE | base64`.  
@@ -77,10 +118,10 @@ Create a K8s secret in the runtime cluster, using the example below as a guideli
 **Before you begin**  
 
 Make sure you have the following handy:
-* Application ID from the application's URL
-* Client ID 
-* Client secret
-* GitHub URL
+* GitHub: Application ID from the URL, Client ID, and the client secret  
+* GitLab Cloud and Server: Application ID and Secret
+* Bitbucket Server: Key and Secret
+
 
 **How to**  
 
@@ -96,27 +137,31 @@ metadata:
   labels:
     codefresh_io_entity: git-pat-obtainer-sec
 data:
-  appId: # application ID of your OAuth app from GitHub
-  clientId: # client ID of your OAuth app from GitHub
-  clientSecret: # client secret of your OAuth app from GitHub
-  url: https://github.com # GitHub provider URL which by default is github.com, unless self-hosted provider
+  appId: # application ID of your OAuth app
+  clientId: # client ID of your OAuth app 
+  clientSecret: # client secret of your OAuth app
+  url: https://github.com # Git provider URL which by default is github.com, unless self-hosted provider
 ```
 
 {:start="2"}
 1. Apply the secret to the runtime cluster:  
    `kubectl apply -f <filename>`   
 
+{::nomarkdown}
+<br>
+{:/}
 
-#### Step 3: Configure OAuth2 settings in Codefresh 
+#### Step 3: Configure OAuth2 settings for Custom Application in Codefresh 
 
-To complete custom provider authentication, configure the settings for the OAuth2 GitHub application in Codefresh. Configuring the settings creates a K8s ConfigMap that references the OAuth secret credentials. When configuring the settings, you can work in Form mode, or directly in the YAML manifest. 
+Configure the settings for the Custom OAuth2 Application in Codefresh. Configuring the settings creates a K8s ConfigMap that references the OAuth secret credentials. When configuring the settings, you can work in Form mode, or directly update the YAML manifest. 
 
 >Important:  
   > The values for all the settings in the ConfigMap are the `keys` in the secret file. 
 
 1. In the Codefresh UI, go to [Authentication](https://g.codefresh.io/2.0/account-settings/authentication?providerName=github){:target="\_blank"}.
   The list always shows the default predefined Codefresh provider account and custom provider accounts created, organized by Runtime, Type (Codefresh or Custom) and Status. 
-1. From the list, select the runtime to which to apply the current configuration. The runtime must be identical to the runtime to which you saved the K8s secret.
+1. From the list, select the Git provider and the runtime to which to apply the current configuration. 
+   >The runtime must be identical to the runtime to which you saved the K8s secret.
 1. Click **Edit** and then select **Use custom provider**.
    > If you have managed clusters registered to the selected runtime, the authentication account is available to all the clusters.  
   The settings page is opened in **Form** mode.
@@ -132,13 +177,13 @@ To complete custom provider authentication, configure the settings for the OAuth
    %}
 
 {:start="4"}
-1. Configure the settings for the **GitHub OAuth2 Application**, either in **Form** or in **YAML** modes:
+1. Configure the settings for the **Git OAuth2 Application**, either in **Form** or in **YAML** modes:
   * **Secret Name**: The name of the K8s secret file you created in the runtime cluster.
   * **Secret Namespace**: The namespace in the runtime cluster where you created the K8s secret.
   * **Application ID**: The `key` representing the OAuth application ID in the K8s secret. For example, `appId`.
   * **Client ID**: The `key` representing the client ID in the K8s secret. For example, `clientId`.
   * **Client Secret**: The `key` representing the client secret in the K8s secret. For example, `clientSecret`.
-  * **URL**: The `key` representing the provider URL in the K8s secret. For example, `url`.
+  * **URL**: The `key` representing the Git provider URL in the K8s secret. For example, `url`.
 
 {:start="5"}
 1. Click **Commit**.
@@ -160,10 +205,10 @@ To complete custom provider authentication, configure the settings for the OAuth
 1. Optional. Enter a commit message.
 1. At the bottom-right, click **Commit** once again.
 
-You have completed the setup to authorize Codefresh as an OAuth App in GitHub. 
+You have completed the setup to authorize Codefresh as an OAuth App for your Git provider. 
 
-### Select authentication account for runtime
-For a Git provider and a runtime account, switch between the Codefresh, Custom provider account if one exists, or enforce token-based authentication.
+### Select authentication mechanism for runtime
+For a Git provider and a runtime account, select the authentication mechanism: Codefresh account, Custom provider account if one exists, or token-based authentication.
 
 1. In the Codefresh UI, go to [Authentication](https://g.codefresh.io/2.0/account-settings/authentication?providerName=github){:target="\_blank"}.
 1. Select the runtime, and click ![](/images/administration/users/icon-Edit.png?display=inline-block) **Edit**. 

_docs/reference/git-tokens.md

@@ -28,7 +28,7 @@ Codefresh requires two types of Git tokens for authentication:
 
 
 
-### Git runtime tokens
+### Git runtime token scopes
 The Git runtime token is mandatory for runtime installation.
 
 {::nomarkdown}
@@ -55,16 +55,17 @@ The Git runtime token is mandatory for runtime installation.
 
 #### Bitbucket Cloud & Bitbucket Server runtime token scopes
 
-* `Project admin`
-* `Repository write`
-* `Project read`
+* **Permissions**: `Read`
+* **Workspace membership**: `Read`
+* **Webhooks**: `Read and write`
+* **Repositories**: `Write`, `Admin`
 
 {::nomarkdown}
 </br></br>
 {:/}
 
 ### Git personal tokens
-The Git personal token is a user-specific personal access token per provisioned runtime. Unique to each user, it is required after installation to authenticate Git-based actions per runtime in Codefresh. 
+The Git personal token is a user-specific personal access token per provisioned runtime. Unique to each user, it may be required after to authenticate Git-based actions per runtime in Codefresh, based on how your admin has set up authentication for Git providers. 
 
 > If you have access to multiple runtimes, you can use the same personal access token for all the runtimes.   
   You must configure the token for each runtime.
@@ -100,8 +101,9 @@ The Git personal token is a user-specific personal access token per provisioned
 
 #### Bitbucket Cloud & Bitbucket Server personal user token scopes
 
-* `Project read`
-* `Repository write`
+* **Permissions**: `Read`
+* **Workspace membership**: `Read`
+* **Repositories**: `Write`, `Admin`
 
 ### Related articles  
 [User settings]({{site.baseurl}}/docs/administration/user-settings/)