7 Managing Customer Authentication

This chapter describes how to manage Oracle Communications Billing and Revenue Management (BRM) customer authentication, including login names, passwords, and security codes.

About Customer Authentication and Authorization

Authentication verifies a customer's identity. By default, this is accomplished by checking the customer's login name and password.

Authorization verifies that a customer is allowed to use the service. A user might not be authorized if the service is inactive or if a credit limit has been reached.

Authorization requires that authentication occur first, so that BRM knows who is being authorized.

To customize authentication, you need to edit the PCM_OP_ACT_POL_SPEC_VERIFY policy opcode. For example, you can change the requirements for authentication. See "Authenticating Customers by Using Your Custom Application".

You use the pin_ipass_loader utility to customize authorization for IP services.

About Login Names and Passwords

By default, all services require a login name and password. For services such as telephony, where a customer does not use a login and password, logins and passwords can be generated automatically for internal use.

  • By default, the login name can be a minimum of 1 character and a maximum of 255 characters.

  • By default, the password must be a minimum of 1 character and a maximum of 255 characters.

  • A login name can be assigned to only one account. Login names are unique.

All login names and passwords are associated with a service; for example, the IP service. Customer service representatives (CSRs) use a login name and password to log in to the admin_client service.

Note:

Changing the customer's email login name also changes the customer's email address. Before changing a login name, make sure the customer wants to change the email address.

For more information, see "Setting Up Login Name and Password Defaults".

About Encrypting Customer Passwords

BRM uses two types of customer passwords:

  • Customers use service passwords, such as the password that a customer provides when logging in to an Internet connection, to access an IP service.

  • Customers use account passwords for non-IP access, such as accessing a Web page.

By default, account passwords are stored in the database in an encrypted format; service passwords are not.

For more information on encryption, see "About Encrypting Information" in BRM Developer's Guide.

About Customer Security Codes

You can specify two security codes for a customer. When a customer calls a CSR, the CSR asks the customer for the security code, which is displayed in Customer Center as shown below in Figure 7-1:

Figure 7-1 Customer Security Code

Description of Figure 7-1 follows
Description of ''Figure 7-1 Customer Security Code''

Customers can change their security codes at any time. Security codes are not validated by BRM. See "Using Customer Security Codes".

Assigning New Login Names and Passwords

By default, login names and passwords are assigned at account creation or when adding a service.

In Customer Center, you assign new login names and passwords in the "Service Tab".

Changing Login Names

Use Customer Center to change login names.

Important:

Changing the customer's login name for an email service also changes the customer's email address for the service. Before changing a login name, make sure the customer wants to change the email address.

Changing Passwords

Use Customer Center to change passwords.

If you want customers to change their own passwords, create a Web page that enables customers to change their account information. See "Ways to Implement a Web Interface".

Typically, a customer's password must be changed in the following places:

  • A file on the customer's computer

  • The BRM database, by using Customer Center

To change the password on the customer's computer, have the customer locate their password file and make the change. The name and location of the password file differ depending on the configuration of the customer's connection software. For example, if your customer uses Netscape, the password file is usually located in the netscape\dialer\ISP.sr file, where ISP is the name of your company. However, because customers can change the default location of their password file when they install their connection software, they might have trouble finding this file.

Replacing Lost Passwords

A customer password is not displayed in Customer Center. If a customer loses a password, try the following:

  • Change the password in Customer Center on the Service tab. Have this customer reconfigure the dial-in software with the new password.

    You can also set up BRM to charge a fee for changing the password. See "About Charging for Administrative Events" in BRM Setting Up Pricing and Rating.

  • If the customer cannot change the password in the dial-in software, have the customer contact the company that produces the dial-in software to find out whether there is a way to locate the lost password.

  • If the customer cannot find or change the password, close the current BRM account and open a new one. This may be the easiest method for many customers.

    The drawback to this method is that closed accounts remain in your company's database. See "Reusing Login Names and Passwords from Closed Accounts or Canceled Services".

Using Customer Security Codes

You create customer security codes in Customer Center. When a customer calls a CSR, the CSR asks the customer for the security code to authenticate the customer.

Unlike service passwords, security codes are not validated by BRM; therefore, you cannot enforce properties such as the number of characters in a security code.

Because security codes require a CSR to validate them, they are not used for Web-based administration. To control access to Web pages, use standard Web password methods.

You can change security codes at any time by using Customer Center.

Assigning New Security Codes

Security codes are assigned at account creation. In Customer Center, you assign security codes on the Contact Information panel.

Use Customer Center to change and assign security codes.

Setting Up Login Name and Password Defaults

You can change the minimum and maximum login name and password lengths by using the Field Validation Editor. You can also customize logins and passwords as follows:

Assigning Passwords Automatically

You can set up registration to do either of the following:

  • Require the customer to specify a password. This is the default.

  • Generate a password automatically for the customer.

To generate a password for the customer, you must supply the algorithm for generating passwords. To do so, customize the PCM_OP_CUST_POL_PREP_PASSWD policy opcode.

Standardizing Account Names

You can standardize how account names are displayed, regardless of how they are entered. For example, you can remove spaces from the name or capitalize the first and last name.

The default is to store the name as it was entered at registration. To change this option, customize the PCM_OP_CUST_POL_PREP_NAMEINFO policy opcode.

Defining Email Login Names

To change the requirements for case-sensitivity in email login names, customize the PCM_OP_CUST_POL_PREP_LOGIN policy opcode.

The default email login requirements are:

  • The email login must use all lowercase characters.

  • The email login must include the domain, in this format:

    login@domain
      
    

    For example: john_smith@oracle.com

Detecting Duplicate Logins

By default, BRM does not check for duplicate logins. This means that more than one customer can log in to a service by using the same name. To check for duplicate logins, customize the PCM_OP_ACT_POL_SPEC_VERIFY policy opcode.

Customizing Login Names

For more information on how login names are used in BRM, see "About Login Names and Passwords".

To set the login for an account, use the PCM_OP_CUST_SET_LOGIN opcode. This opcode sets the login field for a /service storable object to the value specified in the PIN_FLD_LOGINS array of the input flist.

If the PCM_OPFLG_READ_RESULT flag is set and the operation is successful, PCM_OP_CUST_SET_LOGIN returns all fields of the /event/customer/login storable object in the PIN_FLD_RESULTS array. Otherwise, only the Portal object ID (POID) of the event object is returned. If the operation is not successful, PCM_OP_CUST_SET_LOGIN returns the PIN_FLD_FIELDS array which specifies the failing field.

If the PCM_OPFLG_CALC_ONLY flag is not set, PCM_OP_CUST_SET_LOGIN creates an /event/customer/login storable object to record the details of the operation.

Customizing Login Names

Use the following opcodes to customize how login names are created. These opcodes are called by PCM_OP_CUST_SET_LOGIN.

  • To prepare login names, use the PCM_OP_CUST_POL_PREP_LOGIN policy opcode. For example, you can add characters or change the case to all lowercase. See "About the PREP and VALID Opcodes" in BRM Developer's Guide.

  • To validate login names, use the PCM_OP_CUST_POL_VALID_LOGIN policy opcode; for example, to ensure that they have the required number of characters, See "About the PREP and VALID Opcodes" in BRM Developer's Guide.

    You define login validation rules by using the Field Validation Editor. This application loads validation rules into the /config/fld_validate storable object. By default, login names must be 255 characters or fewer.

    Caution:

    BRM requires logins for services (they cannot be NULL). BRM requires that login names be unique. BRM will not function properly if the PCM_OP_CUST_POL_VALID_LOGIN policy opcode is customized to allow non-unique login names.

Requiring Login Names for Email and IP Services

By default, BRM requires all accounts that purchase email or IP services to create a login name and password before they can proceed with the account creation or modification process. BRM enforces the login name requirement by using the following two policy opcodes:

  • The PCM_OP_CUST_POL_PREP_LOGIN policy opcode converts all NULL login names to an empty string. For example, if the service type is /service/email and the policy opcode's PIN_FLD_LOGIN input flist field is set to NULL, the policy opcode changes the PIN_FLD_LOGIN flist field to "".

  • The PCM_OP_CUST_POL_VALID_LOGIN policy opcode rejects all login names that are set to an empty string, because the validation process requires that all login names are at least one character in length.

To override this behavior and allow accounts to purchase email and IP services without supplying a login name, customize the PCM_OP_CUST_POL_PREP_LOGIN policy opcode to skip the conversion of NULL login names to an empty string.

Creating Logins for Prepaid Services

For prepaid services, the login is generated automatically. The default login generated by the PCM_OP_CUST_POL_PREP_LOGIN policy opcode is a unique string composed of the database number, service name, and POID.

In cases where a prepaid service login is needed, such as Self-Care Manager, the customer's Mobile Station Integrated Services Digital Network (MSISDN) number is stored in the service object PIN_FLD_ALIAS_LIST array. See "About Using BRM for Wireless Services" in BRM Telco Integration.

The PCM_OP_CUST_POL_VALID_LOGIN policy opcode enforces that a password for a service cannot be changed when the account is created or when a service is added. The password can be changed later. See "About Telco Service Logins and Passwords" in BRM Telco Integration.

Creating Logins for Email Services

For email services, the PCM_OP_CUST_POL_PREP_LOGIN policy opcode appends the domain entry in the Connection Manager (CM) configuration file (pin.conf) to the login. Passing in a domain name results in an error.

Creating Passwords

For more information on how passwords are used in BRM, see "About Login Names and Passwords".

To add or change passwords, use the PCM_OP_CUST_SET_PASSWD opcode.

This opcode sets the PIN_FLD_PASSWD field for a specified /service storable object to the value specified in the PIN_FLD_PASSWORDS array of the input flist.

If the PCM_OPFLG_CALC_ONLY flag is not set, PCM_OP_CUST_SET_PASSWD creates an /event/customer/password storable object to record the details of the operation.

Before setting the new password value, PCM_OP_CUST_SET_PASSWD calls the following policy opcodes to perform these operations:

  • PCM_OP_CUST_POL_PREP_PASSWD, to process and prepare the new password for validation.

  • PCM_OP_CUST_POL_VALID_PASSWD, to validate the password.

  • PCM_OP_CUST_POL_ENCRYPT_PASSWD, to encrypt the password.

If the PCM_OPFLG_CALC_ONLY flag is not set, PCM_OP_CUST_SET_PASSWD creates an /event/customer/password storable object to record the details of the operation.

If the password is successfully updated, the POID of the /event/customer/password object is returned in the PIN_FLD_RESULTS array. Otherwise, PCM_OP_CUST_SET_PASSWD returns the PIN_FLD_FIELDS array that specifies the failing fields.

Customizing Passwords

Use the following policy opcodes to customize passwords:

  • To prepare account or service passwords for validation, use the PCM_OP_CUST_POL_PREP_PASSWD policy opcode. This policy opcode takes the password field for an /account or /service storable object during customer registration and prepares it for validation.

    If the password is for an account, it is set to NULL.

    If a service password is passed in, the operation does nothing. If there is no password for a service, it generates one. A password is considered to be passed in if the PIN_FLD_PASSWD_CLEAR field is in the input flist, even if it is NULL.

  • To validate account or service passwords, use the PCM_OP_CUST_POL_VALID_PASSWD policy opcode. The default check is to make sure the password is not NULL and is less than 255 characters.

Implementing Password Encryption

Use the following policy opcodes to implement password encryption:

The PCM_OP_CUST_POL_ENCRYPT_PASSWD policy opcode encrypts a cleartext password based on the type of the account or service POID given and/or the requested encryption algorithm. The binary result is stored as an ASCII-like string to facilitate storage. All encryption requests from IP accounts get clear text encryption (to support Challenge Handshake Authentication Protocol, or CHAP). Advanced Encryption Standard (AES) is used for all others. For more information, see "About AES Encryption" in BRM Developer's Guide.

  • The PCM_OP_CUST_POL_COMPARE_PASSWD policy opcode takes a cleartext password and an encrypted password from the PCM_OP_CUST_POL_ENCRYPT_PASSWD policy opcode and performs a comparison to check if the cleartext password was the source value of the encrypted password. The type of the /account or /service storable object whose password is being compared is included in the input flist, so the encryption mechanism can be varied for different storable object types. The PCM_OP_CUST_POL_COMPARE_PASSWD policy opcode returns true (match) or false (no match). The PCM_OP_CUST_POL_COMPARE_PASSWD policy opcode is used by BRM whenever a client application supplies a password to be authenticated against an /account or /service storable object.

  • The PCM_OP_CUST_POL_DECRYPT_PASSWD policy opcode decrypts a cleartext password.

Creating Passwords for Prepaid Services

For prepaid services, the password is generated automatically. the PCM_OP_CUST_POL_PREP_PASSWD policy opcode generates a default password (password), which can be customized. See "About Telco Service Logins and Passwords" in BRM Telco Integration.

Customizing Password Expiration

To customize password expiration, use the PCM_OP_CUST_POL_EXPIRATION_PASSWD policy opcode.

This policy opcode calculates and sets the expiration date for the password. This policy opcode is called when the password status of a CSR account is set as Expires.

By default, the PCM_OP_CUST_POL_EXPIRATION_PASSWD policy opcode sets the password expiration date to 90 days.

To change the default password expiry duration, edit the passwd_age entry in the CM pin.conf file. For example, instead of 90 days you can set the expiration duration to 150 days. See "Setting the Default Password Expiry Duration" in BRM Developer's Guide.

If successful, the PCM_OP_CUST_POL_EXPIRATION_PASSWD policy opcode returns:

  • PIN_FLD_POID: The POID of the /account object passed in.

  • PIN_FLD_PASSWORD_EXPIRATION_T: The expiration date and time when the password expires.

For more information, see "Managing CSR Passwords" in BRM Developer's Guide.

Tracking Customer Authentication and Authorization Records

You can record authentication failures to detect possible service problems or the occurrence of fraud. For example, duplicate logins might indicate fraudulent usage. You can specify which authentication failures to record.

You can record user authentication or authorization failures for any reason except using an unknown login name. For example, you can record events when customers try to:

  • Log in with the wrong password

  • Log in to an inactive service

  • Log in after exceeding their credit limit

You can also record successful logins, although doing this slows BRM performance.

Specifying and Loading Verification Preferences

To record user authentication and authorization failures, specify the types of login failures you want to record in the pin_verify file and then load those preferences into the BRM database with the load_pin_verify command.

Note:

The load_pin_verify utility requires a configuration file. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

To specify login failure types:

  1. Edit the BRM_Home/sys/data/config/pin_verify file, where BRM_Home is the directory in which you installed the BRM software. The pin_verify file includes examples and instructions.

    You can make these types of changes:

    • Edit a list of predefined types of login failures to specify which events you want to record and to modify their descriptions.

    • Add custom types of login failures you want to record.

      Caution:

      When you run load_pin_verify, it overwrites the existing preferences for recording customer login failures. If you are updating your preferences, you cannot load new preferences only. You must load complete sets of preferences each time you run the load_pin_verify utility.
  2. Save the file.

  3. Use the following command to run load_pin_verify utility:

    load_pin_verify pin_verify_file 
      
    

    For more information, see "load_pin_verify".

  4. Stop and restart the CM.

To verify that the network elements were loaded, you can display the /config/verify object by using Object Browser, or by using the robj command with the testnap utility. (See "Reading an Object and Writing Its Contents to a File" in BRM Developer's Guide.)

Specifying the Account That Records Login Failures

BRM logs verification events against the root account by default. If you want to use a different account, do the following:

  1. (Optional) Use Customer Center to create an account specifically for logging verification events. You can create a CSR account or a dummy account.

    If you create a dummy account, you should:

    • Use a dummy plan that includes no rates and has a purchase level of all accounts and no services.

    • Use the internal payment method.

    • Use any name and address you want. You have to enter something for name and address to create an account.

  2. Open the CM configuration file in BRM_Home/sys/cm.

  3. Add this entry to the end of the file:

    - fm_act account_name database_number /account 1 
      
    

    where

    • account_name is the name of the account to which verification logging should go.

    • database_number is the database number of the BRM database. By default, this number is 0.0.0.1.

    This example sets an account called verify_acct to log verification events:

    - fm_act verify_acct 0.0.0.1 /account 1 
      
    
  4. Save the file.

  5. Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

Viewing Login Failures

To view login failures:

  1. Use Customer Center to open the root account or the account you specified in the CM configuration file.

  2. Open Event Browser.

  3. Search for verification activity events.

    Following are two examples of how to do this:

    • If you have an account set up especially to log verification events, you can search for all events logged to that account.

    • If you are using root or another account that is logging many types of events, you can use the Any Event (Advanced) template in the Search dialog box to search only for events of the type /event/activity/verify.

    Figure 7-2 is an example of what a verification event looks like in Event Browser:

Figure 7-2 Verification Event in Event Browser

Description of Figure 7-2 follows
Description of ''Figure 7-2 Verification Event in Event Browser''

See "About Event Browser" for more information.

Authenticating Customers by Using Your Custom Application

When customers login, BRM first verifies the customer's login name and password and then performs a variety of checks; for example, when customers attempt to access a service or content offered by your company or a third-party provider.

Authenticating User Actions

Use PCM_OP_ACT_FIND_VERIFY to verify a customer's identity and to perform authentication checks, such as verifying that the customer has good credit and an active account status.

PCM_OP_ACT_FIND_VERIFY takes as input a type-only POID, the action to verify, and the user's login and password. PCM_OP_ACT_FIND_VERIFY then:

  1. Calls PCM_OP_ACT_FIND to retrieve the user's /account and /service objects. See "Finding a Customer's Account Information".

  2. Calls the PCM_OP_ACT_POL_SPEC_VERIFY policy opcode to retrieve the list of authentication checks for the specified action. See "Customizing Authentication Checks".

  3. Performs all authentication checks specified by the policy opcode.

  4. Returns the following, depending on the success of the transaction:

    • If authentication succeeds, PCM_OP_ACT_FIND_VERIFY returns the POID of the service object and the PIN_FLD_RESULT field set to one of the following:

      –   0 to indicate a valid login and password.

      –   4 to indicate that the customer used a temporary password.

    • If authentication fails, PCM_OP_ACT_FIND_VERIFY returns PIN_FLD_RESULT set to one of the following:

      –   2 to indicate an incorrect password.

      –   5 to indicate that the customer used an expired password.

      –   6 to indicate that the password is no longer valid.

Finding a Customer's Account Information

Use PCM_OP_ACT_FIND to locate a customer's account information by using the login name.

PCM_OP_ACT_FIND searches for information on a specific account. In addition, the opcode performs the following operations:

  • If you use a multischema BRM system, it searches all database schemas to find the /account object.

  • If there is an open context (CM connection) to a schema when it is called and it finds the account in a different schema, it switches the context to the correct schema.

  • If there is no open context when it is called, it searches all schemas.

    Note:

    PCM_OP_ACT_FIND does not perform authentication.

PCM_OP_ACT_FIND searches for the /account and /service object. If PCM_OP_ACT_FIND is called with the PCM_OPFLG_READ_RESULT flag, it returns all fields of the /service storable object, not just the POID.

Customizing Authentication Checks

Use the PCM_OP_ACT_POL_SPEC_VERIFY policy opcode to specify the list of authentication checks to perform for each user action.

This policy opcode is called by other opcodes to specify a list of checks used to authenticate user actions.The specified checks are then performed by standard opcodes.

Table 7-1 lists the available authentication checks:

Table 7-1 Default Authentication Checks

Authentication Check Enum Value Description

PIN_ACT_CHECK_UNDEFINED

0

None

PIN_ACT_CHECK_ACCT_TYPE

1

Check type of /account storable object.

PIN_ACT_CHECK_SRVC_TYPE

4

Check type of /service storable object.

PIN_ACT_CHECK_SRVC_STATUS

5

Check the service status. Can be active, inactive, or closed.

PIN_ACT_CHECK_SRVC_PASSWD

6

Confirm that the password is correct.

PIN_ACT_CHECK_CREDIT_AVAIL

7

Check the available credit.

PIN_ACT_CHECK_DUPE_SESSION

8

Check the open session count for the service. See "Enabling Duplicate Session Checking".


You can control the list of checks that each action requires and, to some extent, the behavior of the checks. Few authentication checks lend themselves to these behavior changes. Those that do can define a PIN_FLD_CHOICES array for the options.

The other fields present in an element of the checks array depend on which of the checks is specified by that element. See the output flist specification for more details.

Table 7-2 shows the authentication checks that the PCM_OP_ACT_POL_SPEC_VERIFY policy opcode returns and their behavior:

Table 7-2 Authentications Checks Returned by PCM_OP_ACT_POL_SPEC_VERIFY

Action Default Authentication Checks

PCM_OP_MAIL_DELIV_VERIFY

PIN_ACT_CHECK_SRVC_STATUS = active

PCM_OP_ACT_LOGIN

PIN_ACT_CHECK_SRVC_STATUS = active

PIN_ACT_CHECK_SRVC_PASSWD

PIN_ACT_CHECK_CREDIT_AVAIL = >=0

PCM_OP_MAIL_LOGIN_VERIFY

PIN_ACT_CHECK_SRVC_STATUS = active

PIN_ACT_CHECK_SRVC_PASSWD

PIN_ACT_CHECK_CREDIT_AVAIL = >=0

PCM_OP_TERM_IP_DIALUP_AUTHORIZE

PIN_ACT_CHECK_SRVC_STATUS = active

PIN_ACT_CHECK_SRVC_PASSWD

PIN_ACT_CHECK_CREDIT_AVAIL = >=0

PCM_OP_TERM_IP_DIALUP_AUTHENTICATE/CHAP

PCM_OP_TERM_IP_DIALUP_AUTHENTICATE

PIN_ACT_CHECK_SRVC_STATUS = active

DEFAULT (for everything else)

PIN_ACT_CHECK_SRVC_STATUS = active

PIN_ACT_CHECK_SRVC_PASSWD


You can customize the PCM_OP_ACT_POL_SPEC_VERIFY policy opcode to:

  • Choose a different combination of authentication checks to use on an action.

  • Change the behavior of the authentication checks.

  • Decide not to use any checks to authenticate an action.

  • Authorize a custom action using the list of authentication checks.

The PCM_OP_ACT_POL_SPEC_VERIFY policy opcode uses the DEFAULT set of authentication checks on any action it does not recognize.

If you want to specify a different set of authentication checks for a new action, you must:

  1. Edit the BRM_Home/source/sys/fm_policy/fm_act_pol/fm_act_pol_spec_vrfy.c source file.

  2. Create a new Activity Policy Facilities Module (FM). See "Adding and Modifying Policy Facilities Modules" in BRM Developer's Guide.

    Each authentication check must have a type (the enum value from the table of authentication checks above), and choice options to control the behavior of the check. See the PCM_OP_MAIL_DELIV_VERIFY action definition in the fm_act_pol_spec_vrfy.c file for an example of a PIN_FLD_CHOICES array.

For example, suppose you have defined a non-currency resource. If you want to enforce a credit limit on that resource, you must modify the fm_act_pol_spec_vrfy.c file to include a new action that checks the non-currency resource balance. (By default, checks are performed only on the currency resource.)

Reducing the number of authentication checks does not have a significant effect on performance, with the exception of duplicate session checking.

Enabling Duplicate Session Checking

You can customize the PCM_OP_ACT_POL_SPEC_VERIFY policy opcode to check for duplicate login attempts (PIN_ACT_CHECK_DUPE_SESSION) by performing the following tasks:

  1. Modify your BRM_Home/source/sys/fm_act/pol/fm_act_pol_spec_vrfy.c file to add duplicate session checking to the input flist for the desired actions. This is just the term_ip_dialup related action. Assuming the default version of fm_act_pol_spec_vrfy.c is used as a base, add the following code fragment at line 339:

    type = PIN_ACT_CHECK_DUPE_SESSION;
          c_flistp = PIN_FLIST_ELEM_ADD(a_flistp, PIN_FLD_CHECKS, 4, ebufp);
          PIN_FLIST_FLD_SET(c_flistp, PIN_FLD_TYPE, (void *)&type, ebufp);
          action = "/dialup";
          PIN_FLIST_FLD_SET(c_flistp, PIN_FLD_OBJ_TYPE, (void *)action, ebufp);
      
    
  2. Add the same code fragment at line 390.

  3. Recompile the file and use it as a new Activity Policy FM.