# Register and log in with the UI

Authentication and authorization of UI operations is managed through the **Ripple Custody: Auth & Sign** app. The app stores secure information associated with a user and provides it during login, intent submission, approval, rejection, and other secure UI operations.

## Keys and token

When you register for the Ripple Custody UI, Ripple Custody generates your keys and JSON Web Token (JWT) and stores them in the authenticator app.

Whenever you log in, the app uses this information to authenticate you.

The app stores your private key on your device, and Ripple Custody never keeps a copy. Because the key exists only on your device, certain actions delete it permanently. Before you reinstall the app or change your device biometrics, read [Protect your device key](#protect-your-device-key).

## Register and log in

Registration for the Ripple Custody UI is a two-step process:

1. The new user creates a profile in the UI and authenticator app.
2. A user administrator creates the user account from the user's alias and public key.


For the user-administrator step, see [Create a user in the UI](/products/custody/v1.42/governance/users/manage-users-and-roles#create-a-user-in-the-ui).

### Prerequisites

Before you register or log in, download the **Ripple Custody: Auth & Sign** app from your app store and install it on your mobile device.

The Auth & Sign app is supported on the following platforms:

| Platform | Requirement |
|  --- | --- |
| Desktop | Windows only |
| iOS | v15.1 or later |
| Android | v7.0 (SDK 24) or later |


The mobile app is tested primarily on stock Android OS. While the app may function on custom Android operating systems, such as OxygenOS, GrapheneOS, or LineageOS, full compatibility is not guaranteed.

### Create a profile

When you create a profile, Ripple Custody:

- Pairs your mobile device with the UI.
- Generates and stores your private authentication data on your mobile device.
- Generates the public key that the user administrator uses to create your user account.


To create a profile:

1. On the UI login page:
  1. Click **Create a profile**.
  2. Click **Continue**.
A QR code is displayed.
![UI registration QR code](/assets/register-uiqr.6b47f9122d53879d36b8e0bb7eea9ce1ec6b44d0528c7dd8918a3bb8e4dffcd1.8aea3934.png)
2. In the app:
  1. Select **Get started**.
The **Pair your device** page is displayed.
![App registration pair device](/assets/register-pair.f9471cf4d3d3e1f866d3fa0cc37ffe4e1ad8713579d83cea70ac710f13ce1f3d.8aea3934.png)
  2. Select **Scan**.
  3. Scan the QR code.
The Ripple Custody server address is filled in for you.
![App registration server address](/assets/register-address.2d9241b07097095e5f8ea4f8d127f961b3729d786a84d1db7a62de02721fd947.8aea3934.png)
  4. Select **Continue**.
The **Complete your profile** page is displayed.
![App registration email address](/assets/register-email.fdf958b7ab0ef5a80ad22f03d12b9e17e4192887dbc6f7581b5d606153032846.8aea3934.png)
  5. Enter your email address.
  6. Select **Continue**.
Your public key is displayed in the **Share your public key** page.
![App registration share key](/assets/register-share.35c4f3a673c7c74228aec7830839ec790a3182e21f6b18d49beb838120defa4b.8aea3934.png)
3. Share the public key with your user administrator by using the on-screen QR code or the share icon next to the **Public key** field.
4. Select **Continue** until you reach the final screen.
5. Select **Finish**.


After your user administrator creates your account, you can log in.

During onboarding, the app also registers your device for push notifications, so that signing and login requests reach your phone. If registration fails, or you select **Continue without notifications**, you can register later from your profile. See [Manage push notifications](#manage-push-notifications).

### Protect your device key

The app stores your private key on your device. Ripple Custody never keeps a copy, so you can't recover the key if your device deletes it.

Some actions permanently delete your device key
The following actions delete the private key from your device. After any of them, you can't log in or sign operations until you register again:

- Uninstalling or reinstalling the app.
- On a mobile device, changing or re-enrolling the biometrics that unlock your device, such as adding or removing a fingerprint or re-enrolling Face ID.


Before you take any of these actions, contact your user administrator so they can plan to replace your key.

If your device deletes the key, you regain access by registering again. Create a new profile, share the new public key with your user administrator, and the administrator creates a replacement user with your new key. For more information, see [Refresh user keys](/products/custody/v1.42/governance/users/refresh-user-keys).

### Log in

Ripple Custody includes the following login types:

- An internal user name and password.
- If available, one or more external single sign-on (SSO) identity providers.


To log in:

1. In the Ripple Custody UI, select one of the login options available to you:
  - To log in with your internal user name and password, select **Harmonize**.
  - To log in with SSO, select an identity provider, such as Azure AD.
![Login options](/assets/sso-login.fe2a6ab21669e7d6acb3774caca038c9224b7af3e63d1f40cf0ff00119fd3a88.8aea3934.png)
The login options available depend on your configuration. All users can log in with the internal user name and password.
2. On the login page, enter the details for the login type:
  - To log in with SSO, enter the details requested by the identity provider.
  - To log in with your standard user name and password:
    1. Enter your email address.
![Enter email address](/assets/login-email.f5638a0aca74835fdebc46331795ea0c1890cb261aa30db2beb8378d3e2425b4.8aea3934.png)
    2. Click **Login**.
A QR code is displayed.
![QR code in UI](/assets/login-qr.8c23b9bf4c521cf8775f74d3bb5e341587092cf7470c64e68527116788fab629.8aea3934.png)
    3. In the app:
      1. Select **Scan** and scan the QR code.
The app displays a set of two-digit numbers.
![Select number in app](/assets/login-app.b4f2c2706dc7a2ac081736eb6cd33090ec0b71b5cd863e63dda6724b99b79ca7.8aea3934.png)
      2. Select the number that matches the two-digit code displayed in the UI.
      3. If prompted, authenticate in your app.


If the UI shows an error instead of a code
Ripple Custody issues the login code from the server. If the login page shows an error instead of a QR code and a code, the server refused the request, the service was unavailable, or you exceeded the login rate limit. When you see **Too many login attempts. Please try again later.**, wait a few minutes before you try again. The rate limit protects you from a flood of push notifications to your phone.

Ripple Custody approves your login and redirects you to your dashboard.

After login, select a domain in the drop-down at the top left to access the entities and operations available to your user in that domain.

## Sign UI operations

Any change requested in the Ripple Custody UI requires authorization with a digital signature. You sign when you submit an intent for approval, approve an intent, or reject an intent.

When you submit, approve, or reject an operation, the UI briefly shows **Preparing your signing request** and then opens the **Check your device** window with a QR code and a two-digit verification code. Ripple Custody issues the code from the server for this request only. The app shows the same code after you scan the QR code, and matching the two confirms that your phone is signing the operation that your browser requested.

To sign an operation:

1. With the app, scan the QR code displayed in the UI.
![Authenticator signing intent update](/assets/sign-app.045ca52ac0bda7003867003c94e53b0dd72db26aca46b76934e768977e778707.8aea3934.png)
2. In the **Signature requested** window:
  1. Check that the two-digit code at the top of the app matches the code in the UI. If the codes differ, select **Cancel** and contact your user administrator.
  2. Review the information displayed in the app in the **Intent details** and **Raw details** sections.
![Authenticator signing intent details](/assets/sign-app2.44ff608541763547505740b3b2d452f8761062abbe8e7c63e1226f5ff56460be.8aea3934.png)
  3. Select **Sign**.


If a code is unavailable
If the UI can't obtain a valid code from the server, it shows an error and stops the signing request. Close the window and submit the operation again. If the app can't obtain a valid code, it shows **Verification code unavailable** with **Retry** and **Cancel this request**, and doesn't offer **Sign** or **Reject** in that state. Never approve a request whose code you can't verify.

Cancelling a signing request in the UI also cancels a request that is still preparing.

Result
The Ripple Custody UI shows a success message if the signature was successful and an error message if the signature was unsuccessful. If the signature was successful, you can check the progress of the intent in [Manage intents and approvals](/products/custody/v1.42/governance/intents/manage-intents-and-approvals#check-state-in-the-ui).

## Manage push notifications

The app receives signing and login requests as push notifications. To receive them, the app registers your device with Ripple Custody. From app version 5.12.0, the app ties this registration to your signing key, so only your device can register or unregister itself for your user.

The first time you open the app after updating to version 5.12.0, the app re-registers your device. If your key is hardware-backed, the app asks you to authenticate once with your device biometrics. The app requests no new permissions.

### Register or retry registration

You can register your device during onboarding or later from your profile:

1. In the app, open your profile.
2. Select one of the following:
  - **Register**, to register a device that isn't registered yet.
  - **Retry registration**, if a previous attempt failed.
  - When you edit your profile, **Save and register** or **Save without registering**.


If registration fails, the app tells you why. For example, registration fails until your user administrator activates your user in Ripple Custody. Complete the activation, then retry.

### Delete a profile or change its server

When you delete a profile or point it at a different Ripple Custody server, the app unregisters your device with a signature from your key, and removes the profile only after the server confirms. If the app can't reach the server, or the server refuses the request, the app keeps the profile and tells you why. Try again when the server is reachable, or contact your user administrator.

Before you delete a profile
Deleting a profile deletes your private key from the device. Read [Protect your device key](#protect-your-device-key) first.