From 52b63082e12de5024058c9e7cd1ca7abb63dbb6d Mon Sep 17 00:00:00 2001 From: phac008 Date: Thu, 14 Nov 2024 17:00:44 +0100 Subject: [PATCH 1/6] base info about backstage authorization and integration Signed-off-by: phac008 --- backstage-resources/entities/uibklab/showcase-templates.yaml | 1 + backstage-resources/mkdocs.yaml | 1 + 2 files changed, 2 insertions(+) diff --git a/backstage-resources/entities/uibklab/showcase-templates.yaml b/backstage-resources/entities/uibklab/showcase-templates.yaml index f5b280b54..8622b0c95 100644 --- a/backstage-resources/entities/uibklab/showcase-templates.yaml +++ b/backstage-resources/entities/uibklab/showcase-templates.yaml @@ -7,3 +7,4 @@ spec: type: url targets: - https://github.com/suxess-it/sx-cnp-oss/blob/main/backstage-resources/templates/scaffolder-templates/sx-virt-template/template.yaml + - https://github.com/suxess-it/sx-cnp-oss/blob/main/backstage-resources/templates/scaffolder-templates/sx-virt-template/template.yaml \ No newline at end of file diff --git a/backstage-resources/mkdocs.yaml b/backstage-resources/mkdocs.yaml index 1a990a1be..53e8ecdde 100644 --- a/backstage-resources/mkdocs.yaml +++ b/backstage-resources/mkdocs.yaml @@ -15,6 +15,7 @@ nav: - Backup and Recovery: grc/backuprecovery.md - Identity and Access Management: grc/iam.md - RBAC Portal: grc/rbacportal.md + - Backstage Authorization and Integration: grc/backstage_auth.md - Application Migration: - Migration Process Steps: application-migration/migration-process.md - Learning Path for Developers: application-migration/learning-path.md From f42023043c030a7f96e7add0823d491e649ad802 Mon Sep 17 00:00:00 2001 From: phac008 Date: Thu, 14 Nov 2024 17:03:01 +0100 Subject: [PATCH 2/6] base info about backstage authorization and integration Signed-off-by: phac008 --- .../docs/grc/backstage_auth.md | 112 ++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 backstage-resources/docs/grc/backstage_auth.md diff --git a/backstage-resources/docs/grc/backstage_auth.md b/backstage-resources/docs/grc/backstage_auth.md new file mode 100644 index 000000000..28be9943a --- /dev/null +++ b/backstage-resources/docs/grc/backstage_auth.md @@ -0,0 +1,112 @@ +# Authentication/Integration in Backstage + +In this document we give an overview how Backstage Authentication/Integration works + +Base information: +[Authorization](https://backstage.io/docs/auth/) +[Integration](https://backstage.io/docs/integrations/) + +## Authorization +### Purpose +- Sign-in and identification of users +- Delegating access to 3rd party resources + +There are several build-in auth providers build-in in, also custom providers are possible. Only "one" will be used for sign-in, the rest provides access to external resources. +For different showcases we have 2 different providers active in kubriX demo - GitHub and oidc/keyloak + +``` +auth: + environment: development + providers: + github: + development: + clientId: ${GITHUB_CLIENT_ID} + clientSecret: ${GITHUB_CLIENT_SECRET} + oidc: + development: + metadataUrl: http://keycloak-service.keycloak.svc.cluster.local:8080/realms/sx-cnp-oss #.well-known/openid-configuration can be ommited + callbackUrl: https://backstage.lab.suxessit.k8s.cloud.uibk.ac.at/api/auth/oidc/handler/frame + clientId: backstage +``` +GitHub secrets created by oauth app, alternativly they can get created by GitHub App. + +### HINT +[Base Information](https://backstage.io/docs/integrations/github/github-apps) + + Difference between GitHub Apps and GitHub OAuth Apps + GitHub Apps handle OAuth scope at the app installation level, meaning that the scope parameter for the call to getAccessToken in the frontend has no effect. When calling getAccessToken in open source plugins, one should still include the appropriate scope, but also document in the plugin README what scopes are required for GitHub Apps. + +Autorization Needs Frontend and Backend configuration +- Backend: https://backstage.io/docs/auth/identity-resolver/ +- Frontend: SignInPage + +### Scenarios +- Authenticate Users to Backstage using their Github accounts + - User Login +- Perform API Actions on behalf of authenticated users, utilizing their permissions + - Opening a PR or creating an Issue in behalf of a user +- Access data that may require user specific scopes or to act as the user + - User repositories, contributions + +#### Required Scopes +- read:user: Access basic profile information +- user:email: Access the user’s email addresses +- repo: Access private repositories (if needed) +- workflow: Access GitHub Actions workflows (if needed) +- write:discussion: For creating or managing discussions (if your Backstage setup involves GitHub Discussions) + +### Scaffolder +[Integration by default](https://backstage.io/docs/auth/identity-resolver) + +### Token issuer +Authentication backend generates and manages its own signing keys automatically for any issued backstage token +The have short lifetime and do not persist after instance restarts! + +[Solution for this](https://backstage.io/docs/auth/#configuring-token-issuers) + +## Integrations + +### Purpose: +- Service account for automated GitHub API Requests +- Allow Backstage to read or publish data using external providers (Github, Gitlab,…) +- Performing static, non-user-specific tasks, such as reading repo data, fethcing org information or indexing repos + +For github (located at root level in app-config.yaml since it is used by many Backstage core features) +``` +integrations: + github: + - host: github.com + token: ${GITHUB_TOKEN} +``` + +### Scenarios +- Github discovery processor + - Scanning Github Repos for catalog files +- Github API requests + - Where admin don't want user specific access +- CI/CD pipelines interacting with GitHub via Backstage +- Backstage scanning GitHub repos and does not need user authentication (sign-in) +- Running Github integration Plugin, that requires persistent access to certain data +- Fetching GitHub Actions logs for a Backstage plugin: Use a PAT with workflow scope. + +#### Required Scopes +- repo: Full control of private repositories (read/write) +- read:org: Read access to organization membership +- admin:org: If the token needs to manage organization settings (rare) +- read:discussion: To read GitHub Discussions +- workflow: To access workflow runs and logs +- write:packages: If interacting with GitHub Packages + +## GitHub comparison +|Feature|GitHub OAuth App|GitHub PAT| +| ------ | ------ | ------ | +|User Athentication|✅ Yes|❌ No| +|Delegated User Permission|✅ Yes(based on user scopes)|❌ No| +|Access to Private Repos|✅ Yes(if user grants access)|✅ Yes (with repo scope)| +|Machine to GitHub API Access|❌ Limited (depends on user)|✅ Yes (using Service Account)| +|CI/CD integration|❌ No, not ideal!|✅ Yes| +|Setup Complexity|Medium|Low| + +## Best Practices Shorty +- Use **OAuth App** for user-related actions, user authentication, and any actions that need to happen on **behalf of a user**. +- Use **PAT** for service-level access where **user context is not required**, such as scanning repositories, reading data, or performing automated tasks. From e4f7473368f556099eac4d07317b7680d8c8051a Mon Sep 17 00:00:00 2001 From: phac008 Date: Fri, 15 Nov 2024 08:38:03 +0100 Subject: [PATCH 3/6] some minor changes Signed-off-by: phac008 --- .../docs/grc/backstage_auth.md | 28 ++++++++++--------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/backstage-resources/docs/grc/backstage_auth.md b/backstage-resources/docs/grc/backstage_auth.md index 28be9943a..92f2071c5 100644 --- a/backstage-resources/docs/grc/backstage_auth.md +++ b/backstage-resources/docs/grc/backstage_auth.md @@ -1,18 +1,18 @@ # Authentication/Integration in Backstage -In this document we give an overview how Backstage Authentication/Integration works +This document should give an overview how Backstage Authentication/Integration works in kubriX Environment -Base information: -[Authorization](https://backstage.io/docs/auth/) -[Integration](https://backstage.io/docs/integrations/) +backstage.io documentation link: +- [Authorization](https://backstage.io/docs/auth/) +- [Integration](https://backstage.io/docs/integrations/) ## Authorization ### Purpose - Sign-in and identification of users - Delegating access to 3rd party resources -There are several build-in auth providers build-in in, also custom providers are possible. Only "one" will be used for sign-in, the rest provides access to external resources. -For different showcases we have 2 different providers active in kubriX demo - GitHub and oidc/keyloak +There are several build-in auth providers, also custom providers are possible. Only "one" will/should be used for sign-in, the rest provide access to external resources. +For different showcases we have currently 2 providers active in our kubriX demo - GitHub and OIDC via Keyloak Instance ``` auth: @@ -28,10 +28,10 @@ auth: callbackUrl: https://backstage.lab.suxessit.k8s.cloud.uibk.ac.at/api/auth/oidc/handler/frame clientId: backstage ``` -GitHub secrets created by oauth app, alternativly they can get created by GitHub App. +GitHub secrets created by oauth app, alternativly they can get created by GitHub App: -### HINT -[Base Information](https://backstage.io/docs/integrations/github/github-apps) +#### HINT +[backstage.io documentation link](https://backstage.io/docs/integrations/github/github-apps) Difference between GitHub Apps and GitHub OAuth Apps GitHub Apps handle OAuth scope at the app installation level, meaning that the scope parameter for the call to getAccessToken in the frontend has no effect. When calling getAccessToken in open source plugins, one should still include the appropriate scope, but also document in the plugin README what scopes are required for GitHub Apps. @@ -40,7 +40,7 @@ Autorization Needs Frontend and Backend configuration - Backend: https://backstage.io/docs/auth/identity-resolver/ - Frontend: SignInPage -### Scenarios +### Scenario Examples - Authenticate Users to Backstage using their Github accounts - User Login - Perform API Actions on behalf of authenticated users, utilizing their permissions @@ -56,13 +56,15 @@ Autorization Needs Frontend and Backend configuration - write:discussion: For creating or managing discussions (if your Backstage setup involves GitHub Discussions) ### Scaffolder -[Integration by default](https://backstage.io/docs/auth/identity-resolver) +Integrated by default +[backstage.io documentation link](https://backstage.io/docs/auth/identity-resolver) ### Token issuer Authentication backend generates and manages its own signing keys automatically for any issued backstage token The have short lifetime and do not persist after instance restarts! -[Solution for this](https://backstage.io/docs/auth/#configuring-token-issuers) +tbd - solution for this +[backstage.io documentation link](https://backstage.io/docs/auth/#configuring-token-issuers) ## Integrations @@ -79,7 +81,7 @@ integrations: token: ${GITHUB_TOKEN} ``` -### Scenarios +### Scenario Example - Github discovery processor - Scanning Github Repos for catalog files - Github API requests From 9fe2ad377d18cbb2771d8532f945c245ca19228a Mon Sep 17 00:00:00 2001 From: phac008 Date: Fri, 15 Nov 2024 08:39:28 +0100 Subject: [PATCH 4/6] remove specific url Signed-off-by: phac008 --- backstage-resources/docs/grc/backstage_auth.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/backstage-resources/docs/grc/backstage_auth.md b/backstage-resources/docs/grc/backstage_auth.md index 92f2071c5..51cb7036c 100644 --- a/backstage-resources/docs/grc/backstage_auth.md +++ b/backstage-resources/docs/grc/backstage_auth.md @@ -25,7 +25,7 @@ auth: oidc: development: metadataUrl: http://keycloak-service.keycloak.svc.cluster.local:8080/realms/sx-cnp-oss #.well-known/openid-configuration can be ommited - callbackUrl: https://backstage.lab.suxessit.k8s.cloud.uibk.ac.at/api/auth/oidc/handler/frame + callbackUrl: https:///api/auth/oidc/handler/frame clientId: backstage ``` GitHub secrets created by oauth app, alternativly they can get created by GitHub App: From dee5c80ccd1f77fb03941531298e7cbbb8fe4894 Mon Sep 17 00:00:00 2001 From: phac008 Date: Fri, 15 Nov 2024 08:40:51 +0100 Subject: [PATCH 5/6] remove unused provider Signed-off-by: phac008 --- backstage-resources/docs/grc/backstage_auth.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/backstage-resources/docs/grc/backstage_auth.md b/backstage-resources/docs/grc/backstage_auth.md index 51cb7036c..b9bfced0f 100644 --- a/backstage-resources/docs/grc/backstage_auth.md +++ b/backstage-resources/docs/grc/backstage_auth.md @@ -70,7 +70,7 @@ tbd - solution for this ### Purpose: - Service account for automated GitHub API Requests -- Allow Backstage to read or publish data using external providers (Github, Gitlab,…) +- Allow Backstage to read or publish data using external providers (Github,…) - Performing static, non-user-specific tasks, such as reading repo data, fethcing org information or indexing repos For github (located at root level in app-config.yaml since it is used by many Backstage core features) From 035c0ba8f93f032b8a47fb9e733362a3c20d2a75 Mon Sep 17 00:00:00 2001 From: phac008 Date: Tue, 19 Nov 2024 09:11:15 +0100 Subject: [PATCH 6/6] adapt comments from draft Signed-off-by: phac008 --- .../docs/grc/backstage_auth.md | 36 ++++++++++--------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/backstage-resources/docs/grc/backstage_auth.md b/backstage-resources/docs/grc/backstage_auth.md index b9bfced0f..78d271d66 100644 --- a/backstage-resources/docs/grc/backstage_auth.md +++ b/backstage-resources/docs/grc/backstage_auth.md @@ -1,12 +1,12 @@ # Authentication/Integration in Backstage -This document should give an overview how Backstage Authentication/Integration works in kubriX Environment +This document should give an overview how Backstage Authentication/Integration works in general and how we use that in kubriX environment backstage.io documentation link: -- [Authorization](https://backstage.io/docs/auth/) +- [Authentication](https://backstage.io/docs/auth/) - [Integration](https://backstage.io/docs/integrations/) -## Authorization +## Authentication ### Purpose - Sign-in and identification of users - Delegating access to 3rd party resources @@ -28,15 +28,15 @@ auth: callbackUrl: https:///api/auth/oidc/handler/frame clientId: backstage ``` -GitHub secrets created by oauth app, alternativly they can get created by GitHub App: +GitHub secrets GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET are created by oauth app, alternativly they can get created by GitHub App: #### HINT [backstage.io documentation link](https://backstage.io/docs/integrations/github/github-apps) - Difference between GitHub Apps and GitHub OAuth Apps - GitHub Apps handle OAuth scope at the app installation level, meaning that the scope parameter for the call to getAccessToken in the frontend has no effect. When calling getAccessToken in open source plugins, one should still include the appropriate scope, but also document in the plugin README what scopes are required for GitHub Apps. +Difference between GitHub Apps and GitHub OAuth Apps: +GitHub Apps handle OAuth scope at the app installation level, meaning that the scope parameter for the call to getAccessToken in the frontend has no effect. When calling getAccessToken in open source plugins, one should still include the appropriate scope, but also document in the plugin README what scopes are required for GitHub Apps. -Autorization Needs Frontend and Backend configuration +Authentication needs frontend and backend configuration - Backend: https://backstage.io/docs/auth/identity-resolver/ - Frontend: SignInPage @@ -56,22 +56,26 @@ Autorization Needs Frontend and Backend configuration - write:discussion: For creating or managing discussions (if your Backstage setup involves GitHub Discussions) ### Scaffolder -Integrated by default -[backstage.io documentation link](https://backstage.io/docs/auth/identity-resolver) +Integrated Identity Resolver | [backstage.io documentation link](https://backstage.io/docs/features/software-templates/writing-templates#accessing-the-signed-in-users-details) + +Integrated Authentication Capabilities | [backstage.io documentation link](https://backstage.io/docs/auth/#scaffolder-configuration-software-templates) + +tbd - access crontrol to certain parameter +[Scaffolder and Permission framework](https://backstage.io/docs/features/software-templates/authorizing-scaffolder-template-details) ### Token issuer Authentication backend generates and manages its own signing keys automatically for any issued backstage token -The have short lifetime and do not persist after instance restarts! +They have short lifetime and do not persist after instance restarts! tbd - solution for this [backstage.io documentation link](https://backstage.io/docs/auth/#configuring-token-issuers) ## Integrations -### Purpose: +### Purpose - Service account for automated GitHub API Requests - Allow Backstage to read or publish data using external providers (Github,…) -- Performing static, non-user-specific tasks, such as reading repo data, fethcing org information or indexing repos +- Performing static, non-user-specific tasks, such as reading repo data, fetching org information or indexing repos For github (located at root level in app-config.yaml since it is used by many Backstage core features) ``` @@ -89,7 +93,7 @@ integrations: - CI/CD pipelines interacting with GitHub via Backstage - Backstage scanning GitHub repos and does not need user authentication (sign-in) - Running Github integration Plugin, that requires persistent access to certain data -- Fetching GitHub Actions logs for a Backstage plugin: Use a PAT with workflow scope. +- Fetching GitHub Actions logs for a Backstage plugin #### Required Scopes - repo: Full control of private repositories (read/write) @@ -109,6 +113,6 @@ integrations: |CI/CD integration|❌ No, not ideal!|✅ Yes| |Setup Complexity|Medium|Low| -## Best Practices Shorty -- Use **OAuth App** for user-related actions, user authentication, and any actions that need to happen on **behalf of a user**. -- Use **PAT** for service-level access where **user context is not required**, such as scanning repositories, reading data, or performing automated tasks. +## Best Practices in kubriX environment +- We use **OAuth App** for user-related actions, user authentication, and any actions that need to happen on **behalf of a user**. +- Use **PAT** for service-level access where **user context is not required**, such as scanning repositories, reading data, or performing automated tasks. \ No newline at end of file