Authentication Repository

Contents

Overview

The Enterprise Gateway supports a wide range of common authentication schemes, including SSL, XML Signatures, WS-Security Username tokens, and HTTP Authentication. With SSL, the client authenticates to the Enterprise Gateway using a client certificate. With XML Signatures, the client is authenticated by validating the signature contained within the XML message. However, when the Enterprise Gateway attempts to authenticate a client using a username and password (for example, WS-Security Username tokens and HTTP Authentication), it must compare the username and password presented by the client to those stored in the Oracle Authentication Repository.

The Authentication Repository acts as a repository for Users. Users serve many roles in the Enterprise Gateway. For example, clients whose username and password combinations are stored in the Authentication Repository can authenticate to the Enterprise Gateway using that username and password combination. For more information on Users, see the Enterprise Gateway Users tutorial.

The Authentication Repository can be maintained in the Enterprise Gateway's local configuration store, in an LDAP directory, or in a range of third-party Identity Management products and services. When a user has been successfully authenticated against one of these repositories, the Enterprise Gateway can use any one of that user's stored attributes (for example, DName, email address, username) to authorize that same user in a subsequent Authorization Filter.

For example, this credential mapping is useful in cases where your client-base uses username-password combinations for authentication (authentication attributes), yet their access rights must be looked up in an authorization server using the client's DName (authorization attribute). In this way, the client possesses a single virtual identity within the Enterprise Gateway. The client can use one identity for authentication, and another for authorization, yet the Enterprise Gateway sees both identities as representing the same client.

You can add a new repository on the External Connections tab by right-clicking the appropriate node (for example, Database Repositories), and selecting Add a new Repository. Similarly, you can edit an existing repository by right-clicking the repository node (for example, the default Local User Store), and selecting Edit Repository. Repositories added on the External Connections tab are available for reuse by multiple filters.

Local Repositories

The Authentication Repository can be maintained in the same database that the Enterprise Gateway uses to store all its configuration information. To edit the default user store, select Local Repositories -> Local User Store -> Edit Repository. Alternatively, to create a new user store, select Local Repositories -> Add a new Repository.

You can enter an appropriate name for the repository in the Repository Name field. The Authorization Attribute Format field enables administrators to specify whether to use the client's X.509 Distinguished Name or User Name in subsequent Authorization Filters. If User Name is selected, the user name used by the client to authenticate to the Enterprise Gateway is used in any configured Authorization filters. If X.509 Distinguished Name is selected, the X.509 DName stored by the Enterprise Gateway for that user is used for subsequent authorization.

For example, if the administrator selected User Name from the Authorization Attribute Format drop-down list, admin (the User Name field) is used for authorization. Alternatively, if X.509 Distinguished Name is selected, the X.509 DName is used for authorization (for example, O=Company, OU=comp, EMAIL=emp@company.com, CN=emp).

For more information on adding and configuring users to the Authentication Repository, see the Users tutorial.

LDAP Repositories

In cases where an organization stores user profiles in an LDAP directory, it does not make sense to re-enter those profiles into the default Enterprise Gateway store. Rather, the Enterprise Gateway can leverage an existing LDAP directory by querying it for user profile data. If a user's profile can be retrieved and you can bind to the LDAP directory as that user, the user is authenticated.

When a filter is configured to authenticate a user against an LDAP repository using a username and password combination, the following steps occur:

  1. A pooled LDAP connection with details corresponding to the repository selected in the LDAP Directory field is retrieved.
  2. A search filter (for example, (&(objectClass={User}) (sAMAccountName={c05vc}))) is run using the retrieved connection. Attributes configured in the Login Authentication Attribute and Authorization Attribute fields are also retrieved in the same search operation.
    For example, if Distinguished Name is selected from the drop-down list, the user's DName is retrieved from the LDAP directory. The user's DName uniquely identifies the user in the LDAP directory, and is used to bind to the directory so that the user's password can be verified. The attribute specified in the Login Authentication Attribute field is used for the bind operation when you bind as any user. The value of the LDAP attribute specified in the Authorization Attribute field is stored in the authentication.subject.id and may be used by subsequent filters in the circuit (for example, by authorization filters to authorize the authenticated user).
  3. If no results are returned from the search, the user has not been found in the directory. It is important that the administrator user configured on the Configure LDAP Server screen has the ability to see the user you are attempting to authenticate.
  4. If multiple results (users) are returned from the search, an attempt is made to bind to the directory using each Login Authentication Attribute value retrieved from the search, together with the password from the message.
  5. If more than one user is authenticated correctly, an error is returned because you only want to authenticate a single user.
  6. If no user is authenticated, an error is returned.
  7. If a single user's Login Authentication Attribute value and password binds successfully to the directory, authentication has succeeded.
  8. Any successful bind is immediately closed.

To create a new LDAP repository, right click LDAP Repositories and select Add a new Repository. The details entered on the Authentication Repository screen depend on the type of LDAP directory that you are using. The Policy Studio has default entries for some of the more common LDAP directories, which are available from the drop-down lists on the screen. However, you can also connect to alternative LDAP directories.

The following subsections demonstrate how to configure this screen for typical user searches on three common LDAP servers:

  • Oracle Directory Server
  • Microsoft Active Directory Server
  • IBM Directory Server

Oracle Directory Server
To configure the Authentication Repository dialog for Oracle Directory Server, perform the following steps:

  1. Enter a suitable name for this user store in the Repository Name field.
  2. Click Add/Edit to add details of your Oracle Directory Server.

The User Search Conditions section instructs the Enterprise Gateway to search the LDAP tree according to certain conditions:

  • Base Criteria:
    This specifies where the Enterprise Gateway should begin searching the LDAP directory.
  • User Class:
    This is the name given by the particular LDAP directory to the User class. For Oracle Directory Server, select 'inetorgperson' LDAP Class from the drop-down list.
  • User Search Attribute:
    The value entered depends on the type of LDAP directory to which you are connecting. When a user is stored in an LDAP directory, a number of user attributes are stored along with that user. One of these attributes corresponds to the user name presented by the client for authentication. However, different LDAP directories use different names for that user attribute. For Oracle Directory Server, select cn from the drop-down list.
  • Allow Blank Passwords:
    Select this box to allow the use of blank passwords.

In the next section, you must specify the following:

  • Login Authentication Attribute:
    In an LDAP directory tree, there must be one user attribute that uniquely distinguishes any one user from all the others. This is usually the Distinguished Name of the user, however this is called different things in different LDAP directories. In Oracle Directory Server, the Distinguished name is referred to as the entrydn, so select Entry Domain Name in this drop-down list to uniquely identify the client authenticating to the Enterprise Gateway.
  • Authorization Attribute:
    When the client has been successfully authenticated, you can use any one of that user's stored attributes in a subsequent Authorization Filter. In this case, you want to use the user's Distinguished Name for an Authorization filter, so enter entrydn in the text box. However, you can enter any user attribute as long as the subsequent Authorization filter supports it. The value of the LDAP attribute specified is stored in the authentication.subject.id Oracle message attribute.
  • Authorization Attribute Format:
    Because any user attribute can be specified in the Authorization Attribute above, it is necessary to inform the Enterprise Gateway of the type of this attribute. This information is used internally by the Enterprise Gateway in subsequent Authorization filters. Select X.509 Distinguished Name from the drop-down list.

Microsoft Active Directory Server
This subsection describes how to configure the Authentication Repository dialog for Microsoft Active Directory Server. It is important to note how the values entered here differ from those entered when interfacing to the Oracle Directory Server:

  • Repository Name:
    Enter a suitable name for this search.
  • LDAP Directory:
    Click Add/Edit to add details of your Active Directory Server.

The User Search Conditions instruct the Enterprise Gateway to search the LDAP tree according to certain criteria. The values entered/selected are different from those selected for Oracle Directory Server, because MS Active Directory Server uses different attributes and classes to Oracle Directory Server:

  • Base Criteria:
    The base criteria specify the base object under which to search for the user's profile.
  • User Class:
    In Active Directory Server, the user class is simply called User, so select 'User' LDAP Class from this drop-down list.
  • User Search Attribute:
    This field specifies the name of the user attribute whose value corresponds to the user name entered by the client during a successful authentication process. With Active Directory Server, this attribute is called givenName and it represents the name of the user. Enter givenName in this drop-down list.
  • Login Authentication Attribute:
    Enter the name of the user attribute that uniquely identifies the user in the LDAP directory. This attribute is the Distinguished Name and is called distinguishedName in Active Directory Server. Select Distinguished Name from the drop-down list to uniquely identify the user. The Enterprise Gateway authenticates the username and password presented by the client against the values stored for the user identified in this field.
  • Authorization Attribute:
    When the client has been successfully authenticated, the Enterprise Gateway can use any of that user's stored attributes in subsequent Authorization filters. Because most Authorization filters require a Distinguished Name, enter Distinguished Name in the text box. However, any user attribute could be entered here, as long as the subsequent Authorization filter supports it.
  • Authorization Attribute Format:
    The Enterprise Gateway needs to know the format of the Authorization Attribute. Select X.509 Distinguished Name from the drop-down list.

IBM Directory Server
The configuration details for IBM Directory Server deserve a special mention as an example of a directory server that does not return a full Distinguished Name (DName) as the result of a standard LDAP user search. Instead, it returns a contextualized DName, which is relative to the specified Base Criteria. In such cases, the Enterprise Gateway can build up the full DName by combining the Base Criteria and the returned name. The following example shows how this works in practice.

If C=IE is specified as the Base Criteria, the IBM Directory Server returns CN=niall, OU=Dev, instead of the full DName, which is C=IE, CN=niall, OU=Dev. To enable the Enterprise Gateway to do this, leave the Login Authentication Attribute field blank. The Enterprise Gateway then automatically concatenates the specified Base Criteria (C=IE) with the contextualized DName returned from the directory server (CN=niall, OU=Dev) to obtain the fully qualified DName (C=IE, CN=niall, OU=Dev).

You can also leave the Authorization Attribute field blank, which enables the Enterprise Gateway to automatically use the fully qualified DName for subsequent Authorization Filters. You should select X.509 Distinguished Name from the Authorization Attribute Format drop-down list.

CA SiteMinder Repositories

In cases where user profiles have been stored in an existing SiteMinder server, the Enterprise Gateway can query SiteMinder to authenticate users.

To authenticate users against a CA SiteMinder repository, right-click CA SiteMinder Repositories, and select Add a new Repository. Complete the following fields on the Authentication Repository dialog:

Repository Name:
Enter a suitable name for this repository.

Agent Name:
Select a previously configured SiteMinder Agent name from the drop-down list. Click Add to register a new agent. Complete the following fields in the SiteMinder Connection Details dialog:

  • Agent Name:
    Enter the name of the agent to connect to SiteMinder in the Agent Name field. This name must correspond with the name of an agent that was previously configured in the Policy Server.
  • Agent Configuration Object:
    The name entered must match the name of the Agent Configuration Object (ACO) configured in the Policy Server. The Enterprise Gateway currently does not support any of the features represented by the ACO parameters except for the PersistentIPCheck setting. For example, the Enterprise Gateway disregards the DefaultAgent parameter and uses the agent value it collects separately during agent registration.
    When the PersistentIPCheck ACO parameter is set to yes, it instructs the Enterprise Gateway to compare the IP address from the last request (stored in a persistent cookie) with the IP address in the current request to see if they match. If the IP addresses do not match, the Enterprise Gateway rejects the request. If this parameter is set to no, this check is disabled.
  • Connection Details:
    For more information on configuring this section, please refer to the instructions in the SiteMinder Connection Details section of the SiteMinder Certificate Authentication help page.

Resource:
Enter the name of the protected resource for which the user must be authenticated.

Alternatively, you can enter a property representing a message attribute, which is looked up and expanded to a value at runtime. Properties have the following format:

${message.attribute}

For example, to specify the original path on which the request was received by the Enterprise Gateway as the resource, enter the following property:

  
${http.request.uri}

Action:
The user must be authenticated for a specific action on the protected resource. By default, this action is taken from the HTTP verb used in the incoming request. You can use the following property to get the HTTP verb:

${http.request.verb}<br/>

Alternatively, you can enter any user-specified value.

Create Single Sign-On Token:
When this option is selected, SiteMinder generates a single sign-on token as part of the authentication event and returns it to the Enterprise Gateway. This is then inserted into the downstream message for re-use later, either by another instance of the Enterprise Gateway running the SiteMinder Session Validation filter, or by another SiteMinder-aware agent.

Put Token in Message Attribute:
Enter the name of the message attribute where you wish to store the single sign-on token. By default, the token is stored in the siteminder.session attribute. Please refer to the Message Attribute Reference for a complete list of available message attributes.

Database Repositories

The Enterprise Gateway can store its Authentication Repository in an external database. This option makes sense when an organization already has a silo of user profiles stored in the database and does not want to duplicate this store within the Enterprise Gateway's local configuration storage.

To authenticate users against a database repository, right-click Database Repositories, and select Add a new Repository. Complete the following fields on the Authentication Repository dialog:

Repository Name:
Enter an appropriate name for the database in the Repository Name field.

Database:
There are two basic configuration items required to retrieve a user's profile from the database:

  • Database Location:
    You can configure connection details for the database by clicking Add, and completing the Database Connection dialog. For details on configuring the fields on this dialog, see the Database Connection topic. You can edit or remove previously configured database connections by selecting them in the drop-down list and clicking Edit or Delete.
  • Database Query:
    The Database Query retrieves a specific user's profile from the database to enable the Enterprise Gateway to authenticate them. Having successfully authenticated the user, you can select an attribute of this user to use for the authorization filter later in the policy. The Database Query can take the form of an SQL statement, stored procedure, or function call. For details on how to configure the Database Query, see the Database Query topic.

Format Password Received From Client:
If the user sends up a clear-text password to the Enterprise Gateway, but that user's password is stored in a hashed format in the database, it is the Enterprise Gateway must hash the password before performing the authentication step.

  • Hash Client Password:
    Depending on whether you wish to hash the user's submitted password, select the appropriate radio button.
  • Hash Format:
    If you have selected to hash the client's password, the Enterprise Gateway needs to know the format of the hashed password. The most typical formats are available from the drop-down list, however, you can also enter another format. Formats should be entered in terms of message attributes. The following formats are available from the Hash Format drop-down list. The first option combines the username, authentication realm, and password respectively. This combination is then hashed. The second option simply creates a hash of the user's password.
  • ${authentication.subject.id}:${authentication.subject.realm}:${authentication.subject.password}
    ${authentication.subject.password}
    

  • Hash Algorithm:
    Select either MD5 or SHA1 to use as the digest algorithm to use when creating the hash.

Query Result Processing:
This section enables you to provide the Enterprise Gateway with some meta information about the result returned by the Database Query configured earlier on this screen. It enables allows you to identify the name of the database table column or row that contains the user's password, and also the name of the column or row that contains the attribute that is to be used for the authorization filter.

  • Password Column:
    Specify the name of the database table column that contains the user's password. The contents of this column are compared to the password submitted by the user.
  • Password Type:
    Depending on how the user's password has been stored in the database, select either Clear Password or Digest Password from the drop-down list.
  • Authorization Attribute Column:
    By running the Database Query, all of the user's attributes are returned. Only the user's username and password are used for the authentication event. You can also use one of the other user's attributes for authorization at a later stage in the policy. The additional authorization attribute should be either a username or an X.509 distinguished name (DName). You should enter the name of the column containing the username or the DName here, but only if this value is required for authorization purposes.
  • Authorization Attribute Format:
    The Enterprise Gateway's authorization filters all operate on the basis of a username or DName. They all evaluate whether a user identified by a username or DName is allowed to access a specific resource. Select the appropriate format from the drop-down list depending on what type of user credential is stored in the database table column entered above.

Entrust GetAccess Repositories

Entrust GetAccess provides Identity Management and access control services for Web resources. It centrally manages access to Web applications, enabling users to benefit from a single sign-on capability when accessing the applications that they are authorized to use.

You can configure the Enterprise Gateway to connect to a group of GetAccess servers in a round-robin fashion. This provides the necessary failover capability when one or more GetAccess servers are not available. When the Enterprise Gateway successfully authenticates to a GetAccess server, it obtains authorization information about the end-user from the GetAccess SAML PDP. The authorization details are returned in a SAML authorization assertion, which is then validated by the Enterprise Gateway to determine whether the request should be denied.

To authenticate users against an Entrust GetAccess repository, right-click Entrust GetAccess Repositories, and select Add a new Repository. Configure the following fields on the Authentication Repository dialog:

Repository Name:
Enter an appropriate name for this repository

Request:
Configure the following request settings:

  • URL Group:
    Select a URL group from the drop-down list. This group consists of a number of GetAccess Servers to which the Enterprise Gateway round-robins connection attempts. You can add URL groups on the External Connections tab in Policy Studio. Expand the URL Connection Sets node, right-click Entrust GetAccess URL Sets, and select Add a URL Set. For more details on adding and editing URL groups, see the Configuring URL Groups topic.
  • WS-Trust Attribute Field Name:
    Specify the field name for the Id field in the WS-Trust request. The default is Id.

Response:
Configure the following response settings:

  • SOAP Actor/Role:
    To add the SAML authorization assertion to the response message, select a SOAP actor/role to indicate the WS-Security block where the assertion is added. By leaving this field blank, the assertion is not added to the message.
  • Drift Time:
    The specified time is used to allow for the possible difference between the time on the GetAccess SAML PDP and the time on the machine hosting the Enterprise Gateway. This comes into effect when validating the SAML authorization assertion.

Further Information
For details on using a filter to integrate the Enterprise Gateway with Entrust GetAccess, see the Entrust GetAccess Authorization topic.

Oracle Access Manager Repositories

You can authorize an authenticated user for a particular resource against an Oracle Access Manager (OAM) repository. After successful authentication, OAM issues a Single Sign On (SSO) token, which can then be used instead of the user name and password.

To authenticate users against an Oracle Access Manager repository, right-click Oracle Access Manager Repositories, and select Add a new Repository. Configure the following fields on the Authentication Repository dialog:

Repository Name:
Enter an appropriate name for this repository.

Resource Request:
Configure the following settings for the resource request:

  • Resource Type:
    Enter the type of the resource for which you are requesting access. For example, for access to a Web-based URL, enter http.
  • Resource Name:
    Enter the name of the resource for which the user is requesting access. By default, this field is set to //hostname${http.request.uri}, which contains the original path requested by the client.
  • Operation:
    In most access management products, users are authorized for a limited set of actions on the requested resource. For example, users with management roles may be permitted to write (HTTP POST) to a certain Web Service, but users with junior roles might only have read access (HTTP GET) to the same service. Use this field to specify the operation to which you want to grant the user access on the specified resource. By default, this is set to the http.request.verb message attribute, which contains the HTTP verb used by the client to send the message to the Enterprise Gateway (for example, HTTP POST).

Single Sign On:
Configure the following settings for single sign on:

  • Create SSO Token:
    Select whether to create an SSO token. This is selected by default.
  • Store SSO Token in User Attribute:
    Enter the name of the message attribute that contains the user's SSO token. This attribute is populated when authenticating to Oracle Access Manager using the HTTP Basic or HTTP Digest filter. By default, the SSO token is stored in the oracle.sso.token message attribute.
  • Add SSO Token to User Attributes:
    Select whether to add the SSO Token to user message attributes. This is selected by default.

Oblix Installation Directory:
Enter the path to your Oblix installation directory. For more details on Oblix, see your Oracle Access Manager documentation.

Further Information
For details on using filters to integrate the Enterprise Gateway with Oracle Access Manager, see the Oracle Access Manager Index topic.

Oracle Entitlements Server Repositories

You can authenticate and authorize a user for a particular resource against an Oracle Entitlements Server (OES) repository.

For example, the Enterprise Gateway can extract credentials from the message sent by the client, and delegate authentication to the Oracle Entitlements Server. When the client has been authenticated, the Enterprise Gateway queries Oracle Entitlements Server to see if the client is permitted to access the Web Service resource. When authentication and authorization have passed, the message is trusted and forwarded to the target Web Service.

To authenticate and authorize users against an Oracle Entitlements Server repository, right-click Oracle Entitlements Server Repositories, and select Add a new Repository. Configure the following fields on the Authentication Repository dialog:

Repository Name:
Enter an appropriate name for this repository.

Oracle SSM Settings:
Click Configure to launch the Oracle Security Service Module Settings dialog. For details on configuring these settings, see the Oracle Security Service Module Settings topic.

RADIUS Repositories

You can configure the Enterprise Gateway to authenticate users in a Remote Authentication Dial In User Service (RADIUS) repository. RADIUS is a client-server network protocol that provides centralized authentication and authorization for clients connecting to remote services.

To authenticate users against a RADIUS repository, perform the following steps:

  1. Right-click RADIUS Repositories, and select Add a new Repository.
  2. In the Authentication Repository dialog, enter the RADIUS Repository Name.
  3. On the Client tab, select the RADIUS clients that you wish to authenticate to the repository. For details on how to add clients to this list, see the RADIUS Clients topic.
  4. On the Attributes tab, click Add to add a RADIUS attribute. This is a name-value pair used to determine how access is granted. Examples include User-Name, User-Password, NAS-IP-Address, or NAS-Port).
  5. In the RADIUS Attributes dialog, specify a Name (for example, User-Name). You can select standard RADIUS attributes from the drop-down list, or enter a custom attribute.
  6. Enter a Value, and click OK.
  7. Click OK.

Repeat steps 4-6 to add multiple attributes. You can edit or delete attributes using the buttons provided.

RSA Access Manager Repositories

RSA Access Manager (formerly known as RSA ClearTrust) provides Identity Management and access control services for Web applications. It centrally manages access to Web applications, ensuring that only authorized users are allowed access to resources. Integration with RSA Access Manager requires RSA ClearTrust SDK version 6.0.

To authenticate users against an RSA Access Manager repository, right-click RSA Access Manager Repositories, and select Add a new Repository. Configure the following fields on the Authentication Repository dialog:

Repository Name:
Enter an appropriate name for this repository.

Connection Details:
The Enterprise Gateway can connect to a group of Access Manager Authorization Servers or Dispatcher Servers. When multiple Access Manager Authorization Servers are deployed for load-balancing purposes, the Enterprise Gateway first connects to a Dispatcher Server, which returns a list of active Authorization Servers. An attempt is made to connect to one of these Authorization Servers using round-robin DNS. If the first Dispatcher Server in the Connection Group is not available, the Enterprise Gateway attempts to connect to the Dispatcher Server with the next highest priority in the group, and so on.

If a Dispatcher Server has not been deployed, the Enterprise Gateway can connect directly to an Authorization Server. If the Authorization Server with the highest priority in the Connection Group is not available, the Enterprise Gateway attempts to connect to the Authorization Server with the next highest priority, and so on. You can select the type of the Connection Group using the Authorization Server or Dispatcher Server radio button. All servers in the group must be of the same type.

Connection Group:
Select the Connection Group to use for authenticating clients. You can add Connection Groups on the External Connections tab in Policy Studio. Expand the Connection Sets node, right-click RSA ClearTrust Connection Sets, and select Add a Connection Set. For more details on adding and editing Connection Groups, see the Configuring Connection Groups topic

Authentication Type:
Select one of the following authentication types for the connection:

  • HTTP Basic
  • Windows NT
  • RSA SecureID
  • LDAP
  • Certificate Distinguished Name

Further Information
For more details on prerequisites and on using a filter to integrate the Enterprise Gateway with RSA Access Manager, see the RSA Access Manager Authorization topic.

Tivoli Repositories

The Enterprise Gateway can integrate with Tivoli Access Manager to authenticate users. To authenticate users against a Tivoli repository, right-click Tivoli Repositories, and select Add a new Repository.

For more information on how to configure Enterprise Gateway to communicate with a Tivoli server, see the Tivoli Integration topic.