ActivID AAA Web Authentication API ASP.NET Functions
The WAA API ASP.NET environment provides:
- General Purpose Services
- Session Management Services
- Authentication Services
- RADIUS Attributes Management Services
Summary
General Purpose Services
| Function | Description |
|---|---|
|
Initializes the components in order to be able to call the services. |
|
|
Stores the specified string into a trace file configured during installation. |
Session Management Services
| Function | Description |
|---|---|
|
Terminates the given session. |
Authentication Services
| Function | Description |
|---|---|
|
Retrieves challenge value from AAA Server. |
|
|
Submits an authentication request on the AAA Server using the given UserID and password. |
|
|
Checks whether the User ID was already authenticated during the session. |
|
|
Returns the authenticated user name. |
RADIUS Attributes Management Services
| Function | Description |
|---|---|
|
Retrieves the specified RADIUS attribute string value. |
|
|
Retrieves the specified RADIUS attribute integer value. |
|
|
Retrieves the specified RADIUS attribute from the AAA Server. The value is protected. |
General Purpose Services
Initialize
Initializes the component. Call this function immediately after instantiation, typically in Application_OnStart() in global.asa. See global.asa: ASP.NET’s provided code sample.
Syntax
void Initialize();
Trace
Outputs the specified string to WAA’s trace file, if tracing is enabled.
Syntax
void Trace(BSTR Trace);
Parameters
Trace
String to be output to WAA’s trace file.
Session Management Services
KillSessionX
Immediately terminate the session. The end of session accounting is immediately sent to the AAA Server.
Syntax
void KillSessionX(BSTR SessionID);
Parameters
SessionID
ASP’s built-in session object.
Authentication Services
SetSessionChallengeX
Receives a challenge from the AAA Server, stores the challenge in the session, and also returns the challenge. This is used for challenge/response method for user authentication.
Syntax
BSTR SetSessionChallengeX(BSTR SessionID);
Parameters
SessionID
ASP’s built-in session object.
Returns
The challenge as a string.
Example
Challenge = ActivPackWAA.SetSessionChallengeX(Session(“UserID”);
Response.status = “401”;
Response.Addheader(“WWW-Authenticate”, “BASIC realm=Challenge: " + Challenge);
Response.end();
AuthenticateX
Authenticates a user with the AAA Server specified in the website configuration. The credentials used for the authentication depend on the parameters supplied:
If the UserName and Password parameters are empty strings, then the component extracts the credential from the HTTP header HTTP_AUTHORIZATION from the Request object. This is typically used when authenticating a response from a client after previously returning a 401 status header. If the HTTP_AUTHORIZATION header is not present, authentication fails.
If UserName and Password are not empty, then the component uses these as credentials for the authentication. This is typically used after gaining user credentials from an HTML form.
If the SetSessionChallenge service was called for the given session prior to Authenticate, then authentication is performed using the challenge, otherwise, a synchronous authentication is executed.
If the session has already been authenticated AND the credentials match those used for the authentication by the AAA Server for the given session, then the AAA Server is not queried again.
If the session is authenticated (whether or not the AAA Server has been queried), AuthenticateX performs the following tasks:
Sets ASP’s Session object’s time-out value to the time-out value stored in the configuration file for the given site.
Performs the accounting for the Author-Acct-URL-Keywd, Author-Acct-URL-Head-Keywd, and Author-Acct-URL-Params-Keywd as described in ActivID Web Access Agent for IIS Installation Guide. The accounting is sent immediately to the AAA Server configured for the given site. The URL visited is extracted from the supplied ASP’s built-in Request object. This requires an Accounting profile configuration in the AAA Server.
Syntax
long AuthenticateX(
BSTR SessionID,
BSTR UserName,
BSTR Password);
Parameters
SessionID
ASP’s built-in session object.
UserName
A user name; can be empty (see the description section).
Password
The user name’s password; can be empty (see the description section).
Returns
Non-zero for successful authentication; 0 for authentication failure.
IsAuthenticatedX
Checks whether the specified session is already authenticated.
If the session is authenticated, IsAuthenticatedX:
Updates the session’s time last use for idle time-out monitoring.
Performs the accounting for the Author-Acct-URL-Keywd, Author-Acct-URL-Head-Keywd, Author-Acct-URL-Params-Keywd and Author-Acct-Page-Out-Keywd as described in ActivID Web Access Agent for IIS Installation Guide. The accounting is sent immediately to the AAA Server configured for the given site. The URL visited is extracted from the supplied ASP’s built-in Request object.
Syntax
long IsAuthenticated(BSTR SessionID);
Parameters
SessionID
ASP’s built-in session object.
Returns
Non-zero if the session is authenticated; 0 if it has not already been authenticated.
GetUserNameX
This service returns the authenticated’s User ID associated with the present session.
Syntax
BSTR GetUserName(IUnknown* Session, IUnknown* Request);
Parameters
Session
ASP’s built-in session object.
Request
ASP’s built-in request object.
Returns
The user’s name, if authenticated.
RADIUS Attributes Management Services
GetAttributeStringX
Returns the application/user parameter value RADIUS attribute. It returns a RADIUS attribute string from a session.
In the RADIUS dictionary, the attribute is represented as a string. For example,
ATTRIBUTE Web-Default-Page 105 string
Syntax
BSTR GetAttributeStringX(BSTR SessionID, BSTR AttribNumber);
Parameters
SessionID
ASP’s built-in session object.
AttribNumber
String representation of the number of the attribute whose value is to be returned.
Returns
The attribute value; an empty string if the attribute is not present.
GetAttributeIntX
Returns the application/user parameter value RADIUS attribute. It returns a RADIUS attribute string from a session.
In the RADIUS dictionary, the attribute is represented as an integer. For example,
ATTRIBUTE Author-Acct-Elapsed-Time 117 integer
Syntax
long GetAttributeIntX(BSTR SessionID, BSTR AttribNumber);
Parameters
SessionID
ASP’s built-in session object.
AttribNumber
String representation of the number of the attribute whose value is to be returned.
Returns
The attribute value; zero if the attribute is not present.
GetCipheredAttributeX
Returns the specified RADIUS attribute from a session. The attribute is decrypted using the 3DES algorithm using the given secret as a key. The secret key is configured during the Web Access Agent installation and configuration.
BSTR GetCipheredAttributeX(BSTR SessionID, BSTR AttribNumber);
Parameters
SessionID
ASP’s built-in session object.
AttribNumber
String representation of the number of the attribute whose value is to be returned.
Returns
The attribute value; an empty string if the attribute is not present.
