Wholesale CBDC Common Pages and Settings

The pages and navigation options that are available to you depend on your assigned permissions.

Sign in to the application using your assigned user account.
Use the navigation panel to open the pages that are available to your role.
Select My Account to review the token and account context, account status, balance, on-hold amounts, daily limits and usage, application groups, configuration history, and status history.
To end a session, open the user menu and then select Sign Out.

Signing out clears the application session. If identity provider logout is configured, the browser continues to the identity provider's logout page.

Administrator Settings and Customization

Before you begin: Sign in as the central bank administrator.

Open the profile menu.
Select Settings to open the Setup page.
Select the area that contains the settings to update:
- Customizations: Controls welcome text, colors, images, token and account names, organization names and logos, transaction labels, application group labels, and role labels.
- Application Configuration: Maintains token, network, authentication, wrapper API, smart contract, wallet, and rich history service settings.

Note:

The Save Changes control inside a customization card saves the values to the Setup page draft only. To publish the draft, select the page-level Apply Changes. Applying changes saves the complete configuration and restarts or redeploys the application as required. Wait until the application becomes available, sign in again, and verify the affected page.

For local development, the application stores application-owned configuration in the local environment file. Do not put client secrets, database credentials, private keys, bearer tokens, or customer URLs in documentation, screen captures, or source control.

Customize the Login Page

Before you begin: Sign in as the central bank administrator and select Settings.

Under Customizations, open the Login Page card.
Enter the sign-in message in Welcome message or Login Page Message. The sign-in message can be up to 300 characters long.
Choose an image:
- Select the built-in image to enlarge its preview.
- Select Upload Image to choose a PNG, JPG, WEBP, or SVG file no larger than 80 KB. For best results, use a landscape image.
- Select Use Default to restore the built-in image.
Select Save Changes to save the card's values in the Setup draft.
Select Close to return to Setup, then select the page-level Apply Changes.
After the application restarts, open the sign-in page and verify the message and image.

Change the Application Background Color

Before you begin: Sign in as the central bank administrator and select Settings.

Under Customizations, open Background Color.
Choose a preset (Default, Soft Blue, Soft Teal, Warm Sand, or Cool Gray), or open the custom color picker to choose a color.
Review the immediate preview in the card. To restore the original color, select Use Default.
Select Save Changes, then Close.
On the Setup page, select Apply Changes.
After the application restarts, sign in and verify the background color on application pages.

The in-card preview does not publish the color. The application-wide change takes effect only after you select Apply Changes.

Change Token and Account Display Names

Before you begin: Sign in as the central bank administrator and select Settings.

Under Customizations, select Token.
For Token Display Name, enter the name to show in the header and token-related pages.
For Account Display Name, enter the name to show in account sections and account details.
Select Save Changes to save the card draft, then select Close.
On the Setup page, select Apply Changes.
After the application restarts, sign in and verify both names in the applicable views.

Changing these names affects presentation only. It does not change the deployed token or smart contract permissions.

Configure Currency Display

Before you begin: Sign in as the central bank administrator and select Settings.

Under Customizations, select Currency.
Review the Token ID field to confirm the token associated with the display settings. Currency presentation controls do not change this identifier.
For Currency Symbol, select a currency from the standardized ISO currency list.
For Number Format, choose the regional format, which determines the thousands and decimal separators. Selecting a number format also loads its usual symbol position.
Review the Decimal Places field. The precision is loaded from the selected token and cannot be changed here.
For Currency Symbol Position, choose whether the symbol appears before or after the amount.
Check Current Preview to verify the currency symbol, separators, decimal places, and symbol position.
Select Save Changes and Close, then select Apply Changes on the Setup page.
After the application restarts, sign in and verify the monetary values in account and transaction views.

Update Organization Presentation and Sequence

Before you begin: Sign in as the central bank administrator and select Settings. The organization must already be registered.

Under Customizations, select Organization.
In the organization selector, choose the registered organization. The selector displays its name and sequence.
Review the Registered Organization ID and Sequence fields. The registered ID is read-only. Sequence 1 is reserved for the founder.
Enter the new customer-facing name in Display Name. Update the sequence as needed.
If the display name or sequence changed, select Update Organization to send the change to the organization registry.
To customize the Organization Logo image, upload a PNG, JPG, WEBP, or SVG file no larger than 80 KB, or select Use Default.
Select Save Changes to save the customization draft, then select Close.
On the Setup page, select Apply Changes.
After the application restarts, sign in and verify the organization name, logo, and sequence in organization cards, selectors, headers, account views, and lists that show organization order.

The registry maintains the organization's identity and sequence. Changing the display name does not replace its registered organization ID. Registry updates made by using the Update Organization control are distinct from publishing the customization draft through the Apply Changes command.

Change Application Group Labels

Before you begin: Sign in as the central bank administrator and select Settings.

Under Customizations, select Application Group.
In the Application Group selector, choose the group to customize.
Review the fixed authorization value. Do not change the underlying authorization mapping.
For Display Label, enter the customer-facing group name.
Select Save Changes and Close, then select Apply Changes on the Setup page.
After the application restarts, sign in and verify the label in headers, account rows, selectors, and profile menus.

Changing the label does not affect user permissions, workspace access, ledger roles, or account assignments.

Change Transaction Type Labels

Before you begin: Sign in as the central bank administrator and select Settings.

Under Customizations, select Transaction Labels.
In the Transaction Type list, select the transaction mapping to customize.
Review the API Transaction Label field. This service value is fixed.
For Display Label, enter the label to display to users.
Select Save Changes and Close, then select Apply Changes on the Setup page.
After the application restarts, sign in and verify the label in the applicable transaction views.

The display label changes, but the API transaction value does not.

Change Token Role Labels

Before you begin: Sign in as the central bank administrator and select Settings.

Under Customizations, select Roles.
In the Token Role list, choose the role to customize.
Review the fixed authorization role used by the blockchain. Do not change this value.
For Display Label, enter the customer-facing role name.
Select Save Changes and Close, then select Apply Changes on the Setup page.
After the application restarts, sign in and verify the label in account and profile views.

Changing the label does not grant, remove, or otherwise change a user's blockchain permissions.

Application Configuration

The application configuration maintains the connection and runtime values used by the application. These values are normally supplied by the deployment administrator. Change them only when the corresponding service, contract, identity provider, or deployment environment changes.

Before editing the application configuration, record which deployment the values belong to. Confirm the replacement values with the deployment administrator, and keep all secrets masked. When a secret field already contains a masked value, leave it blank if the existing secret should be retained.

Configure Application Settings

Before you begin: Sign in as the central bank administrator and select Settings. Confirm the runtime values for deployment.

Under Application Configuration, locate Application Settings.
For Token ID, enter or verify the token identifier provided during Besu deployment. The ID selects the token used for balances, transfers, issuance, retirement, and account views.
Review the Network field. This release uses Besu. The ledger runtime is fixed by the deployment.
Set Connection Security to HTTPS for secured environments. Use HTTP only when the local deployment is intentionally configured for HTTP.
Set Debug Mode to Off for normal use. Enable it temporarily only to diagnose a controlled test or support issue. Debugging adds authentication and back end request details to server logs.
Review the settings and select Apply Changes.
Wait for the application to restart, sign in again, and verify the applicable token and account operations.

Configure Authentication Settings

The identity provider is configured as part of the deployment or Oracle Blockchain Platform installation. Selecting a sign-in method on the Setup page does not create accounts or change the provider's multi-factor authentication (MFA) policy.

Sign in as the central bank administrator and open Settings.
Under Application Configuration, locate Authentication.
For Sign-In Method, select the method configured for the deployment: LDAP or OpenID Connect (OIDC).
If you select OpenID Connect, complete the OIDC settings in the following section before applying the configuration.
After completing the applicable fields, select Apply Changes, wait for the restart, and test a fresh sign-in.

Configure OpenID Connect Settings

Before you begin: Obtain the OIDC issuer metadata and client registration values for the application deployment. The following fields are displayed only when OpenID Connect is selected as the sign-in method.

For Issuer URL, enter the trusted issuer supplied by the identity provider. Verify it against the provider's OIDC discovery metadata. The wholesale CBDC application uses this authority to discover authorization, token, logout, and signing key endpoints and to verify the token issuer. Do not use the application URL, the token endpoint URL, or an issuer copied from another environment.
For Client ID, enter the client or application ID of the wholesale CBDC application created for this deployment's URL.
When the client registration requires it, enter the credential in the masked Client Secret field. If the existing secret should remain unchanged, leave its edit field blank.
For Redirect URI, enter the exact callback address registered with the identity provider. For the default local port, use http://localhost:3000/api/auth/oidc/callback. The scheme, host, port, and path must all match. Register a corresponding URI when using a different local port.
For Post-Logout Redirect URI, enter the registered browser destination after provider logout. For a default local setup, use http://localhost:3000/, or another explicitly registered local post-logout page. Register this URI separately from the sign-in callback.
For Scopes, enter scopes separated by spaces. The normal baseline is openid profile email. Add provider-specific scopes only when required by the deployment.
For User ID Claim, enter the claim whose value exactly matches the user ID used by the wrapper API and ledger account data. The normal local default is preferred_username; use another claim only when the identity provider and application data use it consistently.
Review all values, then select Apply Changes on the Setup page.
Wait for the application to restart, then sign out and sign in again. Confirm that the callback succeeds, the correct wallet loads, and the expected account and persona permissions are available.

OpenID Connect Terminology

OpenID Connect: A sign-in protocol where an identity provider authenticates a user while the wholesale CBDC application verifies the returned identity before creating an application session.
Identity provider: The service that maintains user accounts, passwords, sign-in pages, and MFA policies. The wholesale CBDC application does not receive the user's password.
Authorization code: A short-lived value sent to the registered callback after the user signs in. The wholesale CBDC application back end exchanges it for tokens.
PKCE: Proof Key for Code Exchange. A protection in the browser redirect flow that helps prevent an intercepted authorization code from being used by a different client.
Access token: A short-lived credential used by the back end to obtain or authorize access to configured downstream services. Do not copy it into documentation or support messages.
Claims: Identity attributes contained in a verified token, such as user ID, email, or groups. The User ID Claim setting identifies the attribute that maps to the wholesale CBDC application user.
MFA: Multi-factor authentication performed by the identity provider when its policy requires additional verification. Changing a wholesale CBDC application Setup field does not enable MFA at the provider.

Local OIDC Sign-In Flow

The user opens the local wholesale CBDC application and starts the sign-in process.
The wholesale CBDC application redirects the browser to the configured identity provider using the issuer, client ID, and requested scopes.
The identity provider authenticates the user and performs MFA when its policy requires it.
The provider redirects the browser to the exact registered Redirect URI with an authorization code.
The wholesale CBDC application back end exchanges the code for tokens, verifies the authentication response, reads the configured User ID Claim, and creates the application session.
The application loads the user's eligible wallet, organization, account, and role context.
When the user signs out, the wholesale CBDC application invokes provider logout when supported and sends the browser to the registered Post-Logout Redirect URI.

Verify Identity Provider Registration for Local Setup

Before you begin: Obtain access to the identity provider application registration and the wholesale CBDC application Setup page values.

Verify that the configured issuer matches the provider's OIDC issuer and discovery metadata.
Verify that the registered client type and client authentication method are supported by the local wholesale CBDC application back end.
Verify that the redirect URI exactly matches http://localhost:3000/api/auth/oidc/callback for the default local port, or the correctly registered URI for another port.
Verify that the post-logout redirect URI is separately registered and matches the configured address, such as http://localhost:3000/.
Verify that the provider returns the configured scopes and the selected User ID Claim.
Verify that the user exists at the identity provider, belongs to the expected groups, and can complete the configured MFA policy.
Apply the matching values on the wholesale CBDC application Setup page, wait for the application to restart, and sign in again to verify the callback, wallet, account, and role context.

Configure the Wrapper API

The wrapper connects the web application to Oracle Blockchain Platform services and the deployed ledger integration.

Before you begin: Sign in as the central bank administrator, select Settings, and obtain the endpoints and credentials for the target deployment.

Under Application Configuration, locate Wrapper API Configuration.
For Service Endpoint, enter the service endpoint provided by the deployment.
For Wrapper API URL, enter the accessible wrapper base URL used for account, token, organization, wallet, and transaction operations.
For Access Token URL, enter the token endpoint supplied by the configured service authentication.
For OBP Instance Client ID, enter the client identifier created for this Oracle Blockchain Platform instance.
When necessary, enter the new credential in the masked OBP Instance Client Secret field. Leave it blank to retain the existing secret. Do not expose the secret in documentation, screen captures, source control, or support messages.
Verify that the endpoints, identifiers, and credentials belong to the same deployment, then select Apply Changes.
After the application restarts, sign in and verify wallet loading, account loading, a read operation, and a permitted transaction.

Configure Smart Contract Addresses

Before you begin: Confirm the Besu contract addresses for the deployment with the deployment administrator.

Sign in as the central bank administrator and open Settings.
Under Application Configuration, locate Smart Contract Configuration.
For Account Contract Address, enter the deployed contract that provides account registration, status, limits, roles, and other account-related ledger operations.
For Token Contract Address, enter the deployed contract used for token balances, issuance, transfers, holds, retirement, and related token operations.
Confirm that both addresses belong to the same Besu deployment as the application, then select Apply Changes.
After the application restarts, sign in and verify the expected account information, balances, roles, and transaction results.

Do not use contract addresses copied from another environment. A mismatched contract can make the application seem connected while returning incorrect account, balance, role, or transaction data.

Configure Wallet Service Settings

Before you begin: Obtain wallet service details for the target deployment.

Sign in as the central bank administrator and open Settings.
Under Application Configuration, locate Wallet Configuration.
For Wallet API URL, enter the service URL used to load wallets available to the authenticated user.
For Organization ID, enter the identifier used by the wallet service to scope wallet loading and account creation to the organization.
For Wallet Service Instance ID, enter the service instance that owns the selected organization and user context.
Confirm that all values match the deployment, then select Apply Changes.
After the application restarts, sign in again and verify that the expected organization's wallets load. If the user has no eligible wallet or CBDC account, the application can stop the sign-in process for the applicable persona.

Configure the Rich History Database

Rich history uses the configured ORDS service to support Besu account and history reads.

Before you begin: Obtain the ORDS OAuth configuration for the target deployment.

Sign in as the central bank administrator and open Settings.
Under Application Configuration, locate Rich History Database Configuration.
For ORDS OAuth Token URL, enter the ORDS endpoint where the back end gets its service token.
For ORDS Client ID, enter the client identifier used for the service token request.
If the credential must change, enter it in the masked ORDS Client Secret field. Leave the field blank to retain the stored secret.
Review the settings and select Apply Changes.
After the application restarts, sign in again and verify an account read and a transaction history read.

The backend obtains the ORDS service token and sends it to the wrapper for Besu account and history reads. Do not expose the ORDS bearer token to the browser or copy it into customer documentation.

Apply and Verify Configuration Changes

Before you begin: Sign in as the central bank administrator.

Change the settings on the Setup page.
Review URLs, identifiers, smart contract addresses, and masked secret fields. Confirm that all values belong to the same deployment and that existing credentials have not been unintentionally replaced or cleared.
When a customization card was modified, select its Save Changes to save the card draft.
Select the page-level Apply Changes control. The complete configuration is saved, and the required application restart or rollout begins.
When the application is available again, sign in.
Verify authentication, wallet loading, account loading, balances, a history read, and the affected persona action.

Display name and label changes affect presentation only. Changes to contract addresses, organization IDs, wallet service instances, authentication settings, wrapper values, or ORDS credentials can affect all personas and must follow the deployment change control procedures.

My Account

The My Account page displays information for the wallet and account selected at sign-in.

Sign in with an authorized account.
On the navigation panel, select My Account.
Review the account ID or address, user, organization, token details, account status, balances, and on-hold amounts.
Review daily transaction usage and limits, application groups, configuration history, and status history as permitted by your role.

Review Transactions and Audit Records

Use the Transactions page to search history and inspect details available for your signed-in context. Auditors can also use their authorized audit workspaces.

Sign in and open Transactions from the navigation panel.
Search the available history using applicable filters, such as transaction identifier, transaction type, organization or user, account or counterparty text, purpose or memo, amount, balance, or date. Filter availability depends on the data.
Review the matching transactions and open an entry to inspect its details.
Open the authenticated /audit page for an auditor workspace.
Select System Audit or Organization Audit, depending on the audit data you need and the auditor role assigned to you.