Authentication repository

Overview

The API 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 API Gateway using a client certificate. With XML Signatures, the client is authenticated by validating the signature contained within the XML message. However, when the API Gateway attempts to authenticate a client using a user name and password (for example, WS-Security Username tokens and HTTP Authentication), it must compare the user name 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 API Gateway. For example, clients whose user name and password combinations are stored in the Authentication Repository can authenticate to the API Gateway using that user name and password combination. For more information on Users, see the Manage API Gateway users topic.

The Authentication Repository can be maintained in the API 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 API Gateway can use any one of that user's stored attributes (for example, DName, email address, user name) to authorize that same user in a subsequent Authorization Filter.

For example, this credential mapping is useful in cases where your client-base uses user name and 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 API Gateway. The client can use one identity for authentication, and another for authorization, yet the API Gateway sees both identities as representing the same client.

You can add a new repository under the External Connections node in the Policy Studio tree 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 under the External Connections node are available for reuse by multiple filters.

Axway PassPort repositories

The API Gateway can integrate with Axway PassPort to authenticate and authorize users for resources. To authenticate users against an Axway PassPort repository, right-click Axway PassPort Repositories, and select Add a new Repository.

For more details on configuring a connection to an Axway PassPort repository, see Axway PassPort authentication repository. For details on integrating with Axway PassPort using an authorization filter, see Axway PassPort authorization.

CA SiteMinder repositories

In cases where user profiles have been stored in an existing SiteMinder server, the API 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 API Gateway currently does not support any of the features represented by the ACO parameters except for the PersistentIPCheck setting. For example, the API 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 API 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 API 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 in SiteMinder certificate authentication.

Resource:

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

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

${message.attribute}

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

${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 selector to get the HTTP verb:

${http.request.verb}

Alternatively, you can enter any user-specified value. For more details on selectors, see Select configuration values at runtime.

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 API Gateway. This is then inserted into the downstream message for re-use later, either by another instance of the API 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.

Database repositories

The API 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 API 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 Configure database connections. 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 API 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 Configure database query.

Format Password Received From Client:

If the user sends up a clear-text password to the API Gateway, but that user's password is stored in a hashed format in the database, it is the API 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 API 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 attribute selectors. The following formats are available from the Hash Format drop-down list.

    ${authentication.subject.id}:${authentication.subject.realm}:${authentication.
    subject.password}
    ${authentication.subject.password}

    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.

  • Hash Algorithm:

    Select either MD5 or SHA1 to use as the digest algorithm to use when creating the hash.

For more details on selectors, see Select configuration values at runtime.

Query Result Processing:

This section enables you to provide the API Gateway with some meta information about the result returned by the Database Query configured earlier on this window. 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 API 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 API 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 API 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 API 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 API Gateway round-robins connection attempts. You can add URL groups under the External Connections tree node 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 Configure 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 API Gateway. This comes into effect when validating the SAML authorization assertion.

Further information

For details on using a filter to integrate the API Gateway with Entrust GetAccess, see the Entrust GetAccess authorization topic.

Local repositories

The Authentication Repository can be maintained in the same database that the API 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 API Gateway is used in any configured Authorization filters. If X.509 Distinguished Name is selected, the X.509 DName stored by the API Gateway for that user is used for subsequent authorization.

For example, if the administrator selects 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 Manage API Gateway users.

LDAP repositories

In cases where an organization stores user profiles in an LDAP directory, it does not make sense to re-enter these profiles into the default API Gateway user store. Instead, the API 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.

Authentication with LDAP

The following steps occur when a filter is configured to authenticate a user against an LDAP repository using a user name and password combination:

  1. A pooled LDAP connection to the repository selected in the LDAP Directory field is retrieved.

  2. A search filter is run using the retrieved connection (for example, (&(objectClass={User})(sAMAccountName={c05vc}))). Attributes configured in the Login Authentication Attribute and Authorization Attribute fields are retrieved in this search.

    For example, if you select Distinguished Name from the drop-down list, the user's DName is retrieved from the LDAP directory. This uniquely identifies the user in the LDAP directory, and is used to bind to the directory so the user's password can be verified. The attribute specified in Login Authentication Attribute is used when you bind as any user. The value of the attribute specified in Authorization Attribute is stored in authentication.subject.id, and can be used by subsequent filters in the policy (for example, Authorization filters that authorize the authenticated user).

  3. If no results are returned from the search, the user is not found in the directory. It is important that the administrator user configured on the Configure LDAP Server window has the ability to see the user that you are attempting to authenticate.

  4. If multiple 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.

Create an LDAP repository

To create a new LDAP repository, right-click LDAP Repositories, and select Add a new Repository. The details entered on the Authentication Repository dialog 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. However, you can also connect to alternative LDAP directories.

The following subsections demonstrate how to configure this window 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 (formerly iPlanet and Sun Directory Server), use the following settings:

  • Repository Name:

    Enter a suitable name for this user store.

  • Directory Name:

    Click Add/Edit to add details of your Oracle Directory Server. For more details, see Configure LDAP directories.

The User Search Conditions section instructs the API Gateway to search the LDAP tree according to the following conditions:

  • Base Criteria:

    Enter where the API Gateway should begin searching the LDAP directory (for example, cn=Users, dc=qa, dc=vordel, dc=com).

  • User Class:

    Enter or select the name given by the particular LDAP directory to the User class. For Oracle Directory Server, select 'inetorgperson' LDAP Class.

  • 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 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 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. In Oracle Directory Server, the Distinguished name is referred to as the entrydn or Entry Domain Name. Select Entry Domain Name to uniquely identify the client authenticating to the API 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 Entry Domain Name (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 message attribute.

  • Authorization Attribute Format:

    Because any user attribute can be specified in the Authorization Attribute above, you must inform the API Gateway of the type of this attribute. This information is used internally by the API 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. The values enter 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. For more details, see Configure LDAP directories.

The User Search Conditions instruct the API Gateway to search the LDAP tree according to certain criteria. The values specified 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 (for example, cn=Users, dc=qa, dc=vordel, dc=com.

  • User Class:

    In Active Directory Server, the user class is called User, so select 'User' LDAP Class.

  • User Search Attribute:

    This 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, which represents the name of the user. Enter givenName in this field.

  • 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 API 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 API 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 API 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 provide 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 API 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 API Gateway to do this, leave the Login Authentication Attribute field blank. The API 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 API 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.

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 API Gateway (for example, HTTP POST).

  • Include query string:

    Select whether the query string parameters are used by the OAM server to determine the policy that protects this resource. This setting is optional if the policies configured do not rely on the query string parameters.

  • Client location:

    If the client location must be passed to OAM for it to make its decision, you can enter a valid DNS name or IP address to specify this location.

  • Optional Parameters:

    You can add optional additional parameters to be used in the authentication decision. The available optional parameters include the following:

    ip IP address, in dotted decimal notation, of the client accessing the resource.
    operation Operation attempted on the resource (for HTTP resources, one of GET, POST, PUT, HEAD, DELETE, TRACE, OPTIONS, CONNECT, or OTHER).
    resource The requested resource identifier (for HTTP resources, the full URL).
    targethost The host (host:port) to which resource request is sent.


[Note] Note

One or more of these optional parameters may be required by certain authentication schemes, modules, or plugins configured in the OAM server. To determine which parameters to add, see your OAM server configuration and documentation.

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 authentication or HTTP digest authentication 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.

OAM Access Server SDK Directory:

Enter the path to your OAM Access Server SDK directory. For more details on the OAM Access Server SDK, see your Oracle Access Manager documentation.

Further information

For details on using filters to integrate the API Gateway with Oracle Access Manager, see Part 23, “Oracle Access Manager filters”.

Oracle Entitlements Server 10g repositories

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

For example, the API Gateway can extract credentials from the message sent by the client, and delegate authentication to OES 10g. When the client has been authenticated, the API Gateway queries OES 10g 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 OES 10g repository, right-click Oracle Entitlements Server 10g 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 Oracle Security Service Module settings (10g).

RADIUS repositories

You can configure the API 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 Configure 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 API 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 API 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 API 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 API Gateway can connect directly to an Authorization Server. If the Authorization Server with the highest priority in the Connection Group is not available, the API 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 under the External Connections tree node in the 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 Configure 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 API Gateway with RSA Access Manager, see RSA Access Manager authorization.

Tivoli repositories

The API 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 details on how to configure the API Gateway to communicate with a Tivoli server, see Tivoli integration.