gistfile1.txt

For your first question, if you’re already using Azure AD for OAuth and need to get a user OAuth token without replacing your existing SSO, you typically have a few options:
	1.	Use the OAuth 2.0 Authorization Code Flow – Your app can authenticate users via Azure AD and request an access token with the required scopes. If your users are already authenticated through your SSO, Azure AD should provide a token without requiring them to log in again.
	2.	Use the On-Behalf-Of (OBO) Flow – If your app is acting on behalf of a user after they authenticate via another service, Azure AD allows you to exchange an existing token for another one with different scopes.
	3.	Silent Authentication via MSAL – If your app is using Microsoft Authentication Library (MSAL), you can leverage silent authentication to get an access token if the user has an active session.

It depends on what service you need the OAuth token for and whether your app is considered a first-party or third-party integration within your Azure AD setup.

For your second question about GitHub: Yes, a GitHub App can create repositories and commits, but commits do not automatically appear as if they are from a specific user unless additional steps are taken. By default, commits made by a GitHub App will appear as being made by the app itself. However, you can set the commit’s author and committer fields in the API request to make it appear as though a specific user made the commit.

A couple of key points:
	•	The commit will still have a note indicating it was made by the GitHub App.
	•	If you want the commit to appear exactly as though a user made it, you would typically use a user OAuth token instead of a GitHub App token, which requires the user to grant permissions.
	•	If using a GitHub App, you can set the author email to match the user’s GitHub email, but GitHub may flag it as “unverified” if the app’s permissions don’t allow direct impersonation.

Let me know if you need more details on either!

gistfile2.txt

Got it—you’re using Microsoft Azure SAML SSO for authentication. That means your users authenticate through Azure AD, and you want to integrate GitHub authentication without replacing SAML SSO. Here’s how you can get a GitHub OAuth token while keeping Azure SAML as your primary authentication method.

⸻

How to Get a GitHub OAuth Token While Using Azure SAML SSO

Since Azure SAML SSO provides authentication but does not issue GitHub OAuth tokens, you need a way to link GitHub OAuth to your Azure SAML-authenticated users. Here are the options:

⸻

Option 1: GitHub OAuth Token via User Consent Flow (Recommended)

This method allows users to sign into GitHub separately but link their GitHub identity to their Azure SAML session.

Steps:
	1.	Register a GitHub OAuth App
	•	Go to GitHub Developer Settings.
	•	Click “New OAuth App”.
	•	Set the callback URL to a URL in your application (e.g., https://your-backstage-url.com/auth/github/callback).
	•	Take note of the Client ID and Client Secret.
	2.	Enable OAuth in Backstage
	•	In your Backstage instance, configure GitHub authentication with OAuth by adding the GitHub app credentials to app-config.yaml:

auth:
  environment: production
  providers:
    github:
      development:
        clientId: GITHUB_CLIENT_ID
        clientSecret: GITHUB_CLIENT_SECRET


	3.	Authenticate Users via SAML and GitHub
	•	Users first log into Backstage via Azure SAML SSO.
	•	When they try to interact with GitHub (e.g., create PRs from software templates), Backstage redirects them to GitHub OAuth for one-time user consent.
	•	After consent, GitHub issues an OAuth token scoped to the required permissions.
	•	This token can then be stored only in the user’s session (browser or Backstage database).
	4.	Using the OAuth Token for GitHub API Requests
	•	Once Backstage gets the GitHub OAuth token, it can impersonate the user when making API requests.
	•	Example API request:

curl -H "Authorization: token GITHUB_OAUTH_TOKEN" \
     -H "Accept: application/vnd.github.v3+json" \
     https://api.github.com/user



✅ Pros:
	•	Users keep logging in via Azure SAML.
	•	GitHub OAuth only happens when needed (e.g., when making commits).
	•	Users can control which permissions they grant.

⚠️ Cons:
	•	Requires user interaction during first GitHub OAuth authorization.

⸻

Option 2: GitHub App with Fine-Grained Permissions

Instead of using user OAuth tokens, you can use a GitHub App installed at the organization level to manage repo access without requiring user tokens.

Steps:
	1.	Create a GitHub App
	•	Go to GitHub Apps Settings and create a new GitHub App.
	•	Set permissions to read/write on repositories as needed.
	•	Generate a private key for authentication.
	2.	Install the GitHub App in Your Org
	•	The app can be installed at the organization level or for specific repos.
	•	Once installed, it receives an installation access token.
	3.	Backstage Uses the GitHub App Token
	•	Instead of requesting individual user OAuth tokens, Backstage can authenticate using the GitHub App installation token.
	•	Example API request using a GitHub App token:

curl -H "Authorization: Bearer GITHUB_APP_INSTALLATION_TOKEN" \
     -H "Accept: application/vnd.github.v3+json" \
     https://api.github.com/orgs/YOUR_ORG/repos


	4.	Impersonate Users in Commits
	•	When making commits, you can set the author as a user, even if the commit is made by the GitHub App:

{
  "message": "Commit from Backstage",
  "author": {
    "name": "John Doe",
    "email": "[email protected]"
  }
}



✅ Pros:
	•	No need for individual user OAuth tokens.
	•	More control over permissions at the organization level.
	•	Works well for automated tasks (e.g., Backstage catalog updates).

⚠️ Cons:
	•	Commits made via the GitHub App show as being made by the app (though you can set an author name/email).
	•	Users cannot perform individual actions like PR reviews without OAuth.

⸻

Option 3: Use Azure AD to Issue GitHub Tokens (If Supported by Enterprise GitHub)

Some enterprises configure GitHub Enterprise Cloud to integrate directly with Azure AD for OAuth tokens.

How It Works:
	1.	Users log into Backstage via Azure SAML SSO.
	2.	Azure AD issues an OAuth token that includes GitHub permissions.
	3.	GitHub accepts the Azure AD token for API access.

✅ Pros:
	•	Seamless integration with Azure AD.
	•	No need for GitHub OAuth separately.

⚠️ Cons:
	•	Requires GitHub Enterprise Cloud with Azure AD integration (not all enterprises have this setup).

⸻

Which Option Should You Choose?

Use Case	Recommended Option
Users need to make PRs, commits, or API requests as themselves	Option 1: GitHub OAuth Token via User Consent Flow
You want Backstage to manage repo updates automatically (e.g., catalog sync)	Option 2: GitHub App with Installation Tokens
Your company uses GitHub Enterprise Cloud with Azure AD OAuth integration	Option 3: Azure AD-issued GitHub Tokens

For your case, Option 1 (GitHub OAuth + Azure SAML for login) + Option 2 (GitHub App for org-wide tasks) is likely the best combination.

Let me know if you need more details on implementation!

gistfile3.txt

Got it—you’re using Microsoft Azure SAML SSO for authentication. That means your users authenticate through Azure AD, and you want to integrate GitHub authentication without replacing SAML SSO. Here’s how you can get a GitHub OAuth token while keeping Azure SAML as your primary authentication method.

⸻

How to Get a GitHub OAuth Token While Using Azure SAML SSO

Since Azure SAML SSO provides authentication but does not issue GitHub OAuth tokens, you need a way to link GitHub OAuth to your Azure SAML-authenticated users. Here are the options:

⸻

Option 1: GitHub OAuth Token via User Consent Flow (Recommended)

This method allows users to sign into GitHub separately but link their GitHub identity to their Azure SAML session.

Steps:
	1.	Register a GitHub OAuth App
	•	Go to GitHub Developer Settings.
	•	Click “New OAuth App”.
	•	Set the callback URL to a URL in your application (e.g., https://your-backstage-url.com/auth/github/callback).
	•	Take note of the Client ID and Client Secret.
	2.	Enable OAuth in Backstage
	•	In your Backstage instance, configure GitHub authentication with OAuth by adding the GitHub app credentials to app-config.yaml:

auth:
  environment: production
  providers:
    github:
      development:
        clientId: GITHUB_CLIENT_ID
        clientSecret: GITHUB_CLIENT_SECRET


	3.	Authenticate Users via SAML and GitHub
	•	Users first log into Backstage via Azure SAML SSO.
	•	When they try to interact with GitHub (e.g., create PRs from software templates), Backstage redirects them to GitHub OAuth for one-time user consent.
	•	After consent, GitHub issues an OAuth token scoped to the required permissions.
	•	This token can then be stored only in the user’s session (browser or Backstage database).
	4.	Using the OAuth Token for GitHub API Requests
	•	Once Backstage gets the GitHub OAuth token, it can impersonate the user when making API requests.
	•	Example API request:

curl -H "Authorization: token GITHUB_OAUTH_TOKEN" \
     -H "Accept: application/vnd.github.v3+json" \
     https://api.github.com/user



✅ Pros:
	•	Users keep logging in via Azure SAML.
	•	GitHub OAuth only happens when needed (e.g., when making commits).
	•	Users can control which permissions they grant.

⚠️ Cons:
	•	Requires user interaction during first GitHub OAuth authorization.

⸻

Option 2: GitHub App with Fine-Grained Permissions

Instead of using user OAuth tokens, you can use a GitHub App installed at the organization level to manage repo access without requiring user tokens.

Steps:
	1.	Create a GitHub App
	•	Go to GitHub Apps Settings and create a new GitHub App.
	•	Set permissions to read/write on repositories as needed.
	•	Generate a private key for authentication.
	2.	Install the GitHub App in Your Org
	•	The app can be installed at the organization level or for specific repos.
	•	Once installed, it receives an installation access token.
	3.	Backstage Uses the GitHub App Token
	•	Instead of requesting individual user OAuth tokens, Backstage can authenticate using the GitHub App installation token.
	•	Example API request using a GitHub App token:

curl -H "Authorization: Bearer GITHUB_APP_INSTALLATION_TOKEN" \
     -H "Accept: application/vnd.github.v3+json" \
     https://api.github.com/orgs/YOUR_ORG/repos


	4.	Impersonate Users in Commits
	•	When making commits, you can set the author as a user, even if the commit is made by the GitHub App:

{
  "message": "Commit from Backstage",
  "author": {
    "name": "John Doe",
    "email": "[email protected]"
  }
}



✅ Pros:
	•	No need for individual user OAuth tokens.
	•	More control over permissions at the organization level.
	•	Works well for automated tasks (e.g., Backstage catalog updates).

⚠️ Cons:
	•	Commits made via the GitHub App show as being made by the app (though you can set an author name/email).
	•	Users cannot perform individual actions like PR reviews without OAuth.

⸻

Option 3: Use Azure AD to Issue GitHub Tokens (If Supported by Enterprise GitHub)

Some enterprises configure GitHub Enterprise Cloud to integrate directly with Azure AD for OAuth tokens.

How It Works:
	1.	Users log into Backstage via Azure SAML SSO.
	2.	Azure AD issues an OAuth token that includes GitHub permissions.
	3.	GitHub accepts the Azure AD token for API access.

✅ Pros:
	•	Seamless integration with Azure AD.
	•	No need for GitHub OAuth separately.

⚠️ Cons:
	•	Requires GitHub Enterprise Cloud with Azure AD integration (not all enterprises have this setup).

⸻

Which Option Should You Choose?

Use Case	Recommended Option
Users need to make PRs, commits, or API requests as themselves	Option 1: GitHub OAuth Token via User Consent Flow
You want Backstage to manage repo updates automatically (e.g., catalog sync)	Option 2: GitHub App with Installation Tokens
Your company uses GitHub Enterprise Cloud with Azure AD OAuth integration	Option 3: Azure AD-issued GitHub Tokens

For your case, Option 1 (GitHub OAuth + Azure SAML for login) + Option 2 (GitHub App for org-wide tasks) is likely the best combination.

Let me know if you need more details on implementation!

gistfile4.txt

For your first question, if you’re already using Azure AD for OAuth and need to get a user OAuth token without replacing your existing SSO, you typically have a few options:
	1.	Use the OAuth 2.0 Authorization Code Flow – Your app can authenticate users via Azure AD and request an access token with the required scopes. If your users are already authenticated through your SSO, Azure AD should provide a token without requiring them to log in again.
	2.	Use the On-Behalf-Of (OBO) Flow – If your app is acting on behalf of a user after they authenticate via another service, Azure AD allows you to exchange an existing token for another one with different scopes.
	3.	Silent Authentication via MSAL – If your app is using Microsoft Authentication Library (MSAL), you can leverage silent authentication to get an access token if the user has an active session.

It depends on what service you need the OAuth token for and whether your app is considered a first-party or third-party integration within your Azure AD setup.

For your second question about GitHub: Yes, a GitHub App can create repositories and commits, but commits do not automatically appear as if they are from a specific user unless additional steps are taken. By default, commits made by a GitHub App will appear as being made by the app itself. However, you can set the commit’s author and committer fields in the API request to make it appear as though a specific user made the commit.

A couple of key points:
	•	The commit will still have a note indicating it was made by the GitHub App.
	•	If you want the commit to appear exactly as though a user made it, you would typically use a user OAuth token instead of a GitHub App token, which requires the user to grant permissions.
	•	If using a GitHub App, you can set the author email to match the user’s GitHub email, but GitHub may flag it as “unverified” if the app’s permissions don’t allow direct impersonation.

Let me know if you need more details on either!

gistfile5.txt

Got it—you’re using Microsoft Azure SAML SSO for authentication. That means your users authenticate through Azure AD, and you want to integrate GitHub authentication without replacing SAML SSO. Here’s how you can get a GitHub OAuth token while keeping Azure SAML as your primary authentication method.

⸻

How to Get a GitHub OAuth Token While Using Azure SAML SSO

Since Azure SAML SSO provides authentication but does not issue GitHub OAuth tokens, you need a way to link GitHub OAuth to your Azure SAML-authenticated users. Here are the options:

⸻

Option 1: GitHub OAuth Token via User Consent Flow (Recommended)

This method allows users to sign into GitHub separately but link their GitHub identity to their Azure SAML session.

Steps:
	1.	Register a GitHub OAuth App
	•	Go to GitHub Developer Settings.
	•	Click “New OAuth App”.
	•	Set the callback URL to a URL in your application (e.g., https://your-backstage-url.com/auth/github/callback).
	•	Take note of the Client ID and Client Secret.
	2.	Enable OAuth in Backstage
	•	In your Backstage instance, configure GitHub authentication with OAuth by adding the GitHub app credentials to app-config.yaml:

auth:
  environment: production
  providers:
    github:
      development:
        clientId: GITHUB_CLIENT_ID
        clientSecret: GITHUB_CLIENT_SECRET


	3.	Authenticate Users via SAML and GitHub
	•	Users first log into Backstage via Azure SAML SSO.
	•	When they try to interact with GitHub (e.g., create PRs from software templates), Backstage redirects them to GitHub OAuth for one-time user consent.
	•	After consent, GitHub issues an OAuth token scoped to the required permissions.
	•	This token can then be stored only in the user’s session (browser or Backstage database).
	4.	Using the OAuth Token for GitHub API Requests
	•	Once Backstage gets the GitHub OAuth token, it can impersonate the user when making API requests.
	•	Example API request:

curl -H "Authorization: token GITHUB_OAUTH_TOKEN" \
     -H "Accept: application/vnd.github.v3+json" \
     https://api.github.com/user



✅ Pros:
	•	Users keep logging in via Azure SAML.
	•	GitHub OAuth only happens when needed (e.g., when making commits).
	•	Users can control which permissions they grant.

⚠️ Cons:
	•	Requires user interaction during first GitHub OAuth authorization.

⸻

Option 2: GitHub App with Fine-Grained Permissions

Instead of using user OAuth tokens, you can use a GitHub App installed at the organization level to manage repo access without requiring user tokens.

Steps:
	1.	Create a GitHub App
	•	Go to GitHub Apps Settings and create a new GitHub App.
	•	Set permissions to read/write on repositories as needed.
	•	Generate a private key for authentication.
	2.	Install the GitHub App in Your Org
	•	The app can be installed at the organization level or for specific repos.
	•	Once installed, it receives an installation access token.
	3.	Backstage Uses the GitHub App Token
	•	Instead of requesting individual user OAuth tokens, Backstage can authenticate using the GitHub App installation token.
	•	Example API request using a GitHub App token:

curl -H "Authorization: Bearer GITHUB_APP_INSTALLATION_TOKEN" \
     -H "Accept: application/vnd.github.v3+json" \
     https://api.github.com/orgs/YOUR_ORG/repos


	4.	Impersonate Users in Commits
	•	When making commits, you can set the author as a user, even if the commit is made by the GitHub App:

{
  "message": "Commit from Backstage",
  "author": {
    "name": "John Doe",
    "email": "[email protected]"
  }
}



✅ Pros:
	•	No need for individual user OAuth tokens.
	•	More control over permissions at the organization level.
	•	Works well for automated tasks (e.g., Backstage catalog updates).

⚠️ Cons:
	•	Commits made via the GitHub App show as being made by the app (though you can set an author name/email).
	•	Users cannot perform individual actions like PR reviews without OAuth.

⸻

Option 3: Use Azure AD to Issue GitHub Tokens (If Supported by Enterprise GitHub)

Some enterprises configure GitHub Enterprise Cloud to integrate directly with Azure AD for OAuth tokens.

How It Works:
	1.	Users log into Backstage via Azure SAML SSO.
	2.	Azure AD issues an OAuth token that includes GitHub permissions.
	3.	GitHub accepts the Azure AD token for API access.

✅ Pros:
	•	Seamless integration with Azure AD.
	•	No need for GitHub OAuth separately.

⚠️ Cons:
	•	Requires GitHub Enterprise Cloud with Azure AD integration (not all enterprises have this setup).

⸻

Which Option Should You Choose?

Use Case	Recommended Option
Users need to make PRs, commits, or API requests as themselves	Option 1: GitHub OAuth Token via User Consent Flow
You want Backstage to manage repo updates automatically (e.g., catalog sync)	Option 2: GitHub App with Installation Tokens
Your company uses GitHub Enterprise Cloud with Azure AD OAuth integration	Option 3: Azure AD-issued GitHub Tokens

For your case, Option 1 (GitHub OAuth + Azure SAML for login) + Option 2 (GitHub App for org-wide tasks) is likely the best combination.

Let me know if you need more details on implementation!

gistfile6.txt

For your first question, if you’re already using Azure AD for OAuth and need to get a user OAuth token without replacing your existing SSO, you typically have a few options:
	1.	Use the OAuth 2.0 Authorization Code Flow – Your app can authenticate users via Azure AD and request an access token with the required scopes. If your users are already authenticated through your SSO, Azure AD should provide a token without requiring them to log in again.
	2.	Use the On-Behalf-Of (OBO) Flow – If your app is acting on behalf of a user after they authenticate via another service, Azure AD allows you to exchange an existing token for another one with different scopes.
	3.	Silent Authentication via MSAL – If your app is using Microsoft Authentication Library (MSAL), you can leverage silent authentication to get an access token if the user has an active session.

It depends on what service you need the OAuth token for and whether your app is considered a first-party or third-party integration within your Azure AD setup.

For your second question about GitHub: Yes, a GitHub App can create repositories and commits, but commits do not automatically appear as if they are from a specific user unless additional steps are taken. By default, commits made by a GitHub App will appear as being made by the app itself. However, you can set the commit’s author and committer fields in the API request to make it appear as though a specific user made the commit.

A couple of key points:
	•	The commit will still have a note indicating it was made by the GitHub App.
	•	If you want the commit to appear exactly as though a user made it, you would typically use a user OAuth token instead of a GitHub App token, which requires the user to grant permissions.
	•	If using a GitHub App, you can set the author email to match the user’s GitHub email, but GitHub may flag it as “unverified” if the app’s permissions don’t allow direct impersonation.

Let me know if you need more details on either!

gistfile7.txt

# GitHub App Integration with Backstage: Comprehensive Analysis

## 1. Permissions & Webhook Configuration

### Minimal Required Permissions
A GitHub App used with Backstage should be granted the least privileges necessary for its tasks. Backstage's documentation outlines specific permissions needed for common use cases:

- **Reading catalog data**: 
  - Contents: Read-only (to fetch code and config like catalog-info.yaml)
  - Commit statuses: Read-only (to view build status if needed)
  - If reading organization info (for user/team metadata), Members: Read-only is used

- **Software Template publishing**: For Backstage to create repos and push template code, the app needs:
  - Administration: Read & write (to create repositories)
  - Contents: Read & write (to commit files)
  - Metadata: Read-only
  - Pull requests: Read & write
  - Issues: Read & write
  - Workflows: Read & write (if templates set up GitHub Actions)

- **Optional scopes**: If templates manage secrets or variables for GitHub Actions, permissions like Variables: Read & write or Secrets: Read & write may be required. However, only enable these if your templates truly need them (principle of least privilege).

### Security Best Practices
Grant only the minimum necessary permissions when creating the app. Avoid broad access (e.g., full repo control) if not needed. GitHub Apps allow installation on specific repositories instead of an entire organization. During app installation, choose "Only select repositories" and specify the repos it can access.

This ensures the app can only interact with designated repositories, not every repo in the org. There is no way to restrict a GitHub App's access to only a specific folder within a repository – repository-level is the finest granularity. You can, however, limit the installation to certain repos and even further restrict permissions when generating an installation token (the GitHub API allows creating a token scoped to specific repos and a subset of the app's permissions).

In short, configure the app with least privilege and scope to reduce risk if credentials are compromised.

### Webhook Configuration
When creating the GitHub App, you should configure a webhook URL and set a secret. This can be done at creation time or later by editing the app's settings – GitHub allows updating the webhook URL, secret, and subscribed events at any point.

In Backstage integration, the webhook enables GitHub to notify Backstage of important events. You'll want to subscribe to at least "push" events (code pushes) and "repository" events (repository creations, transfers, etc.). Backstage's catalog can ingest these events so that, for example, when a new repository is created or a catalog file changes, Backstage updates its Software Catalog automatically rather than waiting for a periodic scan.

The Backstage documentation notes that you can deliver webhooks either via a direct HTTP endpoint or via an AWS SQS queue, depending on your setup. In both cases, you should use the webhook secret to verify the authenticity of GitHub's payloads.

The webhook(s) must be configured to trigger on push and repository events for Backstage's GitHub modules to react properly. For example, if a repository is created (or a branch is pushed with a catalog-info.yaml), Backstage will receive the event and can immediately index the new/updated component. (Note: Certain sub-events like repository transfers might not be fully handled by Backstage's current webhook support.)

In summary, set up the webhook with the Backstage endpoint and secret during app creation (or update it afterward if needed), and select the relevant events (push, repository, and any others your use-case requires). This real-time link via webhooks is crucial for keeping Backstage in sync with GitHub changes.

## 2. Authentication & Token Flows

### Installation Tokens vs. User Access Tokens
GitHub Apps support two types of tokens: installation access tokens and user access tokens.

**Installation Token**:
- Obtained by the backend using the app's private key, without interactive login
- Restricted to the app's scopes on the repositories where the app is installed
- Treats the app as a bot/service
- Ideal for automation – e.g., Backstage scanning repositories or publishing templates in a controlled way
- Short-lived (typically one hour) with automatic refreshing
- Does not take into account who the end-user is – grants whatever the app is allowed to do, regardless of the triggering user's permissions

**User Access Token**:
- Obtained via an OAuth user consent flow
- Tied to a specific user, limited by both the app's permission set and the user's own permissions on GitHub
- Useful for actions that should reflect the user's authority
- Actions are attributed to both the app and the specific user
- Recommended when performing actions on behalf of a user to avoid overstepping privileges

### User Approval Flow & Refresh Tokens
When a user needs to authenticate with GitHub through Backstage, the platform utilizes a popup-based OAuth flow:

1. If the user is not logged in or if an action requires additional scopes that haven't been approved yet, Backstage will prompt the user and open a GitHub authorization window
2. User signs in to GitHub (if not already) and approves the scopes the Backstage app needs
3. GitHub redirects back to Backstage's backend with an authorization code, which Backstage exchanges for an access token (and a refresh token, if applicable)
4. The backend closes the loop by sending the result to the frontend

Importantly, Backstage implements an "offline" token model for GitHub:
- Access tokens are short-lived
- A long-lived refresh token is stored so the user doesn't have to log in again frequently
- Refresh token is stored in an HTTP-only cookie, scoped to the GitHub auth provider
- Tokens are not accessible via JavaScript (protecting from XSS attacks)
- Backend can use the refresh token to get a new access token when the old one expires

### Token Binding to Sessions
Once authenticated, the user's identity and tokens are tied to their Backstage session:

- Backstage issues its own session cookie or uses the provider cookie to maintain the login
- GitHub refresh token in the cookie ensures that as the user continues to use Backstage, any plugin that needs to call GitHub on the user's behalf can obtain a fresh access token via the backend
- Frontend plugins use a utility API (e.g., githubAuthApiRef) to request an access token when needed
- The refresh cycle is invisible to the user – prompts only appear for initial sign-in or if a new permission scope is required
- If the user logs out, the session cookie and any tokens are cleared, requiring re-authentication next time

### Installation Access Token Flow (Server-to-Server)
For catalog reading or default scaffolding behavior, Backstage uses the GitHub App installation token:

1. The Backstage backend possesses the GitHub App's private key and App ID from app-config.yaml
2. When Backstage needs to call a GitHub API using the app, it will:
   - Generate a JWT signed with the app's private key identifying the app
   - Call GitHub's App endpoint to exchange that JWT for an installation access token for the specific installation
   - Use that token to authenticate the API requests
3. The obtained installation token usually lasts 60 minutes, after which the backend will repeat the process
4. The token is cached in memory for its duration to avoid excessive re-authentication

This flow is invisible to the user – no consent screen or login is required because the token is granted based on the app's prior installation approval.

### Security Implications
It's important to understand the security trade-offs between installation vs user tokens:

- An installation token is only constrained by the app's permissions, not by any one user
- If your app has broad write access to an org, any action triggered through Backstage could execute that write
- In Backstage's context, initially any user could create a repo in any org the app was installed in, even if that user didn't have org permissions
- The remedy is to incorporate user access tokens when performing user-initiated changes, or implement checks (e.g., only allow certain Backstage groups to execute certain templates)
- User tokens require each user to have appropriate GitHub permissions; if a user lacks access to do something, their token won't work for that action

## 3. Software Templates & User Interaction

Backstage Software Templates provide a guided workflow (wizard UI) for users to create new projects or modify existing ones. Users input information such as component name, description, owner, and target repository location.

Once the user submits, the Scaffolder (Backstage's backend for templates) takes over:
- A templating engine populates the chosen template with the given parameters
- Executes a series of actions defined in the template YAML
- For GitHub integrations, Backstage comes with built-in publish actions to interact with repositories

Depending on the template, the workflow can do one of two high-level things:

### Create a New Repository
For templates that generate a brand-new codebase:
- The Scaffolder uses the GitHub App credentials to create a repository in the specified organization
- The template defines a repoUrl (usually composed of the organization and new repo name)
- The publish:github action calls the GitHub App's installation token to create the repo (requires Administration: write permission)
- Contents: write permission is used to upload the files (committing the templated code)
- By default, Backstage will use a generic commit author (configurable as "Scaffolder [email protected]")
- The commit message is also configurable ("Initial commit" by default)
- Backstage can set the repository visibility (public/internal/private) based on template input or defaults
- After completion, the user is typically presented with a link to the newly created repository on GitHub

### Submit a Pull Request to an Existing Repository
Some templates are designed to onboard or modify an existing project:
- The template will ask for the target repository (often through a repository picker UI or by entering a URL)
- The Scaffolder will fetch that repo, apply changes, and then use the publish:github action in PR mode
- Rather than directly pushing to main, Backstage can create a new branch with the changes and open a pull request
- The GitHub App needs Contents: write (to push the branch) and Pull requests: write (to open the PR)
- The PR will be created by the GitHub App account (or by the user, if using a user token flow)
- Once merged, Backstage detects the new catalog file and imports the component into the catalog
- This workflow significantly lowers the friction for developers to onboard their services

### Limitations and Considerations
- When using installation tokens, actions are not inherently tied to user permissions
- Any user who can access Backstage could potentially trigger a template that creates or modifies resources
- This could be controlled within Backstage by using its permission framework or by moving to user access tokens
- The Backstage GitHub App approach is primarily geared towards organization-owned repositories
- When the app performs commits or PRs, those actions are attributed to the app's bot user, which can be less transparent
- Consider rate limits and performance: if many users trigger templates around the same time using a single installation token, you're operating within the GitHub App's rate limits

## 4. Default Backstage Integration vs. Manual Token Handling

Backstage can integrate with GitHub in two fundamental ways:
- Using the built-in GitHub App integration (the "default" approach)
- Using manually provided tokens (such as a Personal Access Token or prompting the user for a token)

### Default Integration (GitHub App)
**Advantages**:
- Permissions are fine-grained and centrally controlled
- Avoids using any single user's credentials
- Operates at the organization level rather than a personal level
- Actions are clearly marked as coming from your app/bot and are often signed by GitHub
- Tokens are short-lived and rotated automatically, reducing the risk window of a leaked credential
- End-users need not deal with tokens at all
- Higher rate limits on the API (GitHub Apps get a dedicated quota)
- Cleaner "application" authorization model

**Downsides**:
- The app's credentials are global, creating risk if those credentials were compromised
- By default, the integration might not enforce user-by-user permissions
- Any Backstage user triggering an action will use the app's power

### Manual Token Handling
This refers to scenarios where instead of relying on a GitHub App, you supply tokens manually (e.g., a Personal Access Token stored in app-config.yaml).

**Disadvantages**:
- Less secure and less flexible
- PAT scopes are coarse and don't expire unless revoked
- Cannot easily restrict a PAT to certain organizations or repositories
- All actions appear as the same user, muddling audit trails
- Installed at the user level, which is less ideal for organization-wide tooling
- User-unfriendly if requiring users to provide a PAT for each action
- Insecure if users paste tokens over HTTP or store them in the UI

### Security Comparison
The GitHub App approach adheres to the principle of least privilege better than a PAT:
- Select only the permissions needed for the app
- Any additional permission later needed requires explicit approval
- GitHub Apps use separate trust mechanisms with automatic expiration
- From an auditing standpoint, GitHub App events are attributed to the app and can include which installation made a request
- GitHub explicitly discourages using personal access tokens for app authentication

### Usability and User Experience
The default integration is generally superior for end-users:
- They don't need to know about tokens once SSO is set up
- Everything "just works" after logging in to Backstage
- Higher rate limits and no cap tied to a single user
- Reduces the chance of hitting limits and impacting users

### Trade-offs
- With the default approach, Backstage-generated commits or repositories are created by the app, which is less personal
- If having the actual user's name on actions is important, you'd need to incorporate user access tokens
- The best practice is leaning on the default integration and enabling user-to-server token exchange for user-initiated actions
- Setting up a GitHub App integration requires more work up-front compared to using a PAT

### Best Practices
- Prefer the GitHub App integration for any production or team Backstage instance
- Use the minimal permissions as outlined
- Subscribe to the relevant webhooks for real-time updates
- Store the GitHub App credentials in a secure vault or environment, not in plaintext config
- Configure Backstage's authentication (GitHub OAuth provider) so that users log in with GitHub
- For high-privilege actions, consider using the user's token if available
- Design templates and plugins to respect user permissions
- If using manual tokens, treat them with care and transition to an App when possible
- Monitor usage and apply the principle of least privilege

In summary, the default Backstage GitHub App integration is both more secure and more convenient once set up, compared to manual token handling. It aligns with a modern OAuth model: short-lived, scoped tokens and explicit permissions, versus a static token with broad access. It improves usability by abstracting authentication away from the user and leveraging SSO. The key is ensuring that the power given to Backstage via the app is used responsibly – ideally binding actions to user intent where appropriate.