|Oracle® Access Manager Integration Guide
Part Number B25347-01
The following discussions explain how to implement Smart Card authentication:
Smart Card provides a stronger form of authentication than a username and password alone because it is based on something the user knows and something the user has.
Something the User Knows: This is the user's secret personal identification number (PIN), similar in concept to a personal bank code PIN.
Something the User Has: This is the cryptographically-based identification and proof-of-possession generated by the Smart Card device that you insert into the Smart Card reader attached to a computer.
Smart Card authentication can be used with Oracle Access Manager to protect resources. After setting up your environment, Smart Card authentication is triggered when you:
Insert your ActivCard containing a public key certificate previously issued by the Enterprise Certification Authority (CA) into the reader attached to your computer.
Request access to a resource protected by the Oracle Access Manager Client_Certificate authentication scheme before inserting your ActivCard into the reader.
The first method displays a window prompting you for your PIN, rather than requesting a username, password, and domain. The second method displays a window prompting you to insert the ActivCard and provide your PIN.
Note:When you initialize a Smart Card, you are asked to supply a PIN. If the PIN is incorrectly entered three times, the card locks. To restore a locked certificate, either use the unlock code provided during Smart Card initialization or re-initialize the card.
The Identity System provides the applications you need to manage users, groups, organizations, identity-based workflows, and delegated administration.
The Access System provides policy-based authentication, authorization, auditing, and Web single sign-on. All Access System components are involved with Smart Card authentication, as discussed next:
The Policy Manager: The Policy Manager provides the applications for policy management, resource designation (Web and non-Web) and policy testing. Master Access Administrators define policy domains and Delegated Access Administrators define the resources to be protected by a policy domain.
When you set up the Policy Manager after installation, you are asked if you want to automatically configure the Client Certificate authentication scheme. This scheme is required for Smart Card authentication. Typically, a certificate must be installed on your browser and the Web server must have SSL enabled. For Smart Card authentication, however, the certificate resides on the card.
If the Client Certificate authentication scheme was configured automatically during setup, it may be used without further modification.
The Access System Console: Master Administrators and Master Access Administrators use the Access System Console to define and enable authentication schemes that allow or deny access to resources.
You can use the Access System Console to verify and/or modify the Client Certificate authentication scheme. However, if the Client Certificate authentication scheme was configured automatically during setup, it may be used without further modification.
The Access Server: The Access Server receives requests from a WebGate and queries authentication, authorization, and auditing rules stored in the directory server. The Access Server returns the authentication scheme, user credentials, and authorization to the requesting WebGate.
The Access Server installation includes the cert_decode and credential_mapping authentication plug-ins required with the Client Certificate scheme for Smart Card authentication.
The WebGate(s): WebGates intercept and forward HTTP requests for Web resources to the Access Server for authentication and authorization. The WebGate also starts the user's session, then creates session cookies and passes these to the user's browser.
The cert_authn.dll required for Smart Card authentication is provided with the WebGate installation in WebGate_install_dir\access\oblix\apps\webgate\bin. The WebGate used for Smart Card authentication must be installed with an IIS 5.0 Web server with SSL enabled.
The following process occurs during Smart Card authentication with Oracle Access Manager. Figure 14-1 illustrates the sequence and is followed by a process overview.
The browser prompts the user for the Smart Card and the WebGate intercepts the user's resource request and queries the Access Server to determine if and how the resource is protected, and if the user is authenticated.
The Access Server queries the Active Directory server for authentication information and receives information from the directory.
The Access Server responds to the WebGate, which prompts the browser to challenge the user to either insert their ActivCard and/or enter their PIN.
The user submits their credentials, which the browser passes to the WebGate and the WebGate presents to the Access Server, at which point one or more authentication plug-ins are used.
The cert_decode and credential_mapping plug-ins are required with the Client Certificate authentication scheme.
The Access Server performs the authentication dialog with the Active Directory, which maps the certificate information stored in the Smart Card to the user certificate in the directory and returns a success response to the Access Server.
When the user's credentials are valid, the Access Server provides the response to the WebGate, which starts a session for the user.
The WebGate queries the Access Server for resource authorization.
The Access Server queries Active Directory for authorization information that allows or denies access based upon the policy domain's authentication and authorization rules.
When access is granted, the Access Server passes authorization to the WebGate, which presents the resource to the user.
See ActivCard Gold specifications and details about Smart Card standards and compatibility at
Oracle Access Manager 10g (10.1.4.0.1) supports Smart Card authentication in the environments shown on Metalink. 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.
Several procedures must be completed to set up Smart Card authentication with Oracle Access Manager 10g (10.1.4.0.1).
Confirm your environment meets requirements in "Supported Versions and Platforms".
Set up Active Directory, as described in "Preparing Active Directory".
Set up a certificate, as described in "Preparing the CA and Enrolling for a Certificate".
Set up the IIS Web Servers, as described in "Preparing IIS Web Servers".
Set up Oracle Access Manager, as described in "Preparing Oracle Access Manager for Smart Card Authentication".
Configure your protected resources, as described in "Protecting Resources with Oracle Access Manager".
Set up IIS Manager, as described in "Setting Up the IIS Manager".
The following sections discuss preparing Active Directory.
Tip:For more information about this procedure, see the Active Directory manual.
For details about setting up your Active Directory to operate with Oracle Access Manager, see the Oracle Access Manager Installation Guide and Oracle Access Manager Identity and Common Administration Guide.
Ensure that you have a domain controller and Active Directory installed and properly running.
Ensure that you have a Domain Name System (DNS) server installed and properly running.
Note:You must install a Microsoft certification server with Active Directory, as discussed next.
The following sections discuss preparing the CA and enrolling for a certificate.
Tip:For more information about the following tasks, see the ActivCard documentation, Configuring Smart Card logon with ActivCard CSP for Windows 2000.
Confirm that you have met all setup requirements for certification authorities (CAs), install ActivCard Gold utilities, and set up the CA.
If you want the user's certificate installed on the ActivCard only, rather than on both the machine and the ActivCard, you need at least two installations of the ActivCard Gold utilities because you need an administrator's certificate to digitally sign a user's certificate.
Establish the certificate types that an enterprise certification authority can use.
Prepare a certification authority to issue Smart Card certificates.
Prepare a Smart Card certificate enrollment station on a computer that you will use to set up smart cards and install a ActivCard USB reader v2.0.
If you want the user's certificate installed on the ActivCard only, rather than on both the machine and the ActivCard, you need multiple ActivCard USB Readers and at least two ActivCard Gold.
Connect a Smart Card reader.
Enroll for a Smart Card Logon or Smart Card User certificate, initialize the card, and digitally sign the request.
For more information about downloading certificates onto ActivCards, see the ActivCard Gold User Guide.
Log on with an ActivCard, as described in Configuring Smart Card logon with ActivCard CSP for Windows 2000.
Set policies for Smart Card removal behavior.
The following sections describe preparing IIS Web Servers.
Tip:For more information about the following tasks, see the ActivCard documentation, Configuring Smart Card logon with ActivCard CSP for Windows 2000.
Deploy a certificate and the CA that issued the certificate within IIS on the Web server that hosts the WebGate.
Enable SSL to protect communication on port 443 on the Web server that hosts the WebGate.
Enable client certificate authentication within IIS.
Download a 1024-bit-length Web server certificate from your Microsoft certificate server.
Note:Do not use a 512-bit-length certificate.
The following sections describe preparing Oracle Access Manager for Smart Card authentication.
Tip:For more information, see the Oracle Access Manager Installation Guide
Ensure that Oracle Access Manager is properly installed and running with Active Directory, including the latest patches, for example:
Identity Server and WebPass
Policy Manager and Access System Console
Access Server and WebGates
Confirm that SSL is enabled on the IIS Web server hosting the WebGate.
You need to modify the Client Certificate authentication scheme and add it to a policy domain to protect resources for Smart Card authentication.
Steps are provided in this procedure. For additional information, see the Oracle Access Manager Access Administration Guide
Navigate to the Access System Console, Access System Configuration tab, Authentication Management function.
Create or modify the Client Certificate authentication scheme to use the X509Cert challenge method, as shown in the example in Figure 14-2.
Click the Plug-Ins tab and ensure that the cert_decode and credential_mapping plug-ins contain appropriate parameters and values for Smart Card authentication, as shown in the example in Figure 14-3.
For more information, see "Client Certificate Authentication Schemes".
This scheme will appear in the Authentication Scheme list when you add authentication rules to the policy domain.
Next, you create a policy domain in the Policy Manager. Steps are provided here and additional information is available in "About Policy Domains for Smart Card Authentication".
Navigate to the landing page for Access System administration:
Select the Policy Manager application, and click Create Policy Domain in the left navigation pane.
Note:Do not enable the policy domain until all specifications are completed.
Click the Resources tab, then click Add and add a resource.
Resource Type—Your ChoiceURL Prefix—Your ChoiceDescription—Optional
Click Authorization rules, and configure those that apply to your policy domain and resource, then confirm or add plug-in parameters, as usual.
Click the Default Rules tab, click the Add button, enter the details for the authentication rule and confirm that you are using the modified Client Certificate authentication scheme.
Name—Your choiceDescription—OptionalAuthentication Scheme—Client Certificate
Add an access policy, as needed.
Delegating Administration is done as usual. There are no special requirements. For more information, see the Oracle Access Manager Identity and Common Administration Guide.
Click the General tab and enable the policy domain, as usual.
Continue with "Setting Up the IIS Manager".
Next you must configure the Oracle Access Manager cert_authn.dll to "accept cookies", in the Internet Services Manager.
Navigate to the Internet Services Manager: Start, Programs, Administrative Tools, Internet Services Manager.
Expand the host, double click the Default Web Site (or another Web site if you are not using the default), then navigate to and double-click the cert_authn.dll.
hostname > Default Web Siteaccess\oblix\apps\webgate\bin\cert_authn.dll
Note:If the ISAPI WebGate installation configuration is performed manually, the following information will be presented on an HTML page:
"If you are using client certificate authentication you must enable client certificates for the WebGate and SSL must be enabled on the IIS Web server hosting the WebGate. Once this is done, do the following steps to enable client certificates for the WebGate:"
Select the File Security tab, then click Edit in the Secure Communications panel at the bottom of the window: File Security, Secure communications Edit.
In the Client Certificate Authentication subpanel, enable Accept Certificates.
Click OK in the Secure Communications window, and click OK in the cert_authn.dll Properties window.
The key to creating an effective policy domain is to group the content that you want to manage in the same way. In this case, you will group resources that require Smart Card authentication under one policy domain.
Each policy domain includes a definition of the authentication scheme, rules, optional policies, administrative rights, and resources to protect. Only one authentication rule is allowed per policy domain or policy. Only one authentication scheme is allowed per rule to enforce authentication.The default rule applies unless you set overriding policies (exceptions) for specific resources (URL patterns).
Authentication Scheme: An existing authentication scheme must be specified as the building block for a rule. The Client Certificate authentication scheme is required for Smart Card authentication. For more information, see "Client Certificate Authentication Schemes".
Administrative Rights: Administrative rights for the policy domain are optional. Until the Master Access Administrator delegates administration rights to a policy domain, he or she is the only person who can access it. All Administrators may create an authentication rule for a policy domain or a policy (exception). Only a Master Access Administrator or a Master Administrator may add resources to a policy domain.
Resources: Resources may be either static content such as HTML pages, .gifs, and .pdfs, or dynamic content such as scripts, applications, and EJBs.
For more information about policy domains, see the Oracle Access Manager Access Administration Guide.
Oracle Access Manager automatically configures the default Client Certificate authentication scheme if the Master Administrator selected this option during Access System installation. This scheme may be set up and/or modified after installation.
The Client Certificate scheme indicates that the user must supply a digital certificate to the policy domain to complete authentication. Oracle Access Manager supports client certificate authentication using public key encryption cryptography and X.509 certificates.
Your organization can determine how to obtain a certificate; there are no Oracle Access Manager requirements for this.
When you use the Oracle-provided schemes and plug-ins, you must be sure the obMappingFilter of the plug-in parameter is set correctly for your directory and environment. For additional information, see:
Oracle Access Manager Access Administration Guide for details on protecting resources using policy domains.
Each authentication scheme requires a challenge method to obtain user credentials for authentication. Only one challenge method is allowed per authentication scheme. Smart Card authentication has no Challenge Redirect requirement; however, the following is required:
Smart Card authentication requires the X509Cert Challenge Method and X509 Challenge Parameter, which support public key encryption cryptography and X.509 certificates.
Smart Card authentication requires an SSL connection.
The X509Cert challenge method uses the Secure Sockets Layer (SSL) version 3 certificate authentication protocol (SSLv3) certificate authentication protocol built into browsers and Web servers. Authenticating users with a client certificate requires the client to establish an SSL connection with a Web server that has been configured to process client certificates.
Note:Smart Card authentication has no Challenge Redirect requirement.
Two plug-ins supplied with Oracle Access Manager are required with the Client Certificate authentication scheme for Smart Card authentication. The order of execution in the Client Certificate authentication scheme for Smart Card logon is as follows.
|Authentication Scheme||Plug-Ins and Order of Execution|
Each plug-in defines how information will be looked up in the directory server. A number of parameters are available depending upon the plug-in. For more information, see "cert_decode Plug-In" and "credential_mapping Plug-In".
If your certificate is stored in the browser, you can view the certificate details. For more information, including the OIDs of the attributes that are supported by the Access Server with the corresponding suffix used to retrieve the attribute, see the Oracle Access Manager Access Administration Guide.
The cert_decode plug-in can be used with the X509Cert challenge method and must be included in the Client Certificate authentication scheme for Smart Card authentication.
The cert_decode plug-in has no parameters and does not use a data source. This should be the first plug-in in the Client Certificate authentication scheme for Smart Card authentication.
cert_decode decodes the certificate and extracts the components of the certificate subject's and issuer's Distinguished Name. For each component, the plug-in inserts a credential with a certSubject or certIssuer prefix. For instance, if your certificates have a subject name such as givenName=somename, the plug-in will add the credential certSubject.givenName=somename to the credential list.
If decoding is successful, the elements of the certificate's subject and issuer DN are added to the list of credentials. If not, authentication fails.
The credential_mapping plug-in can be used with the X509Cert challenge method and must be included in the Client Certificate authentication scheme for Smart Card authentication.
The credential_mapping plug-in should be second in the Client Certificate authentication scheme for Smart Card authentication. This plug-in maps the user-provided information to a valid Distinguished Name (DN) in the directory using the following parameters:
You can configure the attribute to which the user ID is mapped to find the DN by changing the obMappingFilter parameter as shown in the previous paragraph, where:
dc=the Active Directory Domain Controllermail=%certSubject.E%=maps the email in the Active Directory to the email in the certificate
With these concepts in mind, complete the steps under "Protecting Resources with Oracle Access Manager".
This section discusses the following troubleshooting tips for Smart Card authentication:
Oracle Access Manager requires X.509 certificates from Microsoft's Certification Server on Windows 2000 to be downloaded to the Smart Card. In this case, you need the ActivCard Gold for authentication.
You request a certificate for Smart Card from the following Web page:
You see the message "Downloading ActiveX Controls..." yet never complete the process.
Visit the following Web page:
Obtain security patch Q323172 for certificate downloads with IIS.
There are several sources of information that you may find useful when setting up Smart Card authentication for Oracle Access Manager 10g (10.1.4.0.1).
For more information about setting up Active Directory, see:
Microsoft Active Directory documentation
Oracle Access Manager Installation Guide chapter on installing on Active Directory
Oracle Access Manager Identity and Common Administration Guide for details on deploying with Active Directory
For more information about setting up ActivCard utilities and the Smart Card, see the documentation that accompanies your ActivCard product packages, including:
ActivCard Gold User Guide
ActivCard: Configuring Smart Card logon with ActivCard CSP for Windows 2000
ActivCard Trouble Shooting Guide
For general information about smart cards, see:
Microsoft Step-by-Step Guide to Installing and Using a Smart Card Reader
Microsoft Step-by-Step Guide to Mapping Certificates to User Accounts
For more information about setting up protecting resources with Oracle Access Manager policy domains, see the Oracle Access Manager Access Administration Guide.