Configuring Billing Care

About Billing Care Configuration Files

Billing Care uses YAML configuration files to define server settings, application behavior, BRM connections, and security settings. During installation, the Billing Care installer creates these files and populates them with the values you specify. After installation, you can edit the files to configure additional supported settings for your environment.

The installer creates the Billing Care configuration files in the Oracle_home/billingcare_rest/config directory, where Oracle_home is the Oracle Home directory you specify during installation.

Table 4-1 describes the configuration files.

Table 4-1 Billing Care Configuration Files

File	Description
application.yaml	Defines server settings, including the host, application and administration ports, and SSL/TLS configuration. Includes LDAP connection settings when you configure LDAP.
brm-connection.yaml	Defines BRM connection settings under the infranet configuration root, including connection pool settings, timeouts, logging, and SSL wallet settings.
configurations.yaml	Defines Billing Care application settings, including batch payment directories, role mapping, and overrides for supported product settings.
authentication.yaml	Defines authentication settings, including the OpenID Connect (OIDC) identity provider, client information, and session cookie settings. You can reference sensitive values, such as the client secret, from the Billing Care application wallet.
authorization.yaml	Defines authorization settings for Billing Care endpoints under the server.features.security configuration root.
meta-config.yaml	Identifies the configuration sources that Billing Care loads, including external YAML files and packaged application defaults. When you enable security, these sources include the authentication and authorization configuration files.

Billing Care combines settings from multiple configuration sources in the following order, from highest to lowest priority:

Java system properties
Environment variables
External configuration files
Packaged application defaults

When a setting appears in multiple configuration sources, Billing Care uses the value from the source with the highest priority. You can override individual settings without copying the entire configuration. When you override an array, the new array replaces the inherited array. Include all entries that you want to retain.

To override a supported Billing Care application setting, add or update the corresponding key under billingcare.configuration in the configurations.yaml file. These changes do not require an SDK customization.

Note:

Do not store passwords, client secrets, or other credentials under billingcare.configuration. Billing Care sends the settings under this configuration root to authenticated Billing Care UI clients. For configuration properties that support wallet references, store credentials in the Billing Care application wallet and reference them from the appropriate configuration file.

Configuring Billing Care Application Settings

You configure Billing Care application settings, such as account search size and session idle timeout, in the configurations.yaml file.

To configure Billing Care application settings:

Open the Oracle_home/billingcare_rest/config/configurations.yaml file.
Add or update the settings under billingcare.configuration. If the file already contains the billingcare and configuration sections, preserve the other settings in the file.

For example, the following configuration sets the account search size to 100 and the session idle timeout to 15 minutes:
```
billingcare:
  configuration:
    fetch-sizes:
      accounts: 100
    timing:
      session-idle-timeout: PT15M
```
Include only supported settings that you want to override. Billing Care uses the packaged defaults for other settings unless a higher-priority configuration source overrides them. Billing Care rejects unrecognized application settings.

Note:

Do not store passwords, client secrets, or other credentials under billingcare.configuration. Billing Care sends the settings under this configuration root to authenticated Billing Care UI clients.
Save the file.
Start or restart Billing Care. See "Starting and Stopping Billing Care".

Billing Care validates the application settings during startup. If invalid settings prevent startup, correct the settings and start Billing Care again.
Sign in to Billing Care again or reload the browser page to use the updated settings.

Verify that the application reflects your changes.

Configuring BRM Connections

Billing Care uses brm-connection.yaml to configure communication with BRM. The file contains Infranet settings for connection pooling, timeouts, logging, and SSL.

The installer configures the initial connection using the information you enter on the BRM Connection Details screen. If you specify an SSL Wallet Location, the installer enables SSL communication with BRM. If you leave this field blank, the installer configures the connection without SSL.

To update the BRM connection settings:

Open Oracle_home/billingcare_rest/config/brm-connection.yaml.

Update the applicable settings under infranet. Preserve the existing values for settings that you do not change.

Table 4-2 lists the settings for connecting Billing Care to BRM.

Table 4-2 BRM Connection Parameters

Setting	Description
PcmTimeoutInMsecs	Specifies the PCM timeout in milliseconds.
connectionpool.minsize	Specifies the minimum connection pool size.
connectionpool.maxsize	Specifies the maximum connection pool size.
log.level	Specifies the PCM logging level.
log.file	Specifies the path to the PCM log file.
pcp.ssl.enabled	Enables or disables SSL communication with BRM.
pcp.ssl.wallet.location	Specifies the directory that contains the BRM SSL wallet.
pcp.ssl.wallet.filename	Specifies the BRM SSL wallet filename, such as cwallet.sso.
wallet.location	Specifies the Billing Care application wallet directory. This setting applies to both SSL-enabled and SSL-disabled connections.

Configure SSL to match your BRM environment.
- To enable SSL, set pcp.ssl.enabled to true and specify the directory and filename of a valid BRM SSL wallet in pcp.ssl.wallet.location and pcp.ssl.wallet.filename.
- To disable SSL, set pcp.ssl.enabled to false. Keep wallet.location set to the Billing Care application wallet directory in either case.
Save the file.
Start or restart Billing Care. See "Starting and Stopping Billing Care".
Sign in to Billing Care and open an existing account to verify that Billing Care retrieves account information from BRM.

The following examples show the configuration for each SSL option. They use /opt/oracle/billingcare as the Oracle Home directory and /opt/oracle/brm-ssl-wallet as the BRM SSL wallet directory. Replace these paths with the paths for your installation. The numeric values illustrate a sample configuration; retain the values appropriate for your environment.

For a connection with SSL disabled:

infranet:
  PcmTimeoutInMsecs: 15000
  connectionpool:
    minsize: 25
    maxsize: 50
  login:
    type: 1
  log:
    level: 2
    file: /opt/oracle/billingcare/billingcare_rest/logs/javapcm-billingcare-rest.pinlog
  pcp:
    ssl:
      enabled: false
  wallet:
    location: /opt/oracle/billingcare/billingcare_rest/wallet

For a connection with SSL enabled:

infranet:
  PcmTimeoutInMsecs: 15000
  connectionpool:
    minsize: 25
    maxsize: 50
  login:
    type: 1
  log:
    level: 2
    file: /opt/oracle/billingcare/billingcare_rest/logs/javapcm-billingcare-rest.pinlog
  pcp:
    ssl:
      enabled: true
      wallet:
        location: /opt/oracle/brm-ssl-wallet
        filename: cwallet.sso
  wallet:
    location: /opt/oracle/billingcare/billingcare_rest/wallet

Configuring SSL or TLS for Billing Care

You configure SSL/TLS in the application.yaml file to secure connections to the Billing Care application and administration ports. Billing Care supports the following SSL/TLS authentication modes:

One-way SSL: The client verifies the Billing Care server certificate.
Two-way SSL (mutual TLS): The client verifies the server certificate, and Billing Care requires and verifies a client certificate.

The Billing Care installer configures SSL/TLS using the values you enter on the Server Details and Management and Observability screens. You can update the connection settings after installation in the application.yaml file.

Before you configure SSL/TLS, complete the following prerequisites for each connection:

Prepare a PKCS12 keystore that contains the server’s private key and certificate chain. Ensure that the certificate matches the host name that clients use.
Configure clients to trust the server’s certificate authority.
For two-way SSL, prepare a PKCS12 truststore containing trusted client certificate authorities. Configure clients with their certificates and private keys.
Ensure that Billing Care can read each configured keystore and truststore file.

Store the keystore and truststore passwords in the Billing Care application wallet using the following aliases:

server-ssl-keystore-password: Application keystore password
server-ssl-truststore-password: Application truststore password
admin-ssl-keystore-password: Administration keystore password
admin-ssl-truststore-password: Administration truststore password

Configuring SSL/TLS Connections

To configure the SSL/TLS connections for Billing Care:

Open Oracle_home/billingcare_rest/config/application.yaml.

Configure the connection settings under server. Table 4-3 lists the entries to use based on the connection type. You can use a different SSL/TLS authentication mode for each connection.

Use the following examples as guidelines for configuring the connection settings:

Table 4-3 SSL and TLS Configuration Locations

Connection	Port	SSL/TLS configuration
Application	server.port	server.tls
Administration	server.sockets.admin.port	server.sockets.admin.tls

If you enable HTTPS for an installation that uses OIDC authentication, update the registered redirect and logout URLs as required and set cookie-secure to true in the OIDC provider configuration. See "Configuring OIDC Authentication".
Save your configuration changes and restart Billing Care. See "Starting and Stopping Billing Care".
Verify that clients can connect to both configured HTTPS ports without certificate errors. For two-way SSL, verify that connections succeed with a trusted client certificate and fail without one.

Configuring One-Way SSL Example

The following example configures one-way SSL for both application and administration connections:

Note:

Each key.alias setting must identify the private-key entry in the corresponding keystore.

server:
   host: billingcare.example.com
   port: 8082
   tls:
      enabled: true
      client-auth: NONE
      private-key:
         keystore:
            type: PKCS12
            passphrase: "${wallet=server-ssl-keystore-password}"
            key:
               alias: billingcare
            resource:
               path: "/opt/billingcare/certs/server.p12"
   sockets:
      admin:
         port: 8084
         tls:
            enabled: true
            client-auth: NONE
            private-key:
               keystore:
                  type: PKCS12
                  passphrase: "${wallet=admin-ssl-keystore-password}"
                  key:
                     alias: billingcare-admin
                  resource:
                     path: "/opt/billingcare/certs/admin.p12"

Configuring Two-Way SSL Example

When configuring two-way SSL, keep the keystore settings from the one-way SSL configuration. For each connection that requires two-way SSL, change client-auth to REQUIRED and add a trust section.

The following example shows the two-way SSL settings for both application and administration connections. Merge these settings into the existing configuration and retain the enabled and private-key settings.

server:
   tls:
      client-auth: REQUIRED
      trust:
         keystore:
            type: PKCS12
            trust-store: true
            passphrase: "${wallet=server-ssl-truststore-password}"
            resource:
               path: "/opt/billingcare/certs/server-truststore.p12"
   sockets:
      admin:
         tls:
            client-auth: REQUIRED
            trust:
               keystore:
                  type: PKCS12
                  trust-store: true
                  passphrase: "${wallet=admin-ssl-truststore-password}"
                  resource:
                     path: "/opt/billingcare/certs/admin-truststore.p12"

Configure browsers, API clients, and administration tools that connect to these ports to present trusted client certificates.

Note:

Two-way SSL does not replace Billing Care authentication or authorization. Users must still sign in and have permission to perform the requested operations.

Configuring OIDC Authentication

Before you begin, obtain the identity-provider URL, client ID, and audience values for the Billing Care application.

Billing Care uses OpenID Connect (OIDC) to authenticate users through an identity provider. The installer configures OIDC when you select Yes on the Security Details screen and enter your OIDC provider information. You can review or update these settings after installation in the authentication.yaml file.

To configure OIDC authentication:

Register the Billing Care redirect URL with your identity provider.
Use the redirect URL that the Billing Care installer displays when installation completes. For an HTTPS deployment, the URL has the following format: https://hostname:port/bc/oidc/redirect.

Use the host name and port through which users access Billing Care.
Open Oracle_home/billingcare_rest/config/authentication.yaml.

Under security.providers, locate the oidc entry and update the settings listed in Table 4-4.

Table 4-4 Identity Provider Settings

Setting	Description
identity-uri	Specifies the identity-provider URL.
client-id	Specifies the client ID of the confidential OAuth application you configure for Billing Care in the identity provider.
scope-audience	Specifies the primary audience for the confidential OAuth application.
audience	Specifies the secondary audience, if you configure one. Otherwise, use the same value as scope-audience.
client-secret	References the client secret in the Billing Care application wallet through ${wallet=oidc-client-secret}.
cookie-encryption-password	References the cookie encryption password through ${wallet=oidc-cookie-encryption-password}.
cookie-secure	Controls whether the browser sends the session cookie only over HTTPS. Set this value to true when Billing Care uses HTTPS.

Ensure that the Billing Care application wallet contains the client secret that matches your identity-provider application and the cookie encryption password. Retain the wallet references in authentication.yaml.

Preserve the installer-generated redirect and logout paths, including /bc/oidc/redirect, /bc/logout, and /bc.

Save and close the file.
Open Oracle_home/billingcare_rest/config/meta-config.yaml and verify that its configuration sources include authentication.yaml and authorization.yaml.
Preserve the other configuration sources and their order.
Start or restart Billing Care. See "Starting and Stopping Billing Care".
Access the Billing Care URL in a new browser session and verify that Billing Care redirects you to the identity provider.
Sign in with a valid user and verify that the browser returns to Billing Care.

Configuring Role Mapping

Billing Care uses a role mapper to retrieve the users available for Collections and Payment Suspense assignments. The role mapper retrieves users from a directory, an identity provider, or a list that you configure.

You select the role mapper in the configurations.yaml file. Billing Care uses the roles allowed for the assignment operation in the authorization.yaml file to determine which groups to retrieve.

Note:

Adding a user to an assignment list does not create a login account or grant access permissions. Configure authentication and authorization separately.

To configure role mapping:

Open Oracle_home/billingcare_rest/config/configurations.yaml.
Locate billingcare.role-mapper and set type to one of the following values:
- ldap: Users in an LDAP directory.
- keycloak: Members of Keycloak groups.
- idcs: Members of Oracle Identity Cloud Service (IDCS) groups.
- static: Users you list under billingcare.role-mapper.static.fixed-members.
- basic: Users and roles configured in the global http-basic-auth provider in authentication.yaml.
For example, to use LDAP, specify:
```
billingcare:
  role-mapper:
    type: ldap
```
Update the existing billingcare section and preserve its other settings.
Configure one of the following selected user sources:
Verify that the group names or configured role names match the assignment roles in authorization.yaml. See “Matching Users to Assignment Roles”.
Save and close the files.
Start or restart Billing Care. See "Starting and Stopping Billing Care".
Sign in as an authorized user and open the Collections and Payment Suspense assignment lists. Verify that the expected users appear.

Using LDAP

Use the LDAP role mapper to retrieve users from directory groups for Collections and Payment Suspense assignments. Select ldap as the role-mapper type in configurations.yaml, then configure the directory connection in application.yaml.

The installer creates the connection settings when you enter information on the LDAP Connection Details screen. You can update these settings after installation. Billing Care supports LDAP and SSL/TLS-enabled LDAP (LDAPS) connections.

Ensure that the configured bind user can read the groups and their member entries. Group members must have uid values that identify their login user names. The LDAP mapper retrieves only direct group members.

To configure the directory connection:

Open Oracle_home/billingcare_rest/config/application.yaml.

Locate the ldap section and update the settings in Table 4-5.

Table 4-5 LDAP Settings

Setting	Description
urls	Specifies the LDAP server address and port.
bind.dn	Specifies the distinguished name (DN) of the directory user that Billing Care uses to connect to the LDAP server.
bind.password	Specifies the credential for the directory connection. Retain the existing credential setting when you update other connection details.
users.base-dn	Specifies the base DN of the directory tree that contains users.
users.user-from-name-filter	Specifies the search filter that locates a user by user name.
groups.base-dn	Specifies the base DN of the directory tree that contains groups.
groups.group-from-name-filter	Specifies the search filter that locates a group by group name.

Configure the base DNs and filters to match your directory structure. Keep {username} and {group} as placeholders in the corresponding filters.

For an LDAPS connection, configure the directory server to accept LDAPS connections and set ldap.urls to the server’s LDAPS address, such as ldaps://ldap.example.com:1636. Make a PKCS12 truststore containing the required trusted CA certificates available on the Billing Care host. Ensure that Billing Care can read the file.

Under ldap.tls, configure the settings in Table 4-6.

Table 4-6 LDAPS Settings

Setting	Description
mode	Set to LDAPS.
trust-store.path	Specifies the path to the truststore file on the Billing Care host.
trust-store.type	Set to PKCS12 for a PKCS12 truststore.
trust-store.password	Specifies the credential for accessing the truststore. Use the supported wallet reference for this credential.

After you configure the connection, complete the remaining steps in "Configuring Role Mapping" to save your changes, restart Billing Care, and verify the assignment lists.

The following examples show the ldap section in application.yaml for LDAP and LDAPS connections. Replace the server addresses, ports, bind DN, base DNs, and truststore path with the values for your environment. Adjust the filters to match your directory’s attributes and object classes.

For an LDAP connection:

ldap: &ldapConfig
  urls:
    - "ldap.example.com:1389"
  bind:
    dn: "cn=Directory Manager"
    password: "<existing bind.password value>"
  users:
    base-dn: "ou=people,dc=example,dc=com"
    user-from-name-filter: "(&(uid={username})(objectClass=person))"
  groups:
    base-dn: "ou=groups,dc=example,dc=com"
    group-from-name-filter: "(&(cn={group})(|(objectClass=groupOfNames)(objectClass=groupOfUniqueNames)))"

For an LDAPS connection:

ldap: &ldapConfig
  urls:
    - "ldaps://ldap.example.com:1636"
  tls:
    mode: LDAPS
    trust-store:
      path: "/opt/oracle/certificates/ldap-truststore.p12"
      type: "PKCS12"
      password: "<truststore password wallet reference>"
  bind:
    dn: "cn=Directory Manager"
    password: "<existing bind.password value>"
  users:
    base-dn: "ou=people,dc=example,dc=com"
    user-from-name-filter: "(&(uid={username})(objectClass=person))"
  groups:
    base-dn: "ou=groups,dc=example,dc=com"
    group-from-name-filter: "(&(cn={group})(|(objectClass=groupOfNames)(objectClass=groupOfUniqueNames)))"

The examples reference ldap-admin-password for the directory bind password and ldap-truststore-password for the truststore password. The installer creates the bind-password entry when you configure LDAP. Create the truststore-password entry separately before using the LDAPS configuration. Preserve the other settings in application.yaml.

Using Keycloak or IDCS

The Keycloak and IDCS role mappers use the first global oidc provider in authentication.yaml to obtain a service token and retrieve group members.

Before selecting either mapper:

Configure OIDC authentication. See “Configuring OIDC Authentication”.
Enable the client credentials grant for the configured client.
Grant the client permission to read the required groups and their members.
Verify that Billing Care trusts the certificates used by the token endpoint and directory APIs.

Successful browser sign-in does not verify that the client can retrieve assignment users.

For Keycloak, set identity-uri to the realm URL, such as https://keycloak.example.com/realms/billingcare.

Create Keycloak groups with names that match the allowed assignment roles. Realm roles and token role claims alone do not provide the group membership that the mapper retrieves.

For IDCS, grant the client access to the required SCIM group and member operations. Ensure that each returned member’s name contains the login user name. The mapper requests the administrative scope urn:opc:idm:myscopes.

These mappers use the global OIDC client settings. They do not provide separate role-mapper settings for a client ID, client secret, token endpoint, or TLS connection.

Using a Static User List

Use static to define assignment users directly in configurations.yaml.

Under fixed-members, add an entry for each allowed role group. For each user, specify:

id: A stable, nonblank user identifier.
name: The user’s login user name. Specify the login name, not a display name.

For example:

billingcare:
  role-mapper:
    type: static
    static:
      fixed-members:
        super-csr:
          - id: "csr-alice"
            name: "alice"
          - id: "csr-charlie"
            name: "charlie"
        regular-csr:
          - id: "csr-bob"
            name: "bob"
          - id: "csr-charlie"
            name: "charlie"

Replace the example groups and users with values for your environment.

If an assignment operation allows both super-csr and regular-csr, this example returns alice, bob, and charlie. Billing Care removes duplicate login user names from the final assignment list.

Entries with a missing or blank id or name do not appear in the list. Groups without configured members return no users.

Using Users Configured for Basic Authentication

Use basic when the assignment users come from the global http-basic-auth provider in the authentication.yaml file.

In the configurations.yaml file, specify the following:

billingcare:
  role-mapper:
    type: basic

In the existing global http-basic-auth provider, configure each user’s login, password, and roles. For example:

security:
  providers:
    - abac: {}
    - http-basic-auth:
        realm: BillingCare
        users:
          - login: "alice"
            password: "${wallet=basic-alice-password}"
            roles: [super-csr]
          - login: "bob"
            password: "${wallet=basic-bob-password}"
            roles: [regular-csr]
          - login: "charlie"
            password: "${wallet=basic-charlie-password}"
            roles: [super-csr, regular-csr]

Create the referenced wallet entries with the users’ passwords. Use HTTPS for requests that use Basic authentication.

Note:

This example configures a global authentication provider. Preserve the existing provider list, and change the sign-in configuration only if you intend to change how users authenticate. Selecting type: basic alone does not enable Basic authentication.

The mapper uses login as both the user identifier and login user name. It retrieves users from global Basic authentication providers; credentials configured only for an outbound service do not supply assignment users.

Restart Billing Care after changing these users or their roles.

Matching Users to Assignment Roles

Billing Care determines assignment groups based on the roles allowed in the matching endpoint policies defined in the authorization.yaml file. Table 4-7 lists the path aliases and HTTP methods for these operations.

Table 4-7 Path Aliases and Methods for Assignment Operations

Assignment Operation	Path Alias	Method
Collections	collections-perform	GET
Payment Suspense	payment-suspense-allocate	POST

Ensure that the allowed role names match the group names or roster keys in your selected user source. For example, an operation that allows super-csr requires a corresponding super-csr group or roster entry.

Update the existing endpoint policy. If multiple entries have the same path alias and method, Billing Care uses the first matching entry to retrieve assignment groups.

Note:

The assignment lookup uses roles-allowed to retrieve candidates. It does not evaluate roles-denied or other authorization conditions for each candidate. Billing Care still enforces endpoint authorization when a user performs an operation.

If an assignment list is empty, check the matching endpoint policy, its allowed roles, and the corresponding group memberships. For Keycloak and IDCS, also verify that the configured client can obtain a service token and read group members.

Configuring Billing Care Authorization

Billing Care uses authorization rules to control which operations users can perform. You configure these rules in authorization.yaml by specifying the roles that can access each REST endpoint. Billing Care also uses these rules to determine which actions users can access in the UI.

Before you configure authorization, configure authentication and ensure that the authenticated user’s roles match the role names in your authorization rules. For OIDC authentication, see “Configuring OIDC Authentication”.

To configure authorization:

Open Oracle_home/billingcare_rest/config/authorization.yaml.
Under server.features.security.endpoints, locate the entry for the operation you want to configure. Identify the entry by its path, method, and path-alias.

Preserve the existing paths, methods, and aliases when you change access permissions. Billing Care uses path aliases for UI access checks and assignment-user lookups.

Update the authorization rules using the settings in Table 4-8.

Table 4-8 Endpoint Authorization Settings

Setting	Description
path	Specifies the REST endpoint path.
method	Specifies the HTTP methods covered by the entry, such as [get] or [post].
path-alias	Identifies the operation for UI access checks and other authorization lookups.
config.authenticate	Specifies whether the endpoint requires authentication. Retain true for protected endpoints.
config.authorize	Specifies whether Billing Care checks authorization for the endpoint. Retain true for protected endpoints.
config.authorization-explicit	Specifies whether the endpoint requires explicit authorization configuration. Retain true for protected endpoints.
config.abac.rule-validator	Contains the authorization rules for the endpoint. Rules can include role checks and additional policy conditions.
name	Identifies a rule within rule-validator.
roles-allowed	Lists the roles that the rule allows.
roles-denied	Lists the roles that the rule denies.

Preserve existing policy conditions, such as amount limits, when you update role permissions. For operations that modify data, preserve applicable restrictions on read-only-csr.

Save and close the file.
Start or restart Billing Care. See "Starting and Stopping Billing Care".
Sign in with users who have the affected roles. Verify that permitted operations are available and prohibited operations remain denied. Check REST access as well as UI access.

The following example defines role-based access to the account-details endpoint for super-csr and regular-csr:

server:
  features:
    security:
      endpoints:
        - path: /bcws/webresources/v1.0/accounts/{id}
          method: [get]
          path-alias: account-view
          config:
            authenticate: true
            authorize: true
            authorization-explicit: true
            abac:
              rule-validator:
                - name: super-csr
                  roles-allowed: [super-csr]
                - name: regular-csr
                  roles-allowed: [regular-csr]

Update the corresponding entry in your existing authorization.yaml file. Preserve the other endpoint entries and any additional conditions that apply to this operation.

Note:

Configuration sources can replace an entire YAML list. Do not replace the endpoints list with this single-entry example.

Configuring the Oracle Analytics Publisher Connection

Billing Care retrieves invoice PDFs from Oracle Analytics Publisher. Configure the Publisher connection in the application.yaml file and select an authentication method that Publisher accepts.

Table 4-9 describes the supported authentication methods.

Table 4-9 Supported Authentication Methods

Authentication Method	When to Use
Signed-in user’s access token	Publisher accepts the Billing Care user’s token and grants report access to that user.
OAuth service client	Publisher requires a service identity to retrieve reports.
Basic authentication	Publisher accepts an account name and password.

Before you configure the connection, obtain the Oracle Analytics Publisher reports service URL and verify that the required BRM invoice reports are available. Ensure that the user or service identity has permission to access these reports.

To configure the connection to Oracle Analytics Publisher, complete the following steps:

Open Oracle_home/billingcare_rest/config/application.yaml.
Locate or add the api-processor.backends.invoice-publisher configuration entry.
Set base-uri to the Oracle Analytics Publisher reports service URL. For example, use this reports service URL: https://publisher.example.com:8443/xmlpserver/services/rest/v1/reports.

Replace the host and port with the values for your environment. Do not include a trailing slash or an individual report path. Billing Care adds the report path when it requests an invoice.
Configure one of the following authentication methods:
Configure the certificate trust and wallet entries described in "Configuring Certificate Trust and Credentials".
Save and close the configuration files that you modified.
Start or restart Billing Care. See "Starting and Stopping Billing Care".
Sign in to Billing Care and retrieve an existing invoice.

Verify that Billing Care displays a valid invoice PDF and that Oracle Analytics Publisher records the expected user or service identity.

Using the Signed-In User’s Access Token

Use this method when Publisher accepts the access token of the user signed in to Billing Care. Publisher must accept the token’s issuer, audience, and scopes and map the user to the required report permissions.

In the application.yaml file, configure the connection as follows:

api-processor:
   backends:
      invoice-publisher:
         base-uri: "https://publisher.example.com:8443/xmlpserver/services/rest/v1/reports"
         security: {}

The empty security section enables the connection to use the current request’s security context. Retain this section when you use the signed-in user’s token.

In the authentication.yaml file, locate the existing oidc provider under security.providers that Billing Care uses for user authentication. Add outbound-type, propagate, and outbound to that provider, as shown below:

security:
  providers:
    - oidc:
        # Existing authentication settings remain here.
        outbound-type: USER_JWT
        propagate: true
        outbound:
          - name: publisher-user-token
            hosts: ["publisher.example.com"]
            transports: ["https"]
            propagate: true
          - name: other-targets
            propagate: false

This example shows only the settings for forwarding the token. Update the existing OIDC provider; do not create another provider or replace its authentication settings. Preserve other providers and any approved outbound destinations.

Replace publisher.example.com with the Publisher host name, without a scheme or port. Keep approved destinations before the final other-targets entry, which prevents token forwarding to unmatched hosts.

Billing Care forwards the access token associated with the request. It does not forward the browser cookie or obtain a replacement token for Publisher.

Using an OAuth Service Client

Use an OAuth service client when Oracle Analytics Publisher requires a service identity. Register an OAuth client with the identity provider. Obtain the client's ID and secret, the identity provider's token endpoint, and the scope required for Publisher access.

In the application.yaml file, configure the OAuth service client under api-processor.backends.invoice-publisher.security as shown in the following example:

api-processor:
   backends:
      invoice-publisher:
         base-uri: "https://publisher.example.com:8443/xmlpserver/services/rest/v1/reports"
         security:
            providers:
               - oidc:
                    client-id: "<publisher-service-client-id>"
                    client-secret: "${wallet=bip.oidc.client.secret}"
                    identity-uri: "https://<publisher-identity-provider>"
                    token-endpoint-uri: "https://<publisher-identity-provider>/oauth2/v1/token"
                    token-endpoint-auth: CLIENT_SECRET_BASIC
                    outbound-type: CLIENT_CREDENTIALS
                    propagate: true
                    outbound:
                       - name: publisher-service-token
                         hosts: ["publisher.example.com"]
                         transports: ["https"]
                         propagate: true
                       - name: other-targets
                         propagate: false
                    client-credentials:
                       scope: "<publisher-scope>"
                    redirect: false
                    cookie-use: false
                    cookie-encryption-enabled: false

Replace the example values with the values for your environment and registered service client. The /oauth2/v1/token path is an IDCS example. Use the token endpoint published by your identity provider. Table 4-10 describes the OAuth service client settings for authenticating the service client, obtaining an access token, and forwarding the token to Oracle Analytics Publisher.

Table 4-10 OAuth Service Client Settings

Setting	Description
client-id	Identifies the registered Publisher service client.
client-secret	References the wallet entry that contains the client secret.
identity-uri	Specifies the identity provider’s base or issuer URI.
token-endpoint-uri	Specifies the published token endpoint.
token-endpoint-auth	Specifies how the client authenticates to the token endpoint. The example uses CLIENT_SECRET_BASIC.
outbound-type	Specifies CLIENT_CREDENTIALS as the outbound authentication type used to obtain a service token.
client-credentials.scope	Specifies the exact scope registered for Publisher access.
outbound	Restricts token forwarding to the configured Publisher host.

Oracle Analytics Publisher receives the resulting bearer token. The CLIENT_SECRET_BASIC value specifies how the service client authenticates to the token endpoint.

The service client can use the same identity provider as Billing Care or a different provider. Keep the OAuth service client configuration inside the invoice-publisher backend and preserve the global Billing Care sign-in provider in authentication.yaml.

Using Basic Authentication

Use this method when Publisher accepts an account name and password.

In the application.yaml file, use the following:

api-processor:
   backends:
      invoice-publisher:
         base-uri: "https://publisher.example.com:8443/xmlpserver/services/rest/v1/reports"
         security:
            providers:
               - http-basic-auth:
                    outbound:
                       - name: publisher-basic
                         hosts: ["publisher.example.com"]
                         transports: ["https"]
                    username: "<publisher-account>"
                    password: "${wallet=invoice.publisher.password}"

Replace the host name and account name with your values. Store the account password in the invoice.publisher.password wallet entry.

Grant the account permission to access the required invoice reports. This provider authenticates the Publisher connection; Billing Care sign-in continues to use its existing authentication configuration.

Configuring Certificate Trust and Credentials

Configure certificate trust for each HTTPS connection. Billing Care may require separate trust settings for Oracle Analytics Publisher and the identity provider that issues access tokens. Table 4-11 lists the truststore configuration locations for each connection type.

Table 4-11 Certificate Trust Configuration Locations

Connection	Configuration Location
Publisher reports service	api-processor.backends.invoice-publisher.tls in application.yaml
Identity provider for the signed-in user’s token	webclient.tls under the global oidc provider in authentication.yaml
Identity provider for the service client	webclient.tls under the oidc provider in the invoice-publisher backend

If the existing Java trust configuration validates a server certificate, you can omit custom trust settings for that connection.

In the application.yaml file, add tls alongside base-uri and security under api-processor.backends.invoice-publisher to configure a custom Publisher truststore:

tls:
   trust:
      keystore:
         type: PKCS12
         trust-store: true
         passphrase: "${wallet=publisher-truststore-password}"
         resource:
            path: "/opt/billingcare/certs/publisher-truststore.p12"

To configure a custom truststore for the service client’s identity provider, add the following webclient settings under the service client’s oidc entry:

webclient:
   tls:
      trust:
         keystore:
            type: PKCS12
            trust-store: true
            passphrase: "${wallet=publisher-oidc-truststore-password}"
            resource:
               path: "/opt/billingcare/certs/publisher-oidc.p12"

Replace the example paths with paths to truststore files that Billing Care can read on its host. Populate the truststores with approved CA certificates. Use server URLs whose host names match the names in the corresponding server certificates. Keep hostname verification enabled.

For the global OIDC provider, preserve its existing trust configuration. If you add a custom truststore for that provider, specify its path and the corresponding wallet reference.

Table 4-12 lists the Billing Care wallet aliases used in the configuration examples for the Publisher account password, OAuth service client secret, and truststore passwords.

Table 4-12 Wallet Entries Used in the Examples

Wallet alias	Value
invoice.publisher.password	Publisher account password for Basic authentication.
bip.oidc.client.secret	OAuth service client secret.
publisher-truststore-password	Password for the Publisher truststore.
publisher-oidc-truststore-password	Password for the service client’s identity-provider truststore.

Create only the entries required for your selected configuration. The Billing Care installer does not create these wallet entries automatically.

Set BILLINGCARE_REST_HOME to Oracle_home/billingcare_rest and use the Java runtime configured by bin/setenv.sh. For example, run the following command to add the service client secret:

java -cp "$BILLINGCARE_REST_HOME/libs/*" \
   oracle.security.pki.OracleSecretStoreTextUI \
   -wrl "$BILLINGCARE_REST_HOME/wallet" \
   -createEntry bip.oidc.client.secret

The command prompts you to enter the service client secret and any required wallet password. Use -modifyEntry to update an existing wallet entry. Preserve the existing wallet and its auto-login configuration.

4 Configuring Billing Care

About Billing Care Configuration Files

Configuring Billing Care Application Settings

Configuring BRM Connections

Configuring SSL or TLS for Billing Care

Configuring OIDC Authentication

Configuring Role Mapping

Using LDAP

Using Keycloak or IDCS

Using a Static User List

Using Users Configured for Basic Authentication

Matching Users to Assignment Roles

Configuring Billing Care Authorization

Configuring the Oracle Analytics Publisher Connection

Using the Signed-In User’s Access Token

Using an OAuth Service Client

Using Basic Authentication

Configuring Certificate Trust and Credentials