Skip to content

Commit da403c1

Browse files
batzionbbatzionb
authored
docs(orchestrator): add documentation for using the auth requester widget (#976)
* docs(orchestrator): add documentation for using the auth requester widget * improvements following comments
1 parent 218c868 commit da403c1

2 files changed

Lines changed: 165 additions & 0 deletions

File tree

‎workspaces/orchestrator/README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -211,6 +211,10 @@ For more information about audit logs in RHDH, please refer to [the official doc
211211

212212
The `orchestrator` plugin includes an extensible form for executing workflows. Details are available in the [extensible form documentation](./docs/extensibleForm.md).
213213

214+
### Authentication in Workflows
215+
216+
Workflows that call external APIs requiring authentication can request tokens in the input schema — [see docs/auth.md](docs/auth.md) for details.
217+
214218
## Run locally from this repo
215219

216220
The orchestrator workspace is structured like a standard backstage application. To get it up and running locally run the following:

‎workspaces/orchestrator/docs/auth.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# Requesting Authentication in Workflow Input Schema
2+
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
10+
11+
## Key Concept
12+
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
21+
22+
Only the following properties control behavior:
23+
24+
- `"ui:widget": "AuthRequester"` — activates token acquisition
25+
- `"ui:props.authTokenDescriptors"` — declares which tokens and scopes are needed
26+
27+
All other properties are either ignored or required solely for schema validity.
28+
29+
## Example Schema
30+
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+
}
47+
```
48+
49+
### ✅ Field name: can be anything
50+
51+
### ✅ `type`: required only for schema validation
52+
53+
### ✅ `ui:widget`: must be `"AuthRequester"`
54+
55+
### ✅ `ui:props.authTokenDescriptors`: required
56+
57+
## Field Definition Reference
58+
59+
### Required JSON Schema Properties
60+
61+
| Property | Type | Required | Description |
62+
| -------- | ------ | -------- | ------------------------------------ |
63+
| `type` | string | Yes | Must be included for schema validity |
64+
65+
### UI Schema (`ui:widget` and `ui:props`)
66+
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"]` |
74+
75+
## Multiple Providers Example
76+
77+
```json
78+
{
79+
"authSetup": {
80+
"type": "string",
81+
"ui:widget": "AuthRequester",
82+
"ui:props": {
83+
"authTokenDescriptors": [
84+
{
85+
"provider": "github",
86+
"tokenType": "oauth",
87+
"scope": ["repo", "read:user"]
88+
},
89+
{
90+
"provider": "microsoft",
91+
"tokenType": "openId"
92+
}
93+
]
94+
}
95+
}
96+
}
97+
```
98+
99+
In this example, the form will trigger login/token requests for GitHub and Microsoft, using the specified scopes where given.
100+
101+
## About `tokenType`
102+
103+
The `tokenType` field defines which type of token Backstage should return:
104+
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/). |
109+
110+
> ⚠️ Github backstage OAuth provider doesn't support openId tokens.
111+
112+
## About Scopes
113+
114+
When specifying the `scope` field, refer to the official documentation for available scopes and their meanings:
115+
116+
### GitHub
117+
118+
GitHub scopes control access to repositories, user data, and other GitHub features.
119+
120+
- [GitHub OAuth scopes](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps)
121+
122+
**Examples:**
123+
124+
- `"repo"` – Full control of private and public repositories
125+
- `"read:user"` – Read profile info
126+
- `"workflow"` – Access GitHub Actions
127+
128+
---
129+
130+
### GitLab
131+
132+
GitLab scopes are used in OAuth and determine what actions the token allows.
133+
134+
- [GitLab OAuth 2 scopes](https://docs.gitlab.com/integration/oauth_provider/#view-all-authorized-applications)
135+
136+
**Examples:**
137+
138+
- `"read_user"` – Read user profile
139+
- `"api"` – Full API access
140+
- `"write_repository"` – Push access
141+
142+
---
143+
144+
### Microsoft
145+
146+
Microsoft tokens usually access Microsoft Graph, covering users, calendar, mail, Teams, and more.
147+
148+
- [Microsoft Graph permissions reference](https://learn.microsoft.com/en-us/graph/permissions-reference)
149+
150+
**Examples:**
151+
152+
- `"User.Read"` – Read user profile
153+
- `"Mail.Read"` – Read email
154+
- `"Calendars.Read"` – Read calendar events
155+
156+
---
157+
158+
## Notes
159+
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`.

0 commit comments

Comments
 (0)