Skip to content

Commit b45bb12

Browse files
AnuradhaSKAnuradhaSK
authored
Merge pull request #5030 from BimsaraBodaragama/fix-2/user-sharing-api-is-7.1
[Docs][API][IS]Refactor User Sharing API Specification to Improve Security and Documentation
2 parents 86dbdbe + 3b24fb9 commit b45bb12

File tree

2 files changed

+286
-28
lines changed

2 files changed

+286
-28
lines changed

‎en/identity-server/next/docs/apis/organization-apis/restapis/organization-user-share.yaml‎

Lines changed: 144 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,13 @@
11
openapi: 3.0.0
22
info:
3-
version: v1
3+
version: "v1"
44
title: 'User Sharing API Definition'
55
description: |-
6-
This API provides organization administrators with the ability to manage user access across child organizations. It supports operations to share users with specific or all child organizations, retrieve shared access details, and remove shared access as needed. The API also includes features for paginated retrieval of organizations and roles associated with shared users.
7-
contact:
8-
name: WSO2
9-
url: 'http://wso2.com/products/identity-server/'
10-
email: iam-dev@wso2.org
11-
license:
12-
name: Apache 2.0
13-
url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
6+
This document specifies the **User Sharing RESTful API** for **WSO2 Identity Server**. This API enables organization administrators to share user access across child organizations, manage shared access, revoke access, and retrieve shared organizations and roles.
7+
8+
security:
9+
- OAuth2: []
10+
1411
servers:
1512
- url: 'https://{server-url}/t/{tenant-domain}/api/server/v1'
1613
variables:
@@ -27,7 +24,7 @@ paths:
2724
description: |
2825
This API shares one or more users across specified organizations, assigning roles based on the provided policy. The policy defines the sharing scope for each organization, including whether access extends to child organizations.
2926
30-
<b>Scope(Permission) required:</b> `internal_user_share`
27+
<b>Scope(Permission) required:</b> `internal_org_user_share`
3128
operationId: processUserSharing
3229
requestBody:
3330
content:
@@ -48,7 +45,7 @@ paths:
4845
display: "My Org 1"
4946
type: "organization"
5047
- orgId: "a17b28ca-9f89-449c-ae27-fa955e66465f"
51-
policy: "SELECTED_ORG_ONLY"
48+
policy: "SELECTED_ORG_WITH_EXISTING_IMMEDIATE_AND_FUTURE_CHILDREN"
5249
roles: []
5350
required: true
5451
responses:
@@ -70,6 +67,42 @@ paths:
7067
application/json:
7168
schema:
7269
$ref: '#/components/schemas/Error'
70+
x-codeSamples:
71+
- lang: Curl
72+
source: |
73+
curl --location 'https://localhost:9443/o/api/server/v1/users/share' \
74+
-H 'Accept: application/json' \
75+
-H 'Content-Type: application/json' \
76+
-H 'Authorization: Bearer {bearer_token}' \
77+
-d '{
78+
"userCriteria": {
79+
"userIds": [
80+
"7a1b7d63-8cfc-4dc9-9332-3f84641b72d8",
81+
"5d2a1c84-9f7a-43cd-b12e-6e52d7f87e16"
82+
]
83+
},
84+
"organizations": [
85+
{
86+
"orgId": "b028ca17-8f89-449c-ae27-fa955e66465d",
87+
"policy": "SELECTED_ORG_ONLY",
88+
"roles": [
89+
{
90+
"displayName": "role_2",
91+
"audience": {
92+
"display": "My Org 1",
93+
"type": "organization"
94+
}
95+
}
96+
]
97+
},
98+
{
99+
"orgId": "a17b28ca-9f89-449c-ae27-fa955e66465f",
100+
"policy": "SELECTED_ORG_WITH_EXISTING_IMMEDIATE_AND_FUTURE_CHILDREN",
101+
"roles": []
102+
}
103+
]
104+
}'
105+
x-codegen-request-body-name: body
73106

74107
/users/share-with-all:
75108
post:
@@ -79,7 +112,7 @@ paths:
79112
description: |
80113
This API shares users across all organizations, applying the provided roles to each organization. The policy determines the scope of sharing, including whether it applies to all current organizations or future organizations as well.
81114
82-
<b>Scope(Permission) required:</b> `internal_user_share`
115+
<b>Scope(Permission) required:</b> `internal_org_user_share`
83116
operationId: processUserSharingAll
84117
requestBody:
85118
content:
@@ -121,6 +154,39 @@ paths:
121154
application/json:
122155
schema:
123156
$ref: '#/components/schemas/Error'
157+
x-codeSamples:
158+
- lang: Curl
159+
source: |
160+
curl --location 'https://localhost:9443/o/api/server/v1/users/share-all' \
161+
-H 'Accept: application/json' \
162+
-H 'Content-Type: application/json' \
163+
-H 'Authorization: Bearer {bearer_token}' \
164+
-d '{
165+
"userCriteria": {
166+
"userIds": [
167+
"7a1b7d63-8cfc-4dc9-9332-3f84641b72d8",
168+
"5d2a1c84-9f7a-43cd-b12e-6e52d7f87e16"
169+
]
170+
},
171+
"policy": "ALL_EXISTING_ORGS_ONLY",
172+
"roles": [
173+
{
174+
"displayName": "role_1",
175+
"audience": {
176+
"display": "My Org 1",
177+
"type": "organization"
178+
}
179+
},
180+
{
181+
"displayName": "role_2",
182+
"audience": {
183+
"display": "My App 1",
184+
"type": "application"
185+
}
186+
}
187+
]
188+
}'
189+
x-codegen-request-body-name: body
124190

125191
/users/unshare:
126192
post:
@@ -131,7 +197,7 @@ paths:
131197
This API removes shared access for one or more users from specified organizations.
132198
The payload includes the list of user IDs and the organizations from which the users should be unshared.
133199
134-
<b>Scope(Permission) required:</b> `internal_user_unshare`
200+
<b>Scope(Permission) required:</b> `internal_org_user_unshare`
135201
operationId: processUserUnsharing
136202
requestBody:
137203
content:
@@ -166,6 +232,26 @@ paths:
166232
application/json:
167233
schema:
168234
$ref: '#/components/schemas/Error'
235+
x-codeSamples:
236+
- lang: Curl
237+
source: |
238+
curl --location 'https://localhost:9443/o/api/server/v1/users/unshare' \
239+
-H 'Accept: application/json' \
240+
-H 'Content-Type: application/json' \
241+
-H 'Authorization: Bearer {bearer_token}' \
242+
-d '{
243+
"userCriteria": {
244+
"userIds": [
245+
"7a1b7d63-8cfc-4dc9-9332-3f84641b72d8",
246+
"5d2a1c84-9f7a-43cd-b12e-6e52d7f87e16"
247+
]
248+
},
249+
"organizations": [
250+
"b028ca17-8f89-449c-ae27-fa955e66465d",
251+
"a17b28ca-9f89-449c-ae27-fa955e66465f"
252+
]
253+
}'
254+
x-codegen-request-body-name: body
169255

170256
/users/unshare-with-all:
171257
post:
@@ -175,7 +261,7 @@ paths:
175261
description: |
176262
This API removes all shared access for one or more users, unsharing them from all organizations.
177263
178-
<b>Scope(Permission) required:</b> `internal_user_unshare`
264+
<b>Scope(Permission) required:</b> `internal_org_user_unshare`
179265
operationId: removeUserSharing
180266
requestBody:
181267
content:
@@ -207,6 +293,22 @@ paths:
207293
application/json:
208294
schema:
209295
$ref: '#/components/schemas/Error'
296+
x-codeSamples:
297+
- lang: Curl
298+
source: |
299+
curl --location 'https://localhost:9443/o/api/server/v1/users/unshare-all' \
300+
-H 'Accept: application/json' \
301+
-H 'Content-Type: application/json' \
302+
-H 'Authorization: Bearer {bearer_token}' \
303+
-d '{
304+
"userCriteria": {
305+
"userIds": [
306+
"7a1b7d63-8cfc-4dc9-9332-3f84641b72d8",
307+
"5d2a1c84-9f7a-43cd-b12e-6e52d7f87e16"
308+
]
309+
}
310+
}'
311+
x-codegen-request-body-name: body
210312

211313
/users/{userId}/shared-organizations:
212314
get:
@@ -216,7 +318,7 @@ paths:
216318
description: |
217319
This API retrieves the list of organizations where the specified user has shared access, with support for pagination and filtering.
218320
219-
<b>Scope(Permission) required:</b> `internal_user_shared_access_view`
321+
<b>Scope(Permission) required:</b> `internal_org_user_shared_access_view`
220322
parameters:
221323
- in: path
222324
name: userId
@@ -269,6 +371,12 @@ paths:
269371
application/json:
270372
schema:
271373
$ref: '#/components/schemas/Error'
374+
x-codeSamples:
375+
- lang: Curl
376+
source: |
377+
curl --location 'https://localhost:9443/o/api/server/v1/users/{userId}/shared-organizations' \
378+
-H 'Accept: application/json' \
379+
-H 'Authorization: Bearer {bearer_token}'
272380
273381
/users/{userId}/shared-roles:
274382
get:
@@ -278,7 +386,7 @@ paths:
278386
description: |
279387
This API fetches the roles assigned to the specified user within a particular organization, with support for pagination, filtering, and recursion.
280388
281-
<b>Scope(Permission) required:</b> `internal_user_shared_access_view`
389+
<b>Scope(Permission) required:</b> `internal_org_user_shared_access_view`
282390
parameters:
283391
- in: path
284392
name: userId
@@ -336,9 +444,28 @@ paths:
336444
application/json:
337445
schema:
338446
$ref: '#/components/schemas/Error'
339-
447+
x-codeSamples:
448+
- lang: Curl
449+
source: |
450+
curl --location 'https://localhost:9443/o/api/server/v1/users/{userId}/shared-roles?orgId={orgId}' \
451+
-H 'Accept: application/json' \
452+
-H 'Authorization: Bearer {bearer_token}'
340453
341454
components:
455+
456+
securitySchemes:
457+
458+
OAuth2:
459+
type: oauth2
460+
flows:
461+
authorizationCode:
462+
authorizationUrl: https://localhost:9443/oauth2/authorize
463+
tokenUrl: https://localhost:9443/oauth2/token
464+
scopes:
465+
share: internal_org_user_share
466+
unshare: internal_org_user_unshare
467+
view: internal_org_user_shared_access_view
468+
342469
schemas:
343470

344471
UserShareRequestBody:

0 commit comments

Comments
 (0)