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/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-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-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/cpp/users/manage-user-tokens-get-user-access-token-description.rst b/source/includes/api-details/cpp/users/manage-user-tokens-get-user-access-token-description.rst new file mode 100644 index 0000000000..09b8299327 --- /dev/null +++ b/source/includes/api-details/cpp/users/manage-user-tokens-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/manage-user-tokens-manually-refresh-access-token-description.rst b/source/includes/api-details/cpp/users/manage-user-tokens-manually-refresh-access-token-description.rst new file mode 100644 index 0000000000..9958ea93e3 --- /dev/null +++ b/source/includes/api-details/cpp/users/manage-user-tokens-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/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-description.rst b/source/includes/api-details/csharp/users/authenticate-observe-authentication-changes-description.rst new file mode 100644 index 0000000000..8ec8b1edee --- /dev/null +++ b/source/includes/api-details/csharp/users/authenticate-observe-authentication-changes-description.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-description.rst b/source/includes/api-details/dart/users/authenticate-get-current-user-description.rst new file mode 100644 index 0000000000..3360becf5a --- /dev/null +++ b/source/includes/api-details/dart/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 +:flutter-sdk:`App.currentUser ` +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-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/dart/users/manage-user-tokens-get-user-access-token-description.rst b/source/includes/api-details/dart/users/manage-user-tokens-get-user-access-token-description.rst new file mode 100644 index 0000000000..8a364e4237 --- /dev/null +++ b/source/includes/api-details/dart/users/manage-user-tokens-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/manage-user-tokens-manually-refresh-access-token-description.rst b/source/includes/api-details/dart/users/manage-user-tokens-manually-refresh-access-token-description.rst new file mode 100644 index 0000000000..a458c7cbdf --- /dev/null +++ b/source/includes/api-details/dart/users/manage-user-tokens-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/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-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-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/kotlin/users/manage-user-tokens-get-user-access-token-description.rst b/source/includes/api-details/kotlin/users/manage-user-tokens-get-user-access-token-description.rst new file mode 100644 index 0000000000..7edaa8b3ac --- /dev/null +++ b/source/includes/api-details/kotlin/users/manage-user-tokens-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/manage-user-tokens-manually-refresh-access-token-description.rst b/source/includes/api-details/kotlin/users/manage-user-tokens-manually-refresh-access-token-description.rst new file mode 100644 index 0000000000..e14533c89a --- /dev/null +++ b/source/includes/api-details/kotlin/users/manage-user-tokens-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/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-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-async-description.rst b/source/includes/api-details/swift/users/authenticate-log-in-user-async-description.rst new file mode 100644 index 0000000000..61368a30a8 --- /dev/null +++ b/source/includes/api-details/swift/users/authenticate-log-in-user-async-description.rst @@ -0,0 +1,9 @@ +.. 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 new file mode 100644 index 0000000000..e636a255b3 --- /dev/null +++ b/source/includes/api-details/swift/users/authenticate-log-in-user-description.rst @@ -0,0 +1,15 @@ +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 `. 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..d73afec133 --- /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 +` 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/manage-user-tokens-get-user-access-token-description.rst b/source/includes/api-details/swift/users/manage-user-tokens-get-user-access-token-description.rst new file mode 100644 index 0000000000..72148976c7 --- /dev/null +++ b/source/includes/api-details/swift/users/manage-user-tokens-get-user-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/manage-user-tokens-manually-refresh-access-token-description.rst b/source/includes/api-details/swift/users/manage-user-tokens-manually-refresh-access-token-description.rst new file mode 100644 index 0000000000..72148976c7 --- /dev/null +++ b/source/includes/api-details/swift/users/manage-user-tokens-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/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-google.rst b/source/includes/sdk-examples/users/authenticate-google.rst new file mode 100644 index 0000000000..6fae9b5f49 --- /dev/null +++ b/source/includes/sdk-examples/users/authenticate-google.rst @@ -0,0 +1,65 @@ +.. 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: | + + **ID Token** + + .. literalinclude:: /examples/generated/code/start/Authenticate.snippet.google-with-googleId.swift + :language: swift + + **Server Auth Code** + + .. 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..d96f3b6f52 --- /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/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 + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/AuthenticationTest.snippet.anonymous.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/authenticate.snippet.anonymous-login.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/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-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-observe-authentication-changes.rst b/source/includes/sdk-examples/users/authenticate-observe-authentication-changes.rst new file mode 100644 index 0000000000..5b6a8bd6e8 --- /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-java-kotlin.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/sdk-examples/users/manage-user-tokens-get-user-access-token.rst b/source/includes/sdk-examples/users/manage-user-tokens-get-user-access-token.rst new file mode 100644 index 0000000000..ec97ba4526 --- /dev/null +++ b/source/includes/sdk-examples/users/manage-user-tokens-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/manage-user-tokens-manually-refresh-access-token.rst b/source/includes/sdk-examples/users/manage-user-tokens-manually-refresh-access-token.rst new file mode 100644 index 0000000000..55d5dd87fe --- /dev/null +++ b/source/includes/sdk-examples/users/manage-user-tokens-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/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.txt b/source/sdk/users.txt index c059ed53b7..dba749b85e 100644 --- a/source/sdk/users.txt +++ b/source/sdk/users.txt @@ -15,6 +15,7 @@ Manage Users Create, Delete, & Remove 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 43f43425c3..69e9012d16 100644 --- a/source/sdk/users/authenticate-users.txt +++ b/source/sdk/users/authenticate-users.txt @@ -4,25 +4,854 @@ 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. +.. tabs-selector:: drivers -.. _sdks-offline-login: +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. + +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 +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: + +- :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. -Offline Login +Prerequisites ------------- -.. _sdks-refresh-token-expiry: +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 ` +#. Enable and configure one or more authentication providers. For more + information, refer to :ref:`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 + +.. include:: /includes/tip-acct-deletion-reqs.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 + + **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:: + :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:: -Refresh Token Expiration ------------------------- + .. 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-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 --------------- \ No newline at end of file +-------------- + +.. 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 + +.. _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-get-current-user-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/users/authenticate-get-current-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 diff --git a/source/sdk/users/manage-user-tokens.txt b/source/sdk/users/manage-user-tokens.txt new file mode 100644 index 0000000000..5df4c3eda6 --- /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/manage-user-tokens-get-user-access-token-description.rst + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/users/manage-user-tokens-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/manage-user-tokens-get-user-access-token-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/users/manage-user-tokens-get-user-access-token-description.rst + + .. tab:: + :tabid: typescript + +.. include:: /includes/sdk-examples/users/manage-user-tokens-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/manage-user-tokens-manually-refresh-access-token-description.rst + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/users/manage-user-tokens-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/manage-user-tokens-manually-refresh-access-token-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/users/manage-user-tokens-manually-refresh-access-token-description.rst + + .. tab:: + :tabid: typescript + +.. include:: /includes/sdk-examples/users/manage-user-tokens-manually-refresh-access-token.rst + +Configure Refresh Token Expiration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/refresh-token-expiry.rst