Move best practices info from Marketplace article (#37598)

Co-authored-by: Ben Ahmady <32935794+subatoi@users.noreply.github.com>

content/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app.md

@@ -73,6 +73,8 @@ User access tokens will attribute activity to a user and to your app. These are
 
 An installation access token is restricted based on the {% data variables.product.prodname_github_app %}'s permissions and access. A user access token is restricted based on both the {% data variables.product.prodname_github_app %}'s permission and access and the user's permission and access. Therefore, if your {% data variables.product.prodname_github_app %} takes an action on behalf of a user, it should always use a user access token instead of an installation access token. Otherwise, your app might allow a user to see or do things that they shouldn't be able to see or do.
 
+Your app should never use a {% data variables.product.pat_generic %} or {% data variables.product.company_short %} password to authenticate.
+
 ## Validate organization access for every new authentication
 
 When you use a user access token, you should track which organizations the token is authorized for. If an organization uses SAML SSO and a user has not performed SAML SSO, the user access token should not have access to that organization. You can use the `GET /user/installations` REST API endpoint to verify which organizations a user access token has access to. If the user is not authorized to access an organization, you should reject their access until they perform SAML SSO. For more information, see "[AUTOTITLE](/rest/apps/installations#list-app-installations-accessible-to-the-user-access-token)."
@@ -83,13 +85,17 @@ When you use a user access token, you should track which organizations the token
 
 Installation access tokens expire after one hour, expiring user access tokens expire after eight hours, and refresh tokens expire after six months. However, you can also revoke tokens as soon as you no longer need them. For more information, see "[AUTOTITLE](/rest/apps/installations#revoke-an-installation-access-token)" to revoke an installation access token and "[AUTOTITLE](/rest/apps/oauth-applications#delete-an-app-token)" to revoke a user access token.
 
-## Make a plan for rotating credentials
+## Make a plan for handling security breaches
 
 You should have a plan in place so that you can handle any security breaches in a timely manner.
 
 In the event that your app's private key or secret is compromised, you will need to generate a new key or secret, update your app to use the new key or secret, and delete your old key or secret.
 
-In the event that installation access tokens, user access tokens, or refresh tokens are compromised, you should immediately revoke these tokens. For more information, see "[AUTOTITLE](/rest/apps/installations#revoke-an-installation-access-token)."
+In the event that installation access tokens, user access tokens, or refresh tokens are compromised, you should immediately revoke these tokens. For more information, see "[AUTOTITLE](/rest/apps/installations#revoke-an-installation-access-token)" to revoke an installation access token and "[AUTOTITLE](/rest/apps/oauth-applications#delete-an-app-token)" to revoke a user access token.
+
+## Conduct regular vulnerability scans
+
+{% data reusables.apps.app-scans %}
 
 ## Choose an appropriate environment
 
@@ -111,6 +117,18 @@ When you add repository or organization permissions to your {% data variables.pr
 
 When you update permissions, you should consider making your app backwards compatible to give your users time to accept the new permissions. You can use the [installation webhook with the `new_permissions_accepted` action property](/webhooks-and-events/webhooks/webhook-events-and-payloads?actionType=new_permissions_accepted#installation) to learn when users accept new permissions for your app.
 
+## Use services in a secure manner
+
+{% data reusables.apps.app-services %}
+
+## Add logging and monitoring
+
+{% data reusables.apps.apps-logging %}
+
+## Enable data deletion
+
+If your {% data variables.product.prodname_github_app %} is available to other users or organizations, you should give users and organization owners a way to delete their data. Users should not need to email or call a support person in order to delete their data.
+
 {% ifversion fpt or ghec %}
 
 ## Further reading

content/apps/oauth-apps/building-oauth-apps/best-practices-for-creating-an-oauth-app.md

@@ -0,0 +1,85 @@
+---
+title: Best practices for creating an OAuth App
+shortTitle: Best practices
+intro: 'Follow these best practices to improve the security and performance of your OAuth App.'
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghae: '*'
+  ghec: '*'
+topics:
+  - OAuth Apps
+---
+
+## Use a {% data variables.product.prodname_github_app %} instead
+
+If possible, consider using a {% data variables.product.prodname_github_app %} instead of an OAuth App. In general, {% data variables.product.prodname_github_app %}s are preferred over {% data variables.product.prodname_oauth_app %}s. {% data variables.product.prodname_github_app %}s use fine-grained permissions, give the user more control over which repositories the app can access, and use short-lived tokens. These properties can harden the security of your app by limiting the damage that could be done if your app's credentials are leaked.
+
+Similar to {% data variables.product.prodname_oauth_app %}s, {% data variables.product.prodname_github_app %}s can still use OAuth 2.0 and generate a type of OAuth token (called a user access token) and take actions on behalf of a user. However, {% data variables.product.prodname_github_app %}s can also act independently of a user.
+
+For more information about {% data variables.product.prodname_github_app %}s, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps)."
+
+For more information about migrating an existing {% data variables.product.prodname_oauth_app %} to a {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/apps/creating-github-apps/guides/migrating-oauth-apps-to-github-apps)."
+
+## Use minimal scopes
+
+Your OAuth App should only request the scopes that the app needs to perform its intended functionality. If any tokens for your app become compromised, this will limit the amount of damage that can occur. For more information, see "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps)."
+
+## Secure your app's credentials
+
+With a client secret, your app can authorize a user and generate user access tokens. These tokens can be used to make API requests on behalf of a user.
+
+You must store your app's client secret and any generated tokens securely. The storage mechanism depends on your integrations architecture and the platform that it runs on. In general, you should use a storage mechanism that is intended to store sensitive data on the platform that you are using.
+
+### Client secrets
+
+If your app is a website or web app, consider storing your client secret in a key vault, such as [Azure Key Vault](https://azure.microsoft.com/products/key-vault), or as an encrypted environment variable or secret on your server.
+
+If your app is a native client, client-side app, or runs on a user device (as opposed to running on your servers), you cannot secure your client secret. You should use caution if you plan to gate access to your own services based on tokens generated by your app, because anyone can access the client secret to generate a token.
+
+### User access tokens
+
+If your app is a website or web app, you should encrypt the tokens on your back end and ensure there is security around the systems that can access the tokens. Consider storing refresh tokens in a separate place from active access tokens.
+
+If your app is a native client, client-side app, or runs on a user device (as opposed to running on your servers), you may not be able to secure tokens as well as an app that runs on your servers. You should store tokens via the mechanism recommended for your app's platform, and keep in mind that the storage mechanism may not be fully secure.
+
+## Use the appropriate token type
+
+OAuth Apps can generate user access tokens in order to make authenticated API requests. Your app should never use a {% data variables.product.pat_generic %} or {% data variables.product.company_short %} password to authenticate.
+
+## Make a plan for handling security breaches
+
+You should have a plan in place so that you can handle any security breaches in a timely manner.
+
+In the event that your app's client secret is compromised, you will need to generate a new secret, update your app to use the new secret, and delete your old secret.
+
+In the event that user access tokens are compromised, you should immediately revoke these tokens. For more information, see "[AUTOTITLE](/rest/apps/oauth-applications#delete-an-app-token)."
+
+## Conduct regular vulnerability scans
+
+{% data reusables.apps.app-scans %}
+
+## Choose an appropriate environment
+
+If your app runs on a server, verify that your server environment is secure and that it can handle the volume of traffic that you expect for your app.
+
+## Use services in a secure manner
+
+{% data reusables.apps.app-services %}
+
+## Add logging and monitoring
+
+{% data reusables.apps.apps-logging %}
+
+## Enable data deletion
+
+If your app is available to other users, you should give users a way to delete their data. Users should not need to email or call a support person in order to delete their data.
+
+{% ifversion fpt or ghec %}
+
+## Further reading
+
+- "[AUTOTITLE](/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/security-best-practices-for-apps)"
+- "[AUTOTITLE](/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/customer-experience-best-practices-for-apps)"
+
+{% endif %}

content/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps.md

@@ -24,7 +24,7 @@ shortTitle: GitHub Apps & OAuth Apps
 
 In general, {% data variables.product.prodname_github_app %}s are preferred over {% data variables.product.prodname_oauth_app %}s. {% data variables.product.prodname_github_app %}s use fine grained permissions, give the user more control over which repositories the app can access, and use short-lived tokens. These properties can harden the security of your app by limiting the damage that could be done if your app's credentials were leaked.
 
-Similar to {% data variables.product.prodname_oauth_app %}s, {% data variables.product.prodname_github_app %}s can still generate a type of OAuth token (called a user access token) and take actions on behalf of a user. However, {% data variables.product.prodname_github_app %}s can also act independently of a user. This is beneficial for automations that do not require user input. The app will continue to work even if the person who installed the app on an organization leaves the organization.
+Similar to {% data variables.product.prodname_oauth_app %}s, {% data variables.product.prodname_github_app %}s can still use OAuth 2.0 and generate a type of OAuth token (called a user access token) and take actions on behalf of a user. However, {% data variables.product.prodname_github_app %}s can also act independently of a user. This is beneficial for automations that do not require user input. The app will continue to work even if the person who installed the app on an organization leaves the organization.
 
 {% data variables.product.prodname_github_app %}s have built-in, centralized webhooks. {% data variables.product.prodname_github_app %}s can receive webhook events for all repositories and organizations the app can access. Conversely, {% data variables.product.prodname_oauth_app %}s must configure webhooks individually for each repository and organization.
 

content/apps/oauth-apps/building-oauth-apps/index.md

@@ -20,5 +20,6 @@ children:
   - /authorizing-oauth-apps
   - /scopes-for-oauth-apps
   - /creating-a-custom-badge-for-your-oauth-app
+  - /best-practices-for-creating-an-oauth-app
 ---
 

content/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/customer-experience-best-practices-for-apps.md

@@ -22,6 +22,7 @@ If you follow these best practices it will help you to provide a good customer e
 - Apps should include links to user-facing documentation that describe how to set up and use the app.
 - Customers should be able to see what type of plan they have in the billing, profile, or account settings section of the app.
 - Customers should be able to install and use your app on both a personal account and an organization account. They should be able to view and manage the app on those accounts separately.
+- Apps should provide customers with a way to delete their account, without having to email or call a support person. Apps should delete all {% data variables.product.company_short %} user data within 30 days of receiving a request from the user, or within 30 days of the end of the user's legal relationship with {% data variables.product.company_short %}.
 
 ## Plan management
 
@@ -30,4 +31,5 @@ If you follow these best practices it will help you to provide a good customer e
 ## Further reading
 
 - "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app)"
+- "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/best-practices-for-creating-an-oauth-app)"
 - "[AUTOTITLE](/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/security-best-practices-for-apps)"

content/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/security-best-practices-for-apps-on-github-marketplace.md

@@ -18,56 +18,11 @@ topics:
 
 {% data reusables.marketplace.marketplace-apps-not-actions %}
 
-If you follow these best practices it will help you to provide a secure user experience.
-
-## Authorization, authentication, and access control
-
-We recommend creating a GitHub App rather than an OAuth App. {% data reusables.marketplace.github_apps_preferred %}. See "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/differences-between-github-apps-and-oauth-apps)" for more details.
-- Apps should use the principle of least privilege and should only request the OAuth scopes and GitHub App permissions that the app needs to perform its intended functionality. For more information, see [Principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) in Wikipedia.
-- Apps should provide customers with a way to delete their account, without having to email or call a support person.
-- Apps should not share tokens between different implementations of the app. For example, a desktop app should have a separate token from a web-based app. Individual tokens allow each app to request the access needed for GitHub resources separately.
-- Design your app with different user roles, depending on the functionality needed by each type of user. For example, a standard user should not have access to admin functionality, and billing managers might not need push access to repository code.
-- Apps should not share service accounts such as email or database services to manage your SaaS service.
-- All services used in your app should have unique login and password credentials.
-- Admin privilege access to the production hosting infrastructure should only be given to engineers and employees with administrative duties.
-- Apps should not use {% data variables.product.pat_generic %}s to authenticate and should authenticate as an [OAuth App](/apps/oauth-apps/building-oauth-apps) or a [GitHub App](/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps#about-github-apps):
-  - OAuth Apps should authenticate using an [OAuth token](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps).
-  - GitHub Apps should authenticate using either a [JSON Web Token (JWT)](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-json-web-token-jwt-for-a-github-app), [OAuth token](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps), or [installation access token](/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app).
-
-## Data protection
-
-- Apps should encrypt data transferred over the public internet using HTTPS, with a valid TLS certificate, or SSH for Git.
-- Apps should store client ID and client secret keys securely. We recommend storing them as [environmental variables](https://en.wikipedia.org/wiki/Environment_variable#Getting_and_setting_environment_variables).
-- Apps should delete all GitHub user data within 30 days of receiving a request from the user, or within 30 days of the end of the user's legal relationship with GitHub.
-- Apps should not require the user to provide their GitHub password.
-- Apps should encrypt tokens, client IDs, and client secrets.
-
-## Logging and monitoring
-
-Apps should have logging and monitoring capabilities. App logs should be retained for at least 30 days and archived for at least one year.
-A security log should include:
-
-- Authentication and authorization events
-- Service configuration changes
-- Object reads and writes
-- All user and group permission changes
-- Elevation of role to admin
-- Consistent timestamping for each event
-- Source users, IP addresses, and/or hostnames for all logged actions
-
-## Incident response workflow
-
-To provide a secure experience for users, you should have a clear incident response plan in place before listing your app. We recommend having a security and operations incident response team in your company rather than using a third-party vendor. You should have the capability to notify {% data variables.product.product_name %} within 24 hours of a confirmed incident.
-
-For an example of an incident response workflow, see the "Data Breach Response Policy" on the [SANS Institute website](https://www.sans.org/information-security-policy/). A short document with clear steps to take in the event of an incident is more valuable than a lengthy policy template.
-
-## Vulnerability management and patching workflow
-
-You should conduct regular vulnerability scans of production infrastructure. You should triage the results of vulnerability scans and define a period of time in which you agree to remediate the vulnerability.
-
-If you are not ready to set up a full vulnerability management program, it's useful to start by creating a patching process. For guidance in creating a patch management policy, see this TechRepublic article "[Establish a patch management policy](https://www.techrepublic.com/article/establish-a-patch-management-policy-87756/)."
-
-## Further reading
+Before listing an app on {% data variables.product.prodname_marketplace %}, you should follow the best practices for the type of app that you are listing:
 
 - "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app)"
-- "[AUTOTITLE](/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/customer-experience-best-practices-for-apps)"
+- "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/best-practices-for-creating-an-oauth-app)"
+
+Additionally, you should have the capability to notify {% data variables.product.product_name %} within 24 hours of a confirmed security incident.
+
+In addition to following security best practices, you should also follow customer experience best practices. For more information, see "[AUTOTITLE](/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/customer-experience-best-practices-for-apps)."

data/reusables/apps/app-scans.md

@@ -0,0 +1 @@
+You should conduct regular vulnerability scans for your app. For example, you might set up code scanning and secret scanning for the repository that hosts your app's code. For more information, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning)" and "[AUTOTITLE](/code-security/secret-scanning/about-secret-scanning)."

data/reusables/apps/app-services.md

@@ -0,0 +1,5 @@
+If your app uses third-party services, they should be used in a secure manner:
+
+- Any services used by your app should have a unique login and password.
+- Apps should not share service accounts such as email or database services to manage your SaaS service.
+- Only employees with administrative duties should have admin access to the infrastructure that hosts your app.

data/reusables/apps/apps-logging.md

@@ -0,0 +1,9 @@
+Consider adding logging and monitoring capabilities for your app. A security log could include:
+
+- Authentication and authorization events
+- Service configuration changes
+- Object reads and writes
+- User and group permission changes
+- Elevation of role to admin
+
+Your logs should use consistent timestamping for each event and should record the users, IP addresses, or hostnames for all logged events.