Add id and org contexts best practices (#50817)

Co-authored-by: jokego <[email protected]>
Co-authored-by: Siara <[email protected]>
Co-authored-by: SiaraMist <[email protected]>

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

@@ -74,9 +74,21 @@ An installation access token is restricted based on the {% data variables.produc
 
 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
+## Authorize thoroughly and durably
 
-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)."
+After signing in a user, app developers must take additional steps to ensure that the user is meant to have access to the data in your system. Each sign in requires fresh checks around their memberships, access, and their current SSO status.
+
+### Use the durable, unique `id` to store the user
+
+{% data reusables.apps.best-practice-use-durable-id %}
+
+### Validate organization access for every new authentication
+
+{% data reusables.apps.best-practice-validate-org-access %}
+
+### Store user data with organizational and enterprise contexts
+
+{% data reusables.apps.best-practice-store-data-with-context %}
 
 ## Expire tokens
 

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

@@ -24,6 +24,30 @@ For more information about migrating an existing {% data variables.product.prodn
 
 Your {% data variables.product.prodname_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)."
 
+## Authorize thoroughly and durably
+
+After signing in a user, app developers must take additional steps to ensure that the user is meant to have access to the data in your system. Each sign in requires fresh checks around their memberships, access, and their current SSO status.
+
+### Use the durable, unique `id` to store the user
+
+{% data reusables.apps.best-practice-use-durable-id %}
+
+### Validate organization access for every new authentication
+
+{% data reusables.apps.best-practice-validate-org-access %}
+
+### Store user data with organizational and enterprise contexts
+
+{% data reusables.apps.best-practice-store-data-with-context %}
+
+### Verify a user's access to your app
+
+Your OAuth app can be accessed by users outside your organization or enterprise. If you intend an app to be used only by members of your organization or enterprise, you should check the user's membership status when the user signs in to your app.
+
+To find the list of organizations a user is a member of, you can use the "List organizations for the authenticated user" endpoint. Then you can validate this list against a list of approved organizations for your app. For more information, see "[AUTOTITLE](/rest/orgs/orgs#list-organizations-for-the-authenticated-user)."
+
+{% data reusables.emus.oauth-app-note %}
+
 ## 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.
@@ -54,14 +78,6 @@ In the event that your app's client secret is compromised, you will need to gene
 
 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)."
 
-## Verify a user's access to your organizations
-
-Your OAuth app can be accessed by users outside your organization or enterprise. If you intend an app to be used only by members of your organization or enterprise, you should check the user's membership status when the user signs in to your app.
-
-To find the list of organizations a user is a member of, you can use the "List organizations for the authenticated user" endpoint. Then you can validate this list against a list of approved organizations for your app. For more information, see "[AUTOTITLE](/rest/orgs/orgs#list-organizations-for-the-authenticated-user)."
-
-{% data reusables.emus.oauth-app-note %}
-
 ## Conduct regular vulnerability scans
 
 {% data reusables.apps.app-scans %}

data/reusables/apps/best-practice-store-data-with-context.md

@@ -0,0 +1,11 @@
+Beyond tracking user identity via the `id` field, you should retain data for the organization or enterprise each user is operating under. This will help ensure you don't leak sensitive information if a user switches roles.
+
+For example:
+
+1. A user is in the `Mona` organization, which requires SAML SSO, and signs into your app after performing SSO. Your app now has access to whatever the user does within `Mona`.
+1. The user pulls a bunch of code out of a repository in `Mona` and saves it in your app for analysis.
+1. Later, the user switches jobs, and is removed from the `Mona` organization.
+
+When the user accesses your app, can they still see the code and analysis from the `Mona` organization in their user account?
+
+This is why it's critical to track the source of the data that your app is saving. Otherwise, your app is a data protection threat for organizations, and they're likely to ban your app if they can't trust that your app correctly protects their data.

data/reusables/apps/best-practice-use-durable-id.md

@@ -0,0 +1,7 @@
+When a user signs in and performs actions in your application, you have to remember which user took that action in order to grant them access to the same resources the next time they sign in.
+
+To store users in your database correctly, always use the `id` of the user. This value will never change for the user or be used to point to a different user, so it ensures you are providing access to the user you intend. You can find a user's `id` with the `GET /user` REST API endpoint. See "[AUTOTITLE](/rest/users/users#get-a-user)."
+
+If you store references to repositories, organizations, and enterprises, use their `id` as well to ensure your links to them remain accurate.
+
+_Never_ use identifiers that can change over time, including user handles, organization slugs, or email addresses.

data/reusables/apps/best-practice-validate-org-access.md

@@ -0,0 +1 @@
+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 will 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 prevent their access to organization owned data within your own application until they perform SAML SSO. For more information, see "[AUTOTITLE](/rest/apps/installations#list-app-installations-accessible-to-the-user-access-token)."