previous next

Chapter 19: Authentication

RealServer can store an encrypted password file for verifying usernames and passwords supplied by users. It can thereby validate file requests or any other operation requiring authentication parameters. When communicating through RTSP, RealSystem can transmit passwords securely over the network. This section discusses supported authorization types and explains how to add authentication functionality to a RealSystem plug-in.

Additional Information
You also need to set RealServer's authentication parameters as described in "Authentication Parameters". See "Handling Password Authentication" for information on how the RealSystem client gathers a username and password from the user.

Definitions

Authentication Manager
The object that gathers a username and password from the user. This is typically the RealSystem top-level client.

Authentication Request Object
The object with access to the username/password values to be authenticated. It provides these values to the authenticator object on request.

Authentication Response Object
The object that receives notice that the authentication succeeded or failed. When the validation succeeds, the response object carries out the action, such as file access, that was originally requested.

Authenticator Object
An object instantiated by RealServer that performs authentication by comparing a username/password combination against RealServer's encrypted password file.

Interfaces

RealSystem authentication involves the following interfaces:

Implementing Authentication

Any plug-in that needs to perform password authorization can compare username/password values sent in by a user against those stored in RealServer's encrypted password file. As the following examples illustrate, RealSystem's structure of authenticator object, authentication request object, and authentication response object provides a flexible means of implementing authentication under different circumstances.

Example 1: File System Plug-In

The most common use of authentication is a file system plug-in that performs password validation for a file requested by a RealSystem client. This process works as follows:

  1. RealServer accepts a client connection through HTTP or RTSP and creates an authenticator object with IRMACommonClassFactory. It identifies itself as the authentication request object by calling IRMAAuthenticator::InitAuthenticator.

  2. The client requests a password-protected file.

  3. To serve the request, RealServer instantiates a file system plug-in that in turn creates a file object with access to the file data.

    Additional Information
    See "Chapter 7: File System Plug-In".

  4. RealServer calls IRMAFileAuthenticator::SetAuthenticator on the file object to associate it with the IRMAAuthenticator interface.

  5. During initialization (or whenever appropriate), the file object calls IRMAAuthenticator::Authenticate, identifying itself as the response object that implements IRMAAuthenticatorResponse.

    Optionally, the IRMAAuthenticator::Authenticate call can include a pointer to an IRMAValues interface that contains a value for AuthType. A value of 1 instructs RealServer to use basic authorization for an HTTP connection. A value of 2 tells it to use DIGEST authorization (which is always used on an RTSP connection). If this information is not included, RealServer determines the authorization type as described below.

  6. The authenticator object calls IRMAAuthenticatorRequest:::GetAuthValues to get from the authentication request object (RealServer) the username and password to be authenticated. This method passes along the IRMAValues interface that sets the authorization type.

  7. The authentication request object (RealServer) retrieves the username/password sent from the client by the appropriate means, such as an RTSP authorization header. If the authenticator object did not specify the authorization type, RealServer looks at its HTTPAuthType variable to determine whether to use basic or DIGEST authorization for an HTTP connection. It always uses DIGEST authorization for an RTSP connection.

    Additional Information
    See "Authentication Parameters".

    The authentication request object calls IRMAAuthenticator::AuthValuesReady to pass the authenticator object a pointer to an IRMAValues interface that contains the Username and Password values to be authenticated. The values interface also contains the AuthType value.

    Additional Information
    See "Handling Password Authentication" for information on how the client gathers passwords.

  8. The authenticator object verifies the retrieved username/password against the password file, calling IRMAAuthenticatorResponse::AuthenticateDone to pass the file object a status code of PNR_OK or PNR_NOT_AUTHORIZED. The call includes a pointer to an IRMAValues interface that contains Username and Password.

    Additional Information
    See "Status Codes".

  9. The file object then takes the appropriate action. If authorization succeeds, it returns PNR_OK through IRMAFileResponse::InitDone. If authorization fails, it passes along PNR_NOT_AUTHORIZED.

    Because it has access to the username and password in the IRMAValues interface it receives, the file object can perform its own authorization checking to narrow the scope of valid users.

    Suppose that users Blakes7 and RedDwarf are validated by RealServer's password file, but only Blakes7 should have access to files served by this file system plug-in. The plug-in can implement its own user list that its file object accesses after a successful system validation. This prevents RedDwarf from accessing the file even though RealServer's authenticator object returned PNR_OK.

Example 2: Monitor Plug-In

RealSystem can perform password authorization on actions other than file requests. A monitor plug-in, for example, may validate passwords when a client connects to RealServer. In this example, the monitor plug-in implements both IRMAAuthenticatorRequest and IRMAAuthenticatorResponse, supplying the values to be authenticated and receiving the authentication results:

  1. The monitor plug-in is instantiated on RealServer and uses Network Services to listen for connections on a specific port or ports.

    Additional Information
    See "Chapter 14: Network Services".

  2. A client connects to a monitored port and requests RealServer information.

  3. The plug-in requests authorization identification.

  4. The client sends a username and password to the monitor plug-in.

  5. The plug-in puts the values in an IRMAValues interface under Username and Password.

  6. The plug-in uses IRMACommonClassFactory to instantiate an authenticator object.

  7. The plug-in calls IRMAAuthenticator::InitAuthenticator to identify itself as the authentication request object.

  8. The plug-in calls IRMAAuthenticator::Authenticate, identifying itself as the authentication response object.

  9. The authenticator object calls IRMAAuthenticatorRequest:::GetAuthValues to get from the plug-in the username and password to be authenticated.

  10. The plug-in calls IRMAAuthenticator::AuthValuesReady to pass the authenticator object a pointer to the IRMAValues interface that contains the Username and Password values.

  11. The authenticator object verifies the username/password against the password file, calling IRMAAuthenticatorResponse::AuthenticateDone to pass the plug-in a status code of PNR_OK or PNR_NOT_AUTHORIZED.

    Additional Information
    See "Status Codes".

Authorization Types

RealSystem supports two authorization types:

RTSP communication between RealServer and the client uses DIGEST authorization. The RealServer configuration parameter HTTPAuthType determines whether HTTP communication between RealServer and a client uses basic or DIGEST authentication.

Additional Information
See "Authentication Parameters".

Updating the Password File

The mkpnpass program adds username and password combinations to the RealServer password file, which is defined by the RealServer configuration file. Windows and UNIX executables are provided in the utilities directory of the SDK. You can invoke mkpnpass from a CGI script or run it from the command line with the following syntax:


% mkpnpass <username> <realm> 

The realm is a required parameter. It is used with DIGEST authorization and is also specified in the RealServer configuration file. After you specify the username and realm, the program prompts you to enter and then confirm the password. The username and password combination work for either basic or DIGEST authorization.

Modifying the Authentication Sample Code

The RealSystem SDK includes a sample authentication plug-in in /samples/intermed/exauth/exauth.cpp. This plug-in implements a simple authentication protocol as described in the HTTP/1.1 standard (rfc2068). Follow the instructions in the source file to test the sample or use it as the basis for your own plug-in.


Copyright © 2000 RealNetworks
For technical support, please contact supportsdk@real.com.
This file last updated on 05/17/00 at 12:50:24.
previous next