| Oracle® Access Manager Integration Guide 10g (10.1.4.0.1) Part Number B25347-01 |
|
|
View PDF |
| Oracle® Access Manager Integration Guide 10g (10.1.4.0.1) Part Number B25347-01 |
|
|
View PDF |
Oracle Access Manager supports the ASP.NET component of the Microsoft .NET Framework, which developers can use to build, deploy, and run Web applications and distributed applications.
The Security Connector for ASP.NET supports and enhances native .NET role-based security. This chapter explains how to use the Security Connector for ASP.NET to instantiate a new OblixPrincipal object and populate it with roles (Oracle Access Manager authorization rules) and the native WindowsPrincipal object.
This chapter includes the following topics:
ASP.NET is a set of technologies in the Microsoft .NET Framework that enables the building of Web applications and XML Web services using compilation and caching technologies available in the .NET Framework. Characteristics of ASP.NET pages:
Run on a server and generate markup that is sent to a browser, for example, HTML, WML, or XML
Use a compiled, event-driven programming model that enables the separation of application logic and the user interface
Contain server-side logic, rather than client-side logic, written in Visual Basic .NET, C# .NET, or any .NET-compatible language
Developers can use the .NET Framework class library, which is an object-oriented collection of reusable types, to create ASP.NET applications. Web applications and XML Web services benefit from features of the common language runtime (CLR).
Both ASP.NET and Microsoft Internet Information Services (IIS) provide security models that allow you to authenticate users appropriately and obtain the correct security context within your application.
The user's (or potentially an application's or computer's) identity is referred to as a security principal. The client must provide credentials to allow the server to verify the identity of the principal. After the identity is known, the application can authorize the principal to access protected resources.
WIndows provides a WindowsPrincipal object that defines a user identity and the user's role identity. The role identity is the role or roles defined in Windows for the user identity. Microsoft .NET technology provides an interface to create a Principal object using only Windows-specific roles. ASP.NET applications can call the Windows IPrincipal.IsInRole method to find out if the identity is in a specific role, for example, the admin role or users role.
Security within the ASP.NET Framework revolves around security identifiers (SIDs). SIDs are equal to Oracle Access Manager single sign-on tokens and represent a unique user within the Windows operating system. ASP.NET wraps each SID into a series of managed objects that allow a developer to impersonate that user.
The main object that wraps the SID is the Identity object (IIdentity). This object enables a developer to discover how that identity was established by calling methods to obtain the following:
The authentication method
The name of the identity
The authentication status (authenticated or not)
For more information, consult the Microsoft ASP.NET documentation.
A principal object represents the security context of the user on whose behalf the code is running, including that user's identity (IIdentity) and any roles to which the user belongs. The .NET Framework class library IPrincipal interface defines the basic functionality of a principal object.
|
Note: All principal objects are required to implement the IPrincipal interface. |
During the authorization process, the public IPrincipal.IsInRole method determines whether the current principal belongs to the specified role.
The following IPrincipal.IsInRole method syntax is based on .NET Framework version 1.1 and is intended only as an example:
[Visual Basic]
Function IsInRole( _
ByVal role As String _
) As Boolean
[C#]
bool IsInRole(
string role
);
[C++]
bool IsInRole(
string* role
);
[JScript]
function IsInRole(
role : String
) : Boolean;
true—Returns true if the current principal is a member of the specified role.
false—Returns false otherwise.
To see the supported versions and platforms for this integration, refer to Metalink, as follows.
To view information on Metalink
Go to the following URL:
Click the Certify tab.
Click View Certifications by Product.
Select the Application Server option and click Submit.
Choose Oracle Application Server and click Submit.
This operates on all Windows platforms that support the .NET framework.
Older WebGates are compatible with more current Access Servers. However, older WebGates use a different encryption scheme for the shared secret, as discussed in the Oracle Access Manager Access Administration Guide.
For more information and the most current syntax, see the following Web site:
The Security Connector for ASP.NET:
Provides a dynamically-loaded native library assembly to enhance ASP.NET behavior to take advantage of Oracle Access Manager features
Extends pre-defined Microsoft roles to include dynamic groups and any attribute values defined in an Oracle Access Manager user's profile
For example, Microsoft provides pre-defined roles within a Windows domain. However, Microsoft roles do not include the flexibility of Oracle Access Manager's dynamic groups, timing, and other conditions that can alter a user's access rights.
You can customize your ASP.NET application or Web service to use the Oracle Access Manager assembly during the authorization process. This converts Oracle Access Manager authorization actions into roles using a header variable that maps to roles that are meaningful to the .NET environment.
|
Note: Administrators must plan and coordinate the roles that will be used with the application developer or deployer. Oracle Access Manager does not know what the .NET roles are, and has no way to discover what the roles are. The Oracle Access Manager role and the .NET role are related only through an Oracle Access Manager role string. There is no referential integrity supplied or implied. |
The Security Connector for ASP.NET library assembly, OBPrincipalHTTPModule.dll, is installed with the WebGate in the same directory as the webgate.dll. For example:
\WebGate_install_dir\access\oblix\apps\webgate\bin\ObPrincipalHTTPModule.dll
Because more than one application may share the OBPrincipalHTTPModule assembly, it is included in the global assembly cache (GAC).
The new Oracle Access Manager library assembly runs as an ASP.NET HttpModule. Therefore, you must include details about this assembly in the Web.config file on the same machine and in the same directory as the ASP.NET application.
The ObPrincipalHTTPModule assembly includes a new OblixPrincipal object class and the OblixHttpModule. With this assembly, the ASP.NET application can define and pass an Oracle Access Manager role. Without this assembly, the application can pass only Windows roles.
The OblixHttpModule recognizes Oracle Access Manager roles, and the roles supported with the WindowsPrincipal object. In fact, Oracle Access Manager recognizes any principal object in the .NET framework class library.
The OblixHttpModule must be specified as an action type in the Oracle Access Manager authorization rule that protects the ASP.NET application. See "Setting up the Oracle Access Manager Role Action" for details.
During authorization, the OblixHTTPModule:
Instantiates the new OblixPrincipal object before control is given to the ASP.NET application using the WindowsPrincipal object (or any other type of principal object in the .NET framework class library) that was extracted from the request.
Adds Oracle Access Manager role data (the authorization rule action) to the OblixPrincipal object.
Associates the OblixPrincipal object with the ASP.NET HTTP request.
|
Note: Whenever the application requests the principal object, it receives the OblixPrincipal object, which encapsulates all other principal objects. |
A role is the name of a membership category, for example, admin or user. The OblixPrincipal object represents the security context of the user on whose behalf the code is running. This includes the user's identity (IIdentity) and any roles to which they belong as derived from the Windows IPrincipal interface. The iPrincipal.IsInRole method checks both Oracle Access Manager roles and the iPrincipal interface.
The following high-level overview introduces authorization using the Security Connector for ASP.NET. For a more detailed example, see "Oracle Access Manager Role-Based Authorization".
Process overview: Authorization with the Security Connector for ASP.NET
After the user is authenticated, the WebGate begins the authorization process with the Access Server, as usual.
The IIS Web server creates the WindowsPrincipal object based on Windows Impersonation.
The OblixHttpModule receives the request, instantiates a new OblixPrincipal object using the WindowsPrincipal object, and adds Oracle Access Manager role data based on the Oracle Access Manager authorization rule action.
The OblixPrincipal object initializes itself, then recognizes and stores Oracle Access Manager role data in memory.
The OblixHttpModule associates the OblixPrincipal object with the request and returns control to the IIS Web server.
The ASP application extracts the OblixPrincipal object for the request and calls the IPrincipal.IsInRole method.
The OblixPrincipal object calls the WindowsPrincipal object's IsInRole method from the .NET framework class library to determine whether the current principal belongs to the specified .NET role, checks the Oracle Access Manager role, and returns the answer to the ASP.NET application.
The IPrincipal.IsInRole method returns true or false, depending on the current user's identity and the Oracle Access Manager authorization rule. For a syntax example, see "IPrincipal.IsInRole Method Syntax".
If the answer is false, the Principal object looks in the Oracle Access Manager role list for the requested role and returns the answer to the ASP.NET application. If the answer is true, the ASP.NET application completes processing and access to the resource is granted.
The following task overview explains how to use the Security Connector for ASP.NET.
Task overview: Setting up the Security Connector for ASP.NET
Install a WebGate, as described in "Setting Up Your Environment" .
Set up the application, as described in "Setting Up the ASP.NET Application for the Security Connector".
Configure the Oracle Access Manager role action, as described in "Setting up the Oracle Access Manager Role Action" .
For a process overview, see "Oracle Access Manager Role-Based Authorization".
Before you can use the Security Connector for ASP.NET, you must set up the WebGate on a machine hosting the IIS Web server and the .NET framework with ASP.NET.
You are given the option to include the .NET framework and ASP.NET during IIS Web server installation. This automatically configures the IIS metabase. The ASP.NET application security configuration and the IIS security configuration are independent. Each may be use separately or together.
IIS maintains security related configuration settings in the IIS metabase. ASP.NET maintains security (and other) configuration settings in XML configuration files. For more information, see your Microsoft documentation.
To set up your environment
Install the IIS Web server and the .NET Framework with ASP.NET.
If you are using IIS v6.x, be sure to enable ASP.NET applications. The actions in the next step occur automatically if you install the .NET framework after installing the IIS Web server. If this reflects your installation, skip the next step.
Register ASP.NET and allow the ASP.NET Web Service Extension on the machine that will host the WebGate, if needed.
For example, if you configure aspnet.regiis.exe, you would go to IIS, then local_host, then to Web Service Extensions, then to ASP.NET v1.1.4322, then to Properties, then to Allowed, as illustrated in the following screen shot:
Install the WebGate on a machine that hosts the IIS Web server, the .NET Framework, and ASP.NET.
The WebGate installation will end before completion if the .NET framework is not included on the WebGate host. To share the ObPrincipalHTTPModule assembly among all applications, the assembly is installed as part of the global assembly cache.
When you create the ASP.NET application or Web service using Visual Studio.NET, a generic Web.config file is created automatically. You can modify this file to customize your application to use the ObPrincipalHTTPModule.dll assembly during authorization.
With impersonation enabled, ASP.NET applications can run with the identity of the client on whose behalf they are operating. ASP.NET will receive the token to impersonate from IIS.
|
Note: If you do not enable impersonation in the application and in Oracle Access Manager, Oracle Access Manager roles will not be returned, which encapsulate all roles. However, the permissions may not be all you need. |
To set up the ASP.NET application
Use Visual Studio .NET to write your ASP.NET application or Web service, as described in the Microsoft documentation.
Include the following details in the Web.config file under <System.Web> to use the OblixHttpModule and OBPrincipalHTTPModule.dll.
Be sure to include your own PublicKeyToken. For example:
-->
<httpModules>
<add type="Oblix.Agents.OblixHttpModule,
ObPrincipalHttpModule, Version=7.0.0.0, Culture=neutral,
PublicKeyToken="xxxxxxxxnnnnxxxx" name="OblixHttpModule"/>
</httpModules>
<compilation
defaultLanguage="c#"
debug="true"
/>
|
Note: The value of Culture= is case-sensitive; "neutral" must be lowercase. |
Reference the ObPrincipalHttpModule assembly in your application.
Right-click the project in Visual Studio, select Add Reference, click the Project tab, then browse for and select the global assembly cache.
|
Note: You may also use the /r option if the application is built from the command line. |
You can either reference the iPrincipal object in the application, as described in the following steps, or point to the ACLs in the Web.config file.
Add the iPrincipal references for the required .NET assemblies to the application (or see the sample web.config file).
For example:
using System.Security.Principal; using System.Web.Security;
Add a method to the application that calls the IPrincipal.IsInRole() function with the appropriate parameters for your application.
For example, if the return value of the authorization rule action is Manager, the method would be the following.
Context.User.IsInRole("Manager"); // Context - HTTPContext
object associated with the page
// user - Principal object
The application is now set up to use the Security Connector. Next you must set up the Oracle Access Manager role action.
Actions can pass information about users to other applications in the same, or different, Oracle Access Manager policy domain. Authorization actions occur when a user requests access to a resource (that is, when the user requests the resource's URL).
Before passing roles to the OblixHttpModule, you need to create a role action in the authorization rule for the policy domain that protects the ASP.NET application. This action relies on the OblixHttpModule. Aware Oracle Access Manager clients can use the role action to define roles separate from header variables.
The role is contained in a Principal object. You may have as many roles as you choose. Each role value will be added to the OblixPrincipal object. When calling the IPrincipal.IsInRole method from the .NET Framework class library with any of the Role values, true is returned.
To set up Oracle Access Manager Role Actions
Create a policy domain in the Policy Manager to protect the ASP.NET applications and include an impersonation action.
For more information on policy domain configuration and single sign-on configuration, see the Oracle Access Manager Access Administration Guide.
Select the authorization rule and click the Actions tab to define an action for this authorization rule to pass roles to the OblixHttpModule:
Type: Specify OblixHttpModule. Only a type of OblixHttpModule will be forwarded to the ASP.NET HttpModule.
Name: Supply a role or a name.
You can have as many roles as you choose. Each role value is added to the OblixPrincipal object. When calling the IPrincipal.IsInRole method with any of these values, true is returned.
Only one name may be set. Name exists in the event that IIS does not provide an Identity name, for example, None authentication in the Web.config file. If Windows authentication is set and the WebGate is configured for impersonation, this action is ignored.
Return Value: This can be any static or dynamic value, like any other action.
Save the rule and restart the Access Server to have your changes take effect.
Your environment is set up, the ASP.Net application is complete, and the Oracle Access Manager policy domain protects the application with the new authorization rule.
The following process occurs during authentication and role-based authorization with the Security Connector for ASP.NET. Figure 16-1 illustrates the sequence and is followed by a detailed description.
Process overview: Events during authentication and authorization
The Web server receives the user's ASP URL request. The WebGate intercepts the request and communicates with the Access Server to determine:
If the resource is protected
How the resource is protected
If the user is authenticated
If user access is authorized
Authentication is performed between the Access Server and directory server, as usual.
When the user is authenticated, the WebGate begins the authorization process with the Access Server and:
Sets action headers for roles
Performs Windows Impersonation
Returns control to the IIS Web server
The IIS Web server creates the WindowsPrincipal object based on Windows Impersonation.
The OblixHttpModule:
Receives the request
Instantiates a new OblixPrincipal object using the WindowsPrincipal object that was extracted from the request
Adds Oracle Access Manager role data (the authorization rule action)
The OblixPrincipal object initializes itself and stores Oracle Access Manager role data in memory.
The OblixHttpModule associates the OblixPrincipal object with the request and returns control to the IIS Web server.
The ASP application extracts the OblixPrincipal object for the request and calls the IPrincipal.InIsRole method. The OblixPrincipal object does the following:
Calls the WindowsPrincipal object's IsInRole method
Checks the Oracle Access Manager role
Returns the answer to the ASP.NET application
If the answer is false, the Principal object looks in the Oracle Access Manager role list for the requested role and returns the answer to the ASP.NET application.
The ASP.NET application completes processing and access to the resource is granted.
