Skip to content

Commit 61caf1d

Browse files
sadilchamishkasadilchamishka
authored
Merge pull request #5533 from sadilchamishka/doc-improvements
Add documentation for triggering email verification when user onboarding and other doc improvements
2 parents 742ebb2 + 321a76e commit 61caf1d

File tree

7 files changed

+301
-7
lines changed

7 files changed

+301
-7
lines changed

‎en/asgardeo/docs/assets/img/guides/account-configurations/invite-user-to-set-password.png‎

-31.2 KB
Loading

‎en/asgardeo/docs/guides/users/manage-users.md‎

Lines changed: 128 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
This guide walks you through the process of managing a user account. An owner or an administrator can manage user accounts.
44

55
## Onboard users
6+
67
There are three ways to onboard a user:
78

89
- The user can self-register via the My Account portal or the login page of an application if self-registration is enabled in the organization. Learn how to [configure self-registration]({{base_path}}/guides/user-accounts/configure-self-registration/).
@@ -189,7 +190,7 @@ Alternatively, administrators can use the resend-code API to resend the link or
189190
-d '{
190191
"user": {
191192
"username": "jane",
192-
"realm": "PRIMARY"
193+
"realm": "DEFAULT"
193194
},
194195
"properties": [
195196
{
@@ -364,3 +365,129 @@ To filter users by account status:
364365
- **Pending mobile verification**: Filters users who haven't yet verified their primary mobile numbers.
365366
366367
![Filter users by account status]({{base_path}}/assets/img/guides/users/filter-users-by-account-status.png){: width="600" style="display: block; margin: 0; border: 0.3px solid lightgrey;"}
368+
369+
## Add users with email verification
370+
371+
1: Enable email verification
372+
373+
!!! abstract ""
374+
375+
curl -X 'PATCH' \
376+
'https://api.asgardeo.io/t/<org_name>/api/server/v1/identity-governance/VXNlciBPbmJvYXJkaW5n/connectors/dXNlci1lbWFpbC12ZXJpZmljYXRpb24' \
377+
-H 'Authorization: Bearer <access_token>' \
378+
-H 'Content-Type: application/json' \
379+
-d '{
380+
"operation": "UPDATE",
381+
"properties": [
382+
{
383+
"name": "EmailVerification.Enable",
384+
"value": true
385+
}
386+
]
387+
}'
388+
389+
2: Configure email verification method (Optional). Enable this to send OTP via email.
390+
391+
!!! abstract ""
392+
393+
curl -X 'PATCH' \
394+
'https://api.asgardeo.io/t/<org_name>/api/server/v1/identity-governance/VXNlciBPbmJvYXJkaW5n/connectors/dXNlci1lbWFpbC12ZXJpZmljYXRpb24' \
395+
-H 'Authorization: Bearer <access_token>' \
396+
-H 'Content-Type: application/json' \
397+
-d '{
398+
"operation": "UPDATE",
399+
"properties": [
400+
{
401+
"name": "EmailVerification.OTP",
402+
"value": true
403+
}
404+
]
405+
}'
406+
407+
3: Create user with email verification required
408+
409+
!!! abstract ""
410+
411+
=== "Request format"
412+
413+
```curl
414+
curl -X 'POST' \
415+
'https://api.asgardeo.io/t/<org_name>/scim2/Users' \
416+
-H 'Authorization: Bearer <access_token>' \
417+
-H 'Content-Type: application/json' \
418+
-d '{
419+
"userName": "<USERNAME>",
420+
"emails": [
421+
{
422+
"primary": true,
423+
"value": "<EMAIL>"
424+
}
425+
],
426+
"password": "<PASSWORD>",
427+
"urn:scim:wso2:schema": {
428+
"verifyEmail": "true"
429+
}
430+
}'
431+
```
432+
=== "Sample request"
433+
434+
```
435+
curl -X 'POST' \
436+
'https://api.asgardeo.io/t/<org_name>/scim2/Users' \
437+
-H 'Authorization: Bearer <access_token>' \
438+
-H 'Content-Type: application/json' \
439+
-d '{
440+
"userName": "DEFAULT/bob",
441+
"emails": [
442+
{
443+
"primary": true,
444+
"value": "[email protected]"
445+
}
446+
],
447+
"password": "P@ssw0rd",
448+
"urn:scim:wso2:schema": {
449+
"verifyEmail": "true"
450+
}
451+
}'
452+
```
453+
454+
---
455+
**Response**
456+
```
457+
"HTTP/1.1 201 Created"
458+
```
459+
460+
4: Confirm email or validate OTP (One-Time Password)
461+
462+
You can verify the email using the confirmation link, or enter the OTP using the following API.
463+
464+
!!! abstract ""
465+
466+
=== "Request format"
467+
468+
```curl
469+
curl -X 'POST' \
470+
'https://api.asgardeo.io/t/<org_name>/api/identity/user/v1.0/validate-code' \
471+
-H 'Authorization: Bearer <access_token>' \
472+
-H 'Content-Type: application/json' \
473+
-d '{
474+
"code": "<CODE>"
475+
}'
476+
```
477+
=== "Sample request"
478+
479+
```
480+
curl -X 'POST' \
481+
'https://api.asgardeo.io/t/<org_name>/api/identity/user/v1.0/validate-code' \
482+
-H 'Authorization: Bearer <access_token>' \
483+
-H 'Content-Type: application/json' \
484+
-d '{
485+
"code": "c1KLdm"
486+
}'
487+
```
488+
489+
---
490+
**Response**
491+
```
492+
"HTTP/1.1 202 Accepted"
493+
```

‎en/identity-server/7.1.0/docs/guides/account-configurations/user-onboarding/self-registration.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,6 @@
1-
{% include "../../../../../../includes/guides/account-configurations/user-onboarding/self-registration.md" %}
1+
{% set host_name = "localhost:9443" %}
2+
{% set host_name_example = "localhost:9443" %}
3+
{% set scim_schema_for_wso2_custom_claims = "urn:scim:wso2:schema" %}
4+
{% set organization_path_param = "" %}
5+
6+
{% include "../../../../../../includes/guides/account-configurations/user-onboarding/self-registration.md" %}

‎en/identity-server/next/docs/assets/img/guides/account-configurations/invite-user-to-set-password.png‎

-37.5 KB
Loading

‎en/identity-server/next/docs/guides/account-configurations/user-onboarding/self-registration.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
{% set host_name = "localhost:9443" %}
22
{% set host_name_example = "localhost:9443" %}
3+
{% set scim_schema_for_wso2_custom_claims = "urn:scim:wso2:schema" %}
4+
{% set organization_path_param = "" %}
35

4-
{% include "../../../../../../includes/guides/account-configurations/user-onboarding/self-registration.md" %}
6+
{% include "../../../../../../includes/guides/account-configurations/user-onboarding/self-registration.md" %}

‎en/identity-server/next/docs/guides/users/manage-users.md‎

Lines changed: 136 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
This guide walks you through how you can manage user accounts as an administrator.
44

55
## Onboard users
6+
67
There are three ways to onboard a user:
78

89
- The user can self-register via the My Account portal or the login page of an application if self-registration is enabled in the organization. Learn how to [configure self-registration]({{base_path}}/guides/account-configurations/user-onboarding/self-registration/).
@@ -84,17 +85,19 @@ In addition to adding a single user, you can onboard multiple users at once, eit
8485
5. Ensure your CSV file is formatted correctly, with headers that correspond to user attributes. These attributes must be mapped to local attributes.
8586
- A sample CSV file format would include: `username, givenname, emailaddress, groups`
8687
- For example:
87-
```
88+
89+
```csv
8890
username,givenname,emailaddress,groups
8991
user1,john,[email protected],group1|group2
9092
user2,jake,[email protected],group2
9193
user3,jane,[email protected],group1
9294
```
95+
9396
6. Click **Import** to add the users to the system.
9497
7. An email with a confirmation link will be sent to the provided email addresses, allowing the users to set their own passwords.
9598
96-
9799
## Assign groups
100+
98101
Groups are useful when you wish to assign a certain permission level to multiple users. A user can be a member of multiple groups in the organization. Learn how to [manage groups]({{base_path}}/guides/users/manage-groups/).
99102
100103
To assign users to groups:
@@ -332,6 +335,7 @@ To disable a user account,
332335
![Account disable reason]({{base_path}}/assets/img/guides/users/account-disable-text.png){: width="600" style="display: block; margin: 0; border: 0.3px solid lightgrey;"}
333336
334337
## Delete a user
338+
335339
A user account can be deleted by administrators. Once an account is deleted, the action is irreversible.
336340
337341
To delete a user account:
@@ -357,7 +361,135 @@ To filter users by account status:
357361
- **Disabled**: Filters users with deactivated accounts.
358362
- **Pending password reset**: Filters users for whom the administrator has initiated a forced password reset, but the users haven't yet reset their passwords.
359363
- **Pending initial password setup**: Filters users an administrator invited to set their own password during initial account creation but who haven't done so yet.
360-
- **Pending email verification**: Filters users who haven't yet verified their primary email addresses.
361-
- **Pending mobile verification**: Filters users who haven't yet verified their primary mobile numbers.
364+
- **Pending email verification**: Filters users who haven't yet verified their primary email addresses.
365+
- **Pending mobile verification**: Filters users who haven't yet verified their primary mobile numbers.
362366
363367
![Filter users by account status]({{base_path}}/assets/img/guides/users/filter-users-by-account-status.png){: width="600" style="display: block; margin: 0; border: 0.3px solid lightgrey;"}
368+
369+
## Add users with email verification
370+
371+
1. Enable email verification
372+
373+
!!! abstract ""
374+
375+
curl -X 'PATCH' \
376+
'https://localhost:9443/api/server/v1/identity-governance/VXNlciBPbmJvYXJkaW5n/connectors/dXNlci1lbWFpbC12ZXJpZmljYXRpb24' \
377+
-H 'Authorization: Bearer <access_token>' \
378+
-H 'Content-Type: application/json' \
379+
-d '{
380+
"operation": "UPDATE",
381+
"properties": [
382+
{
383+
"name": "EmailVerification.Enable",
384+
"value": true
385+
}
386+
]
387+
}'
388+
389+
2. Configure email verification method (Optional). Enable this to send OTP via email.
390+
391+
!!! abstract ""
392+
393+
curl -X 'PATCH' \
394+
'https://localhost:9443/api/server/v1/identity-governance/VXNlciBPbmJvYXJkaW5n/connectors/dXNlci1lbWFpbC12ZXJpZmljYXRpb24' \
395+
-H 'Authorization: Bearer <access_token>' \
396+
-H 'Content-Type: application/json' \
397+
-d '{
398+
"operation": "UPDATE",
399+
"properties": [
400+
{
401+
"name": "EmailVerification.OTP",
402+
"value": true
403+
}
404+
]
405+
}'
406+
407+
3. Create user with email verification required
408+
409+
!!! abstract ""
410+
411+
=== "Request format"
412+
413+
```curl
414+
curl -X 'POST' \
415+
'https://localhost:9443/scim2/Users' \
416+
-H 'Authorization: Bearer <access_token>' \
417+
-H 'Content-Type: application/json' \
418+
-d '{
419+
"userName": "<USERNAME>",
420+
"emails": [
421+
{
422+
"primary": true,
423+
"value": "<EMAIL>"
424+
}
425+
],
426+
"password": "<PASSWORD>",
427+
"urn:scim:wso2:schema": {
428+
"verifyEmail": "true"
429+
}
430+
}'
431+
```
432+
=== "Sample request"
433+
434+
```
435+
curl -X 'POST' \
436+
'https://localhost:9443/scim2/Users' \
437+
-H 'Authorization: Bearer <access_token>' \
438+
-H 'Content-Type: application/json' \
439+
-d '{
440+
"userName": "bob",
441+
"emails": [
442+
{
443+
"primary": true,
444+
"value": "[email protected]"
445+
}
446+
],
447+
"password": "P@ssw0rd",
448+
"urn:scim:wso2:schema": {
449+
"verifyEmail": "true"
450+
}
451+
}'
452+
```
453+
454+
Ensure that the username provided is without the user store domain prefix, and the realm parameter specifies the relevant user store domain name.
455+
456+
---
457+
**Response**
458+
```
459+
"HTTP/1.1 201 Created"
460+
```
461+
462+
4. Confirm email or validate OTP (One-Time Password)
463+
464+
You can verify the email using the confirmation link, or enter the OTP using the following API.
465+
466+
!!! abstract ""
467+
468+
=== "Request format"
469+
470+
```curl
471+
curl -X 'POST' \
472+
'https://localhost:9443/api/identity/user/v1.0/validate-code' \
473+
-H 'Authorization: Bearer <access_token>' \
474+
-H 'Content-Type: application/json' \
475+
-d '{
476+
"code": "<CODE>"
477+
}'
478+
```
479+
=== "Sample request"
480+
481+
```
482+
curl -X 'POST' \
483+
'https://localhost:9443/api/identity/user/v1.0/validate-code' \
484+
-H 'Authorization: Bearer <access_token>' \
485+
-H 'Content-Type: application/json' \
486+
-d '{
487+
"code": "c1KLdm"
488+
}'
489+
```
490+
491+
---
492+
**Response**
493+
```
494+
"HTTP/1.1 202 Accepted"
495+
```

‎en/includes/guides/account-configurations/user-onboarding/invite-user-to-set-password.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,34 @@ This defines how long the password setup invitation email or OTP remains valid.
7979
<td>Set the number of characters in the generated OTP codes.</td>
8080
</tr>
8181
</table>
82+
83+
## Try out Invite user to set password
84+
85+
1. On the {{product_name}} Console, go to **User Management**.
86+
87+
2. Go to **Users**.
88+
89+
3. Click **Add User** > **Single User**.
90+
91+
4. Fill in the user's details.
92+
93+
5. Select the **Invite the user to set their own password** option.
94+
95+
6. Click **Next** and **Finish**.
96+
97+
7. You will receive an **email link**, **email OTP**, or **SMS OTP** based on your configuration.
98+
99+
- **Click the email link** to start the password setup flow.
100+
- **If you receive an OTP**, enter it to begin the password setup flow.
101+
102+
This step verifies the user's identity and starts the password creation process.
103+
104+
**Tip:**
105+
106+
- You can redirect users to the password recovery endpoint with the OTP to initiate setup.
107+
108+
- Otherwise you can try your application's basic authentication with the username and OTP as the password. This triggers the password setup flow if the OTP is valid.
109+
82110
{% else %}
83111
<table>
84112
<tr>

0 commit comments

Comments
 (0)