Skip to content

Commit 4cd6298

Browse files
batzionbbatzionb
authored
docs(orchestrator): auth widget doc improvement (#982)
* docs(orchestrator): added section on required workflow application.properties configuration and more improvements * fix following code review and added section about backstage auth config requirement
1 parent d208ebf commit 4cd6298

1 file changed

Lines changed: 53 additions & 75 deletions

File tree

  • workspaces/orchestrator/docs

‎workspaces/orchestrator/docs/auth.md‎

Lines changed: 53 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -1,80 +1,57 @@
11
# Requesting Authentication in Workflow Input Schema
22

3-
This guide explains how to declare authentication requirements in a SonataFlow workflow input schema. This is necessary when a workflow interacts with external APIs that require user authorization — such as GitHub, GitLab, or Microsoft Graph.
4-
5-
Common use cases include:
6-
7-
- Creating a GitHub pull request
8-
- Accessing private GitLab repositories
9-
- Calling Microsoft Graph APIs on behalf of the user
3+
This guide explains how to declare authentication requirements in a SonataFlow workflow input schema for the orchestrator plugin. It enables workflows to access external APIs on behalf of the user by forwarding authentication tokens from the user’s active Backstage session to SonataFlow.
104

115
## Key Concept
126

13-
To request tokens, you define a **virtual field** in the input schema that triggers Backstage’s authentication system. This field:
14-
15-
- Does **not appear** in the form
16-
- Is **not persisted** or included in the workflow input data
17-
- Can have **any field name**
18-
- Uses a special widget to signal token requirements
19-
20-
## What Matters
7+
To request tokens, you define a **virtual field** in the workflow’s input schema that triggers Backstage’s authentication system. Once tokens are obtained, Backstage forwards them to the SonataFlow `execute` API as HTTP headers. These headers must match the configuration defined in the workflow’s OpenAPI specification.
218

22-
Only the following properties control behavior:
9+
## Workflow Header Configuration
2310

24-
- `"ui:widget": "AuthRequester"` — activates token acquisition
25-
- `"ui:props.authTokenDescriptors"` — declares which tokens and scopes are needed
11+
These are the headers Backstage will send:
2612

27-
All other properties are either ignored or required solely for schema validity.
13+
| Provider | Header |
14+
| --------- | --------------------------- |
15+
| GitHub | `X-Github-Authorization` |
16+
| GitLab | `X-Gitlab-Authorization` |
17+
| Microsoft | `X-Microsoft-Authorization` |
2818

29-
## Example Schema
19+
### Example `application.properties` Configuration
3020

31-
```json
32-
{
33-
"anyFieldName": {
34-
"type": "string",
35-
"ui:widget": "AuthRequester",
36-
"ui:props": {
37-
"authTokenDescriptors": [
38-
{
39-
"provider": "github",
40-
"tokenType": "oauth",
41-
"scope": "repo"
42-
}
43-
]
44-
}
45-
}
46-
}
21+
```
22+
quarkus.openapi-generator.github_yaml.auth.BearerToken.token-propagation=true
23+
quarkus.openapi-generator.github_yaml.auth.BearerToken.header-name=X-Github-Authorization
4724
```
4825

49-
### ✅ Field name: can be anything
50-
51-
### ✅ `type`: required only for schema validation
26+
> 🔗 See the [SonataFlow token propagation documentation](https://www.rhdhorchestrator.io/main/docs/serverless-workflows/configuration/token-propagation/) for more details.
5227
53-
### ✅ `ui:widget`: must be `"AuthRequester"`
28+
## Input Schema AuthRequester Field
5429

55-
### ✅ `ui:props.authTokenDescriptors`: required
30+
### Field Behavior
5631

57-
## Field Definition Reference
32+
- Does **not appear** in the form
33+
- Is **not persisted** or included in the workflow input data
34+
- Can have **any field name**
35+
- Must **not be listed** in the schema's `required` array
36+
- Only one `AuthRequester` field is needed, even for multiple providers. If multiple are included, only one will be applied.
5837

5938
### Required JSON Schema Properties
6039

61-
| Property | Type | Required | Description |
62-
| -------- | ------ | -------- | ------------------------------------ |
63-
| `type` | string | Yes | Must be included for schema validity |
40+
`type` – use the value `string` just for schema validity.
6441

6542
### UI Schema (`ui:widget` and `ui:props`)
6643

67-
| Property | Type | Required | Description |
68-
| ------------------------------- | ------------------ | -------- | --------------------------------------------------------------------- |
69-
| `ui:widget` | string | Yes | Must be `"AuthRequester"` |
70-
| `ui:props.authTokenDescriptors` | array of objects | Yes | List of token requirements |
71-
| — `provider` | string | Yes | One of `github`, `gitlab`, `microsoft` |
72-
| — `tokenType` | string | Yes | `"oauth"` or `"openId"` |
73-
| — `scope` | string or string[] | Optional | Scope or scopes to request, e.g., `"repo"` or `["repo", "read:user"]` |
44+
| Property | Type | Required | Description |
45+
| ------------------------------- | ------------------ | -------- | -------------------------------------------------------------- |
46+
| `ui:widget` | string | Yes | Must be `"AuthRequester"` |
47+
| `ui:props.authTokenDescriptors` | array of objects | Yes | List of token requirements |
48+
| — `provider` | string | Yes | One of `github`, `gitlab`, `microsoft` |
49+
| — `tokenType` | string | Yes | `"oauth"` or `"openId"` |
50+
| — `scope` | string or string[] | Optional | Scope(s) to request, e.g., `"repo"` or `["repo", "read:user"]` |
7451

75-
## Multiple Providers Example
52+
## Example
7653

77-
```json
54+
```
7855
{
7956
"authSetup": {
8057
"type": "string",
@@ -96,20 +73,20 @@ All other properties are either ignored or required solely for schema validity.
9673
}
9774
```
9875

99-
In this example, the form will trigger login/token requests for GitHub and Microsoft, using the specified scopes where given.
76+
In this example, the form will trigger the login popup for GitHub and Microsoft, using the specified scopes where given. If the user is already logged in with the specified scopes, the popup will not appear, and the tokens from earlier login will be propagated.
10077

101-
## About `tokenType`
78+
## `tokenType` details
10279

10380
The `tokenType` field defines which type of token Backstage should return:
10481

105-
| `tokenType` | Description |
106-
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
107-
| `"oauth"` | Retrieves an **OAuth access token** — Uses backstage [`getAccessToken`](https://backstage.io/docs/reference/core-app-api.oauth2.getaccesstoken/). |
108-
| `"openId"` | Retrieves an **ID token** (OpenID Connect) — used mainly for identity verification. Uses backstage [`getIdToken`](https://backstage.io/docs/reference/core-app-api.oauth2.getidtoken/). |
82+
| `tokenType` | Description |
83+
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
84+
| `"oauth"` | Retrieves an **OAuth access token** — Uses Backstage [getAccessToken](https://backstage.io/docs/reference/core-app-api.oauth2.getaccesstoken/). |
85+
| `"openId"` | Retrieves an **ID token** (OpenID Connect) — used mainly for identity verification. Uses Backstage [getIdToken](https://backstage.io/docs/reference/core-app-api.oauth2.getidtoken/). |
10986

110-
> ⚠️ Github backstage OAuth provider doesn't support openId tokens.
87+
> ⚠️ GitHub's Backstage OAuth provider does **not** support `openId` tokens.
11188
112-
## About Scopes
89+
## Scopes details
11390

11491
When specifying the `scope` field, refer to the official documentation for available scopes and their meanings:
11592

@@ -121,9 +98,9 @@ GitHub scopes control access to repositories, user data, and other GitHub featur
12198

12299
**Examples:**
123100

124-
- `"repo"` – Full control of private and public repositories
125-
- `"read:user"` – Read profile info
126-
- `"workflow"` – Access GitHub Actions
101+
- "repo" – Full control of private and public repositories
102+
- "read:user" – Read profile info
103+
- "workflow" – Access GitHub Actions
127104

128105
---
129106

@@ -135,9 +112,9 @@ GitLab scopes are used in OAuth and determine what actions the token allows.
135112

136113
**Examples:**
137114

138-
- `"read_user"` – Read user profile
139-
- `"api"` – Full API access
140-
- `"write_repository"` – Push access
115+
- "read_user" – Read user profile
116+
- "api" – Full API access
117+
- "write_repository" – Push access
141118

142119
---
143120

@@ -149,13 +126,14 @@ Microsoft tokens usually access Microsoft Graph, covering users, calendar, mail,
149126

150127
**Examples:**
151128

152-
- `"User.Read"` – Read user profile
153-
- `"Mail.Read"` – Read email
154-
- `"Calendars.Read"` – Read calendar events
129+
- "User.Read" – Read user profile
130+
- "Mail.Read" – Read email
131+
- "Calendars.Read" – Read calendar events
155132

156-
---
133+
## ⚙️ Required Backstage Auth Configuration
157134

158-
## Notes
135+
To use this feature, the relevant authentication providers must be properly configured in your Backstage app. This ensures the necessary tokens can be obtained when the workflow requests them. Each provider must be declared under the `auth.providers` section in `app-config.yaml`.
159136

160-
- Only one `AuthRequester` field is needed per form, even for multiple providers. If multiple ones are included, only one of them will be applied.
161-
- Never rely on the value of this field — it will always be `undefined`.
137+
- [Backstage GitHub Auth Provider](https://backstage.io/docs/auth/github/provider)
138+
- [Backstage GitLab Auth Provider](https://backstage.io/docs/auth/gitlab/provider)
139+
- [Backstage Microsoft Auth Provider](https://backstage.io/docs/auth/microsoft/provider)

0 commit comments

Comments
 (0)