This method lets you grant access to the passwords and client certificates that are stored in an Oracle wallet to users to authenticate themselves to an external Web server. This enables the user to retrieve protected Web pages from the Web server. This section contains:
■ Step 1: Create an Oracle Wallet
■ Step 2: Create an Access Control List that Grants the Wallet Privileges ■ Step 3: Assign the Access Control List to the Wallet
■ Step 4: Make the HTTP Request with the Passwords and Client Certificates
Step 1: Create an Oracle Wallet
To create the wallet, you can use either the mkstore command-line utility or the Oracle Wallet Manager user interface. To store passwords in the wallet, you must use
mkstore. You can use both standard and PKCS11 wallet types, and the wallet can be an auto-login wallet if you want. For detailed information about creating wallets, see Oracle Database Advanced Security Administrator's Guide.
When you create the wallet, do the following:
■ Ensure that you have exported the wallet to a file.
■ Make a note of the directory in which you created the wallet. You will need this
Managing Fine-Grained Access in PL/SQL Packages and Types
Step 2: Create an Access Control List that Grants the Wallet Privileges
After you have created the wallet, you are ready to create the access control list that will assign the password or client certificate privilege the user needs to use password credentials in the wallet for HTTP authentication.
For example: BEGIN DBMS_NETWORK_ACL_ADMIN.CREATE_ACL ( acl => 'file_name.xml', description => 'description', principal => 'user_or_role', is_grant => TRUE|FALSE, privilege => 'privilege'; ... END; In this specification:
■ acl: Enter a name for the ACL, and make a note of this name. You will need this
name in Step 3: Assign the Access Control List to the Wallet, next. Oracle Database creates this file relative to the /sys/acls directory in the XML DB Repository in the database. Include the .xml extension. For example:
acl => 'hr_access_wallet_acl.xml',
■ description: Enter a brief description of the purpose of this file. For example:
description => 'Wallet ACL for the hr_access application',
■ principal: Enter the user account or role being granted or denied privileges. For
example:
principal => 'HR_CLERK',
Enter this name using case sensitive characters. For example, if the database stores the role name HR_CLERK in all capital letters, entering it in mixed or lower-case letters will not work. You can find the user accounts and roles in the current database instance by querying the DBA_USERS and DBA_ROLES data dictionary views. Typically, user names and roles are stored in upper-case letters.
If you want to add multiple users, or if you want to grant this user an additional privilege, you can use the DBMS_NETWORK_ACL.ADD_PRIVILEGE procedure after you have created this access control list XML file.
■ is_grant: Enter either TRUE or FALSE, to indicate whether the privilege is to be
granted or denied. For example: is_grant => TRUE,
■ privilege: Enter one of the following settings using lowercase letters and
hyphens. Remember that the privilege name is case-sensitive.
– use-passwords to give the user permission to use passwords in the wallet See Also:
■ "Example of an Access Control List for Using Passwords in a
Non-Shared Wallet" on page 4-62
■ "Example of an Access Control List for Wallets in a Shared
Managing Fine-Grained Access in PL/SQL Packages and Types
– use-client-certificates to authenticate the user with a client certificate in the wallet
For example:
privilege => 'use-client-certificates');
Step 3: Assign the Access Control List to the Wallet
In this step, you assign this access control list to the wallet you created earlier. Afterward, you can check your settings by querying the DBA_WALLET_ACLS data dictionary view. For example: BEGIN ... DBMS_NETWORK_ACL_ADMIN.ASSIGN_WALLET_ACL ( acl => 'file_name.xml',
wallet_path => 'file:path_to_directory_containing_wallet'); END;
In this specification:
■ acl: Enter the name that you created for this wallet in Step 2: Create an Access
Control List that Grants the Wallet Privileges, in the previous section. For example: acl => 'hr_access_wallet_acl.xml',
■ wallet_path: Enter the path to the directory that contains the wallet. When you
specify the wallet path, you must use an absolute path and include file: before this directory path. Do not use environment variables, such as $ORACLE_HOME, nor insert a space after file: and before the path name. For example:
wallet_path => 'file:/oracle/wallets/hr_access_access'
Step 4: Make the HTTP Request with the Passwords and Client Certificates
In this step, you use the UTL_HTTP PL/SQL package to create a request context object that is used privately with the HTTP request and its response. For detailed information about the UTL_HTTP package, see Oracle Database PL/SQL Packages and Types Reference. For example: DECLARE req_context UTL_HTTP.REQUEST_CONTEXT_KEY; req UTL_HTTP.REQ; BEGIN req_context := UTL_HTTP.CREATE_REQUEST_CONTEXT (
wallet_path => 'file:path_to_directory_containing_wallet', wallet_password => 'wallet_password'|NULL);
req := UTL_HTTP.BEGIN_REQUEST(
url => 'URL_to_application', request_context => 'request_context'|NULL); ...
END;
In this specification:
■ req_context: Use the UTL_HTTP.CREATE_REQUEST_CONTEXT_KEY datatype to create the request context object. This object stores a randomly-generated numeric key that Oracle Database uses to identify the request context. The UTL_HTTP.CREATE_ REQUEST_CONTEXT function creates the request context itself.
Managing Fine-Grained Access in PL/SQL Packages and Types
■ req: Use the UTL_HTTP.REQ datatype to create the object that will be used to begin
the HTTP request. You will refer to this object later on, when you set the user name and password from the wallet to access a password-protected Web page.
■ wallet_path: Enter the path to the directory that contains the wallet. Ensure that
this path is the same path you specified when you created access control list in Step 3: Assign the Access Control List to the Wallet in the previous section.You must include file: before the directory path. Do not use environment variables, such as $ORACLE_HOME.
For example:
wallet_path => 'file:/oracle/wallets/hr_access_access',
■ wallet_password: Enter the password used to open the wallet. The default is NULL,
which is used for auto-login wallets. For example: wallet_password => NULL);
■ url: Enter the URL to the application that uses the wallet.
For example:
url => 'www.hr_access.example.com',
■ request_context: Enter the name of the request context object that you created
earlier in this section. This object prevents the wallet from being shared with other applications in the same database session.
For example:
request_context => req_context);
Using a Request Context to Hold the Wallet When Sharing the Session with Other Applications
You should use a request context to hold the wallet when the database session is shared with other applications. If your application has exclusive use of the database session, you can hold the wallet in the database session by using the SET_WALLET procedure instead. For example: DECLARE req UTL_HTTP.REQ; BEGIN UTL_HTTP.SET_WALLET(
path => 'file:path_to_directory_containing_wallet', password => 'wallet_password'|NULL);
req := UTL_HTTP.BEGIN_REQUEST(
url => 'URL_to_application'); ...
END;
If the protected URL being requested requires the user name and password to
authenticate, then use the SET_AUTHENTICATION_FROM_WALLET procedure to set the user name and password from the wallet to authenticate.
Using Only a Client Certificate to Authenticate
If the protected URL being requested requires only the client certificate to authenticate, the BEGIN_REQUEST function sends the necessary client certificate from the wallet. assuming the user has been granted the use-client-certificates privilege in the
Managing Fine-Grained Access in PL/SQL Packages and Types
ACL assigned to the wallet. The authentication should succeed at the remote Web server and the user can proceed to retrieve the HTTP response by using the GET_ RESPONSE function.
Using the Password to Authenticate
If the protected URL being requested requires the username and password to
authenticate, you should use the SET_AUTHENTICATION_FROM_WALLET procedure to set the username and password from the wallet to authenticate.
For example: DECLARE req_context UTL_HTTP.REQUEST_CONTEXT_KEY; req UTL_HTTP.REQ; BEGIN ... UTL_HTTP.SET_AUTHENTICATION_FROM_WALLET( r => HTTP_REQUEST, alias => 'alias_to_retrieve_credentials_stored_in_wallet', scheme => 'AWS|Basic', for_proxy => TRUE|FALSE); END; In this specification:
■ r: Enter the HTTP request defined in the UTL_HTTP.BEGIN_REQUEST procedure that
you created above, in the previous section. For example: r => req,
■ alias: Enter the alias used to identify and retrieve the user name and password
credential stored in the Oracle wallet. For example, assuming the alias used to identify this user name and password credential is hr_access.
alias => 'hr_access',
■ scheme: Enter one of the following:
– AWS: Specifies the Amazon Simple Storage Service (S3) scheme. Use this scheme only if you are configuring access to the Amazon.com Web site. (Contact Amazon for more information about this setting.)
– Basic: Specifies HTTP basic authentication. The default is Basic. For example:
scheme => 'Basic',
■ for_proxy: Specify whether the HTTP authentication information is for access to
the HTTP proxy server instead of the Web server. The default is FALSE. For example:
for_proxy => TRUE);
The use of the user name and password in the wallet requires the use-passwords privilege to be granted to the user in the ACL assigned to the wallet.