Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

BEP 0012-device-auth #27680

Closed
wants to merge 5 commits into from
Closed

BEP 0012-device-auth #27680

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
aee0505
add empty bep
phclark Nov 15, 2024
e4db659
add details
phclark Nov 15, 2024
8459df2
added comments
phclark Nov 15, 2024
52bd902
beps/device-auth: fill proposal + ts API out of scope
Rugvip Nov 15, 2024
a3da102
beps/device-auth: spelling fixes
Rugvip Nov 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
beps/device-auth: fill proposal + ts API out of scope 
Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
  • Loading branch information
@Rugvip
Rugvip committed Nov 15, 2024
commit 52bd902ae6c0d81beb4b8a564fe372e2ebfe428c
15 changes: 9 additions & 6 deletions beps/0012-device-auth/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,8 @@
The following are out of scope for this BEP:

- Access delegation, using OAuth providers, such as the ability to acquire a Github token when running a template task.
- Implementation of refresh flow, as we expect future design of the auth signin to make this easier to implement.
- Implementation of refresh flow, as we expect future design of the auth sign-in to make this easier to implement.
- A client implementation for CLIs, including a TypeScript API for CLI developers to use. This requires support for profiles or similar in the CLI, and is considered a future effort.

## Proposal

Expand All @@ -78,6 +79,12 @@
implementation.
-->

The authorization flow is initiated with a user CLI command to `login`. The CLI first performs a request to the authorization token endpoint in the Device Auth Backend API, which returns a device code, user code, and a verification URI. The CLI then displays the device code, user code, and the verification URI to the user, and opens the verification URI in the user's default browser.

When the browser opens the verification page a check is performed to confirm the user has an active Backstage session. If they don't have an active session, a popup is opened by the Backstage Auth plugin for the user to authenticate with the configured Auth Provider. Once this is complete and a valid session is established, the user is able to verify the pre-filled user code by clicking the verify button. Clicking the button to verify the user code sends a request to the CLI Auth Backend API's device_authorization endpoint.

The CLI then polls the Device Auth `/token` endpoint until the user has successfully authenticated with the configured Auth Provider and verified the user code. Once the user has authenticated, the Device Auth Backend API returns the users's Backstage Identity token to the CLI, which is then used to authenticate the user on subsequent called to Backstage Backend APIs.

Check failure on line 86 in beps/0012-device-auth/README.md

View workflow job for this annotation

GitHub Actions / check-all-files 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'users's'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'users's'?", "location": {"path": "beps/0012-device-auth/README.md", "range": {"start": {"line": 86, "column": 235}}}, "severity": "ERROR"}

## Design Details

<!--
Expand All @@ -86,11 +93,7 @@
If there's any ambiguity about HOW your proposal will be implemented, this is the place to discuss them.
-->

The authorization flow is initiated with a user CLI command to `login`. The CLI first performs a request to the authorization token endpoint in the Device Auth Backend API, which returns a device code, user code, and a verification URI. The CLI then displays the device code, user code, and the verification URI to the user, and opens the verification URI in the user's default browser.

When the browser opens the verification page a check is performed to confirm the user has an active Backstage session. If they don't have an active session, a popup is opened by the Backstage Auth plugin for the user to authenticate with the configured Auth Provider. Once this is complete and a valid session is established, the user is able to verify the pre-filled user code by clicking the verify button. Clicking the button to verify the user code sends a request to the CLI Auth Backend API's device_authorization endpoint.

The CLI then polls the Device Auth `/token` endpoint until the user has successfully authenticated with the configured Auth Provider and verified the user code. Once the user has authenticated, the Device Auth Backend API returns the users's Backstage Identity token to the CLI, which is then used to authenticate the user on subsequent called to Backstage Backend APIs.
### Sequence Diagram

```mermaid
sequenceDiagram
Expand Down Expand Up @@ -240,7 +243,7 @@

### State Management

The CLI Auth backend must store the device code and user code in state in order to determine if the user has verified the user code. This state could technically live in any storage mechanism, such as memory, file, database, or external cache. The state should be stored in a way that is accessible by all instances of the CLI Auth backend API, as the CLI may be running in multiple instances. Given this requirement, the state should be stored in a shared database or cache. While it possible to use an external cache, such as Redis, for this purpose, there is no guarentee that the cache will be secure (e.g. if the cache is not encrypted or authenticated). Therefore, it is recommended to store the state in a the Backstage database, where Backstage itself stores its secure state.

Check failure on line 246 in beps/0012-device-auth/README.md

View workflow job for this annotation

GitHub Actions / check-all-files 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'guarentee'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'guarentee'?", "location": {"path": "beps/0012-device-auth/README.md", "range": {"start": {"line": 246, "column": 566}}}, "severity": "ERROR"}

### Security Considerations

Expand Down