Chapter 12: Authenticating RealProxy Users

RealProxy authentication provides a way for you to control the sites visited by RealPlayer. With this feature, you can configure RealProxy to require a valid user name and password before allowing a RealPlayer to access a particular URL.

Overview

You can restrict which users can access content originated from specific locations. You can use this feature to ensure that only certain users can play streaming media that originates outside your network.

You create a list of the sites that all users can visit. If a user requests content from a site not on this list, she is asked for a user name and password. If you have previously created a username and password for that person, she receives the media. If you haven't created a password, or if the user types it incorrectly, she is denied access.

RealProxy identifies requests for secure content by the host name in the URL.

Authentication is a feature also used by some RealServers. As a result, some users may be asked more than once for a user name and password—once by RealProxy, and once by the transmitter RealServer. In each case, the information the user needs to type will be different.

Setting Up Authentication

Setting up the authentication feature has these steps.

Identify the sites that all users are allowed to visit.
To visit any other sites, users must enter their name and password (see the next step).

Additional Information
See "Step 1: Identify Permitted Sites".
Add user names and passwords.
These users are permitted to visit sites not listed in the previous step.

Additional Information
See "Step 2: Setting Up User Names and Passwords".

	Additional Information
See "Step 1: Identify Permitted Sites".

	Additional Information
See "Step 2: Setting Up User Names and Passwords".

Step 1: Identify Permitted Sites

In this step you choose the sites which all users are allowed to visit without having to supply a user name and password.

Setting Up Permitted Sites

To set up permitted sites:

In RealSystem Administrator, click Security. Click Authentication.
From the Enable Authentication list, select Yes.
From the Realm list, select ConnectRealm.
If you have set up another Realm, select that name here.
From the Database list, select Connect_RN5.
If you have set up another database, select that name here.
In the No Authenticate Rules area, click Add New.
A generic rule name appears.
In the Edit Rule Name box, type a name for this rule.
Click Edit.

In the Host box, type the name of the site to which all users will be permitted access. Use a single asterisk to avoid specificity..

Naming Scheme for Host
Use this form...	...to indicate these sites:
*.org	All sites ending with .org
example.com	The site named www.example.com, including www.sports.example.com.
*.example.com

Note
Use only one asterisk. For example, *.*.com is not allowed.

Repeat Step 2 through Step 8 for each site you want to give access to.
If you want a user to be able to log in from more than one location and view the same content at more than one location, set Allow Duplicate IDs to Yes.
Normally, when Allow Duplicate IDs is set to No, a user can use only one computer to play streaming media. If a user tries to log in from a second computer, he or she will receive an error message. The user must log out at the first location before being permitted to log in at the second location.
Click Apply.

	Note
Use only one asterisk. For example, `..com` is not allowed.

Step 2: Setting Up User Names and Passwords

Add the user names and passwords for those users who are allowed to access content. These users will be able to receive streaming media from sites outside the rules you created in "Step 1: Identify Permitted Sites".

Adding User Names and Passwords

Use the following instructions to add to the list of authorized users.

If you are using Windows NT to list the users, use tools supplied by Windows NT instead.

To add user names and passwords:

In RealSystem Administrator, click Security. Click Realms.
In the Authentication Realms area, select ConnectRealm.
Click Add a User to Realm.
In the new window that appears, type the user's name in the Name box.
In the Password box, give the user's password.
In the Confirm Password box, type the password again.
Click OK.
Repeat Step 3 through Step 7 for each user you want to add.
Click Apply.

Optional Authentication Features

Authentication has these optional features:

Setting Up a New Database

The databases stores the list of users' credentials. RealProxy includes these database interfaces:

Flat file—The text file method is enabled during installation, as it allows the greatest insight into the access permission structure, but the text file method lacks the flexibility of a full database application.
It's best to use the text file method only for simple tracking or for troubleshooting the system before linking a full-fledged database to RealProxy. For small-scale data, the text file method is also faster than a full-fledged database.
ODBC and MSQL—The authentication package contains templates for common databases, including mSQL and some ODBC-compliant databases. Users can also work with databases for which templates do not exist, by setting up the data source with the appropriate table structure. The mSQL database is generally used on UNIX.

Setting Up a Database

Use the instructions below to choose the name and type of database that will store users' names and passwords.

To set up a database:

In RealSystem Administrator, click Security. Click Databases.
Click Add New.
A generic database name appears in the Edit Database Name box.
Type a description for the new database in the Edit Database Name box.
Click Edit.
From the Database Type list, select the data storage method you want to use: Flat file, MSQL, or ODBC.
Depending on the database type method you chose, additional information is required.

Flat File needs only the path to the main text file directory. For example, the con_r_db directory under the main RealProxy directory. See "Authentication Data Storage".
mSQL has two required names, and three optional items:
- Host Name—IP address or DNS name of computer where database is stored.
- Database Name—Name of the database.
- Table Name Prefix—Prefix used to make field names unique, when used with an existing database.
- User Name—Name required by database application.
- Password—Password required by database application. Re-enter your password in the Confirm Password box to ensure you typed it correctly.
ODBC uses the same information as mSQL, but ODBC does not ask for a Host Name. (Refer to "Setting Up Other Types of Data Storage" for further instructions.)

After filling out the appropriate values, click Apply.

Creating a New Realm

A realm contains information about the type of authentication protocol and the database where the authenticated users' names will be stored. If you will be using Windows NT to authenticate users, the realm lists the type of NT authentication and the NT administrator-defined group name.

Authentication Protocols

RealProxy has three methods of authenticating the identity of visitors. Each realm can use only one authentication method.

RealSystem 5.0—also called "RN5", it is RealNetworks' own authentication protocol. This is a more sophisticated protocol than Basic authentication. It provides better security than Basic because it does not send the password in a manner that can be reversed.
If the clients that will be accessing content on your RealProxy are RealPlayer version 5.0 and earlier, be sure to use the RealSystem 5.0 style.
Windows NT LAN Manager—this method allows RealProxy to use the existing NT database of user groups and permissions. It also allows access control of content via NTFS file permissions. This protocol uses Windows NT authentication.
This method is only available to systems using Windows NT, and requires that RealProxy itself be installed on an NT Server. For authenticating content, it also requires Microsoft Internet Explorer and RealNetworks RealPlayer.
Basic Authentication Protocol—encodes the user's name and password with the Base64 algorithm and sends it to RealProxy, which then decodes the password and verifies it.

Setting Up a Realm

Use the instructions below to create a realm.

To create a realm:

In RealSystem Administrator, click Security. Click Realm.
In the Authentication Realms area, click Add New.
A generic realm name appears in the Edit Realm Description box.
In the Edit Realm Description box, type a name for this realm.
Click Edit.
In the Realm ID box, type a name. You will use this name in other areas of RealSystem Administrator, so make a name that is meaningful to you. The Realm name may also appear to users as part of the name and password prompt.
In the Authentication Protocol list, select the authentication method you want to use for this realm, based on the descriptions in "Authentication Protocols" earlier in this chapter.
If you choose Basic or RealSystem 5.0, you will also need to select a database in which the names and passwords of authenticated users will be stored. Refer to "Setting Up a Database".

If you choose Windows NT Lan Manager, you do not need to select a database—instead, RealProxy will use the NT list of names. Use the additional steps shown here:
1. Type the appropriate provider in the Provider list, such as NTLM.
2. Type the Group name in the Group box.
Click Apply.

Changing RealSystem 5.0 Authentication Passwords

When you use the RealSystem 5.0 authentication protocol, RealProxy stores all passwords in an encrypted format. Passwords can be entered and changed through RealSystem Administrator. If you want to change the passwords manually, without using RealSystem Administrator, you can use the supplied password command line utility. It is located in the RealProxy Bin directory.

You can also use these instructions as a basis for writing your own CGI scripts and Web pages to accomplish the same purpose automatically.

To use the password tool manually:

At a command line, in the Bin directory, type the following:
```
mkpnpass username realm
```
where:

username is the user name exactly as it is entered or will be entered in the authentication database or text file.

realm is the value of the Realm variable specified in the relevant list.

For RealSystem Administrator users, use the value of the Realm variable in the RealAdministrator_Files list within the FSMount list in the configuration file. (You must open the configuration file itself to see this value.)
A password prompt appears, followed by a prompt to type the password again.
The resulting encrypted password is displayed on the screen.

RealProxy encrypts passwords with the MD5 hashing algorithm. It uses the form MD5("username:realm:new_password"). On BSD systems and some other UNIX systems, you can generate these passwords with the following command:
```
echo -n "username:realm:new_password" | md5
```
Add the resulting encrypted password into the appropriate field of the database:
- For flat text files, place it in the password field of the User directory (see "Users Directory").
- For databases, place it in the password field of the Users table (see "Users Table").

Authentication Data Storage

This section describes the methods for storing user name and password data. The information can be stored in either a series of text files or in a database. Templates for common databases are created during installation, that correspond to the database methods listed in "Setting Up a New Database".

Text file storage—this method uses a combination of directory structure and text files to achieve a sensible data storage method. It is the default method. See "Using Text Files for Authentication Data" for details.
Database templates—the supplied templates use a similar structure to the text file method, in a more familiar database format. Refer to "Using a Database for Authentication Data" for more information.

Using Text Files for Authentication Data

The default configuration uses the text file storage method to provide storage for all the realms.

The following directories contain the text files which store data. The center letter indicates the authentication protocol: r is for RN5, b is for Basic.

Supplied Data Storage Directories
Directory Name	Data Storage for the following type of information
`adm_b_db`	RealSystem Administrator User Authentication
`con_r_db`	Connection Authentication

The contents of the directories are given in the table below.:

Text File Storage Directory Structure
Directory	Contents	File or Directory Description
Main directory (`con_r_db` or `adm_b_db`)	`ppvbasic.txt`	The text file indicates to RealProxy that this is the storage area for the list of authenticated names.
`users`	(initially blank)	Files in this directory list the clips and permission types.
`logs`	`accesslog.txt`	See below for a description.
`redirect`	(initially blank)	For player validation, files contain an URL to which to send the client if redirection is necessary.

When RealProxy creates the file structure, it creates the ppvbasic.txt file. The second and subsequent times you start the RealProxy, the program looks for this file. If the file does not exist, it recreates the directory structure.

Warning
Do not delete the ppvbasic.txt file! If you delete the ppvbasic.txt file, RealProxy will rewrite the directories and will erase their prior content.

	Warning
Do not delete the `ppvbasic.txt` file! If you delete the `ppvbasic.txt` file, RealProxy will rewrite the directories and will erase their prior content.

Users Directory

The files in this directory are named username, where username is the user name. This directory contains one file per registered user.

The first line of each file has the following format:


password;uuid;uuid_writeable

where:


`password`	When user authentication is in use, this stores the password. Otherwise shows an asterisk (*). Note: Passwords are encrypted. To change them manually, see "Changing RealSystem 5.0 Authentication Passwords".
`uuid`	In player validation, stores playerID. In user authentication, an asterisk (*) appears in this field.
`uuid_writeable`	A flag set and used by RealProxy: 0 playerID is in database 1 record created, but playerID is not yet registered

Note
If you manually edit the files, be sure that any blank (or unused) fields use an asterisk (*) as a placeholder. Do not use a space for a placeholder.

	Note
If you manually edit the files, be sure that any blank (or unused) fields use an asterisk (`*`) as a placeholder. Do not use a space for a placeholder.

Logs Directory

This directory contains accesslog.txt, which is not created until authentication is enabled and the first user connects to RealProxy.

Accesslog.txt

Each line of accesslog.txt describes the result of an attempt to view a clip. Syntax of this file:


status;userid;uuid;ip;url;access_type;permission_on;start_time;end_time;total_time;
why_disconnect

where:


`status`	Result of user's attempt to connect: `0` access to clip granted `1` denied
`userid`	Unique name of up to 50 characters.
`uuid`	Stores playerID.
`ip`	IP address from which user is attempting to connect
`url`	Secured clip user is attempted to access.
`permission_type`	Event value.
`permission_on`	Always `0`.
`start_time`	Time/date clip started playing.
`end_time`	Time/date clip stopped playing.
`total_time`	Total time clip played.
`why_disconnect`	Reasons for disconnection: `0` client disconnected voluntarily `1` server access expired

Using a Database for Authentication Data

This section describes the structure of the database templates included with RealProxy.

To set up the database, see "Setting Up Other Types of Data Storage".

The database templates include these tables:

Users table—Lists who is registered and with what access.
Access_log table—Used by this feature.

Users Table

Gives the list of user names and passwords.

Users Table
Field	Description
`userid`	User name of up to 50 characters. Ties to permissions table.
`password`	In user authentication, this stores the password. Otherwise blank. Note: Passwords are encrypted. To change them manually, see "Changing RealSystem 5.0 Authentication Passwords".
`uuid`	In player validation, stores clientID. In user authentication, an asterisk (*) appears in this field.
`uuid_writeable`	A flag set and used by RealProxy: `0` clientID is in the database `1` the record has been created but the clientID is not yet registered with RealProxy.

Access_log Table

Shows which restricted sites have been accessed.

Access_log Table
Field	Description
`status`	Result of user's attempt to connect: `0` access to clip granted `1` denied
`userid`	Unique name of up to 50 characters.
`uuid`	Stores player ID.
`ip`	IP address from which user is attempting to connect.
`url`	Secured clip user is attempted to access.
`permission_type`	Event value.
`permission_on`	This field is always `0`.
`start_time`	Time/date clip started playing.
`end_time`	Time/date clip stopped playing.
`total_time`	Total time clip played.
`why_disconnect`	Reason for disconnection: `0` client disconnected voluntarily `1` server access expired

Setting Up Other Types of Data Storage

Support for two types of databases is included: ODBC and MSQL.

To set up your Windows computer for ODBC compliance:

On the Start menu, point to Settings, and click Control Panel.
Double-click 32bit ODBC.
On the System DSN tab, click Add.
Select your ODBC driver from the list of drivers and click Finish.
In the ODBC SQL Server Setup dialog box, type the data source name. Click Select.
Type or browse for the path to your database file and click OK.
Click OK to exit the ODBC Data Source Administrator.

You must now tell RealProxy where to find your database.

To set up the supplied database application on UNIX:

At a command line, start the database by typing the following:
```
./msql2d &
```
Create the database by typing the following:
```
./msqladmin create databasename
```
Note that whatever you type for databasename will need to match the database cited in the Databases list.
Create the tables using the database text file by typing the following:
```
.msql -h localhost databasename < ppvdemo.db
```
Be sure to include the less-than sign (<).