-
Notifications
You must be signed in to change notification settings - Fork 90
/
Copy pathmanage-email-password-users.txt
216 lines (159 loc) · 8.85 KB
/
manage-email-password-users.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
.. meta::
:robots: noindex, nosnippet
.. _kotlin-manage-email-password-users:
.. _kotlin-register-users:
========================================
Manage Email/Password Users - Kotlin SDK
========================================
.. contents:: On this page
:local:
:backlinks: none
:depth: 2
:class: singlecol
When you enable the :ref:`email/password provider <email-password-authentication>`
in your Atlas App Services App, you can handle user authentication from client code
by registering and logging in new user.
.. _kotlin-register-email-password-user:
.. _kotlin-register-an-email-password-account:
Register a New User
-------------------
To register a new user, pass a user-provided email and password to
`app.emailPasswordAuth.registerUser()
<{+kotlin-sync-prefix+}io.realm.kotlin.mongodb.auth/-email-password-auth/register-user.html>`__:
.. literalinclude:: /examples/generated/kotlin/ManageEmailPasswordUsers.snippet.register-email-password-user.kt
:language: kotlin
.. _kotlin-confirm-a-new-users-email-address:
Confirm a New User's Email Address
----------------------------------
When you enable the :ref:`email/password provider <email-password-authentication>`,
in App Services, you select a confirmation method. The App Services email/password
confirmation service provides a token and token ID that you can get to the
user through email or a custom Atlas Function. To confirm the user,
provide that token and tokenId to `app.emailPasswordAuth.confirmUser()
<{+kotlin-sync-prefix+}io.realm.kotlin.mongodb.auth/-email-password-auth/confirm-user.html>`__:
.. literalinclude:: /examples/generated/kotlin/ManageEmailPasswordUsers.snippet.confirm-email-password-user.kt
:language: kotlin
After you confirm the user, you can proceed to :ref:`login with email/password
credentials <kotlin-email-password-login>`.
.. _kotlin-retry-user-confirmation:
Retry User Confirmation Methods
-------------------------------
The SDK provides methods to resend user confirmation emails or retry custom
confirmation methods.
Resend a User Confirmation Email
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Resend a :ref:`confirmation email <auth-send-a-confirmation-email>`. The
confirmation tokens in each URL expire after 30 minutes. If a user does not
follow the link and confirm within that period, they must request a new
confirmation email.
To resend a user confirmation email, provide the user's email address to
`app.emailPasswordAuth.resendConfirmationEmail()
<{+kotlin-sync-prefix+}io.realm.kotlin.mongodb.auth/-email-password-auth/resend-confirmation-email.html>`__:
.. literalinclude:: /examples/generated/kotlin/ManageEmailPasswordUsers.snippet.resend-password-confirmation-email.kt
:language: kotlin
Retry a User Confirmation Function
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To retry a :ref:`custom user confirmation function <auth-run-a-confirmation-function>`,
provide the user's email address to `app.emailPasswordAuth.retryCustomConfirmation()
<{+kotlin-sync-prefix+}io.realm.kotlin.mongodb.auth/-email-password-auth/retry-custom-confirmation.html>`__:
.. literalinclude:: /examples/generated/kotlin/ManageEmailPasswordUsers.snippet.retry-custom-confirmation.kt
:language: kotlin
.. _kotlin-reset-a-users-password:
Reset a User's Password
-----------------------
Resetting a user's password is a multi-step process.
1. In your client app, you provide a UI for the user to reset their password.
Your App Services App can then send an email or run a custom function
to confirm the user's identity.
#. After confirming the user's identity, you can complete the password reset
request.
#. After the password reset is complete, the user can log in using the new
password.
For more information about how to set your preferred password reset method,
refer to the :ref:`App Services Email/Password Authentication documentation
<email-password-authentication-password-resets>`.
Send a Password Reset Email
~~~~~~~~~~~~~~~~~~~~~~~~~~~
To send password reset emails to confirm the user's identity,
you must configure your App to :ref:`send a password reset email
<auth-send-a-password-reset-email>`.
To begin the password reset process, call `app.emailPasswordAuth.sendResetPasswordEmail()
<{+kotlin-sync-prefix+}io.realm.kotlin.mongodb.auth/-email-password-auth/send-reset-password-email.html>`__
with the user's email. App Services sends an email to the user that contains
a unique URL. The user must visit this URL within 30 minutes to confirm
the reset.
.. literalinclude:: /examples/generated/kotlin/ManageEmailPasswordUsers.snippet.send-password-reset-email.kt
:language: kotlin
After the user has visited the URL from the password reset email, call
`app.emailPasswordAuth.resetPassword()
<{+kotlin-sync-prefix+}io.realm.kotlin.mongodb.auth/-email-password-auth/reset-password.html>`__
with the user's email, the new password, and the ``token`` and ``tokenId``
provided in the unique URL.
If the user does not visit the URL from the password reset email within 30
minutes, the ``token`` and ``tokenId`` expire. You must begin the password
reset process again.
.. literalinclude:: /examples/generated/kotlin/ManageEmailPasswordUsers.snippet.reset-password.kt
:language: kotlin
Run a Password Reset Function
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When you configure your app to :ref:`run a password reset function
<auth-run-a-password-reset-function>`, you define the function that
should run when you call `app.emailPasswordAuth.callResetPasswordFunction()
<{+kotlin-sync-prefix+}io.realm.kotlin.mongodb.auth/-email-password-auth/call-reset-password-function.html>`__
from the SDK. This function can take a username, a password, and any number
of additional arguments. You can use these arguments to specify details
like security question answers or other challenges that the user should
pass to successfully complete a password reset.
You might prefer to use a custom password reset function when you want to
define your own password reset flows. For example, you might send a custom
password reset email from a specific domain. Or you might use a service other
than email to confirm the user's identity.
On the App Services side, you define the custom password reset function that
runs when you call this method. That function can return one of three possible
statuses:
- ``fail``
- ``pending``
- ``success``
A ``fail`` status is treated as a ``ServiceException`` error by the SDK.
The SDK ``callResetPasswordFunction()`` does not return a ``pending`` or
``success`` status to the client.
Server-Side Pending Case
````````````````````````
Your :ref:`App Services password reset function
<auth-run-a-password-reset-function>` may return ``pending`` if you want
the user to take some additional step to confirm their identity. However, that
return value is not passed to the SDK's ``callResetPasswordFunction()``, so
your client app must implement its own logic to handle a ``pending`` status.
.. literalinclude:: /examples/generated/kotlin/ManageEmailPasswordUsers.snippet.call-password-reset-function-assume-pending.kt
:language: kotlin
Your server-side function might send an email using a custom email provider.
Or you may use SMS to confirm the user's identity via text message.
You have access to a ``token`` and ``tokenId`` in the App Services password
reset function context. If you pass this information from your App Services
password reset function, you can pass these values back to your app using
`deep links in Android <https://developer.android.com/training/app-links/deep-linking>`__
or :apple:`universal links in iOS <ios/universal-links/>`. Then, your client
application can call ``resetPassword()`` to complete the password reset flow.
.. literalinclude:: /examples/generated/kotlin/ManageEmailPasswordUsers.snippet.reset-password.kt
:language: kotlin
Server-Side Success Case
````````````````````````
If your :ref:`App Services password reset function
<auth-run-a-password-reset-function>` does additional validation within
the function, or if you have validated the user's identity prior to
attempting to reset the password, you may configure the App Services function
to return ``success``. However, that return value is not passed to the SDK's
``callResetPasswordFunction()``, so your client app must implement its
own logic to handle a ``success`` status.
Calling the function in this example performs the entire password reset process.
.. literalinclude:: /examples/generated/kotlin/ManageEmailPasswordUsers.snippet.call-password-reset-function.kt
:language: kotlin
.. _kotlin-authenticate-email-password-user:
Log In or Log Out a User
------------------------
After you register a user, it is a separate step to log the user in.
.. literalinclude:: /examples/generated/kotlin/AuthenticationTest.snippet.email-password-authentication.kt
:language: kotlin
You can log out an authenticated user.
.. literalinclude:: /examples/generated/kotlin/AuthenticationTest.snippet.log-out.kt
:language: kotlin