From 3ce78b2272831d1d3e2d46b164fe95c3ae2cb08d Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 31 May 2024 18:05:53 -0400 Subject: [PATCH 01/14] Draft consolidated Authenticate Users page --- ...henticate-get-current-user-description.rst | 1 + ...cate-get-user-access-token-description.rst | 6 + .../users/authenticate-google-description.rst | 8 + .../authenticate-log-in-user-description.rst | 14 + ...ually-refresh-access-token-description.rst | 3 + ...-observe-authentication-changes-no-api.rst | 8 + ...er-create-new-user-account-description.rst | 7 + ...henticate-get-current-user-description.rst | 3 + .../authenticate-log-in-user-description.rst | 23 + .../authenticate-log-user-out-description.rst | 1 + ...nticate-observe-authentication-changes.rst | 8 + ...er-create-new-user-account-description.rst | 8 + .../authenticate-anonymous-description.rst | 11 + .../authenticate-api-key-description.rst | 3 + .../users/authenticate-apple-description.rst | 3 + ...thenticate-custom-function-description.rst | 3 + .../authenticate-custom-jwt-description.rst | 3 + ...uthenticate-email-password-description.rst | 4 + .../authenticate-facebook-description.rst | 3 + .../users/authenticate-get-current-user.rst | 3 + ...cate-get-user-access-token-description.rst | 2 + .../users/authenticate-google-description.rst | 10 + .../authenticate-log-in-user-description.rst | 21 + .../authenticate-log-user-out-description.rst | 2 + ...ually-refresh-access-token-description.rst | 9 + ...-observe-authentication-changes-no-api.rst | 5 + ...er-create-new-user-account-description.rst | 8 + .../authenticate-anonymous-description.rst | 4 + .../authenticate-api-key-description.rst | 4 + .../users/authenticate-apple-description.rst | 4 + ...thenticate-custom-function-description.rst | 23 + .../authenticate-custom-jwt-description.rst | 4 + ...uthenticate-email-password-description.rst | 4 + .../authenticate-facebook-description.rst | 7 + .../users/authenticate-google-description.rst | 72 ++ .../authenticate-log-in-user-description.rst | 36 + .../authenticate-log-user-out-description.rst | 3 + ...er-create-new-user-account-description.rst | 8 + ...thenticate-anonymous-js-ts-description.rst | 1 + ...authenticate-api-key-js-ts-description.rst | 2 + .../authenticate-apple-js-ts-description.rst | 5 + ...cate-custom-function-js-ts-description.rst | 2 + ...henticate-custom-jwt-js-ts-description.rst | 2 + ...icate-email-password-js-ts-description.rst | 2 + ...uthenticate-facebook-js-ts-description.rst | 4 + .../users/authenticate-google-description.rst | 42 + ...enticate-log-in-user-js-ts-description.rst | 21 + ...nticate-log-user-out-js-ts-description.rst | 1 + ...ate-new-user-account-js-ts-description.rst | 8 + .../authenticate-anonymous-description.rst | 14 + .../authenticate-api-key-description.rst | 6 + .../users/authenticate-apple-description.rst | 11 + ...thenticate-custom-function-description.rst | 11 + .../authenticate-custom-jwt-description.rst | 6 + ...uthenticate-email-password-description.rst | 6 + .../authenticate-facebook-description.rst | 21 + ...henticate-get-current-user-description.rst | 2 + ...cate-get-user-access-token-description.rst | 3 + .../users/authenticate-google-description.rst | 15 + .../authenticate-log-in-user-description.rst | 38 + .../authenticate-log-user-out-description.rst | 3 + ...ually-refresh-access-token-description.rst | 3 + ...rve-authentication-changes-description.rst | 15 + ...er-create-new-user-account-description.rst | 8 + .../authenticate-facebook-description.rst | 6 + .../authenticate-get-user-access-token.rst | 5 + .../users/authenticate-google-description.rst | 17 + .../authenticate-log-in-user-description.rst | 27 + ...ually-refresh-access-token-description.rst | 5 + ...er-create-new-user-account-description.rst | 8 + .../authenticate-google-missing-example.rst | 5 + ...authorization-appleidcredential-string.rst | 5 - .../includes/log-out-queries-in-progress.rst | 2 +- source/includes/note-enable-facebook-auth.rst | 5 - source/includes/offline-login.rst | 10 - source/includes/refresh-token-expiry.rst | 11 +- .../users/authenticate-anonymous.rst | 59 ++ .../users/authenticate-api-key.rst | 58 ++ .../sdk-examples/users/authenticate-apple.rst | 58 ++ .../users/authenticate-custom-function.rst | 58 ++ .../users/authenticate-custom-jwt.rst | 58 ++ .../users/authenticate-email-password.rst | 58 ++ .../users/authenticate-facebook.rst | 60 ++ .../users/authenticate-get-current-user.rst | 56 + .../authenticate-get-user-access-token.rst | 58 ++ .../users/authenticate-google.rst | 69 ++ .../users/authenticate-log-in-offline.rst | 58 ++ .../users/authenticate-log-in-user.rst | 56 + .../users/authenticate-log-user-out.rst | 58 ++ ...enticate-manually-refresh-access-token.rst | 56 + ...nticate-observe-authentication-changes.rst | 56 + source/includes/swift-async-await-support.rst | 6 +- source/sdk/users/authenticate-users.txt | 961 +++++++++++++++++- source/sdk/users/create-and-delete-users.txt | 10 + templates/consolidated-page.rst | 2 +- 95 files changed, 2530 insertions(+), 32 deletions(-) create mode 100644 source/includes/api-details/cpp/users/authenticate-get-current-user-description.rst create mode 100644 source/includes/api-details/cpp/users/authenticate-get-user-access-token-description.rst create mode 100644 source/includes/api-details/cpp/users/authenticate-google-description.rst create mode 100644 source/includes/api-details/cpp/users/authenticate-log-in-user-description.rst create mode 100644 source/includes/api-details/cpp/users/authenticate-manually-refresh-access-token-description.rst create mode 100644 source/includes/api-details/cpp/users/authenticate-observe-authentication-changes-no-api.rst create mode 100644 source/includes/api-details/cpp/users/authenticate-register-create-new-user-account-description.rst create mode 100644 source/includes/api-details/csharp/users/authenticate-get-current-user-description.rst create mode 100644 source/includes/api-details/csharp/users/authenticate-log-in-user-description.rst create mode 100644 source/includes/api-details/csharp/users/authenticate-log-user-out-description.rst create mode 100644 source/includes/api-details/csharp/users/authenticate-observe-authentication-changes.rst create mode 100644 source/includes/api-details/csharp/users/authenticate-register-create-new-user-account-description.rst create mode 100644 source/includes/api-details/dart/users/authenticate-anonymous-description.rst create mode 100644 source/includes/api-details/dart/users/authenticate-api-key-description.rst create mode 100644 source/includes/api-details/dart/users/authenticate-apple-description.rst create mode 100644 source/includes/api-details/dart/users/authenticate-custom-function-description.rst create mode 100644 source/includes/api-details/dart/users/authenticate-custom-jwt-description.rst create mode 100644 source/includes/api-details/dart/users/authenticate-email-password-description.rst create mode 100644 source/includes/api-details/dart/users/authenticate-facebook-description.rst create mode 100644 source/includes/api-details/dart/users/authenticate-get-current-user.rst create mode 100644 source/includes/api-details/dart/users/authenticate-get-user-access-token-description.rst create mode 100644 source/includes/api-details/dart/users/authenticate-google-description.rst create mode 100644 source/includes/api-details/dart/users/authenticate-log-in-user-description.rst create mode 100644 source/includes/api-details/dart/users/authenticate-log-user-out-description.rst create mode 100644 source/includes/api-details/dart/users/authenticate-manually-refresh-access-token-description.rst create mode 100644 source/includes/api-details/dart/users/authenticate-observe-authentication-changes-no-api.rst create mode 100644 source/includes/api-details/dart/users/authenticate-register-create-new-user-account-description.rst create mode 100644 source/includes/api-details/java/users/authenticate-anonymous-description.rst create mode 100644 source/includes/api-details/java/users/authenticate-api-key-description.rst create mode 100644 source/includes/api-details/java/users/authenticate-apple-description.rst create mode 100644 source/includes/api-details/java/users/authenticate-custom-function-description.rst create mode 100644 source/includes/api-details/java/users/authenticate-custom-jwt-description.rst create mode 100644 source/includes/api-details/java/users/authenticate-email-password-description.rst create mode 100644 source/includes/api-details/java/users/authenticate-facebook-description.rst create mode 100644 source/includes/api-details/java/users/authenticate-google-description.rst create mode 100644 source/includes/api-details/java/users/authenticate-log-in-user-description.rst create mode 100644 source/includes/api-details/java/users/authenticate-log-user-out-description.rst create mode 100644 source/includes/api-details/java/users/authenticate-register-create-new-user-account-description.rst create mode 100644 source/includes/api-details/javascript/users/authenticate-anonymous-js-ts-description.rst create mode 100644 source/includes/api-details/javascript/users/authenticate-api-key-js-ts-description.rst create mode 100644 source/includes/api-details/javascript/users/authenticate-apple-js-ts-description.rst create mode 100644 source/includes/api-details/javascript/users/authenticate-custom-function-js-ts-description.rst create mode 100644 source/includes/api-details/javascript/users/authenticate-custom-jwt-js-ts-description.rst create mode 100644 source/includes/api-details/javascript/users/authenticate-email-password-js-ts-description.rst create mode 100644 source/includes/api-details/javascript/users/authenticate-facebook-js-ts-description.rst create mode 100644 source/includes/api-details/javascript/users/authenticate-google-description.rst create mode 100644 source/includes/api-details/javascript/users/authenticate-log-in-user-js-ts-description.rst create mode 100644 source/includes/api-details/javascript/users/authenticate-log-user-out-js-ts-description.rst create mode 100644 source/includes/api-details/javascript/users/authenticate-register-create-new-user-account-js-ts-description.rst create mode 100644 source/includes/api-details/kotlin/users/authenticate-anonymous-description.rst create mode 100644 source/includes/api-details/kotlin/users/authenticate-api-key-description.rst create mode 100644 source/includes/api-details/kotlin/users/authenticate-apple-description.rst create mode 100644 source/includes/api-details/kotlin/users/authenticate-custom-function-description.rst create mode 100644 source/includes/api-details/kotlin/users/authenticate-custom-jwt-description.rst create mode 100644 source/includes/api-details/kotlin/users/authenticate-email-password-description.rst create mode 100644 source/includes/api-details/kotlin/users/authenticate-facebook-description.rst create mode 100644 source/includes/api-details/kotlin/users/authenticate-get-current-user-description.rst create mode 100644 source/includes/api-details/kotlin/users/authenticate-get-user-access-token-description.rst create mode 100644 source/includes/api-details/kotlin/users/authenticate-google-description.rst create mode 100644 source/includes/api-details/kotlin/users/authenticate-log-in-user-description.rst create mode 100644 source/includes/api-details/kotlin/users/authenticate-log-user-out-description.rst create mode 100644 source/includes/api-details/kotlin/users/authenticate-manually-refresh-access-token-description.rst create mode 100644 source/includes/api-details/kotlin/users/authenticate-observe-authentication-changes-description.rst create mode 100644 source/includes/api-details/kotlin/users/authenticate-register-create-new-user-account-description.rst create mode 100644 source/includes/api-details/swift/users/authenticate-facebook-description.rst create mode 100644 source/includes/api-details/swift/users/authenticate-get-user-access-token.rst create mode 100644 source/includes/api-details/swift/users/authenticate-google-description.rst create mode 100644 source/includes/api-details/swift/users/authenticate-log-in-user-description.rst create mode 100644 source/includes/api-details/swift/users/authenticate-manually-refresh-access-token-description.rst create mode 100644 source/includes/api-details/swift/users/authenticate-register-create-new-user-account-description.rst create mode 100644 source/includes/api-details/typescript/users/authenticate-google-missing-example.rst delete mode 100644 source/includes/authorization-appleidcredential-string.rst delete mode 100644 source/includes/note-enable-facebook-auth.rst delete mode 100644 source/includes/offline-login.rst create mode 100644 source/includes/sdk-examples/users/authenticate-anonymous.rst create mode 100644 source/includes/sdk-examples/users/authenticate-api-key.rst create mode 100644 source/includes/sdk-examples/users/authenticate-apple.rst create mode 100644 source/includes/sdk-examples/users/authenticate-custom-function.rst create mode 100644 source/includes/sdk-examples/users/authenticate-custom-jwt.rst create mode 100644 source/includes/sdk-examples/users/authenticate-email-password.rst create mode 100644 source/includes/sdk-examples/users/authenticate-facebook.rst create mode 100644 source/includes/sdk-examples/users/authenticate-get-current-user.rst create mode 100644 source/includes/sdk-examples/users/authenticate-get-user-access-token.rst create mode 100644 source/includes/sdk-examples/users/authenticate-google.rst create mode 100644 source/includes/sdk-examples/users/authenticate-log-in-offline.rst create mode 100644 source/includes/sdk-examples/users/authenticate-log-in-user.rst create mode 100644 source/includes/sdk-examples/users/authenticate-log-user-out.rst create mode 100644 source/includes/sdk-examples/users/authenticate-manually-refresh-access-token.rst create mode 100644 source/includes/sdk-examples/users/authenticate-observe-authentication-changes.rst diff --git a/source/includes/api-details/cpp/users/authenticate-get-current-user-description.rst b/source/includes/api-details/cpp/users/authenticate-get-current-user-description.rst new file mode 100644 index 0000000000..c212b410e6 --- /dev/null +++ b/source/includes/api-details/cpp/users/authenticate-get-current-user-description.rst @@ -0,0 +1 @@ +You can get the current user with ``app::get_current_user()``: diff --git a/source/includes/api-details/cpp/users/authenticate-get-user-access-token-description.rst b/source/includes/api-details/cpp/users/authenticate-get-user-access-token-description.rst new file mode 100644 index 0000000000..09b8299327 --- /dev/null +++ b/source/includes/api-details/cpp/users/authenticate-get-user-access-token-description.rst @@ -0,0 +1,6 @@ +You can call :cpp-sdk:`.refresh_custom_user_data() +` +on a logged-in user to refresh the user's auth session. Then, get the +:cpp-sdk:`.access_token() ` +as a string you can use in your code. You might use code similar to this to +fetch an access token: diff --git a/source/includes/api-details/cpp/users/authenticate-google-description.rst b/source/includes/api-details/cpp/users/authenticate-google-description.rst new file mode 100644 index 0000000000..3503dd905b --- /dev/null +++ b/source/includes/api-details/cpp/users/authenticate-google-description.rst @@ -0,0 +1,8 @@ +To log in with a Google authentication code, pass a Google authentication code to +:cpp-sdk:`credentials::google_auth_code() `. + +.. literalinclude:: /examples/generated/cpp/authentication.snippet.google-auth-code.cpp + :language: cpp + +To log in with a Google ID token, pass a Google ID token to +:cpp-sdk:`credentials::google_id_token() `. diff --git a/source/includes/api-details/cpp/users/authenticate-log-in-user-description.rst b/source/includes/api-details/cpp/users/authenticate-log-in-user-description.rst new file mode 100644 index 0000000000..99e6c5f717 --- /dev/null +++ b/source/includes/api-details/cpp/users/authenticate-log-in-user-description.rst @@ -0,0 +1,14 @@ +To authenticate and log users in to your :cpp-sdk:`App +`, first instantiate a +:cpp-sdk:`credentials ` +object containing the credentials associated with the authentication provider. +Then, pass it to the ``login()`` function. + +Each authentication provider corresponds to a :cpp-sdk:`static function +` +used to instantiate ``credentials`` objects for that authentication provider. + +If successful, ``app::login()`` returns a :cpp-sdk:`user +` object. In the event of a failure, +``app::login()`` throws an exception of type :cpp-sdk:`app_error +`. diff --git a/source/includes/api-details/cpp/users/authenticate-manually-refresh-access-token-description.rst b/source/includes/api-details/cpp/users/authenticate-manually-refresh-access-token-description.rst new file mode 100644 index 0000000000..9958ea93e3 --- /dev/null +++ b/source/includes/api-details/cpp/users/authenticate-manually-refresh-access-token-description.rst @@ -0,0 +1,3 @@ +You can call :cpp-sdk:`.refresh_custom_user_data() +` +on a logged-in user to refresh the user's auth session. diff --git a/source/includes/api-details/cpp/users/authenticate-observe-authentication-changes-no-api.rst b/source/includes/api-details/cpp/users/authenticate-observe-authentication-changes-no-api.rst new file mode 100644 index 0000000000..7ae12db86f --- /dev/null +++ b/source/includes/api-details/cpp/users/authenticate-observe-authentication-changes-no-api.rst @@ -0,0 +1,8 @@ +C++ does not provide a dedicated API to observe authentication changes. However, +you can check the user's :cpp-sdk:`state +`, which is +an enum whose possible values are: + +- ``logged_out`` +- ``logged_in`` +- ``removed`` diff --git a/source/includes/api-details/cpp/users/authenticate-register-create-new-user-account-description.rst b/source/includes/api-details/cpp/users/authenticate-register-create-new-user-account-description.rst new file mode 100644 index 0000000000..b50470127d --- /dev/null +++ b/source/includes/api-details/cpp/users/authenticate-register-create-new-user-account-description.rst @@ -0,0 +1,7 @@ +When a user registers or successfully authenticates to your App, Atlas App +Services automatically creates a :cpp-sdk:`user +` object, which contains a unique +identifier and user state information. You can optionally configure +:ref:`custom user data ` if your app needs to store +additional user data. To learn more about the user object that App Services +provides, refer to :ref:`` in the App Services documentation. diff --git a/source/includes/api-details/csharp/users/authenticate-get-current-user-description.rst b/source/includes/api-details/csharp/users/authenticate-get-current-user-description.rst new file mode 100644 index 0000000000..034c5dfce7 --- /dev/null +++ b/source/includes/api-details/csharp/users/authenticate-get-current-user-description.rst @@ -0,0 +1,3 @@ +Once you have an authenticated user, you can retrieve the User object with the +:dotnet-sdk:`App.CurrentUser ` +property. diff --git a/source/includes/api-details/csharp/users/authenticate-log-in-user-description.rst b/source/includes/api-details/csharp/users/authenticate-log-in-user-description.rst new file mode 100644 index 0000000000..b91ea30ecb --- /dev/null +++ b/source/includes/api-details/csharp/users/authenticate-log-in-user-description.rst @@ -0,0 +1,23 @@ +To authenticate and log users in to your :dotnet-sdk:`App +`, first instantiate a +:dotnet-sdk:`Credentials ` +object containing the credentials associated with the authentication provider. +Then, pass it to :dotnet-sdk:`LogInAsync() +`. + +Each authentication provider corresponds to a :dotnet-sdk:`factory method +` +used to instantiate ``Credentials`` objects for that authentication provider. + +If successful, ``LogInAsync()`` returns a :dotnet-sdk:`User +` object. In the event of a failure, +``LogInAsync()`` throws an exception of type :dotnet-sdk:`AppException +`. + +.. tip:: + + You can get the authentication provider type used to log in a user + through the :dotnet-sdk:`UserIdentity.Provider + ` + property. If the user is currently logged out, the most recent provider + used to log in the user is returned. diff --git a/source/includes/api-details/csharp/users/authenticate-log-user-out-description.rst b/source/includes/api-details/csharp/users/authenticate-log-user-out-description.rst new file mode 100644 index 0000000000..a56ce6975a --- /dev/null +++ b/source/includes/api-details/csharp/users/authenticate-log-user-out-description.rst @@ -0,0 +1 @@ +Once logged in, you can log out by calling the ``LogOutAsync()`` method: diff --git a/source/includes/api-details/csharp/users/authenticate-observe-authentication-changes.rst b/source/includes/api-details/csharp/users/authenticate-observe-authentication-changes.rst new file mode 100644 index 0000000000..8ec8b1edee --- /dev/null +++ b/source/includes/api-details/csharp/users/authenticate-observe-authentication-changes.rst @@ -0,0 +1,8 @@ +.. versionadded:: v11.6.0 + +You can observe a flow of authentication change events by calling +:dotnet-sdk:`User.Changed() ` +on a valid user object. + +Currently, ``User.Changed()`` triggers on all user events and you should add a +handler to ensure your responses to events are idempotent. diff --git a/source/includes/api-details/csharp/users/authenticate-register-create-new-user-account-description.rst b/source/includes/api-details/csharp/users/authenticate-register-create-new-user-account-description.rst new file mode 100644 index 0000000000..96a7fe9a90 --- /dev/null +++ b/source/includes/api-details/csharp/users/authenticate-register-create-new-user-account-description.rst @@ -0,0 +1,8 @@ +When a user registers or successfully authenticates to your App, Atlas App +Services automatically creates a :dotnet-sdk:`User +` object, which contains a unique +identifier and provider-specific :ref:`user metadata `. +You can optionally configure :ref:`custom user data ` +if your app needs to store additional user data. To learn more about the +user object that App Services provides, refer to :ref:`` in the +App Services documentation. diff --git a/source/includes/api-details/dart/users/authenticate-anonymous-description.rst b/source/includes/api-details/dart/users/authenticate-anonymous-description.rst new file mode 100644 index 0000000000..6db6d11cc4 --- /dev/null +++ b/source/includes/api-details/dart/users/authenticate-anonymous-description.rst @@ -0,0 +1,11 @@ +To log in with anonymous +authentication, create an anonymous credential by calling +:flutter-sdk:`Credentials.anonymous() ` +and then pass the generated credential to +``app.logIn``. + +.. literalinclude:: /examples/generated/flutter/authenticate_users_test.snippet.anonymous-credentials.dart + :language: dart + +If you want more than one anonymous user, set ``reuseCredentials: false`` +when creating additional anonymous credentials. diff --git a/source/includes/api-details/dart/users/authenticate-api-key-description.rst b/source/includes/api-details/dart/users/authenticate-api-key-description.rst new file mode 100644 index 0000000000..f490f14c4e --- /dev/null +++ b/source/includes/api-details/dart/users/authenticate-api-key-description.rst @@ -0,0 +1,3 @@ +To log in with API key authentication, create an :flutter-sdk:`ApiKey ` +credential by calling :flutter-sdk:`Credentials.apiKey() ` +on an API key string. Then pass the credential to ``app.logIn()``. diff --git a/source/includes/api-details/dart/users/authenticate-apple-description.rst b/source/includes/api-details/dart/users/authenticate-apple-description.rst new file mode 100644 index 0000000000..a8a209a3e9 --- /dev/null +++ b/source/includes/api-details/dart/users/authenticate-apple-description.rst @@ -0,0 +1,3 @@ +To log in with Apple authentication, pass an Apple access token to +:flutter-sdk:`Credentials.apple() `. +Then pass the credential to ``app.logIn``. diff --git a/source/includes/api-details/dart/users/authenticate-custom-function-description.rst b/source/includes/api-details/dart/users/authenticate-custom-function-description.rst new file mode 100644 index 0000000000..7dd6910a7a --- /dev/null +++ b/source/includes/api-details/dart/users/authenticate-custom-function-description.rst @@ -0,0 +1,3 @@ +To log in with Custom Function authentication, pass a stringified JSON with +your custom arguments to :flutter-sdk:`Credentials.function() `. +Then pass the credential to ``app.logIn``. diff --git a/source/includes/api-details/dart/users/authenticate-custom-jwt-description.rst b/source/includes/api-details/dart/users/authenticate-custom-jwt-description.rst new file mode 100644 index 0000000000..5388201a41 --- /dev/null +++ b/source/includes/api-details/dart/users/authenticate-custom-jwt-description.rst @@ -0,0 +1,3 @@ +To log in with Custom JWT authentication, create a JWT credential by calling +:flutter-sdk:`Credentials.jwt() ` +on a JWT string. Then pass the credential to ``app.logIn``. diff --git a/source/includes/api-details/dart/users/authenticate-email-password-description.rst b/source/includes/api-details/dart/users/authenticate-email-password-description.rst new file mode 100644 index 0000000000..76eb83d4ba --- /dev/null +++ b/source/includes/api-details/dart/users/authenticate-email-password-description.rst @@ -0,0 +1,4 @@ +To log in with email/password authentication, create an +email/password credential by calling :flutter-sdk:`Credentials.emailPassword() ` +with the user's email and password. +Then pass the credential to ``app.logIn``. diff --git a/source/includes/api-details/dart/users/authenticate-facebook-description.rst b/source/includes/api-details/dart/users/authenticate-facebook-description.rst new file mode 100644 index 0000000000..3b2124c738 --- /dev/null +++ b/source/includes/api-details/dart/users/authenticate-facebook-description.rst @@ -0,0 +1,3 @@ +To log in with Facebook authentication, pass a Facebook access token to +:flutter-sdk:`Credentials.facebook() `. +Then pass the credential to ``app.logIn``. diff --git a/source/includes/api-details/dart/users/authenticate-get-current-user.rst b/source/includes/api-details/dart/users/authenticate-get-current-user.rst new file mode 100644 index 0000000000..3360becf5a --- /dev/null +++ b/source/includes/api-details/dart/users/authenticate-get-current-user.rst @@ -0,0 +1,3 @@ +Once you have an authenticated user, you can retrieve the User object with the +:flutter-sdk:`App.currentUser ` +property. diff --git a/source/includes/api-details/dart/users/authenticate-get-user-access-token-description.rst b/source/includes/api-details/dart/users/authenticate-get-user-access-token-description.rst new file mode 100644 index 0000000000..8a364e4237 --- /dev/null +++ b/source/includes/api-details/dart/users/authenticate-get-user-access-token-description.rst @@ -0,0 +1,2 @@ +You can get the access token with the :flutter-sdk:`User.accessToken +` property. diff --git a/source/includes/api-details/dart/users/authenticate-google-description.rst b/source/includes/api-details/dart/users/authenticate-google-description.rst new file mode 100644 index 0000000000..acb21e3f03 --- /dev/null +++ b/source/includes/api-details/dart/users/authenticate-google-description.rst @@ -0,0 +1,10 @@ +To log in with a Google authentication code, pass a Google authentication code to +:flutter-sdk:`Credentials.googleAuthCode() `. +Then pass the credential to ``app.logIn``. + +.. literalinclude:: /examples/generated/flutter/authenticate_users_test.snippet.google-auth-code-credentials.dart + :language: dart + +To log in with a Google ID token, pass a Google ID token to +:flutter-sdk:`Credentials.googleIdToken() `. +Then pass the credential to ``app.logIn``. diff --git a/source/includes/api-details/dart/users/authenticate-log-in-user-description.rst b/source/includes/api-details/dart/users/authenticate-log-in-user-description.rst new file mode 100644 index 0000000000..59f3f8eb17 --- /dev/null +++ b/source/includes/api-details/dart/users/authenticate-log-in-user-description.rst @@ -0,0 +1,21 @@ +To authenticate and log users in to your :flutter-sdk:`App +`, first instantiate a +:flutter-sdk:`Credentials ` +object containing the credentials associated with the authentication provider. +Then, pass it to :flutter-sdk:`App.logIn() `. + +Each authentication provider corresponds to a :flutter-sdk:`Credentials +constructor ` used to instantiate ``Credentials`` +objects for that authentication provider. + +If successful, ``App.logIn()`` returns a :flutter-sdk:`User +` object. In the event of a failure, ``App.logIn()`` +throws an exception of type :flutter-sdk:`AppException +`. + +.. tip:: + + You can get the authentication provider type used to log in a user + through the :flutter-sdk:`UserIdentity.provider + ` property. If the user is currently logged + out, the most recent provider used to log in the user is returned. diff --git a/source/includes/api-details/dart/users/authenticate-log-user-out-description.rst b/source/includes/api-details/dart/users/authenticate-log-user-out-description.rst new file mode 100644 index 0000000000..da8b852d54 --- /dev/null +++ b/source/includes/api-details/dart/users/authenticate-log-user-out-description.rst @@ -0,0 +1,2 @@ +You can log out any user, regardless of the authentication provider used +to log in, using :flutter-sdk:`User.logOut() `. diff --git a/source/includes/api-details/dart/users/authenticate-manually-refresh-access-token-description.rst b/source/includes/api-details/dart/users/authenticate-manually-refresh-access-token-description.rst new file mode 100644 index 0000000000..a458c7cbdf --- /dev/null +++ b/source/includes/api-details/dart/users/authenticate-manually-refresh-access-token-description.rst @@ -0,0 +1,9 @@ +Refresh an access token with :flutter-sdk:`User.refreshCustomData() `. + +.. literalinclude:: /examples/generated/flutter/access_token_test.snippet.refresh-access-token.dart + :language: dart + +You can also periodically refresh the access token +with `Timer.periodic() `__ +from the ``dart:async`` library. Wrap the call to ``User.refreshCustomData()`` +with the timer's callback function. diff --git a/source/includes/api-details/dart/users/authenticate-observe-authentication-changes-no-api.rst b/source/includes/api-details/dart/users/authenticate-observe-authentication-changes-no-api.rst new file mode 100644 index 0000000000..b685357360 --- /dev/null +++ b/source/includes/api-details/dart/users/authenticate-observe-authentication-changes-no-api.rst @@ -0,0 +1,5 @@ +Dart does not provide a dedicated API to observe authentication changes. However, +you can check the user's :flutter-sdk:`state +`, whose value is an enum of type +:flutter-sdk:`UserState `. This can give you information +about whether the user is logged in, logged out, or removed from the device. diff --git a/source/includes/api-details/dart/users/authenticate-register-create-new-user-account-description.rst b/source/includes/api-details/dart/users/authenticate-register-create-new-user-account-description.rst new file mode 100644 index 0000000000..f467da98d5 --- /dev/null +++ b/source/includes/api-details/dart/users/authenticate-register-create-new-user-account-description.rst @@ -0,0 +1,8 @@ +When a user registers or successfully authenticates to your App, Atlas App +Services automatically creates a :flutter-sdk:`User +` object, which contains a unique +identifier and provider-specific :ref:`user metadata `. +You can optionally configure :ref:`custom user data ` +if your app needs to store additional user data. To learn more about the +user object that App Services provides, refer to :ref:`` in the +App Services documentation. diff --git a/source/includes/api-details/java/users/authenticate-anonymous-description.rst b/source/includes/api-details/java/users/authenticate-anonymous-description.rst new file mode 100644 index 0000000000..deb27db55f --- /dev/null +++ b/source/includes/api-details/java/users/authenticate-anonymous-description.rst @@ -0,0 +1,4 @@ +To log in with anonymous +authentication, create an anonymous credential by calling +``Credentials.anonymous()`` and then pass the generated credential to +``app.login()`` or ``app.loginAsync()``. diff --git a/source/includes/api-details/java/users/authenticate-api-key-description.rst b/source/includes/api-details/java/users/authenticate-api-key-description.rst new file mode 100644 index 0000000000..613aefa51f --- /dev/null +++ b/source/includes/api-details/java/users/authenticate-api-key-description.rst @@ -0,0 +1,4 @@ +To log in with API Key authentication, create an +API Key credential by calling ``Credentials.apiKey()`` +with an API Key. Then pass the generated credential +to ``app.login()`` or ``app.loginAsync()``. diff --git a/source/includes/api-details/java/users/authenticate-apple-description.rst b/source/includes/api-details/java/users/authenticate-apple-description.rst new file mode 100644 index 0000000000..240ed28e8b --- /dev/null +++ b/source/includes/api-details/java/users/authenticate-apple-description.rst @@ -0,0 +1,4 @@ +To log in with Sign-in with Apple authentication, create a +Sign-in with Apple credential by calling ``Credentials.apple()`` +with the token provided by Apple. Then pass the generated credential +to ``app.login()`` or ``app.loginAsync()``. diff --git a/source/includes/api-details/java/users/authenticate-custom-function-description.rst b/source/includes/api-details/java/users/authenticate-custom-function-description.rst new file mode 100644 index 0000000000..dfcf011980 --- /dev/null +++ b/source/includes/api-details/java/users/authenticate-custom-function-description.rst @@ -0,0 +1,23 @@ +To log in with custom function authentication, create a credential by calling +``Credentials.customFunction()``. The :java-sdk:`customFunction() +` method expects a +Document that contains the properties and values used by the Atlas auth function. +For example, suppose the backend function expects the input parameter to include +a field named ``username``, like this: + +.. code-block:: js + :copyable: false + + exports = async function(loginPayload) { + const { username } = loginPayload; + ... + } + +The document you pass to ``Credentials.customFunction()`` might look like this: + +.. code-block:: java + :copyable: false + + Document("username", "bob") + +You then pass the generated credential to ``app.login()`` or ``app.loginAsync()``. diff --git a/source/includes/api-details/java/users/authenticate-custom-jwt-description.rst b/source/includes/api-details/java/users/authenticate-custom-jwt-description.rst new file mode 100644 index 0000000000..053a56dcfb --- /dev/null +++ b/source/includes/api-details/java/users/authenticate-custom-jwt-description.rst @@ -0,0 +1,4 @@ +To log in with custom JWT authentication, create a +custom JWT credential by calling ``Credentials.jwt()`` +with your custom JWT. Then pass the generated credential +to ``app.login()`` or ``app.loginAsync()``. diff --git a/source/includes/api-details/java/users/authenticate-email-password-description.rst b/source/includes/api-details/java/users/authenticate-email-password-description.rst new file mode 100644 index 0000000000..2a0c21ee62 --- /dev/null +++ b/source/includes/api-details/java/users/authenticate-email-password-description.rst @@ -0,0 +1,4 @@ +To log in with email/password authentication, create an +email/password credential by calling ``Credentials.emailPassword()`` +with the user's email and password. Then pass the generated credential +to ``app.login()`` or ``app.loginAsync()``. diff --git a/source/includes/api-details/java/users/authenticate-facebook-description.rst b/source/includes/api-details/java/users/authenticate-facebook-description.rst new file mode 100644 index 0000000000..d4a7230f31 --- /dev/null +++ b/source/includes/api-details/java/users/authenticate-facebook-description.rst @@ -0,0 +1,7 @@ +Follow the official :facebook:`Facebook Login for Android Quickstart +` to set up the authentication flow for your +application. In the login completion handler, get the logged in user's access +token from the Facebook :facebook:`LoginResult +`. Use the access token to +create a Facebook credential for Atlas Device SDK, and then log the user into +your app. diff --git a/source/includes/api-details/java/users/authenticate-google-description.rst b/source/includes/api-details/java/users/authenticate-google-description.rst new file mode 100644 index 0000000000..8ca3233184 --- /dev/null +++ b/source/includes/api-details/java/users/authenticate-google-description.rst @@ -0,0 +1,72 @@ +Use Google's official :google:`Sign-In for Android ` to authenticate Google +users in your Android application: + +.. note:: Code Example Below + + For an implementation of these instructions, check out the code block + below. + +1. Add the Google Sign-In for Android dependency to the ``dependencies`` + block of your application level ``build.gradle``: + + .. code-block:: groovy + :copyable: false + + com.google.android.gms:play-services-auth:19.2.0 + +#. Create a :google:`GoogleSignInOptions + ` + with the following builder options: + + - :google:`default sign in + ` + - an :google:`ID token request + ` + -- pass your OAuth 2.0 client ID as the ``serverClientId``. + +#. Use the ``GoogleSignInOptions`` to create a ``GoogleSignInClient`` + with :google:`GoogleSignIn.getClient() + ` + +#. Use the ``GoogleSignInClient`` to create an ``Intent`` capable of + triggering Google Sign-In. + +#. Use :android:`registerForActivityResult() + ` + to configure a callback. Your callback should use :google:`GoogleSignIn.getSignedInAccountFromIntent() + ` + to access the result of Google Sign-In: a ``Task``. + +#. Use the :android:`launch() + ` + method of the :android:`ActivityResultLauncher + ` + returned in the previous step to start Google Sign-In. Pass the + ``launch()`` method your Google Sign-In ``Intent``. + +#. Use ``isSuccessful()`` to handle Google Sign-In errors. + +#. Access the result of the task (a :google:`GoogleSignInAccount + `) + with ``getResult()``. + +#. Access the ID token for the ``GoogleSignInAccount`` with ``getIdToken()``. + +#. Create a Realm ``Credentials`` object with :java-sdk:`Credentials.google() + `. + Pass the ID token as the first parameter, and :java-sdk:`GoogleAuthType.ID_TOKEN + ` as the second parameter. + +#. Use the :java-sdk:`app.loginAsync() + ` + or :java-sdk:`app.login() ` + methods to authenticate with the Atlas App Services backend using the token. + +.. seealso:: + + To learn more about Google Sign-In for Android, check out the + official :google:`Google Sign-In for Android Integration Guide + `. + +The following code implements this flow, starting with a method call to +``loginWithGoogle()``: diff --git a/source/includes/api-details/java/users/authenticate-log-in-user-description.rst b/source/includes/api-details/java/users/authenticate-log-in-user-description.rst new file mode 100644 index 0000000000..0f3d086715 --- /dev/null +++ b/source/includes/api-details/java/users/authenticate-log-in-user-description.rst @@ -0,0 +1,36 @@ +To authenticate and log users in to your :java-sdk:`App +`, first instantiate a +:java-sdk:`Credentials ` object containing +the credentials associated with the authentication provider. +Then, pass it to :java-sdk:`App.login() +` or +:java-sdk:`App.loginAsync() `. + +While the ``app.login()`` method blocks +code execution in the calling thread until the supplied credentials have +either succeeded or failed to authenticate a user, the +``app.loginAsync()`` method allows execution to continue, handling +success or failure with a callback function that is guaranteed to +execute on the same thread that called ``app.loginAsync()``. + +Each authentication provider corresponds to a :java-sdk:`static helper method +` used to instantiate ``Credentials`` +objects for that authentication provider. + +If successful, ``App.login()`` returns a :java-sdk:`User ` +object. In the event of a failure, ``App.login()`` throws an +exception of type :java-sdk:`AppException `. + +Pass a callback to the ``App.loginAsync()`` method to handle success or +failure. This callback accepts a single parameter of type +``App.Result``. The ``isSuccess()`` method of the ``App.Result`` object +passed to the callback returns a boolean that indicates whether the +operation succeeded. In the event of a failure, you can view the +error that caused the failure using the ``getError()`` method. + +.. tip:: + + You can get the authentication provider type used to log in a user + through the :java-sdk:`UserIdentity.getProvider() + ` method. If the user is currently + logged out, the most recent provider used to log in the user is returned. diff --git a/source/includes/api-details/java/users/authenticate-log-user-out-description.rst b/source/includes/api-details/java/users/authenticate-log-user-out-description.rst new file mode 100644 index 0000000000..3de604767f --- /dev/null +++ b/source/includes/api-details/java/users/authenticate-log-user-out-description.rst @@ -0,0 +1,3 @@ +You can log out any user, regardless of the authentication provider used +to log in, using the ``user.logOut()`` or ``user.logOutAsync()`` +methods. diff --git a/source/includes/api-details/java/users/authenticate-register-create-new-user-account-description.rst b/source/includes/api-details/java/users/authenticate-register-create-new-user-account-description.rst new file mode 100644 index 0000000000..bfb428b7f4 --- /dev/null +++ b/source/includes/api-details/java/users/authenticate-register-create-new-user-account-description.rst @@ -0,0 +1,8 @@ +When a user registers or successfully authenticates to your App, Atlas App +Services automatically creates a :java-sdk:`User +` object, which contains a unique +identifier and provider-specific :ref:`user metadata `. +You can optionally configure :ref:`custom user data ` +if your app needs to store additional user data. To learn more about the +user object that App Services provides, refer to :ref:`` in the +App Services documentation. diff --git a/source/includes/api-details/javascript/users/authenticate-anonymous-js-ts-description.rst b/source/includes/api-details/javascript/users/authenticate-anonymous-js-ts-description.rst new file mode 100644 index 0000000000..f77e18f9a5 --- /dev/null +++ b/source/includes/api-details/javascript/users/authenticate-anonymous-js-ts-description.rst @@ -0,0 +1 @@ +To log in, create an anonymous credential and pass it to ``App.logIn()``: diff --git a/source/includes/api-details/javascript/users/authenticate-api-key-js-ts-description.rst b/source/includes/api-details/javascript/users/authenticate-api-key-js-ts-description.rst new file mode 100644 index 0000000000..33393a54a8 --- /dev/null +++ b/source/includes/api-details/javascript/users/authenticate-api-key-js-ts-description.rst @@ -0,0 +1,2 @@ +To log in with an API key, create an API Key credential with a server or user +API key and pass it to ``App.logIn()``: diff --git a/source/includes/api-details/javascript/users/authenticate-apple-js-ts-description.rst b/source/includes/api-details/javascript/users/authenticate-apple-js-ts-description.rst new file mode 100644 index 0000000000..67ba80b901 --- /dev/null +++ b/source/includes/api-details/javascript/users/authenticate-apple-js-ts-description.rst @@ -0,0 +1,5 @@ +You can use the :apple:`official Sign in with Apple JS SDK +` to handle the user +authentication and redirect flow from a client application. Once authenticated, +the Apple JS SDK returns an ID token that you can send to your app and +use to finish logging the user in to your app. diff --git a/source/includes/api-details/javascript/users/authenticate-custom-function-js-ts-description.rst b/source/includes/api-details/javascript/users/authenticate-custom-function-js-ts-description.rst new file mode 100644 index 0000000000..c22f0c1e8d --- /dev/null +++ b/source/includes/api-details/javascript/users/authenticate-custom-function-js-ts-description.rst @@ -0,0 +1,2 @@ +To log in with the custom function provider, create a Custom Function credential +with a payload object and pass it to ``App.logIn()``: diff --git a/source/includes/api-details/javascript/users/authenticate-custom-jwt-js-ts-description.rst b/source/includes/api-details/javascript/users/authenticate-custom-jwt-js-ts-description.rst new file mode 100644 index 0000000000..f8f71ea0d2 --- /dev/null +++ b/source/includes/api-details/javascript/users/authenticate-custom-jwt-js-ts-description.rst @@ -0,0 +1,2 @@ +To log in, create a Custom JWT credential with a JWT from the external system +and pass it to ``App.logIn()``: diff --git a/source/includes/api-details/javascript/users/authenticate-email-password-js-ts-description.rst b/source/includes/api-details/javascript/users/authenticate-email-password-js-ts-description.rst new file mode 100644 index 0000000000..1ca3418102 --- /dev/null +++ b/source/includes/api-details/javascript/users/authenticate-email-password-js-ts-description.rst @@ -0,0 +1,2 @@ +To log in, create an email/password credential with the user's email address and +password and pass it to ``App.logIn()``: diff --git a/source/includes/api-details/javascript/users/authenticate-facebook-js-ts-description.rst b/source/includes/api-details/javascript/users/authenticate-facebook-js-ts-description.rst new file mode 100644 index 0000000000..25ed810bd8 --- /dev/null +++ b/source/includes/api-details/javascript/users/authenticate-facebook-js-ts-description.rst @@ -0,0 +1,4 @@ +You can use the :facebook:`official Facebook SDK ` +to handle the user authentication and redirect flow from a client application. +Once authenticated, the Facebook SDK returns an access token that you can send +to your app and use to finish logging the user in to your app. diff --git a/source/includes/api-details/javascript/users/authenticate-google-description.rst b/source/includes/api-details/javascript/users/authenticate-google-description.rst new file mode 100644 index 0000000000..1d34349de6 --- /dev/null +++ b/source/includes/api-details/javascript/users/authenticate-google-description.rst @@ -0,0 +1,42 @@ +.. _example-auth-google-node-server: + +.. example:: Authenticate with Google on a Node.js Server + + Refer to `the code for an example Node.js server `_ + that implements Sign in With Google. + All of the Google OAuth 2.0 implementation is in the ``server.js`` file. + + The example uses `Express `_ for routing and the + Google Auth Library for Node.js. + + You might want to authenticate with Google on a Node.js server + to perform server-side operations on behalf of a user, like call an + Atlas Function with a user's credentials. + +Use the official `Google Auth Library for Node.js `_ +to handle the user authentication and redirect flow from a Node.js client application: + +#. Install the Realm and Google APIs npm packages. + + .. code-block:: + + npm install realm googleapis + +#. Import the packages into your project. + + .. literalinclude:: /examples/generated/node/server.snippet.import-npm-packages.js + :language: javascript + +#. Create configuration for Google OAuth 2.0 client and the SDK. + + .. literalinclude:: /examples/generated/node/server.snippet.google-oauth-realm-config.js + :language: javascript + +#. Generate an OAuth login link, and pass it to the application client. + + .. literalinclude:: /examples/generated/node/server.snippet.generate-log-in.js + :language: javascript + +#. Process the request from the the Google authentication server, which includes + an access code in the query string using the Google OAuth 2.0 client's ``getToken()`` + method. In the callback function, sign in to your App using the ``id_token``. diff --git a/source/includes/api-details/javascript/users/authenticate-log-in-user-js-ts-description.rst b/source/includes/api-details/javascript/users/authenticate-log-in-user-js-ts-description.rst new file mode 100644 index 0000000000..f4b0ecbf1d --- /dev/null +++ b/source/includes/api-details/javascript/users/authenticate-log-in-user-js-ts-description.rst @@ -0,0 +1,21 @@ +To authenticate and log users in to your :js-sdk:`App +`, first instantiate a +:js-sdk:`Credentials ` object containing the +credentials associated with the authentication provider. +Then, pass it to :js-sdk:`App.logIn() `. + +Each authentication provider corresponds to a :js-sdk:`Credentials +method ` used to instantiate ``Credentials`` +objects for that authentication provider. + +If successful, ``App.logIn()`` returns a :js-sdk:`User +` object. In the event of a failure, ``App.logIn()`` +throws an exception. + +.. tip:: + + You can get the authentication provider type used to log in a user + through the :js-sdk:`UserIdentity.providerType + `. If the user is + currently logged out, the most recent provider used to log in the user is + returned. diff --git a/source/includes/api-details/javascript/users/authenticate-log-user-out-js-ts-description.rst b/source/includes/api-details/javascript/users/authenticate-log-user-out-js-ts-description.rst new file mode 100644 index 0000000000..a417e04f50 --- /dev/null +++ b/source/includes/api-details/javascript/users/authenticate-log-user-out-js-ts-description.rst @@ -0,0 +1 @@ +To log any user out, call the ``User.logOut()`` on their user instance. diff --git a/source/includes/api-details/javascript/users/authenticate-register-create-new-user-account-js-ts-description.rst b/source/includes/api-details/javascript/users/authenticate-register-create-new-user-account-js-ts-description.rst new file mode 100644 index 0000000000..7704e4c074 --- /dev/null +++ b/source/includes/api-details/javascript/users/authenticate-register-create-new-user-account-js-ts-description.rst @@ -0,0 +1,8 @@ +When a user registers or successfully authenticates to your App, Atlas App +Services automatically creates a :js-sdk:`User +` object, which contains a unique +identifier and provider-specific :ref:`user metadata `. +You can optionally configure :ref:`custom user data ` +if your app needs to store additional user data. To learn more about the +user object that App Services provides, refer to :ref:`` in the +App Services documentation. diff --git a/source/includes/api-details/kotlin/users/authenticate-anonymous-description.rst b/source/includes/api-details/kotlin/users/authenticate-anonymous-description.rst new file mode 100644 index 0000000000..98ef7b054b --- /dev/null +++ b/source/includes/api-details/kotlin/users/authenticate-anonymous-description.rst @@ -0,0 +1,14 @@ +To log in with anonymous authentication, create an anonymous credential +by calling :kotlin-sync-sdk:`Credentials.anonymous() +`, +and then pass the generated credential to +:kotlin-sync-sdk:`app.login() +`: + +.. literalinclude:: /examples/generated/kotlin/AuthenticationTest.snippet.anonymous-authentication.kt + :language: kotlin + +By default, the Kotlin SDK reuses the same anonymous user +if that user has not logged out. If you want to create more than +one anonymous user, set ``reuseExisting = false`` when logging in +with additional anonymous credentials: diff --git a/source/includes/api-details/kotlin/users/authenticate-api-key-description.rst b/source/includes/api-details/kotlin/users/authenticate-api-key-description.rst new file mode 100644 index 0000000000..471fcb4880 --- /dev/null +++ b/source/includes/api-details/kotlin/users/authenticate-api-key-description.rst @@ -0,0 +1,6 @@ +To log in with API key authentication, create an API Key credential +by calling :kotlin-sync-sdk:`Credentials.apiKey() +` +with the user's API key, and then passing the +generated credential to :kotlin-sync-sdk:`app.login() +`: diff --git a/source/includes/api-details/kotlin/users/authenticate-apple-description.rst b/source/includes/api-details/kotlin/users/authenticate-apple-description.rst new file mode 100644 index 0000000000..a74ebc8f19 --- /dev/null +++ b/source/includes/api-details/kotlin/users/authenticate-apple-description.rst @@ -0,0 +1,11 @@ +To log in with Apple authentication, create an +Apple credential by calling :kotlin-sync-sdk:`Credentials.apple() +` +with the user's token, and then pass the generated credential +to :kotlin-sync-sdk:`app.login() +`: + +Kotlin Multiplatform (KMP) supports many environments, but this example shows +sign-in on the Android platform. For information about signing in with Apple +on Apple platforms, switch the language selector on this page to +:guilabel:`Swift`. diff --git a/source/includes/api-details/kotlin/users/authenticate-custom-function-description.rst b/source/includes/api-details/kotlin/users/authenticate-custom-function-description.rst new file mode 100644 index 0000000000..306de035d3 --- /dev/null +++ b/source/includes/api-details/kotlin/users/authenticate-custom-function-description.rst @@ -0,0 +1,11 @@ +To log in with Custom Function authentication, pass your custom arguments +as a payload to :kotlin-sync-sdk:`Credentials.customFunction() +`, +and then pass the generated credential to :kotlin-sync-sdk:`app.login() +`. + +.. versionadded:: 1.9.0 + +You can serialize data for a Custom Function credential using an +EJSON encoder. For more information, including examples, refer to +:ref:`sdks-serialization`. diff --git a/source/includes/api-details/kotlin/users/authenticate-custom-jwt-description.rst b/source/includes/api-details/kotlin/users/authenticate-custom-jwt-description.rst new file mode 100644 index 0000000000..85fe790cd7 --- /dev/null +++ b/source/includes/api-details/kotlin/users/authenticate-custom-jwt-description.rst @@ -0,0 +1,6 @@ +To log in with JWT authentication, create a +JWT credential by calling :kotlin-sync-sdk:`Credentials.jwt() +` +with the user's JWT, and then pass the generated credential +to :kotlin-sync-sdk:`app.login() +`: diff --git a/source/includes/api-details/kotlin/users/authenticate-email-password-description.rst b/source/includes/api-details/kotlin/users/authenticate-email-password-description.rst new file mode 100644 index 0000000000..f4e321408a --- /dev/null +++ b/source/includes/api-details/kotlin/users/authenticate-email-password-description.rst @@ -0,0 +1,6 @@ +To log in with email/password authentication, create an +email/password credential by calling :kotlin-sync-sdk:`Credentials.emailPassword() +` +with the user's registered email and password, and then pass the +generated credential to :kotlin-sync-sdk:`app.login() +`: diff --git a/source/includes/api-details/kotlin/users/authenticate-facebook-description.rst b/source/includes/api-details/kotlin/users/authenticate-facebook-description.rst new file mode 100644 index 0000000000..e00156c9c3 --- /dev/null +++ b/source/includes/api-details/kotlin/users/authenticate-facebook-description.rst @@ -0,0 +1,21 @@ +Before you can authenticate users with Facebook, you must set up +the authentication flow for your application by following the +official :facebook:`Facebook Login for Android Quickstart +`. + +In the login completion handler, get the logged in user's access +token from the Facebook +:facebook:`LoginResult `. +Use the access token to create a Facebook credential by calling +:kotlin-sync-sdk:`Credentials.facebook() +` +with the user's access token, and then pass the generated credential +to :kotlin-sync-sdk:`app.login() +`. + +.. include:: /includes/note-facebook-profile-picture-url.rst + +Kotlin Multiplatform (KMP) supports many environments, but this example shows +sign-in on the Android platform. For information about signing into a Facebook +account on Apple platforms, switch the language selector on this page to +:guilabel:`Swift`. diff --git a/source/includes/api-details/kotlin/users/authenticate-get-current-user-description.rst b/source/includes/api-details/kotlin/users/authenticate-get-current-user-description.rst new file mode 100644 index 0000000000..ed4c543af7 --- /dev/null +++ b/source/includes/api-details/kotlin/users/authenticate-get-current-user-description.rst @@ -0,0 +1,2 @@ +To retrieve the currently logged-in user with the :kotlin-sync-sdk:`App.currentUser +` property: diff --git a/source/includes/api-details/kotlin/users/authenticate-get-user-access-token-description.rst b/source/includes/api-details/kotlin/users/authenticate-get-user-access-token-description.rst new file mode 100644 index 0000000000..7edaa8b3ac --- /dev/null +++ b/source/includes/api-details/kotlin/users/authenticate-get-user-access-token-description.rst @@ -0,0 +1,3 @@ +You can get the current access token for a logged-in user with the +:kotlin-sync-sdk:`user.accessToken ` +property: diff --git a/source/includes/api-details/kotlin/users/authenticate-google-description.rst b/source/includes/api-details/kotlin/users/authenticate-google-description.rst new file mode 100644 index 0000000000..9569cb959e --- /dev/null +++ b/source/includes/api-details/kotlin/users/authenticate-google-description.rst @@ -0,0 +1,15 @@ +Use Google's official :google:`Sign-In for Android ` +to authenticate Google users in your Android application. The following +code implements this flow, starting with a method call to +``loginWithGoogle()``. + +.. tip:: + + To learn more about Google Sign-In for Android, check out the + official :google:`Google Sign-In for Android Integration Guide + `. + +Kotlin Multiplatform (KMP) supports many environments, but this example shows +sign-in on the Android platform. For information about signing into a Google +account on Apple platforms, switch the language selector on this page to +:guilabel:`Swift`. diff --git a/source/includes/api-details/kotlin/users/authenticate-log-in-user-description.rst b/source/includes/api-details/kotlin/users/authenticate-log-in-user-description.rst new file mode 100644 index 0000000000..07d002302f --- /dev/null +++ b/source/includes/api-details/kotlin/users/authenticate-log-in-user-description.rst @@ -0,0 +1,38 @@ +To authenticate and log users in to your :kotlin-sync-sdk:`App +`, first instantiate a +:kotlin-sync-sdk:`Credentials ` +object containing the credentials associated with the authentication provider. +Then, pass it to :kotlin-sync-sdk:`app.login() +`. + +Each authentication provider corresponds to a :kotlin-sync-sdk:`static helper method +` +used to instantiate ``Credentials`` objects for that authentication provider. + +If successful, ``app.login()`` returns a :kotlin-sync-sdk:`User +` object. In the event of a failure, +``app.login()`` throws one of three exception types, depending on the error: + +- :kotlin-sync-sdk:`AuthException + `: the + top-level or "catch-all" for problems related to user account actions. Prefer + catching sub-types for granular error handling. +- :kotlin-sync-sdk:`InvalidCredentialsException + `: + the provided credentials were not correct. Only email/password, API Key, + and JWT providers can throw this exception. Other providers throw + ``AuthException``. +- :kotlin-sync-sdk:`ServiceException + `: the + top-level or "catch-all" for problems related to HTTP requests made to + App Services. This covers HTTP transport problems, problems passing JSON, or + the server considering the request invalid. Prefer catching sub-types for + more granular error handling. + +.. tip:: + + You can get the authentication provider type used to log in a user + through the :kotlin-sync-sdk:`UserIdentity.provider + ` property. If the + user is currently logged out, the most recent provider used to log in the + user is returned. diff --git a/source/includes/api-details/kotlin/users/authenticate-log-user-out-description.rst b/source/includes/api-details/kotlin/users/authenticate-log-user-out-description.rst new file mode 100644 index 0000000000..d4188cbc7a --- /dev/null +++ b/source/includes/api-details/kotlin/users/authenticate-log-user-out-description.rst @@ -0,0 +1,3 @@ +You can log out any user, regardless of the authentication provider used +to log in, using :kotlin-sync-sdk:`user.logOut() +`: diff --git a/source/includes/api-details/kotlin/users/authenticate-manually-refresh-access-token-description.rst b/source/includes/api-details/kotlin/users/authenticate-manually-refresh-access-token-description.rst new file mode 100644 index 0000000000..e14533c89a --- /dev/null +++ b/source/includes/api-details/kotlin/users/authenticate-manually-refresh-access-token-description.rst @@ -0,0 +1,3 @@ +You can get the current refresh token for a logged-in user with the +:kotlin-sync-sdk:`user.refreshToken ` +property, which you can use to request a new access token: diff --git a/source/includes/api-details/kotlin/users/authenticate-observe-authentication-changes-description.rst b/source/includes/api-details/kotlin/users/authenticate-observe-authentication-changes-description.rst new file mode 100644 index 0000000000..4fdfb03474 --- /dev/null +++ b/source/includes/api-details/kotlin/users/authenticate-observe-authentication-changes-description.rst @@ -0,0 +1,15 @@ +.. versionadded:: 10.8.0 + +You can observe a flow of authentication change events by calling +:kotlin-sync-sdk:`App.authenticationChangeAsFlow() +`. +This flow emits :kotlin-sync-sdk:`AuthenticationChange +` +events of three possible states, represented as subclasses: + +- ``LoggedIn``: A user logs into the app. +- ``LoggedOut``: A a user logs out of the app. +- ``Removed``: A user is removed from the app, which also logs them out. + +These events contain a ``user`` property that provides a reference to the +``User`` object that has logged in, logged out, or been removed. diff --git a/source/includes/api-details/kotlin/users/authenticate-register-create-new-user-account-description.rst b/source/includes/api-details/kotlin/users/authenticate-register-create-new-user-account-description.rst new file mode 100644 index 0000000000..dd69ceee00 --- /dev/null +++ b/source/includes/api-details/kotlin/users/authenticate-register-create-new-user-account-description.rst @@ -0,0 +1,8 @@ +When a user registers or successfully authenticates to your App, Atlas App +Services automatically creates a :kotlin-sync-sdk:`User +` object, which contains a unique +identifier and provider-specific :ref:`user metadata `. +You can optionally configure :ref:`custom user data ` +if your app needs to store additional user data. To learn more about the +user object that App Services provides, refer to :ref:`` in the +App Services documentation. diff --git a/source/includes/api-details/swift/users/authenticate-facebook-description.rst b/source/includes/api-details/swift/users/authenticate-facebook-description.rst new file mode 100644 index 0000000000..80b3da2463 --- /dev/null +++ b/source/includes/api-details/swift/users/authenticate-facebook-description.rst @@ -0,0 +1,6 @@ +Follow the official :facebook:`Facebook Login for iOS Quickstart +` to set up the authentication +flow for your application. In the login completion handler, create an +App Services Facebook credential with the logged in user's +:facebook:`access token string ` and +log the user into your App Services app. diff --git a/source/includes/api-details/swift/users/authenticate-get-user-access-token.rst b/source/includes/api-details/swift/users/authenticate-get-user-access-token.rst new file mode 100644 index 0000000000..72148976c7 --- /dev/null +++ b/source/includes/api-details/swift/users/authenticate-get-user-access-token.rst @@ -0,0 +1,5 @@ +You can call :swift-sdk:`.refreshCustomData() +` +on a logged-in user to refresh the user's auth session. Then, return the +``.accessToken`` as a string you can use in your code. You might use a +function similar to this to fetch an access token: diff --git a/source/includes/api-details/swift/users/authenticate-google-description.rst b/source/includes/api-details/swift/users/authenticate-google-description.rst new file mode 100644 index 0000000000..76e4fd59ba --- /dev/null +++ b/source/includes/api-details/swift/users/authenticate-google-description.rst @@ -0,0 +1,17 @@ +Follow the official :google:`Google Sign-In for iOS Integration Guide +` to set up the authentication flow for +your application. In the sign-in completion handler, create an App Services +Google credential and log the user into your App Services app. + +The value that you pass to the credential depends on whether or not you have +:ref:`enabled OpenID Connect ` for the provider: + +- If OpenID Connect is enabled, pass the ``id_token`` + :google:`included in the Google OAuth response + ` to :swift-sdk:`Credentials.googleId(token:) + `. + +- If OpenID Connect is not enabled, pass the user's :google:`server auth code + ` to + :swift-sdk:`Credentials.google(serverAuthCode:) + `. diff --git a/source/includes/api-details/swift/users/authenticate-log-in-user-description.rst b/source/includes/api-details/swift/users/authenticate-log-in-user-description.rst new file mode 100644 index 0000000000..0632db4092 --- /dev/null +++ b/source/includes/api-details/swift/users/authenticate-log-in-user-description.rst @@ -0,0 +1,27 @@ +To authenticate and log users in to your :swift-sdk:`App +`, first instantiate a +:swift-sdk:`Credentials ` +object containing the credentials associated with the authentication provider. +Then, pass it to :flutter-sdk:`App.logIn() `. + +Each authentication provider corresponds to a :swift-sdk:`Credentials helper +method ` used to instantiate ``Credentials`` +objects for that authentication provider. + +If successful, ``App.login()`` returns a :swift-sdk:`User +` object. In the event of a failure, ``App.login()`` +throws an exception of type :swift-sdk:`AppError +`, which is a type alias for the +underlying :objc-sdk:`RLMAppError `. + +**Async/Await Login** + +.. versionadded:: 10.15.0 + +The async/await version of the :swift-sdk:`App.login ` +method asynchronously returns a User or Error. + +.. literalinclude:: /examples/generated/code/start/Authenticate.snippet.async-await.swift + :language: swift + +.. include:: /includes/swift-async-await-support.rst diff --git a/source/includes/api-details/swift/users/authenticate-manually-refresh-access-token-description.rst b/source/includes/api-details/swift/users/authenticate-manually-refresh-access-token-description.rst new file mode 100644 index 0000000000..72148976c7 --- /dev/null +++ b/source/includes/api-details/swift/users/authenticate-manually-refresh-access-token-description.rst @@ -0,0 +1,5 @@ +You can call :swift-sdk:`.refreshCustomData() +` +on a logged-in user to refresh the user's auth session. Then, return the +``.accessToken`` as a string you can use in your code. You might use a +function similar to this to fetch an access token: diff --git a/source/includes/api-details/swift/users/authenticate-register-create-new-user-account-description.rst b/source/includes/api-details/swift/users/authenticate-register-create-new-user-account-description.rst new file mode 100644 index 0000000000..5794d69794 --- /dev/null +++ b/source/includes/api-details/swift/users/authenticate-register-create-new-user-account-description.rst @@ -0,0 +1,8 @@ +When a user registers or successfully authenticates to your App, Atlas App +Services automatically creates a :swift-sdk:`User +Extensions/User.html>` object, which contains a unique +identifier and provider-specific :ref:`user metadata `. +You can optionally configure :ref:`custom user data ` +if your app needs to store additional user data. To learn more about the +user object that App Services provides, refer to :ref:`` in the +App Services documentation. diff --git a/source/includes/api-details/typescript/users/authenticate-google-missing-example.rst b/source/includes/api-details/typescript/users/authenticate-google-missing-example.rst new file mode 100644 index 0000000000..015d588e2a --- /dev/null +++ b/source/includes/api-details/typescript/users/authenticate-google-missing-example.rst @@ -0,0 +1,5 @@ +The documentation does not contain a TypeScript example for authentication +with Google. + +Instead, refer to the JavaScript example. Select :guilabel:`JavaScript` from +the programming language selector on this page to see the JavaScript example. diff --git a/source/includes/authorization-appleidcredential-string.rst b/source/includes/authorization-appleidcredential-string.rst deleted file mode 100644 index 7931623208..0000000000 --- a/source/includes/authorization-appleidcredential-string.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. tip:: - - If you get a ``Login failed`` error saying that the ``token contains - an invalid number of segments``, verify that you're passing a UTF-8-encoded - string version of the JWT. \ No newline at end of file diff --git a/source/includes/log-out-queries-in-progress.rst b/source/includes/log-out-queries-in-progress.rst index 0f0448f0ab..8188aeee72 100644 --- a/source/includes/log-out-queries-in-progress.rst +++ b/source/includes/log-out-queries-in-progress.rst @@ -1,7 +1,7 @@ .. warning:: When a user logs out, you can no longer read or write data in any - synced realms that the user opened. As a result, any operation + synced databases that the user opened. As a result, any operation that has not yet completed before the initiating user logs out cannot complete successfully and will likely result in an error. Any data in a write operation that fails in this way will be lost. diff --git a/source/includes/note-enable-facebook-auth.rst b/source/includes/note-enable-facebook-auth.rst deleted file mode 100644 index 2f9e0c3bdf..0000000000 --- a/source/includes/note-enable-facebook-auth.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. important:: Enable the Facebook Auth Provider - - To log a user in with their existing Facebook account, you must configure and - enable the :ref:`Facebook authentication provider ` - for your application. diff --git a/source/includes/offline-login.rst b/source/includes/offline-login.rst deleted file mode 100644 index 5f640a0644..0000000000 --- a/source/includes/offline-login.rst +++ /dev/null @@ -1,10 +0,0 @@ -When your Realm application authenticates a user, it caches the user's -credentials. You can check for existing user credentials to bypass the -login flow and access the cached user. Use this to open a realm offline. - -.. note:: Initial login requires a network connection - - When a user signs up for your app, or logs in for the first time with an - existing account on a client, the client must have a network connection. - Checking for cached user credentials lets you open a realm offline, but - only if the user has previously logged in while online. \ No newline at end of file diff --git a/source/includes/refresh-token-expiry.rst b/source/includes/refresh-token-expiry.rst index 73b7174724..3a72d1d882 100644 --- a/source/includes/refresh-token-expiry.rst +++ b/source/includes/refresh-token-expiry.rst @@ -2,11 +2,10 @@ Refresh tokens expire after a set period of time. When the refresh token expires, the access token can no longer be refreshed and the user must log in again. -If the refresh token expires after the realm is open, the device will not -be able to sync until the user logs in again. -Your sync error handler should implement logic that catches a token expired -error when attempting to sync, then redirect users to a -login flow. +If the refresh token expires after the database is open, the device cannot +sync until the user logs in again. Your sync error handler should implement +logic that catches a token expired error when attempting to sync, then redirect +users to a login flow. For information on configuring refresh token expiration, refer to -:ref:`` in the App Services documentation. +:ref:`refresh-token-expiration` in the App Services documentation. diff --git a/source/includes/sdk-examples/users/authenticate-anonymous.rst b/source/includes/sdk-examples/users/authenticate-anonymous.rst new file mode 100644 index 0000000000..0115bec835 --- /dev/null +++ b/source/includes/sdk-examples/users/authenticate-anonymous.rst @@ -0,0 +1,59 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/authentication.snippet.anonymous-login.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/AuthenticationExamples.snippet.logon_anon.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/authenticate_users_test.snippet.multiple-anonymous-credentials.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/AuthenticationTest.snippet.anonymous.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/AuthenticationTest.snippet.anonymous.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/authenticate.snippet.anonymous-login.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/AuthenticationTest.snippet.anonymous-authentication-reuse-existing.kt + :language: kotlin + :emphasize-lines: 6-7 + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/Authenticate.snippet.anonymous.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/authenticate.snippet.anonymous-login.ts + :language: typescript diff --git a/source/includes/sdk-examples/users/authenticate-api-key.rst b/source/includes/sdk-examples/users/authenticate-api-key.rst new file mode 100644 index 0000000000..525efb399f --- /dev/null +++ b/source/includes/sdk-examples/users/authenticate-api-key.rst @@ -0,0 +1,58 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/authentication.snippet.api-key.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/AuthenticationExamples.snippet.logon_API.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/authenticate_users_test.snippet.api-key-auth.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/AuthenticationTest.snippet.api-key.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/AuthenticationTest.snippet.api-key.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/authenticate.snippet.server-api-key-login.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/AuthenticationTest.snippet.api-key-authentication.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/Authenticate.snippet.api-key.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/authenticate.snippet.server-api-key-login.ts + :language: typescript diff --git a/source/includes/sdk-examples/users/authenticate-apple.rst b/source/includes/sdk-examples/users/authenticate-apple.rst new file mode 100644 index 0000000000..a91e521e3b --- /dev/null +++ b/source/includes/sdk-examples/users/authenticate-apple.rst @@ -0,0 +1,58 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/authentication.snippet.apple.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/AuthenticationExamples.snippet.logon_apple.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/authenticate_users_test.snippet.apple-credentials.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/AuthenticationTest.snippet.apple.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/AuthenticationTest.snippet.apple.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/web/authentication-log-in-and-out.test.snippet.apple-sdk-oauth.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/AuthenticationTest.snippet.apple-authentication.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/Authenticate.snippet.apple.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/includes/sdk-examples/users/authenticate-custom-function.rst b/source/includes/sdk-examples/users/authenticate-custom-function.rst new file mode 100644 index 0000000000..b0322f97f9 --- /dev/null +++ b/source/includes/sdk-examples/users/authenticate-custom-function.rst @@ -0,0 +1,58 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/authentication.snippet.custom-function.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/AuthenticationExamples.snippet.logon_Function.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/authenticate_users_test.snippet.custom-function-credentials.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/AuthenticationTest.snippet.custom-function.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/AuthenticationTest.snippet.custom-function.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/authenticate.snippet.custom-function-login.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/AuthenticationTest.snippet.custom-function-authentication.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/Authenticate.snippet.function.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/authenticate.snippet.custom-function-login.ts + :language: typescript diff --git a/source/includes/sdk-examples/users/authenticate-custom-jwt.rst b/source/includes/sdk-examples/users/authenticate-custom-jwt.rst new file mode 100644 index 0000000000..e4a58d1409 --- /dev/null +++ b/source/includes/sdk-examples/users/authenticate-custom-jwt.rst @@ -0,0 +1,58 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/authentication.snippet.custom-jwt.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/AuthenticationExamples.snippet.logon_JWT.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/authenticate_users_test.snippet.custom-jwt-credentials.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/AuthenticationTest.snippet.custom-jwt.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/AuthenticationTest.snippet.custom-jwt.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/authenticate.snippet.custom-jwt-login.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/AuthenticationTest.snippet.jwt-authentication.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/Authenticate.snippet.jwt.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/authenticate.snippet.custom-jwt-login.ts + :language: typescript diff --git a/source/includes/sdk-examples/users/authenticate-email-password.rst b/source/includes/sdk-examples/users/authenticate-email-password.rst new file mode 100644 index 0000000000..139f227d3a --- /dev/null +++ b/source/includes/sdk-examples/users/authenticate-email-password.rst @@ -0,0 +1,58 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/authentication.snippet.log-user-in.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/AuthenticationExamples.snippet.logon_EP.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/authenticate_users_test.snippet.email-password-credentials.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/AuthenticationTest.snippet.email-password.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/AuthenticationTest.snippet.email-password.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/authenticate.snippet.email-password-login.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/AuthenticationTest.snippet.email-password-authentication.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/Authenticate.snippet.email-password.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/authenticate.snippet.email-password-login.ts + :language: typescript diff --git a/source/includes/sdk-examples/users/authenticate-facebook.rst b/source/includes/sdk-examples/users/authenticate-facebook.rst new file mode 100644 index 0000000000..0af2ca4f54 --- /dev/null +++ b/source/includes/sdk-examples/users/authenticate-facebook.rst @@ -0,0 +1,60 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/authentication.snippet.facebook.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/AuthenticationExamples.snippet.logon_fb.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/authenticate_users_test.snippet.facebook-credentials.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/AuthenticationTest.snippet.facebook.java + :language: java + :emphasize-lines: 10-17 + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/AuthenticationTest.snippet.facebook.kt + :language: kotlin + :emphasize-lines: 10-21 + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/web/authentication-log-in-and-out.test.snippet.facebook-sdk-oauth.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/MainActivity.snippet.facebook-authentication.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/Authenticate.snippet.facebook.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/includes/sdk-examples/users/authenticate-get-current-user.rst b/source/includes/sdk-examples/users/authenticate-get-current-user.rst new file mode 100644 index 0000000000..1bd795f1f0 --- /dev/null +++ b/source/includes/sdk-examples/users/authenticate-get-current-user.rst @@ -0,0 +1,56 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/authentication.snippet.get-current-user.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/authenticate_users_test.snippet.retrieve-current-user.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/AuthenticationTest.snippet.retrieve-current-user.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/includes/sdk-examples/users/authenticate-get-user-access-token.rst b/source/includes/sdk-examples/users/authenticate-get-user-access-token.rst new file mode 100644 index 0000000000..ec97ba4526 --- /dev/null +++ b/source/includes/sdk-examples/users/authenticate-get-user-access-token.rst @@ -0,0 +1,58 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/authentication.snippet.get-user-access-token.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/AuthenticationExamples.snippet.get_user_token.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/access_token_test.snippet.get-access-token.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/AuthenticationTest.snippet.get-valid-access-token.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/AuthenticationTest.snippet.get-valid-access-token.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/authenticate.snippet.get-user-access-token.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/AuthenticationTest.snippet.access-token-get.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/Authenticate.snippet.refresh-user-access-token-function.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/authenticate.snippet.get-user-access-token.ts + :language: typescript diff --git a/source/includes/sdk-examples/users/authenticate-google.rst b/source/includes/sdk-examples/users/authenticate-google.rst new file mode 100644 index 0000000000..26b7e9ac78 --- /dev/null +++ b/source/includes/sdk-examples/users/authenticate-google.rst @@ -0,0 +1,69 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/authentication.snippet.google-id-token.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/AuthenticationExamples.snippet.logon_google.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/authenticate_users_test.snippet.google-id-token-credentials.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/AuthActivity.snippet.google.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/AuthActivity.snippet.google.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/server.snippet.login-with-token.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/MainActivity.snippet.google-authentication.kt + :language: kotlin + + - id: swift + content: | + + .. tabs:: + + .. tab:: ID Token + :tabid: idToken + + .. literalinclude:: /examples/generated/code/start/Authenticate.snippet.google-with-googleId.swift + :language: swift + + .. tab:: Server Auth Code + :tabid: serverAuthCode + + .. literalinclude:: /examples/generated/code/start/Authenticate.snippet.google-with-serverAuthCode.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/includes/sdk-examples/users/authenticate-log-in-offline.rst b/source/includes/sdk-examples/users/authenticate-log-in-offline.rst new file mode 100644 index 0000000000..f920afbc79 --- /dev/null +++ b/source/includes/sdk-examples/users/authenticate-log-in-offline.rst @@ -0,0 +1,58 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/AuthenticationTest.snippet.offline.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/AuthenticationTest.snippet.offline.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.open-realm-offline.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/Authenticate.snippet.offline-login.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/includes/sdk-examples/users/authenticate-log-in-user.rst b/source/includes/sdk-examples/users/authenticate-log-in-user.rst new file mode 100644 index 0000000000..472a383603 --- /dev/null +++ b/source/includes/sdk-examples/users/authenticate-log-in-user.rst @@ -0,0 +1,56 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/asymmetric-sync.snippet.create-asymmetric-object.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/data_ingest.test.snippet.write-asymmetric-object.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/AuthenticationTest.snippet.create-new-user.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/AsymmetricSync.snippet.create-asymmetric-object.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/asymmetric-sync.snippet.write-asymmetric-object.ts + :language: typescript diff --git a/source/includes/sdk-examples/users/authenticate-log-user-out.rst b/source/includes/sdk-examples/users/authenticate-log-user-out.rst new file mode 100644 index 0000000000..d6ee1d544d --- /dev/null +++ b/source/includes/sdk-examples/users/authenticate-log-user-out.rst @@ -0,0 +1,58 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/authentication.snippet.log-user-out.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/QuickStartExamples.snippet.logout.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/authenticate_users_test.snippet.log-out.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/AuthenticationTest.snippet.log-out.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/AuthenticationTest.snippet.log-out.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/authenticate.snippet.logout-current-user.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/AuthenticationTest.snippet.log-out.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/Authenticate.snippet.logout.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/includes/sdk-examples/users/authenticate-manually-refresh-access-token.rst b/source/includes/sdk-examples/users/authenticate-manually-refresh-access-token.rst new file mode 100644 index 0000000000..55d5dd87fe --- /dev/null +++ b/source/includes/sdk-examples/users/authenticate-manually-refresh-access-token.rst @@ -0,0 +1,56 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/authentication.snippet.get-user-access-token.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/access_token_test.snippet.periodic-refresh-access-token.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/AuthenticationTest.snippet.access-token-refresh.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/Authenticate.snippet.refresh-user-access-token-function.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/includes/sdk-examples/users/authenticate-observe-authentication-changes.rst b/source/includes/sdk-examples/users/authenticate-observe-authentication-changes.rst new file mode 100644 index 0000000000..5257fc72ad --- /dev/null +++ b/source/includes/sdk-examples/users/authenticate-observe-authentication-changes.rst @@ -0,0 +1,56 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/WorkWithRealm.snippet.observe-auth-change.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/AuthenticationTest.snippet.auth-change-listener.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.ts + :language: typescript diff --git a/source/includes/swift-async-await-support.rst b/source/includes/swift-async-await-support.rst index 6151d3a831..a29cb3a5be 100644 --- a/source/includes/swift-async-await-support.rst +++ b/source/includes/swift-async-await-support.rst @@ -1,5 +1,5 @@ -Starting with Realm Swift SDK Versions 10.15.0 and 10.16.0, many of the -Realm APIs support the Swift async/await syntax. Projects must +Starting with Swift SDK Versions 10.15.0 and 10.16.0, many of the +SDK's APIs support the Swift async/await syntax. Projects must meet these requirements: .. list-table:: @@ -19,5 +19,5 @@ meet these requirements: - Swift 5.5 - iOS 15.x -If your app accesses Realm in an ``async/await`` context, mark the code +If your app accesses the SDK in an ``async/await`` context, mark the code with ``@MainActor`` to avoid threading-related crashes. diff --git a/source/sdk/users/authenticate-users.txt b/source/sdk/users/authenticate-users.txt index 4b334a24b2..28f3dec981 100644 --- a/source/sdk/users/authenticate-users.txt +++ b/source/sdk/users/authenticate-users.txt @@ -4,10 +4,969 @@ Authenticate Users ================== +.. meta:: + :description: Learn how to use Atlas Device SDK authentication providers in client code, including anonymous auth, custom JWT, sign-in with Apple, and Google authentication. + :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Java SDK, .NET SDK, Node.js SDK, Swift SDK, code example + +.. facet:: + :name: genre + :values: reference + +.. facet:: + :name: programming_language + :values: cpp, csharp, dart, java, javascript/typescript, kotlin, swift + .. contents:: On this page :local: :backlinks: none :depth: 2 :class: singlecol -Placeholder page for authenticate users content. +After you :ref:`initialize an Atlas app connection `, +you must authenticate a user with an authentication provider. This page +describes how to authenticate App Services App users with Atlas Device SDK. +Refer to :ref:`` in the App Services documentation +for more information. + +.. include:: /includes/tip-acct-deletion-reqs.rst + +App Services Users +------------------ + +Atlas App Services provides the following built-in authentication providers +to log users in and out of a client app: + +- Anonymous users +- Email/password authentication +- API key authentication +- OAuth 2.0 through Facebook, Google, and Apple ID +- Custom JWT +- Custom Function + +Upon successful login, App Services begins a **user session** for the user. +App Services manages sessions with access tokens and refresh tokens. The SDK +supplies the logic to manage tokens and provide them with requests. For more +information on managing user sessions and tokens, refer to +:ref:`` in the App Services documentation. + +Once you have a logged-in user, you can: + +- :ref:`Open a synced database ` + with the user's configuration object +- :ref:`Call an Atlas Function ` as the logged-in user +- Log the user out (refer to the :ref:`` section) +- :ref:`Remove or delete the user's account ` + +You can also log multiple users in to an app simultaneously on a +single device. Refer to :ref:`sdks-multi-user-applications` for +more information. + +Prerequisites +------------- + +To authenticate users through Atlas App Services, you must have an +App Services App with one or more authentication providers enabled. + +To set up an App Services App with authentication providers, +complete the following: + +#. :ref:`Connect your App to Atlas App Services ` +#. :ref:`Enable and Configure Authentication Providers + ` in the App Services documentation + +.. tip:: + + You can enable multiple authentication providers. + If a user authenticates using more than one method, + you can :ref:`link the user identities ` + for each method to a single user account. + +.. _sdks-register-new-user: + +Register and Create a New User Account +-------------------------------------- + +Atlas App Services registers a user differently depending on the +authentication provider: + +- If you are using email/password authentication, users must + first :ref:`register and confirm their email and password + ` before they can authenticate. +- If you are using Google, Facebook, Apple, or Custom JWT, + registration is handled by these third-party services. +- If you are using anonymous authentication, those users do *not* require + registration. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/users/authenticate-register-create-new-user-account-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/users/authenticate-register-create-new-user-account-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/users/authenticate-register-create-new-user-account-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/users/authenticate-register-create-new-user-account-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/users/authenticate-register-create-new-user-account-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/users/authenticate-register-create-new-user-account-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/users/authenticate-register-create-new-user-account-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/users/authenticate-register-create-new-user-account-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/users/authenticate-register-create-new-user-account-js-ts-description.rst + +.. _kotlin-login: + +Log In a User +------------- + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/users/authenticate-log-in-user-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/users/authenticate-log-in-user-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/users/authenticate-log-in-user-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/users/authenticate-log-in-user-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/users/authenticate-log-in-user-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/users/authenticate-log-in-user-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/users/authenticate-log-in-user-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/users/authenticate-log-in-user-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/users/authenticate-log-in-user-js-ts-description.rst + +.. include:: /includes/sdk-examples/users/authenticate-log-in-user.rst + +.. _sdks-anonymous-login: + +Anonymous +~~~~~~~~~ + +Anonymous authentication enables users to log in to your +application with short-term accounts that store no persistent +personal information. You might use this to allow users to try your +app before they sign up for an account or while developing +and testing your app. Anonymous users do *not* require +registration. Refer to :ref:`anonymous-authentication` in +the App Services documentation for more information. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/users/authenticate-anonymous-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/users/authenticate-anonymous-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/users/authenticate-anonymous-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/users/authenticate-anonymous-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/users/authenticate-anonymous-description.rst + + .. tab:: + :tabid: swift + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/users/authenticate-log-in-user-js-ts-description.rst + +.. include:: /includes/sdk-examples/users/authenticate-anonymous.rst + +.. _sdks-email-password-login: + +Email/Password +~~~~~~~~~~~~~~ + +The email/password authentication provider enables users to log in to +your application with an email username and a password. Refer to +:ref:`email-password-authentication` in the App Services +documentation for more information. + +.. important:: Email/Password Users Require Registration + + Email/password authentication requires that you register + and then confirm the user-provided email and password *before* + the user can authenticate to an App Services App. Learn how to + :ref:`register email/password users + `. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/users/authenticate-email-password-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/users/authenticate-email-password-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/users/authenticate-email-password-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/users/authenticate-email-password-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/users/authenticate-email-password-description.rst + + .. tab:: + :tabid: swift + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/users/authenticate-email-password-js-ts-description.rst + +.. include:: /includes/sdk-examples/users/authenticate-email-password.rst + +.. _sdks-login-jwt: + +Custom JWT +~~~~~~~~~~ + +The Custom JWT authentication provider enables users to log in to +your application with a custom JSON Web Token (JWT). Registration +for JWT authentication is handled by the JWT provider. Refer to +:ref:`custom-jwt-authentication` in the +App Services documentation for more information. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/users/authenticate-custom-jwt-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/users/authenticate-custom-jwt-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/users/authenticate-custom-jwt-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/users/authenticate-custom-jwt-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/users/authenticate-custom-jwt-description.rst + + .. tab:: + :tabid: swift + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/users/authenticate-custom-jwt-js-ts-description.rst + +.. include:: /includes/sdk-examples/users/authenticate-custom-jwt.rst + +.. _sdks-login-api-key: + +API Key +~~~~~~~ + +The API Key authentication provider enables authenticated +non-anonymous users to log in to your application with an API key. +Refer to :ref:`api-key-authentication` in the App Services +documentation for more information. + +User API keys are generated automatically and managed by the SDK. +Learn how to :ref:`sdks-manage-user-api-keys`. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/users/authenticate-api-key-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/users/authenticate-api-key-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/users/authenticate-api-key-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/users/authenticate-api-key-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/users/authenticate-api-key-description.rst + + .. tab:: + :tabid: swift + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/users/authenticate-api-key-js-ts-description.rst + +.. include:: /includes/sdk-examples/users/authenticate-api-key.rst + +.. _sdks-login-custom-function: + +Custom Function +~~~~~~~~~~~~~~~ + +The Custom Function authentication provider enables users to log in +to your application using custom authentication logic handled by an +Atlas Function. Refer to :ref:`custom-function-authentication` in the +App Services documentation for more information. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/users/authenticate-custom-function-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/users/authenticate-custom-function-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/users/authenticate-custom-function-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/users/authenticate-custom-function-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/users/authenticate-custom-function-description.rst + + .. tab:: + :tabid: swift + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/users/authenticate-custom-function-js-ts-description.rst + +.. include:: /includes/sdk-examples/users/authenticate-custom-function.rst + +.. _sdks-login-google: + +Google +~~~~~~ + +The Google authentication provider allows you to authenticate +users through their existing Google account using an OAuth 2.0 +token. Refer to :ref:`google-authentication` in the App Services +documentation for more information. + +Before you can authenticate users with Google, you must set up your +application for Google User authentication: + +#. In the `Google Cloud Platform console + `__, create an + OAuth 2.0 client ID of type "Web application". +#. Configure your backend App to use that client ID and the associated + client secret. +#. Enable OpenID Connect on the backend. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/users/authenticate-google-description.rst + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/users/authenticate-google-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/users/authenticate-google-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/users/authenticate-google-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/users/authenticate-google-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/users/authenticate-google-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/users/authenticate-google-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/users/authenticate-google-missing-example.rst + +.. include:: /includes/sdk-examples/users/authenticate-google.rst + +.. _sdks-login-facebook: + +Facebook +~~~~~~~~ + +The Facebook authentication provider allows +you to authenticate users through a Facebook app using their +existing Facebook account. Refer to :ref:`facebook-authentication` in the +App Services documentation for more information. + +.. include:: /includes/note-facebook-profile-picture-url.rst + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/users/authenticate-facebook-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/users/authenticate-facebook-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/users/authenticate-facebook-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/users/authenticate-facebook-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/users/authenticate-facebook-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/users/authenticate-facebook-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/users/authenticate-facebook-js-ts-description.rst + +.. include:: /includes/sdk-examples/users/authenticate-facebook.rst + +.. _sdks-login-apple: + +Apple +~~~~~ + +The Sign-in with Apple authentication provider enables users to +log in to your application with a custom token provided +by Apple. Refer to :ref:`apple-id-authentication` in the App Services +documentation for more information. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/users/authenticate-apple-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/users/authenticate-apple-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/users/authenticate-apple-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/users/authenticate-apple-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/users/authenticate-apple-description.rst + + .. tab:: + :tabid: swift + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/users/authenticate-apple-js-ts-description.rst + +.. include:: /includes/sdk-examples/users/authenticate-apple.rst + +.. tip:: + + If you get a ``Login failed`` error saying that the ``token contains + an invalid number of segments``, verify that you're passing a UTF-8-encoded + string version of the JWT. + +.. _sdks-get-the-current-user: + +Get the Current User +-------------------- + +When a user logs in through an ``App`` on a device, we cache that App and user +information on the device. You can retrieve the currently logged-in user to +perform app operations without having to log the user in again. + +You can continue to work with the current user until the user session expires. +When the session expires, the SDK automatically uses a refresh token to start +a new session. When the refresh token expires, the SDK cannot start a new +session and the user must log in again. You can configure refresh token +expiration time in Atlas. For more information, refer to +:ref:`refresh-token-expiration` in the App Services documentation. + +If you have multiple users logged in to your app, retrieving a current user +returns the last valid user that logged in. It returns null or nil, depending +on the language, if there are no logged-in users. Refer to +:ref:`sdks-multi-user-applications` for more information. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/users/authenticate-get-current-user-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/users/authenticate-log-in-user-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/users/authenticate-log-in-user-description.rst + + .. tab:: + :tabid: java + + .. tab:: + :tabid: java-kotlin + + .. tab:: + :tabid: javascript + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/users/authenticate-get-current-user-description.rst + + .. tab:: + :tabid: swift + + .. tab:: + :tabid: typescript + +.. include:: /includes/sdk-examples/users/authenticate-get-current-user.rst + +.. _sdks-offline-login: + +Log In Offline +-------------- + +When your application authenticates a user, it caches the user's +credentials. You can check for existing user credentials to bypass the +login flow and access the cached user. Use this to open a synced database +offline. + +.. note:: Initial login requires a network connection + + When a user signs up for your app, or logs in for the first time with an + existing account on a client, the device must have a network connection. + Checking for cached user credentials lets you open a synced database + offline, but only if the user has previously logged in on the device while + online. + +.. TODO +(Android - figure out a way to surface this) +The SDK stores these tokens in +`Shared Preferences `_. + +.. include:: /includes/sdk-examples/users/authenticate-log-in-offline.rst + +.. _sdks-access-token: + +Manage User Tokens +------------------ + +The SDK manages two types of user tokens: + +- **User access token**: a token sent with each request to Atlas. Without a + valid access token, the app can't perform server-related functionality on the + user's behalf. +- **Refresh token**: a token used to refresh the access token. The SDK uses + this to automatically rotate the access token, up to the period when the + refresh token expires. + +Once the refresh token expires, the app can't perform operations that involve +the server, such as calling a Function or syncing the device database, until +the user logs in again. + +Tokens are removed after the user logs out. + +For more information on user session access and refresh tokens, +refer to :ref:`user-sessions` in the App Services documentation. + +Get a User Access Token +~~~~~~~~~~~~~~~~~~~~~~~ + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/users/authenticate-get-user-access-token-description.rst + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/users/authenticate-get-user-access-token-description.rst + + .. tab:: + :tabid: java + + .. tab:: + :tabid: java-kotlin + + .. tab:: + :tabid: javascript + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/users/authenticate-get-user-access-token-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/users/authenticate-get-user-access-token-description.rst + + .. tab:: + :tabid: typescript + +.. include:: /includes/sdk-examples/users/authenticate-get-user-access-token.rst + +Manually Refresh an Access Token +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you send requests outside of the SDK, you must include the user's access +token with each request and manually refresh the token when it expires. +Access tokens expire 30 minutes after a user logs in. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/users/authenticate-manually-refresh-access-token-description.rst + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/users/authenticate-manually-refresh-access-token-description.rst + + .. tab:: + :tabid: java + + .. tab:: + :tabid: java-kotlin + + .. tab:: + :tabid: javascript + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/users/authenticate-manually-refresh-access-token-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/users/authenticate-manually-refresh-access-token-description.rst + + .. tab:: + :tabid: typescript + +.. include:: /includes/sdk-examples/users/authenticate-manually-refresh-access-token.rst + +Configure Refresh Token Expiration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/refresh-token-expiry.rst + +.. _sdks-logout: + +Log a User Out +-------------- + +.. include:: /includes/log-out-queries-in-progress.rst + +The log out method: + +- Deletes locally stored user credentials from the device. +- Immediately halts any synchronization to and from the user's synced databases. +- For anonymous users, :ref:`removes the user `. + +Because logging out halts synchronization, you should only log out after +all synced database updates have uploaded to the server. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/users/authenticate-log-user-out-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/users/authenticate-log-user-out-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/users/authenticate-log-user-out-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/users/authenticate-log-user-out-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/users/authenticate-log-user-out-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/users/authenticate-log-user-out-description.rst + + .. tab:: + :tabid: swift + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/users/authenticate-log-user-out-js-ts-description.rst + +.. include:: /includes/sdk-examples/users/authenticate-log-user-out.rst + +.. _sdks-authentication-change-listener: + +Observe Authentication Changes +------------------------------ + +Some SDKs provide platform-idiomatic APIs to observe authentication changes. +In other SDKs, you can use platform or language-specific architecture to +achieve a similar result without a dedicated API. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/users/authenticate-observe-authentication-changes-no-api.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/users/authenticate-observe-authentication-changes-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/users/authenticate-observe-authentication-changes-no-api.rst + + .. tab:: + :tabid: java + + .. tab:: + :tabid: java-kotlin + + .. tab:: + :tabid: javascript + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/users/authenticate-observe-authentication-changes-description.rst + + .. tab:: + :tabid: swift + + .. tab:: + :tabid: typescript + +.. include:: /includes/sdk-examples/users/authenticate-observe-authentication-changes.rst diff --git a/source/sdk/users/create-and-delete-users.txt b/source/sdk/users/create-and-delete-users.txt index dc4a3c90b6..62dfdad91a 100644 --- a/source/sdk/users/create-and-delete-users.txt +++ b/source/sdk/users/create-and-delete-users.txt @@ -9,3 +9,13 @@ Create and Delete Users :backlinks: none :depth: 2 :class: singlecol + +.. _sdks-delete-users: + +Delete Users +------------ + +.. _sdks-remove-users: + +Remove Users +------------ diff --git a/templates/consolidated-page.rst b/templates/consolidated-page.rst index 3fb572f40a..2c5d93510a 100644 --- a/templates/consolidated-page.rst +++ b/templates/consolidated-page.rst @@ -6,7 +6,7 @@ Page Title .. meta:: :description: Provide a short description of the consolidated page. This is critical for SEO. - :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Java SDK, Node.js SDK, Swift SDK, code example + :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Java SDK, .NET SDK, Node.js SDK, Swift SDK, code example .. facet:: :name: genre From 2bc5605a5f59a45384e6e043da7d58e99ccf71b1 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 31 May 2024 18:17:37 -0400 Subject: [PATCH 02/14] Fix snooty build errors --- ...serve-authentication-changes-description.rst} | 0 ...ticate-get-user-access-token-description.rst} | 0 .../sdk-examples/users/authenticate-google.rst | 16 ++++++---------- source/sdk/users/authenticate-users.txt | 4 +++- 4 files changed, 9 insertions(+), 11 deletions(-) rename source/includes/api-details/csharp/users/{authenticate-observe-authentication-changes.rst => authenticate-observe-authentication-changes-description.rst} (100%) rename source/includes/api-details/swift/users/{authenticate-get-user-access-token.rst => authenticate-get-user-access-token-description.rst} (100%) diff --git a/source/includes/api-details/csharp/users/authenticate-observe-authentication-changes.rst b/source/includes/api-details/csharp/users/authenticate-observe-authentication-changes-description.rst similarity index 100% rename from source/includes/api-details/csharp/users/authenticate-observe-authentication-changes.rst rename to source/includes/api-details/csharp/users/authenticate-observe-authentication-changes-description.rst diff --git a/source/includes/api-details/swift/users/authenticate-get-user-access-token.rst b/source/includes/api-details/swift/users/authenticate-get-user-access-token-description.rst similarity index 100% rename from source/includes/api-details/swift/users/authenticate-get-user-access-token.rst rename to source/includes/api-details/swift/users/authenticate-get-user-access-token-description.rst diff --git a/source/includes/sdk-examples/users/authenticate-google.rst b/source/includes/sdk-examples/users/authenticate-google.rst index 26b7e9ac78..6fae9b5f49 100644 --- a/source/includes/sdk-examples/users/authenticate-google.rst +++ b/source/includes/sdk-examples/users/authenticate-google.rst @@ -48,19 +48,15 @@ - id: swift content: | - .. tabs:: + **ID Token** - .. tab:: ID Token - :tabid: idToken + .. literalinclude:: /examples/generated/code/start/Authenticate.snippet.google-with-googleId.swift + :language: swift - .. literalinclude:: /examples/generated/code/start/Authenticate.snippet.google-with-googleId.swift - :language: swift + **Server Auth Code** - .. tab:: Server Auth Code - :tabid: serverAuthCode - - .. literalinclude:: /examples/generated/code/start/Authenticate.snippet.google-with-serverAuthCode.swift - :language: swift + .. literalinclude:: /examples/generated/code/start/Authenticate.snippet.google-with-serverAuthCode.swift + :language: swift - id: typescript content: | diff --git a/source/sdk/users/authenticate-users.txt b/source/sdk/users/authenticate-users.txt index 28f3dec981..31aabc40c2 100644 --- a/source/sdk/users/authenticate-users.txt +++ b/source/sdk/users/authenticate-users.txt @@ -22,6 +22,8 @@ Authenticate Users :depth: 2 :class: singlecol +.. tabs-selector:: drivers + After you :ref:`initialize an Atlas app connection `, you must authenticate a user with an authentication provider. This page describes how to authenticate App Services App users with Atlas Device SDK. @@ -739,7 +741,7 @@ offline. offline, but only if the user has previously logged in on the device while online. -.. TODO +TODO (Android - figure out a way to surface this) The SDK stores these tokens in `Shared Preferences `_. From c859cd6821e6710e8c28a9e3c6e8657765c21aa0 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 4 Jun 2024 11:03:09 -0400 Subject: [PATCH 03/14] Minor fixups and clarifications --- source/sdk/users/authenticate-users.txt | 37 +++++++++++++++++-------- 1 file changed, 26 insertions(+), 11 deletions(-) diff --git a/source/sdk/users/authenticate-users.txt b/source/sdk/users/authenticate-users.txt index 31aabc40c2..76e250584d 100644 --- a/source/sdk/users/authenticate-users.txt +++ b/source/sdk/users/authenticate-users.txt @@ -741,11 +741,6 @@ offline. offline, but only if the user has previously logged in on the device while online. -TODO -(Android - figure out a way to surface this) -The SDK stores these tokens in -`Shared Preferences `_. - .. include:: /includes/sdk-examples/users/authenticate-log-in-offline.rst .. _sdks-access-token: @@ -763,10 +758,22 @@ The SDK manages two types of user tokens: refresh token expires. Once the refresh token expires, the app can't perform operations that involve -the server, such as calling a Function or syncing the device database, until -the user logs in again. +the server until the user logs in again. + +Tokens are removed after the user logs out. + +.. important:: The SDK Automatically Handles User Access Tokens for Most Functionality -Tokens are removed after the user logs out. + The SDK automatically handles user access tokens for operations that it + performs, such as calling a Function or syncing the device database. It + sends the access token with each request, and automatically handles + refreshing it. When a refresh token expires, your app code must redirect + users to login again. + + If you send requests outside of the SDK, you must include the user's access + token with each request and manually refresh the token when it expires. + You must manually manage this token when calling :ref:`data-api` endpoints + from your client code, for example. For more information on user session access and refresh tokens, refer to :ref:`user-sessions` in the App Services documentation. @@ -774,6 +781,13 @@ refer to :ref:`user-sessions` in the App Services documentation. Get a User Access Token ~~~~~~~~~~~~~~~~~~~~~~~ +Access tokens expire 30 minutes after a user logs in. + +You don't need to send user access tokens when performing operations with the +SDK. The SDK automatically handles this for you. But you must manually manage +this token when performing server operations outside of the SDK - for example, +when calling :ref:`data-api` endpoints from your client code. + .. tabs-drivers:: .. tab:: @@ -816,9 +830,10 @@ Get a User Access Token Manually Refresh an Access Token ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you send requests outside of the SDK, you must include the user's access -token with each request and manually refresh the token when it expires. -Access tokens expire 30 minutes after a user logs in. +You can manually refresh an expired access token. The SDK automatically handles +this for you. This is only required if you are performing server-related +operations outside of the SDK, such as calling :ref:`data-api` endpoints from +your client code. .. tabs-drivers:: From 5163be6e0e662114785aa85b1e52f434fcb054c5 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 4 Jun 2024 11:08:56 -0400 Subject: [PATCH 04/14] Reorder things on page --- .github/workflows/bluehawk.yml | 2 +- source/sdk/users/authenticate-users.txt | 162 ++++++++++++------------ 2 files changed, 82 insertions(+), 82 deletions(-) diff --git a/.github/workflows/bluehawk.yml b/.github/workflows/bluehawk.yml index 456726a93a..685678bdb0 100644 --- a/.github/workflows/bluehawk.yml +++ b/.github/workflows/bluehawk.yml @@ -10,5 +10,5 @@ jobs: - uses: actions/checkout@v3 - uses: actions/setup-node@v1 with: - node-version: 15.x + node-version: 18.x - run: npx bluehawk check -i "*.md" -i "*.properties" -i "*.lock" examples tutorial diff --git a/source/sdk/users/authenticate-users.txt b/source/sdk/users/authenticate-users.txt index 76e250584d..b900b28753 100644 --- a/source/sdk/users/authenticate-users.txt +++ b/source/sdk/users/authenticate-users.txt @@ -663,6 +663,87 @@ documentation for more information. an invalid number of segments``, verify that you're passing a UTF-8-encoded string version of the JWT. +.. _sdks-offline-login: + +Log In Offline +~~~~~~~~~~~~~~ + +When your application authenticates a user, it caches the user's +credentials. You can check for existing user credentials to bypass the +login flow and access the cached user. Use this to open a synced database +offline. + +.. note:: Initial login requires a network connection + + When a user signs up for your app, or logs in for the first time with an + existing account on a client, the device must have a network connection. + Checking for cached user credentials lets you open a synced database + offline, but only if the user has previously logged in on the device while + online. + +.. include:: /includes/sdk-examples/users/authenticate-log-in-offline.rst + +.. _sdks-logout: + +Log a User Out +-------------- + +.. include:: /includes/log-out-queries-in-progress.rst + +The log out method: + +- Deletes locally stored user credentials from the device. +- Immediately halts any synchronization to and from the user's synced databases. +- For anonymous users, :ref:`removes the user `. + +Because logging out halts synchronization, you should only log out after +all synced database updates have uploaded to the server. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/users/authenticate-log-user-out-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/users/authenticate-log-user-out-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/users/authenticate-log-user-out-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/users/authenticate-log-user-out-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/users/authenticate-log-user-out-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/users/authenticate-log-user-out-description.rst + + .. tab:: + :tabid: swift + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/users/authenticate-log-user-out-js-ts-description.rst + +.. include:: /includes/sdk-examples/users/authenticate-log-user-out.rst + .. _sdks-get-the-current-user: Get the Current User @@ -723,26 +804,6 @@ on the language, if there are no logged-in users. Refer to .. include:: /includes/sdk-examples/users/authenticate-get-current-user.rst -.. _sdks-offline-login: - -Log In Offline --------------- - -When your application authenticates a user, it caches the user's -credentials. You can check for existing user credentials to bypass the -login flow and access the cached user. Use this to open a synced database -offline. - -.. note:: Initial login requires a network connection - - When a user signs up for your app, or logs in for the first time with an - existing account on a client, the device must have a network connection. - Checking for cached user credentials lets you open a synced database - offline, but only if the user has previously logged in on the device while - online. - -.. include:: /includes/sdk-examples/users/authenticate-log-in-offline.rst - .. _sdks-access-token: Manage User Tokens @@ -879,67 +940,6 @@ Configure Refresh Token Expiration .. include:: /includes/refresh-token-expiry.rst -.. _sdks-logout: - -Log a User Out --------------- - -.. include:: /includes/log-out-queries-in-progress.rst - -The log out method: - -- Deletes locally stored user credentials from the device. -- Immediately halts any synchronization to and from the user's synced databases. -- For anonymous users, :ref:`removes the user `. - -Because logging out halts synchronization, you should only log out after -all synced database updates have uploaded to the server. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. tab:: - :tabid: csharp - - .. include:: /includes/api-details/csharp/users/authenticate-log-user-out-description.rst - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/dart/users/authenticate-log-user-out-description.rst - - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/users/authenticate-log-user-out-description.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/users/authenticate-log-user-out-description.rst - - .. tab:: - :tabid: javascript - - .. include:: /includes/api-details/javascript/users/authenticate-log-user-out-js-ts-description.rst - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/kotlin/users/authenticate-log-user-out-description.rst - - .. tab:: - :tabid: swift - - .. tab:: - :tabid: typescript - - .. include:: /includes/api-details/javascript/users/authenticate-log-user-out-js-ts-description.rst - -.. include:: /includes/sdk-examples/users/authenticate-log-user-out.rst - .. _sdks-authentication-change-listener: Observe Authentication Changes From c338850635eee02e91abeba5399a0244883f575f Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 4 Jun 2024 11:18:30 -0400 Subject: [PATCH 05/14] Move user access token info out to a new page --- source/sdk/users.txt | 2 + source/sdk/users/authenticate-users.txt | 202 ++++-------------------- source/sdk/users/manage-user-tokens.txt | 148 +++++++++++++++++ 3 files changed, 183 insertions(+), 169 deletions(-) create mode 100644 source/sdk/users/manage-user-tokens.txt diff --git a/source/sdk/users.txt b/source/sdk/users.txt index b3e4a12a79..74390efa5b 100644 --- a/source/sdk/users.txt +++ b/source/sdk/users.txt @@ -15,6 +15,7 @@ Manage Users Create and Delete Users Authenticate Users + Manage User Tokens Custom User Data User Metadata Manage Email/Password Users @@ -26,6 +27,7 @@ The following pages contain information about how to create, delete, and manage users in Atlas Device SDK: - :ref:`sdks-create-and-delete-users` +- :ref:`sdks-manage-user-tokens` - :ref:`sdks-authenticate-users` - :ref:`sdks-custom-user-data` - :ref:`sdks-user-metadata` diff --git a/source/sdk/users/authenticate-users.txt b/source/sdk/users/authenticate-users.txt index b900b28753..56694197da 100644 --- a/source/sdk/users/authenticate-users.txt +++ b/source/sdk/users/authenticate-users.txt @@ -49,7 +49,7 @@ Upon successful login, App Services begins a **user session** for the user. App Services manages sessions with access tokens and refresh tokens. The SDK supplies the logic to manage tokens and provide them with requests. For more information on managing user sessions and tokens, refer to -:ref:`` in the App Services documentation. +:ref:`sdks-manage-user-tokens`. Once you have a logged-in user, you can: @@ -744,172 +744,31 @@ all synced database updates have uploaded to the server. .. include:: /includes/sdk-examples/users/authenticate-log-user-out.rst -.. _sdks-get-the-current-user: - -Get the Current User --------------------- - -When a user logs in through an ``App`` on a device, we cache that App and user -information on the device. You can retrieve the currently logged-in user to -perform app operations without having to log the user in again. +.. _sdks-authentication-change-listener: -You can continue to work with the current user until the user session expires. -When the session expires, the SDK automatically uses a refresh token to start -a new session. When the refresh token expires, the SDK cannot start a new -session and the user must log in again. You can configure refresh token -expiration time in Atlas. For more information, refer to -:ref:`refresh-token-expiration` in the App Services documentation. +Observe Authentication Changes +------------------------------ -If you have multiple users logged in to your app, retrieving a current user -returns the last valid user that logged in. It returns null or nil, depending -on the language, if there are no logged-in users. Refer to -:ref:`sdks-multi-user-applications` for more information. +Some SDKs provide platform-idiomatic APIs to observe authentication changes. +In other SDKs, you can use platform or language-specific architecture to +achieve a similar result without a dedicated API. .. tabs-drivers:: .. tab:: :tabid: cpp-sdk - .. include:: /includes/api-details/cpp/users/authenticate-get-current-user-description.rst + .. include:: /includes/api-details/cpp/users/authenticate-observe-authentication-changes-no-api.rst .. tab:: :tabid: csharp - .. include:: /includes/api-details/csharp/users/authenticate-log-in-user-description.rst - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/dart/users/authenticate-log-in-user-description.rst - - .. tab:: - :tabid: java - - .. tab:: - :tabid: java-kotlin - - .. tab:: - :tabid: javascript - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/kotlin/users/authenticate-get-current-user-description.rst - - .. tab:: - :tabid: swift - - .. tab:: - :tabid: typescript - -.. include:: /includes/sdk-examples/users/authenticate-get-current-user.rst - -.. _sdks-access-token: - -Manage User Tokens ------------------- - -The SDK manages two types of user tokens: - -- **User access token**: a token sent with each request to Atlas. Without a - valid access token, the app can't perform server-related functionality on the - user's behalf. -- **Refresh token**: a token used to refresh the access token. The SDK uses - this to automatically rotate the access token, up to the period when the - refresh token expires. - -Once the refresh token expires, the app can't perform operations that involve -the server until the user logs in again. - -Tokens are removed after the user logs out. - -.. important:: The SDK Automatically Handles User Access Tokens for Most Functionality - - The SDK automatically handles user access tokens for operations that it - performs, such as calling a Function or syncing the device database. It - sends the access token with each request, and automatically handles - refreshing it. When a refresh token expires, your app code must redirect - users to login again. - - If you send requests outside of the SDK, you must include the user's access - token with each request and manually refresh the token when it expires. - You must manually manage this token when calling :ref:`data-api` endpoints - from your client code, for example. - -For more information on user session access and refresh tokens, -refer to :ref:`user-sessions` in the App Services documentation. - -Get a User Access Token -~~~~~~~~~~~~~~~~~~~~~~~ - -Access tokens expire 30 minutes after a user logs in. - -You don't need to send user access tokens when performing operations with the -SDK. The SDK automatically handles this for you. But you must manually manage -this token when performing server operations outside of the SDK - for example, -when calling :ref:`data-api` endpoints from your client code. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/cpp/users/authenticate-get-user-access-token-description.rst - - .. tab:: - :tabid: csharp + .. include:: /includes/api-details/csharp/users/authenticate-observe-authentication-changes-description.rst .. tab:: :tabid: dart - .. include:: /includes/api-details/dart/users/authenticate-get-user-access-token-description.rst - - .. tab:: - :tabid: java - - .. tab:: - :tabid: java-kotlin - - .. tab:: - :tabid: javascript - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/kotlin/users/authenticate-get-user-access-token-description.rst - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/swift/users/authenticate-get-user-access-token-description.rst - - .. tab:: - :tabid: typescript - -.. include:: /includes/sdk-examples/users/authenticate-get-user-access-token.rst - -Manually Refresh an Access Token -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can manually refresh an expired access token. The SDK automatically handles -this for you. This is only required if you are performing server-related -operations outside of the SDK, such as calling :ref:`data-api` endpoints from -your client code. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/cpp/users/authenticate-manually-refresh-access-token-description.rst - - .. tab:: - :tabid: csharp - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/dart/users/authenticate-manually-refresh-access-token-description.rst + .. include:: /includes/api-details/dart/users/authenticate-observe-authentication-changes-no-api.rst .. tab:: :tabid: java @@ -923,48 +782,53 @@ your client code. .. tab:: :tabid: kotlin - .. include:: /includes/api-details/kotlin/users/authenticate-manually-refresh-access-token-description.rst + .. include:: /includes/api-details/kotlin/users/authenticate-observe-authentication-changes-description.rst .. tab:: :tabid: swift - .. include:: /includes/api-details/swift/users/authenticate-manually-refresh-access-token-description.rst - .. tab:: :tabid: typescript -.. include:: /includes/sdk-examples/users/authenticate-manually-refresh-access-token.rst +.. include:: /includes/sdk-examples/users/authenticate-observe-authentication-changes.rst -Configure Refresh Token Expiration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. _sdks-get-the-current-user: -.. include:: /includes/refresh-token-expiry.rst +Get the Current User +-------------------- -.. _sdks-authentication-change-listener: +When a user logs in through an ``App`` on a device, we cache that App and user +information on the device. You can retrieve the currently logged-in user to +perform app operations without having to log the user in again. -Observe Authentication Changes ------------------------------- +You can continue to work with the current user until the user session expires. +When the session expires, the SDK automatically uses a refresh token to start +a new session. When the refresh token expires, the SDK cannot start a new +session and the user must log in again. You can configure refresh token +expiration time in Atlas. For more information, refer to +:ref:`refresh-token-expiration` in the App Services documentation. -Some SDKs provide platform-idiomatic APIs to observe authentication changes. -In other SDKs, you can use platform or language-specific architecture to -achieve a similar result without a dedicated API. +If you have multiple users logged in to your app, retrieving a current user +returns the last valid user that logged in. It returns null or nil, depending +on the language, if there are no logged-in users. Refer to +:ref:`sdks-multi-user-applications` for more information. .. tabs-drivers:: .. tab:: :tabid: cpp-sdk - .. include:: /includes/api-details/cpp/users/authenticate-observe-authentication-changes-no-api.rst + .. include:: /includes/api-details/cpp/users/authenticate-get-current-user-description.rst .. tab:: :tabid: csharp - .. include:: /includes/api-details/csharp/users/authenticate-observe-authentication-changes-description.rst + .. include:: /includes/api-details/csharp/users/authenticate-log-in-user-description.rst .. tab:: :tabid: dart - .. include:: /includes/api-details/dart/users/authenticate-observe-authentication-changes-no-api.rst + .. include:: /includes/api-details/dart/users/authenticate-log-in-user-description.rst .. tab:: :tabid: java @@ -978,7 +842,7 @@ achieve a similar result without a dedicated API. .. tab:: :tabid: kotlin - .. include:: /includes/api-details/kotlin/users/authenticate-observe-authentication-changes-description.rst + .. include:: /includes/api-details/kotlin/users/authenticate-get-current-user-description.rst .. tab:: :tabid: swift @@ -986,4 +850,4 @@ achieve a similar result without a dedicated API. .. tab:: :tabid: typescript -.. include:: /includes/sdk-examples/users/authenticate-observe-authentication-changes.rst +.. include:: /includes/sdk-examples/users/authenticate-get-current-user.rst diff --git a/source/sdk/users/manage-user-tokens.txt b/source/sdk/users/manage-user-tokens.txt new file mode 100644 index 0000000000..9c92181c90 --- /dev/null +++ b/source/sdk/users/manage-user-tokens.txt @@ -0,0 +1,148 @@ +.. _sdks-manage-user-tokens: + +================== +Manage User Tokens +================== + +.. meta:: + :description: Learn how to manage user access tokens and refresh tokens when performing operations outside of Atlas Device SDK. + :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Java SDK, .NET SDK, Node.js SDK, Swift SDK, code example + +.. facet:: + :name: genre + :values: reference + +.. facet:: + :name: programming_language + :values: cpp, csharp, dart, java, javascript/typescript, kotlin, swift + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. tabs-selector:: drivers + +The SDK manages two types of user tokens: + +- **User access token**: a token sent with each request to Atlas. Without a + valid access token, the app can't perform server-related functionality on the + user's behalf. +- **Refresh token**: a token used to refresh the access token. The SDK uses + this to automatically rotate the access token, up to the period when the + refresh token expires. + +Once the refresh token expires, the app can't perform operations that involve +the server until the user logs in again. + +Tokens are removed after the user logs out. + +.. important:: The SDK Automatically Handles User Access Tokens for Most Functionality + + The SDK automatically handles user access tokens for operations that it + performs, such as calling a Function or syncing the device database. It + sends the access token with each request, and automatically handles + refreshing it. When a refresh token expires, your app code must redirect + users to login again. + + If you send requests outside of the SDK, you must include the user's access + token with each request and manually refresh the token when it expires. + You must manually manage this token when calling :ref:`data-api` endpoints + from your client code, for example. + +For more information on user session access and refresh tokens, +refer to :ref:`user-sessions` in the App Services documentation. + +Get a User Access Token +~~~~~~~~~~~~~~~~~~~~~~~ + +Access tokens expire 30 minutes after a user logs in. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/users/authenticate-get-user-access-token-description.rst + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/users/authenticate-get-user-access-token-description.rst + + .. tab:: + :tabid: java + + .. tab:: + :tabid: java-kotlin + + .. tab:: + :tabid: javascript + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/users/authenticate-get-user-access-token-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/users/authenticate-get-user-access-token-description.rst + + .. tab:: + :tabid: typescript + +.. include:: /includes/sdk-examples/users/authenticate-get-user-access-token.rst + +Manually Refresh an Access Token +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can manually refresh an expired access token. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/users/authenticate-manually-refresh-access-token-description.rst + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/users/authenticate-manually-refresh-access-token-description.rst + + .. tab:: + :tabid: java + + .. tab:: + :tabid: java-kotlin + + .. tab:: + :tabid: javascript + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/users/authenticate-manually-refresh-access-token-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/users/authenticate-manually-refresh-access-token-description.rst + + .. tab:: + :tabid: typescript + +.. include:: /includes/sdk-examples/users/authenticate-manually-refresh-access-token.rst + +Configure Refresh Token Expiration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/refresh-token-expiry.rst From e4f1b58af8433377e0b57acbe6a8a1728de2183b Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 4 Jun 2024 11:24:10 -0400 Subject: [PATCH 06/14] Minor page content tweaks --- source/sdk/users/authenticate-users.txt | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/source/sdk/users/authenticate-users.txt b/source/sdk/users/authenticate-users.txt index 56694197da..fac3ab58ff 100644 --- a/source/sdk/users/authenticate-users.txt +++ b/source/sdk/users/authenticate-users.txt @@ -30,11 +30,6 @@ describes how to authenticate App Services App users with Atlas Device SDK. Refer to :ref:`` in the App Services documentation for more information. -.. include:: /includes/tip-acct-deletion-reqs.rst - -App Services Users ------------------- - Atlas App Services provides the following built-in authentication providers to log users in and out of a client app: @@ -146,6 +141,8 @@ authentication provider: .. include:: /includes/api-details/javascript/users/authenticate-register-create-new-user-account-js-ts-description.rst +.. include:: /includes/tip-acct-deletion-reqs.rst + .. _kotlin-login: Log In a User From 543b86d974cbfe62cb7d33bb04b5e034d04c1f9b Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 4 Jun 2024 11:26:44 -0400 Subject: [PATCH 07/14] It's automatic, yo! --- source/sdk/users/authenticate-users.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/sdk/users/authenticate-users.txt b/source/sdk/users/authenticate-users.txt index fac3ab58ff..4eb55291ea 100644 --- a/source/sdk/users/authenticate-users.txt +++ b/source/sdk/users/authenticate-users.txt @@ -42,8 +42,8 @@ to log users in and out of a client app: Upon successful login, App Services begins a **user session** for the user. App Services manages sessions with access tokens and refresh tokens. The SDK -supplies the logic to manage tokens and provide them with requests. For more -information on managing user sessions and tokens, refer to +automatically supplies the logic to manage tokens and provide them with requests. +For more information on managing user sessions and tokens, refer to :ref:`sdks-manage-user-tokens`. Once you have a logged-in user, you can: From f4e502dc6e7c6b34b3156210f8ef961ec628e266 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 4 Jun 2024 11:31:56 -0400 Subject: [PATCH 08/14] Replace placeholders in log in examples --- .../users/authenticate-log-in-user.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/source/includes/sdk-examples/users/authenticate-log-in-user.rst b/source/includes/sdk-examples/users/authenticate-log-in-user.rst index 472a383603..d96f3b6f52 100644 --- a/source/includes/sdk-examples/users/authenticate-log-in-user.rst +++ b/source/includes/sdk-examples/users/authenticate-log-in-user.rst @@ -4,37 +4,37 @@ - id: cpp-sdk content: | - .. literalinclude:: /examples/generated/cpp/asymmetric-sync.snippet.create-asymmetric-object.cpp - :language: cpp + .. literalinclude:: /examples/generated/cpp/authentication.snippet.anonymous-login.cpp + :language: cpp - id: csharp content: | - .. literalinclude:: /examples/MissingPlaceholders/example.cs + .. literalinclude:: /examples/generated/dotnet/AuthenticationExamples.snippet.logon_anon.cs :language: csharp - id: dart content: | - .. literalinclude:: /examples/generated/flutter/data_ingest.test.snippet.write-asymmetric-object.dart + .. literalinclude:: /examples/generated/flutter/authenticate_users_test.snippet.multiple-anonymous-credentials.dart :language: dart - id: java content: | - .. literalinclude:: /examples/MissingPlaceholders/api.java + .. literalinclude:: /examples/generated/java/sync/AuthenticationTest.snippet.anonymous.java :language: java - id: java-kotlin content: | - .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + .. literalinclude:: /examples/generated/java/sync/AuthenticationTest.snippet.anonymous.kt :language: kotlin - id: javascript content: | - .. literalinclude:: /examples/MissingPlaceholders/example.js + .. literalinclude:: /examples/generated/node/authenticate.snippet.anonymous-login.js :language: javascript - id: kotlin @@ -46,11 +46,11 @@ - id: swift content: | - .. literalinclude:: /examples/generated/code/start/AsymmetricSync.snippet.create-asymmetric-object.swift + .. literalinclude:: /examples/generated/code/start/Authenticate.snippet.anonymous.swift :language: swift - id: typescript content: | - .. literalinclude:: /examples/generated/node/asymmetric-sync.snippet.write-asymmetric-object.ts + .. literalinclude:: /examples/generated/node/authenticate.snippet.anonymous-login.ts :language: typescript From 169077d006a4073c5975f4f68acc6f424006cf51 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 4 Jun 2024 12:12:48 -0400 Subject: [PATCH 09/14] Minor cleanup --- ...enticate-log-in-user-async-description.rst | 11 +++++++ .../authenticate-log-in-user-description.rst | 12 ------- ...nticate-observe-authentication-changes.rst | 2 +- source/sdk/users/authenticate-users.txt | 33 +++++++++++++++++++ 4 files changed, 45 insertions(+), 13 deletions(-) create mode 100644 source/includes/api-details/swift/users/authenticate-log-in-user-async-description.rst diff --git a/source/includes/api-details/swift/users/authenticate-log-in-user-async-description.rst b/source/includes/api-details/swift/users/authenticate-log-in-user-async-description.rst new file mode 100644 index 0000000000..390caffe41 --- /dev/null +++ b/source/includes/api-details/swift/users/authenticate-log-in-user-async-description.rst @@ -0,0 +1,11 @@ +**Async/Await Login** + +.. versionadded:: 10.15.0 + +The async/await version of the :swift-sdk:`App.login ` +method asynchronously returns a User or Error. + +.. literalinclude:: /examples/generated/code/start/Authenticate.snippet.async-await.swift + :language: swift + +.. include:: /includes/swift-async-await-support.rst diff --git a/source/includes/api-details/swift/users/authenticate-log-in-user-description.rst b/source/includes/api-details/swift/users/authenticate-log-in-user-description.rst index 0632db4092..e636a255b3 100644 --- a/source/includes/api-details/swift/users/authenticate-log-in-user-description.rst +++ b/source/includes/api-details/swift/users/authenticate-log-in-user-description.rst @@ -13,15 +13,3 @@ If successful, ``App.login()`` returns a :swift-sdk:`User throws an exception of type :swift-sdk:`AppError `, which is a type alias for the underlying :objc-sdk:`RLMAppError `. - -**Async/Await Login** - -.. versionadded:: 10.15.0 - -The async/await version of the :swift-sdk:`App.login ` -method asynchronously returns a User or Error. - -.. literalinclude:: /examples/generated/code/start/Authenticate.snippet.async-await.swift - :language: swift - -.. include:: /includes/swift-async-await-support.rst diff --git a/source/includes/sdk-examples/users/authenticate-observe-authentication-changes.rst b/source/includes/sdk-examples/users/authenticate-observe-authentication-changes.rst index 5257fc72ad..5b6a8bd6e8 100644 --- a/source/includes/sdk-examples/users/authenticate-observe-authentication-changes.rst +++ b/source/includes/sdk-examples/users/authenticate-observe-authentication-changes.rst @@ -28,7 +28,7 @@ - id: java-kotlin content: | - .. literalinclude:: /examples/MissingPlaceholders/api.kt + .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt :language: kotlin - id: javascript diff --git a/source/sdk/users/authenticate-users.txt b/source/sdk/users/authenticate-users.txt index 4eb55291ea..078c33f718 100644 --- a/source/sdk/users/authenticate-users.txt +++ b/source/sdk/users/authenticate-users.txt @@ -197,6 +197,39 @@ Log In a User .. include:: /includes/sdk-examples/users/authenticate-log-in-user.rst +.. This tab group is only used to populate some additional details for Swift + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. tab:: + :tabid: java + + .. tab:: + :tabid: java-kotlin + + .. tab:: + :tabid: javascript + + .. tab:: + :tabid: kotlin + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/users/authenticate-log-in-user-async-description.rst + + .. tab:: + :tabid: typescript + .. _sdks-anonymous-login: Anonymous From de109364f00137ff427926ec1d4301830f889987 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 4 Jun 2024 16:14:38 -0400 Subject: [PATCH 10/14] Rename include files to match new page name --- ...kens-get-user-access-token-description.rst} | 0 ...ually-refresh-access-token-description.rst} | 0 ...kens-get-user-access-token-description.rst} | 0 ...ually-refresh-access-token-description.rst} | 0 ...kens-get-user-access-token-description.rst} | 0 ...ually-refresh-access-token-description.rst} | 0 ...kens-get-user-access-token-description.rst} | 0 ...ually-refresh-access-token-description.rst} | 0 ...nage-user-tokens-get-user-access-token.rst} | 0 ...r-tokens-manually-refresh-access-token.rst} | 0 source/sdk/users/manage-user-tokens.txt | 18 +++++++++--------- 11 files changed, 9 insertions(+), 9 deletions(-) rename source/includes/api-details/cpp/users/{authenticate-get-user-access-token-description.rst => manage-user-tokens-get-user-access-token-description.rst} (100%) rename source/includes/api-details/cpp/users/{authenticate-manually-refresh-access-token-description.rst => manage-user-tokens-manually-refresh-access-token-description.rst} (100%) rename source/includes/api-details/dart/users/{authenticate-get-user-access-token-description.rst => manage-user-tokens-get-user-access-token-description.rst} (100%) rename source/includes/api-details/dart/users/{authenticate-manually-refresh-access-token-description.rst => manage-user-tokens-manually-refresh-access-token-description.rst} (100%) rename source/includes/api-details/kotlin/users/{authenticate-get-user-access-token-description.rst => manage-user-tokens-get-user-access-token-description.rst} (100%) rename source/includes/api-details/kotlin/users/{authenticate-manually-refresh-access-token-description.rst => manage-user-tokens-manually-refresh-access-token-description.rst} (100%) rename source/includes/api-details/swift/users/{authenticate-get-user-access-token-description.rst => manage-user-tokens-get-user-access-token-description.rst} (100%) rename source/includes/api-details/swift/users/{authenticate-manually-refresh-access-token-description.rst => manage-user-tokens-manually-refresh-access-token-description.rst} (100%) rename source/includes/sdk-examples/users/{authenticate-get-user-access-token.rst => manage-user-tokens-get-user-access-token.rst} (100%) rename source/includes/sdk-examples/users/{authenticate-manually-refresh-access-token.rst => manage-user-tokens-manually-refresh-access-token.rst} (100%) diff --git a/source/includes/api-details/cpp/users/authenticate-get-user-access-token-description.rst b/source/includes/api-details/cpp/users/manage-user-tokens-get-user-access-token-description.rst similarity index 100% rename from source/includes/api-details/cpp/users/authenticate-get-user-access-token-description.rst rename to source/includes/api-details/cpp/users/manage-user-tokens-get-user-access-token-description.rst diff --git a/source/includes/api-details/cpp/users/authenticate-manually-refresh-access-token-description.rst b/source/includes/api-details/cpp/users/manage-user-tokens-manually-refresh-access-token-description.rst similarity index 100% rename from source/includes/api-details/cpp/users/authenticate-manually-refresh-access-token-description.rst rename to source/includes/api-details/cpp/users/manage-user-tokens-manually-refresh-access-token-description.rst diff --git a/source/includes/api-details/dart/users/authenticate-get-user-access-token-description.rst b/source/includes/api-details/dart/users/manage-user-tokens-get-user-access-token-description.rst similarity index 100% rename from source/includes/api-details/dart/users/authenticate-get-user-access-token-description.rst rename to source/includes/api-details/dart/users/manage-user-tokens-get-user-access-token-description.rst diff --git a/source/includes/api-details/dart/users/authenticate-manually-refresh-access-token-description.rst b/source/includes/api-details/dart/users/manage-user-tokens-manually-refresh-access-token-description.rst similarity index 100% rename from source/includes/api-details/dart/users/authenticate-manually-refresh-access-token-description.rst rename to source/includes/api-details/dart/users/manage-user-tokens-manually-refresh-access-token-description.rst diff --git a/source/includes/api-details/kotlin/users/authenticate-get-user-access-token-description.rst b/source/includes/api-details/kotlin/users/manage-user-tokens-get-user-access-token-description.rst similarity index 100% rename from source/includes/api-details/kotlin/users/authenticate-get-user-access-token-description.rst rename to source/includes/api-details/kotlin/users/manage-user-tokens-get-user-access-token-description.rst diff --git a/source/includes/api-details/kotlin/users/authenticate-manually-refresh-access-token-description.rst b/source/includes/api-details/kotlin/users/manage-user-tokens-manually-refresh-access-token-description.rst similarity index 100% rename from source/includes/api-details/kotlin/users/authenticate-manually-refresh-access-token-description.rst rename to source/includes/api-details/kotlin/users/manage-user-tokens-manually-refresh-access-token-description.rst diff --git a/source/includes/api-details/swift/users/authenticate-get-user-access-token-description.rst b/source/includes/api-details/swift/users/manage-user-tokens-get-user-access-token-description.rst similarity index 100% rename from source/includes/api-details/swift/users/authenticate-get-user-access-token-description.rst rename to source/includes/api-details/swift/users/manage-user-tokens-get-user-access-token-description.rst diff --git a/source/includes/api-details/swift/users/authenticate-manually-refresh-access-token-description.rst b/source/includes/api-details/swift/users/manage-user-tokens-manually-refresh-access-token-description.rst similarity index 100% rename from source/includes/api-details/swift/users/authenticate-manually-refresh-access-token-description.rst rename to source/includes/api-details/swift/users/manage-user-tokens-manually-refresh-access-token-description.rst diff --git a/source/includes/sdk-examples/users/authenticate-get-user-access-token.rst b/source/includes/sdk-examples/users/manage-user-tokens-get-user-access-token.rst similarity index 100% rename from source/includes/sdk-examples/users/authenticate-get-user-access-token.rst rename to source/includes/sdk-examples/users/manage-user-tokens-get-user-access-token.rst diff --git a/source/includes/sdk-examples/users/authenticate-manually-refresh-access-token.rst b/source/includes/sdk-examples/users/manage-user-tokens-manually-refresh-access-token.rst similarity index 100% rename from source/includes/sdk-examples/users/authenticate-manually-refresh-access-token.rst rename to source/includes/sdk-examples/users/manage-user-tokens-manually-refresh-access-token.rst diff --git a/source/sdk/users/manage-user-tokens.txt b/source/sdk/users/manage-user-tokens.txt index 9c92181c90..d8893aad9b 100644 --- a/source/sdk/users/manage-user-tokens.txt +++ b/source/sdk/users/manage-user-tokens.txt @@ -64,7 +64,7 @@ Access tokens expire 30 minutes after a user logs in. .. tab:: :tabid: cpp-sdk - .. include:: /includes/api-details/cpp/users/authenticate-get-user-access-token-description.rst + .. include:: /includes/api-details/cpp/users/manage-user-tokens-get-user-access-token-description.rst .. tab:: :tabid: csharp @@ -72,7 +72,7 @@ Access tokens expire 30 minutes after a user logs in. .. tab:: :tabid: dart - .. include:: /includes/api-details/dart/users/authenticate-get-user-access-token-description.rst + .. include:: /includes/api-details/dart/users/manage-user-tokens-get-user-access-token-description.rst .. tab:: :tabid: java @@ -86,17 +86,17 @@ Access tokens expire 30 minutes after a user logs in. .. tab:: :tabid: kotlin - .. include:: /includes/api-details/kotlin/users/authenticate-get-user-access-token-description.rst + .. include:: /includes/api-details/kotlin/users/manage-user-tokens-get-user-access-token-description.rst .. tab:: :tabid: swift - .. include:: /includes/api-details/swift/users/authenticate-get-user-access-token-description.rst + .. include:: /includes/api-details/swift/users/manage-user-tokens-get-user-access-token-description.rst .. tab:: :tabid: typescript -.. include:: /includes/sdk-examples/users/authenticate-get-user-access-token.rst +.. include:: /includes/sdk-examples/users/manage-user-tokens-get-user-access-token.rst Manually Refresh an Access Token ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -108,7 +108,7 @@ You can manually refresh an expired access token. .. tab:: :tabid: cpp-sdk - .. include:: /includes/api-details/cpp/users/authenticate-manually-refresh-access-token-description.rst + .. include:: /includes/api-details/cpp/users/manage-user-tokens-manually-refresh-access-token-description.rst .. tab:: :tabid: csharp @@ -116,7 +116,7 @@ You can manually refresh an expired access token. .. tab:: :tabid: dart - .. include:: /includes/api-details/dart/users/authenticate-manually-refresh-access-token-description.rst + .. include:: /includes/api-details/dart/users/manage-user-tokens-manually-refresh-access-token-description.rst .. tab:: :tabid: java @@ -130,7 +130,7 @@ You can manually refresh an expired access token. .. tab:: :tabid: kotlin - .. include:: /includes/api-details/kotlin/users/authenticate-manually-refresh-access-token-description.rst + .. include:: /includes/api-details/kotlin/users/manage-user-tokens-manually-refresh-access-token-description.rst .. tab:: :tabid: swift @@ -140,7 +140,7 @@ You can manually refresh an expired access token. .. tab:: :tabid: typescript -.. include:: /includes/sdk-examples/users/authenticate-manually-refresh-access-token.rst +.. include:: /includes/sdk-examples/users/manage-user-tokens-manually-refresh-access-token.rst Configure Refresh Token Expiration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From bb9b0f31a2ea58c5aa44a7bcd7edebd10e33537a Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 4 Jun 2024 16:21:00 -0400 Subject: [PATCH 11/14] Fix a snooty build error --- source/sdk/users/manage-user-tokens.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/sdk/users/manage-user-tokens.txt b/source/sdk/users/manage-user-tokens.txt index d8893aad9b..5df4c3eda6 100644 --- a/source/sdk/users/manage-user-tokens.txt +++ b/source/sdk/users/manage-user-tokens.txt @@ -135,7 +135,7 @@ You can manually refresh an expired access token. .. tab:: :tabid: swift - .. include:: /includes/api-details/swift/users/authenticate-manually-refresh-access-token-description.rst + .. include:: /includes/api-details/swift/users/manage-user-tokens-manually-refresh-access-token-description.rst .. tab:: :tabid: typescript From bdcf5528a70b4d69ff6928a4b266f4b43dc48db7 Mon Sep 17 00:00:00 2001 From: Dachary Date: Tue, 18 Jun 2024 15:25:46 -0400 Subject: [PATCH 12/14] Apply suggestions from review Co-authored-by: Kyle Rollins <115574589+krollins-mdb@users.noreply.github.com> --- ...icate-register-create-new-user-account-description.rst | 2 +- source/sdk/users/authenticate-users.txt | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/source/includes/api-details/swift/users/authenticate-register-create-new-user-account-description.rst b/source/includes/api-details/swift/users/authenticate-register-create-new-user-account-description.rst index 5794d69794..d73afec133 100644 --- a/source/includes/api-details/swift/users/authenticate-register-create-new-user-account-description.rst +++ b/source/includes/api-details/swift/users/authenticate-register-create-new-user-account-description.rst @@ -1,6 +1,6 @@ When a user registers or successfully authenticates to your App, Atlas App Services automatically creates a :swift-sdk:`User -Extensions/User.html>` object, which contains a unique +` object, which contains a unique identifier and provider-specific :ref:`user metadata `. You can optionally configure :ref:`custom user data ` if your app needs to store additional user data. To learn more about the diff --git a/source/sdk/users/authenticate-users.txt b/source/sdk/users/authenticate-users.txt index 078c33f718..87f0a7ba62 100644 --- a/source/sdk/users/authenticate-users.txt +++ b/source/sdk/users/authenticate-users.txt @@ -5,7 +5,7 @@ Authenticate Users ================== .. meta:: - :description: Learn how to use Atlas Device SDK authentication providers in client code, including anonymous auth, custom JWT, sign-in with Apple, and Google authentication. + :description: Learn how to use Atlas Device SDK authentication providers in client code, including anonymous auth, custom JWT, Sign-in with Apple, and Google authentication. :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Java SDK, .NET SDK, Node.js SDK, Swift SDK, code example .. facet:: @@ -67,7 +67,7 @@ App Services App with one or more authentication providers enabled. To set up an App Services App with authentication providers, complete the following: -#. :ref:`Connect your App to Atlas App Services ` +#. :ref:`Connect your app to Atlas App Services ` #. :ref:`Enable and Configure Authentication Providers ` in the App Services documentation @@ -853,12 +853,12 @@ on the language, if there are no logged-in users. Refer to .. tab:: :tabid: csharp - .. include:: /includes/api-details/csharp/users/authenticate-log-in-user-description.rst + .. include:: /includes/api-details/csharp/users/authenticate-get-current-user-description.rst .. tab:: :tabid: dart - .. include:: /includes/api-details/dart/users/authenticate-log-in-user-description.rst + .. include:: /includes/api-details/dart/users/authenticate-get-current-user-description.rst .. tab:: :tabid: java From 954b7bcf041848a80deb7b6b8c07484b395e06f4 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 18 Jun 2024 15:38:41 -0400 Subject: [PATCH 13/14] Apply review feedback --- ...enticate-log-in-user-async-description.rst | 2 - source/sdk/users/authenticate-users.txt | 44 ++++--------------- 2 files changed, 9 insertions(+), 37 deletions(-) diff --git a/source/includes/api-details/swift/users/authenticate-log-in-user-async-description.rst b/source/includes/api-details/swift/users/authenticate-log-in-user-async-description.rst index 390caffe41..61368a30a8 100644 --- a/source/includes/api-details/swift/users/authenticate-log-in-user-async-description.rst +++ b/source/includes/api-details/swift/users/authenticate-log-in-user-async-description.rst @@ -1,5 +1,3 @@ -**Async/Await Login** - .. versionadded:: 10.15.0 The async/await version of the :swift-sdk:`App.login ` diff --git a/source/sdk/users/authenticate-users.txt b/source/sdk/users/authenticate-users.txt index 87f0a7ba62..69e9012d16 100644 --- a/source/sdk/users/authenticate-users.txt +++ b/source/sdk/users/authenticate-users.txt @@ -68,8 +68,9 @@ To set up an App Services App with authentication providers, complete the following: #. :ref:`Connect your app to Atlas App Services ` -#. :ref:`Enable and Configure Authentication Providers - ` in the App Services documentation +#. Enable and configure one or more authentication providers. For more + information, refer to :ref:`authentication-providers` in the App Services + documentation. .. tip:: @@ -188,6 +189,12 @@ Log In a User .. tab:: :tabid: swift + **Async/Await** + + .. include:: /includes/api-details/swift/users/authenticate-log-in-user-async-description.rst + + **Callback** + .. include:: /includes/api-details/swift/users/authenticate-log-in-user-description.rst .. tab:: @@ -197,39 +204,6 @@ Log In a User .. include:: /includes/sdk-examples/users/authenticate-log-in-user.rst -.. This tab group is only used to populate some additional details for Swift - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. tab:: - :tabid: csharp - - .. tab:: - :tabid: dart - - .. tab:: - :tabid: java - - .. tab:: - :tabid: java-kotlin - - .. tab:: - :tabid: javascript - - .. tab:: - :tabid: kotlin - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/swift/users/authenticate-log-in-user-async-description.rst - - .. tab:: - :tabid: typescript - .. _sdks-anonymous-login: Anonymous From 47ab62b08cfd5d56d40bd2e1ffa5c4c73ebf16fd Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 18 Jun 2024 15:53:17 -0400 Subject: [PATCH 14/14] Update include name --- ...ent-user.rst => authenticate-get-current-user-description.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename source/includes/api-details/dart/users/{authenticate-get-current-user.rst => authenticate-get-current-user-description.rst} (100%) diff --git a/source/includes/api-details/dart/users/authenticate-get-current-user.rst b/source/includes/api-details/dart/users/authenticate-get-current-user-description.rst similarity index 100% rename from source/includes/api-details/dart/users/authenticate-get-current-user.rst rename to source/includes/api-details/dart/users/authenticate-get-current-user-description.rst