Skip Headers
Oracle® Access Manager Integration Guide
10g (10.1.4.2)

Part Number E10356-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

18 Integrating With ASP.NET

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:

18.1 About ASP.NET

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:

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).

18.2 Security Principals and Security Identifiers (SIDs)

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:

For more information, consult the Microsoft ASP.NET documentation.

18.3 IPrincipal.IsInRole Method Syntax

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;

18.3.1 Parameters

role

The name of the role for which to check membership.

18.3.2 Return value

true—Returns true if the current principal is a member of the specified role.

false—Returns false otherwise.

18.3.3 Supported Versions and Platforms

You can find support and certification information at the following URL:

http://www.oracle.com/technology/documentation/

You must register with OTN to view this information.

Also, you can see the supported versions and platforms for this integration on Metalink, as follows.

To view information on Metalink

  1. In your browser, enter the following URL:

    https://metalink.oracle.com

  2. Log in to MetaLink.

  3. Click the Certify tab.

  4. Click View Certifications by Product.

  5. Select the Application Server option and click Submit.

  6. Choose Oracle Identity Management and click Submit.

  7. Click Oracle Identity Management Certification Information 10g (10.1.4.0.1) (html) to display the Oracle Identity Management page.

  8. Click the link for Section 6, Oracle Access Manager Certification to display the certification matrix.

18.3.4 Requirements

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 System Administration Guide.

For more information and the most current syntax, see the following Web site:

http://msdn.microsoft.com/developercenters/

18.4 About the Security Connector for ASP.NET

The Security Connector for ASP.NET:

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.

18.5 Oracle Access Manager Components and Requirements

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.

18.6 The OblixHttpModule

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:

Note:

Whenever the application requests the principal object, it receives the OblixPrincipal object, which encapsulates all other principal objects.

18.6.1 The OblixPrincipal Object

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.

18.7 Authorization with the Security Connector for ASP.NET

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

  1. After the user is authenticated, the WebGate begins the authorization process with the Access Server, as usual.

  2. The IIS Web server creates the WindowsPrincipal object based on Windows Impersonation.

  3. 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.

  4. The OblixPrincipal object initializes itself, then recognizes and stores Oracle Access Manager role data in memory.

  5. The OblixHttpModule associates the OblixPrincipal object with the request and returns control to the IIS Web server.

  6. The ASP application extracts the OblixPrincipal object for the request and calls the IPrincipal.IsInRole method.

  7. 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.

  8. 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.

18.8 Using the Security Connector for ASP.NET

The following task overview explains how to use the Security Connector for ASP.NET.

Task overview: Setting up the Security Connector for ASP.NET

  1. Install a WebGate, as described in "Setting Up Your Environment" .

  2. Set up the application, as described in "Setting Up the ASP.NET Application for the Security Connector".

  3. 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".

18.8.1 Setting Up Your Environment

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

  1. 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.

  2. 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:

    Sample page showing an allowed setting.
  3. 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.

18.9 Setting Up the ASP.NET Application for the Security Connector

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

  1. Use Visual Studio .NET to write your ASP.NET application or Web service, as described in the Microsoft documentation.

  2. 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.
  3. 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.
    Image of referencing the assembly.

    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.

  4. 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;
    
  5. 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.

18.9.1 Setting 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

  1. 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 System Administration Guide.

  2. 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.

  3. 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.

18.10 Oracle Access Manager Role-Based Authorization

The following process occurs during authentication and role-based authorization with the Security Connector for ASP.NET. Figure 18-1 illustrates the sequence and is followed by a detailed description.

Figure 18-1 Security Connector for ASP.NET Authorization Flow

Process diagram. A text version follows this graphic.

Process overview: Events during authentication and authorization

  1. 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.

  2. When the user is authenticated, the WebGate begins the authorization process with the Access Server and:

    1. Sets action headers for roles

    2. Performs Windows Impersonation

    3. Returns control to the IIS Web server

  3. The IIS Web server creates the WindowsPrincipal object based on Windows Impersonation.

  4. The OblixHttpModule:

    1. Receives the request

    2. Instantiates a new OblixPrincipal object using the WindowsPrincipal object that was extracted from the request

    3. Adds Oracle Access Manager role data (the authorization rule action)

  5. The OblixPrincipal object initializes itself and stores Oracle Access Manager role data in memory.

  6. The OblixHttpModule associates the OblixPrincipal object with the request and returns control to the IIS Web server.

  7. The ASP application extracts the OblixPrincipal object for the request and calls the IPrincipal.InIsRole method. The OblixPrincipal object does the following:

    1. Calls the WindowsPrincipal object's IsInRole method

    2. Checks the Oracle Access Manager role

    3. 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.

  8. The ASP.NET application completes processing and access to the resource is granted.