| Oracle® Access Manager Developer Guide 10g (10.1.4.3) E12491-01 |
|
 Previous |
 Next |
| Oracle® Access Manager Developer Guide 10g (10.1.4.3) E12491-01 |
|
Previous |
Next |
The Access Manager Software Developer's Kit (SDK) enables you to enhance the access management capabilities of the Access System. This SDK enables you to create a specialized AccessGate. Its use is optional. For that reason, the installation instructions are provided here, rather than in the Oracle Access Manager Installation Guide.
This appendix includes:
To create one or more custom AccessGates, you must install an instance of the Access Manager SDK on each server that hosts an AccessGate. You can install both UNIX-based and Windows-based AccessGates within the same deployment as long as each instance of the Access Manager SDK matches the type of server on which it is installed. The Access Manager SDK is not part of the Access Server installation package.
|
Note: If your Access System uses WebGates exclusively, you do not need to install the Access Manager SDK, because each self-contained WebGate installation package already contains all the specific resources it needs. |
The Access Manager SDK creates an environment for you to build a dynamic link library or a shared object to perform as an AccessGate. You need the documentation, supporting files, and runtime library provided with the SDK package. You also need the configureAccessGate tool to verify that your client works correctly.
Once an AccessGate is built, you can move it to any computer that can reach the system where an Access Server is installed. Once moved, the AccessGate needs to be able to find its runtime library. You need to have the configureAccessGate.exe tool to configure the AccessGate to connect to the Access server. The simplest way to have both the runtime library and the tool in the correct location is to install the SDK on the computer where the AccessGate is going to run.
|
Note: You can create an AccessGate using a hard-coded installation directory. If you move this AccessGate to a different computer, it must provide a matching directory structure. Otherwise, the AccessGate will not find its configuration file or the runtime library; an error will be generated and the AccessGate will stop. |
Oracle Access Manager 10g (10.1.4.3) provides two software developer kits (SDKs) for Windows platforms. For more information, see:
As in earlier releases, Oracle Access Manager 10g (10.1.4.3) provides an SDK for Windows that supports .NET Framework 1.1 and Microsoft Visual Studio 2002. The following full installer is available on Oracle Technology Network:
Oracle_Access_Manager10_1_4_3_0_Win32_AccessServerSDK.exe
Some time after the initial release, the following 10g (10.1.4.3) patch will be available on My Oracle Support (formerly MetaLink), which can be applied to a 10g (10.1.4.2.0) .NET 1 SDK instance:
Oracle_Access_Manager10_1_4_3_0_Patch_win32_AccessServerSDK.zip
|
See Also: The Readme that accompanies the patch |
A new SDK for Windows is available for AccessGate development with Oracle Access Manager 10g (10.1.4.3). This new SDK:
Provides .NET 2 support (and only .NET 2 support)
Uses Microsoft Development Environment (MSDE) 2005, including NET Framework 2 and MSDE Visual Studio 2005
Can be obtained from Oracle Technology Network and added to any 10g (10.1.4.3) environment (new installation or upgraded and patched)
Does not provide backward compatibility with earlier custom AccessGates compiled with .NET 1.1
The following installer is available on Oracle Technology Network for a fresh installation of the .NET 2 SDK:
Oracle_Access_Manager10_1_4_3_0_Win32-dotnet20_AccessServerSDK.exe
There is no 10g (10.1.4.3) patch for the .NET 2 SDK because this is a new package. However, in an upgraded environment, you can:
Retain and patch the .NET 1 SDK and use this only.
Retain and patch the .NET 1 SDK and then install the .NET 2 SDK.
In this case, both environments will work simultaneously.
Remove the .NET 1 SDK and install only the .NET 2 SDK.
In this case, you must uninstall the earlier .NET 1 SDK, add the 10g (10.1.4.3) patch to the deployment, install the new .NET 2 SDK, and recompile earlier AccessGates for .NET 2 as described in the Oracle Access Manager Upgrade Guide.
The Oracle Access Manager 10g (10.1.4.2.0) SDK supports .NET Framework 1.1 and Microsoft Visual Studio 2002 only. Oracle Access Manager 10g (10.1.4.2.0) packages are required for patching 10g (10.1.4.0.1) instances, and also for zero downtime upgrades. 10g (10.1.4.2.0) is a patch set and packages are available on My Oracle Support (formerly MetaLink). For details, see "Obtaining Packages for Upgrades" in the Oracle Access Manager Upgrade Guide.
After upgrading, you can apply the 10g (10.1.4.3) patch set, which will be available on My Oracle Support (formerly MetaLink) some time after the initial 10g (10.1.4.3) release. For more information, see "Obtaining the Latest Patch Set" in the Oracle Access Manager Installation Guide.
You can add .NET 2 support for custom AccessGates to an upgraded environment that includes the 10g (10.1.4.3) patch set. as described in "Adding the .NET 2 SDK to an Upgraded and Patched Environment".
The Oracle Access Manager 10g (10.1.4.0.1) SDK supports .NET Framework 1.1 and Microsoft Visual Studio 2002 only. 10g (10.1.4.0.1) installers are required for upgrading an earlier deployment (using either the in-place upgrade method or the zero downtime upgrade method). 10g (10.1.4.0.1) packages are available on the Oracle Technology Network, as described in "Obtaining Packages for Upgrades" in the Oracle Access Manager Upgrade Guide.
After upgrading, you can apply the 10g (10.1.4.2.0) patch set and then apply the 10g (10.1.4.3) patch set. Patch sets are available on My Oracle Support (formerly MetaLink) as described in "Obtaining the Latest Patch Set" in the Oracle Access Manager Installation Guide.
You can add .NET 2 support for custom AccessGates to an upgraded environment that includes the 10g (10.1.4.3) patch set. as described in "Adding the .NET 2 SDK to an Upgraded and Patched Environment".
Before installing an SDK, at least one instance of the Identity Server, WebPass, Policy Manager, and Access Server must be installed and running. The SDK can be installed anywhere; there is no fixed relationship to the Access System or Identity System files.
For the latest support details, go to Oracle Technology Network as described in the following procedure.
To locate the latest support details and obtain the SDK
Confirm platform requirements on OTN:
http://www.oracle.com/technology/products/id_mgmt/coreid_acc/pdf/oracle_access_manager_certification_10.1.4_r3_matrix.xls
Obtain the 10g (10.1.4.3) SDK installer from the Oracle Access Manager core server virtual media on OTN at:
http://www.oracle.com/technology/software/products/ias/htdocs/idm_11g.html
.NET: Confirm that the appropriate version of the .NET Framework is installed on the computer that will host the SDK you plan to use (.NET 1 SDK or .NET 2 SDK):
In the Internet Explorer address field, enter the following and review .NET details in the pop-up that appears:
javascript:alert(navigator.userAgent)
Open Windows Registry, browse to the following and view the list of all available .NET versions on the host.
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup\NDP\
The Access Manager SDK for Windows includes the .NET API. You can use the following procedure to install the 10g (10.1.4.3) SDK.
To install the Access Manager SDK on Windows
Perform prerequisite activities as described in "Software Developer Kit Installation Prerequisites".
Confirm that you have at least one instance of the 10g (10.1.4.3) Identity Server, WebPass, Policy Manager, and Access Server running.
Step 3 is needed to confirm you have the correct version of the .NET Framework installed for the SDK you plan to use. If this was confirmed during the previous procedure, you can skip Step 3.
.NET: Confirm that the appropriate version of the .NET Framework is installed on the computer that will host the SDK you plan to use (.NET 1 SDK or .NET 2 SDK):
In the Internet Explorer address field, enter the following and review .NET details in the pop-up that appears:
javascript:alert(navigator.userAgent)
Open Windows Registry, browse to the following and view the list of all available .NET versions on the host.
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup\NDP\
Locate and launch the Access Manager SDK installer from the temporary directory you created (or the Oracle Access Manager installation media). For example:
Oracle_Access_Manager10_1_4_3_0_win32_AccessServerSDK.exe
or
Oracle_Access_Manager10_1_4_3_0_Win32-dotnet20_AccessServerSDK.exe
Installation files are extracted, and the Welcome Screen appears. Confirm at the top of the screen that you have in fact selected Access Manager SDK installation.
Click Next to dismiss the Welcome screen.
The Customer Information screen appears.
Enter a user name and company name of your choice, then click Next.
When the license agreement appears, decide whether to proceed by checking the box "I accept the terms of the license agreement."
The next screen emphasizes that you must have administrator privileges on the host computer where you are installing the SDK.
If your current account has administrator rights, click Next. Otherwise:
Click Cancel to close the installation wizard.
Log out of the system.
Log back on using an administrator account.
Restart the Access Manager SDK installation.
Accept the default installation directory or select an alternate location, then click Next.
You are reminded to note the installation location. This information is important to the operation of the API that will be built using the SDK.
Click OK on the reminder.
The Start Copying Files screen appears, giving you a chance to review the Installation directory and User Information (Customer Information) settings you have selected.
When a screen appears to announce the target installation directory, check to make sure that it shows the exact location you want.
Make a not of the path and click Next to continue.
The program files are copied to the directory you selected.
Click Finish to exit the installation process (and optionally view the README file).
Windows 2003 64-bit Platform:
Compile the C and C++ programs using Microsoft Visual STudio 2002 on a 32-bit computer.
Compile Java on a on a 32-bit computer using jdk 1.4 or later.
Copy all samples to the 64-bit computer and execute them.
Repeat these steps as needed to install another SDK instance.
Proceed to Chapter 4, "Building AccessGates with the Access Manager SDK".
This section applies to UNIX systems, including Linux.
You cannot install components in any directory that contains special characters in its path. Special characters are: blank spaces, new lines, *, [], {}, and so on. For more information, see the Oracle Access Manager Installation Guide.
|
Note: This procedure assumes that your UNIX computer supports GUI-mode. You can also run the installation package in interactive command-line mode by entering the following:
run ./installationPackage
where installationPackage is the name of the Access Manager SDK installer. |
To install the Access Manager SDK on a UNIX system
Perform prerequisite activities as described in "Software Developer Kit Installation Prerequisites".
Confirm that you have at least one instance of the 10g (10.1.4.3) Identity Server, WebPass, Policy Manager, and Access Server running.
Obtain the 10g (10.1.4.3) SDK installer from the core server virtual media on OTN at:
http://www.oracle.com/technology/software/products/ias/htdocs/idm_11g.html
Locate and launch the Access Manager SDK installer from the temporary directory you created (or the Oracle Access Manager installation media). For example:
Oracle_Access_Manager10_1_4_3_0_sparc-s2_AccessServerSDK
Installation files are extracted, and the Welcome Screen appears. Another screen appears, advising you that the Access Manager SDK is about to be installed for the owner and group running the installation script, and telling you to exit the script if this ownership is not correct. If the suggested ownership is not correct, type no to exit the installation process.
When the Welcome screen appears, click next.
When the license agreement appears, decide whether to proceed by checking the box "I accept the terms of the license agreement."
When the installer asks for a user and group to set as the owner of the installed files, you may find it convenient to specify the same user and group that "own" the server application your AccessGate will protect. In any case, you must be logged on as the user you specify, or as "root," in order to continue installation.
Accept the default install directory by hitting Return, or type your preference, then hit return.
|
Note: You cannot install Oracle Access Manager components in any directory that contains special characters in its path. The proscribed characters are: blank spaces, new lines, *, [], {}, and so on. |
If the directory does not exist, the installer creates it.
Another screen appears, stating that the Access Manager SDK is being installed in the directory you specified., and monitoring the progress of the installation.
When a screen appears to announce the target installation directory, ensure that it shows the exact location you want. If the directory does not exist, the installer creates it. Make a note of this path, because you will need it later.
Click next to commence file installation.
Respond to the on-screen prompts, as necessary.
Wait for the installation to finish.
Repeat these steps as needed to install another SDK.
Proceed to Chapter 4, "Building AccessGates with the Access Manager SDK".
This section describes the option to use the Native POSIX Thread Library (NPTL), rather than LinuxThreads. Installing the SDK on Linux is similar to installing on UNIX and steps are not repeated here.
Earlier releases of Oracle Access Manager for Linux used the LinuxThreads library only. Using LinuxThreads required that you manually set the environment variable LD_ASSUME_KERNEL, which is used by the dynamic linker to decide what implementation of libraries is used. When you set LD_ASSUME_KERNEL to 2.4.19 the libraries in /lib/i686 are used dynamically.
Red Hat Linux v5 and later releases support only Native POSIX Thread Library (NPTL), not LinuxThreads. To accommodate this change, Oracle Access Manager 10g (10.1.4.3) is now compliant with NPTL specifications. However, LinuxThreads is used by default.
To support the default, the start_ois_server and start_access_server will start in LinuxThreads mode. In this case, the variable LD_ASSUME_KERNEL is automatically set to 2.4.19. The message "Using Linux Threading Library." appears in the console and in the server's oblog file.
|
Note: On Linux, Oracle Access Manager Web components for Oracle HTTP Server 11g use only NPTL; you cannot use the LinuxThreads library. In this case, do not set the environment variable LD_ASSUME_KERNEL to 2.4.19. |
To use NPTL, you must start the server with the start_ois_server_nptl or start_access_server_nptl scripts (or restart servers using restart_ois_server_nptl or restart_access_server_nptl). In this case, the message "Using NPTL Threading Library." appears in the console and in the server's oblog file.
When you use NPTL with Oracle Access Manager, there is no impact on custom plug-ins and APIs that you have created for Oracle Access Manager. When upgrading, you must still recompile custom plug-ins from Oracle Access Manager release 6.x using the GCC v3.3.2 C++ compiler. With NPTL, there is no requirement to set the environment variable LD_ASSUME_KERNEL to 2.4.19 when installing Web components or third-party connectors for use with Oracle Access Manager.
|
Note: Standard stop scripts and the following standard setup scripts will operate successfully whether you use LinuxThreads or NPTL: start_setup_ois, start_setup_webpass, start_setup_access_manager, start_configureAAAServer, stop_snmp_agent, start_configureWebGate, and start_configureAccessGate. |
|
See Also: The chapter on preparing for installation and the section on NPTL requirements and post-installation tasks in the Troubleshooting chapter of the Oracle Access Manager Installation Guide |
You can add the .NET 2 SDK to an upgraded and patched environment by performing the following tasks.
Task overview: Adding the .NET 2 SDK when upgrading
Confirm .NET 2 Support:
In the Internet Explorer address field, enter the following and review .NET details in the pop-up that appears:
javascript:alert(navigator.userAgent)
Open Windows Registry, browse to the following and view the list of all available .NET versions on the host.
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup\NDP\
|
Note: If needed, install the .NET 2 Framework on the computer to host the .NET 2 SDK. |
Before upgrading, uninstall the .NET 1 SDK in the earlier environment if desired. Otherwise, upgrade the .NET 1 SDK with earlier components as described in Step 3.
Upgrade an Earlier Installation: Use one of the following methods as described in Oracle Access Manager Upgrade Guide:
Use 10g (10.1.4.0.1) packages to perform an in-place component upgrade.
Use 10g (10.1.4.2.0) utilities for a zero downtime upgrade.
Get and apply the latest patches from My Oracle Support (formerly MetaLink), as described in the Oracle Access Manager Installation Guide:
10g (10.1.4.2.0) patch set if needed
10g (10.1.4.3) patch set
Obtain and install the .NET 2 SDK as described in "Installing the Access Manager SDK on Windows".
Redesign and recompile custom AccessGates for .NET 2 support, as described in the Oracle Access Manager Upgrade Guide.
