API Gateway Version September Authentication and Authorization Integration Guide

Transcription

1 API Gateway Version September 2017 Authentication and Authorization Integration Guide

2 Copyright 2017 Axway All rights reserved. This documentation describes the following Axway software: Axway API Gateway No part of this publication may be reproduced, transmitted, stored in a retrieval system, or translated into any human or computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual, or otherwise, without the prior written permission of the copyright owner, Axway. This document, provided for informational purposes only, may be subject to significant modification. The descriptions and information in this document may not necessarily accurately represent or reflect the current or planned functions of this product. Axway may change this publication, the product described herein, or both. These changes will be incorporated in new versions of this document. Axway does not warrant that this document is error free. Axway recognizes the rights of the holders of all trademarks used in its publications. The documentation may provide hyperlinks to third-party web sites or access to third-party content. Links and access to these sites are provided for your convenience only. Axway does not control, endorse or guarantee content found in such sites. Axway is not responsible for any content, associated links, resources or services associated with a third-party site. Axway shall not be liable for any loss or damage of any sort associated with your use of third-party content.

3 Contents Preface 5 Who should read this guide 5 Related documentation 5 Support services 6 Training services 6 Accessibility 7 Screen reader support 7 Support for high contrast and accessible use of colors 7 1 CA SiteMinder integration 8 Flow description 8 Prerequisites 8 Configuration process 9 Configure API Gateway as the SiteMinder agent 9 Add CA binaries to API Gateway 10 Register API Gateway as the SiteMinder agent 10 Configure SiteMinder connection 12 Configure SiteMinder authentication policy 12 Create an authentication repository 12 Configure routing to the protected resource 13 Configure the SiteMinder authentication and authorization policy 13 Configure single sign-on 14 Configure custom cookie creation 14 Configure the cookie check 15 Configure SiteMinder session validation 16 Deploy the policy 17 Configure inserting a SAML authentication assertion 18 Test the policy 19 2 IBM Tivoli Access Manager integration 20 Flow description 20 Prerequisites 21 Configuration process 21 Configure API Gateway for IBM Tivoli Access Manager 21 Install the Tivoli Access Manager runtime environment 22 Generate Tivoli configuration files 22 Configure Tivoli connection 24 Upload Tivoli configuration files in Policy Studio 24 Axway API Gateway Authentication and Authorization Integration Guide 3

4 Upload Tivoli configuration files manually 25 Configure Tivoli repository 26 Configure API Gateway policy 27 Configure a Tivoli authorization policy 27 Configure a Tivoli attribute retrieval policy 28 Configure a Tivoli demo setup 29 Create a Tivoli objectspace 29 Add users and web services to Tivoli 29 Axway API Gateway Authentication and Authorization Integration Guide 4

5 Preface API Gateway contains a set of message filters that directly or indirectly restrict access to resources or web services. Filters that directly control access include XML-signature verification, CA certificate chain verification, and SAML assertion verification. With these filters, policy decisions are made and enforced within API Gateway itself. Filters that indirectly control access offload the policy decision to an external access management system. With these filters, the policy decision is made by the external system but then enforced by API Gateway. API Gateway can leverage your existing Identity Management infrastructure, thus avoiding the need to maintain separate silos of user information. For example, if you already have a database full of user credentials, API Gateway can authenticate requests against this database rather than using its own internal user store. Similarly, the API Gateway can authorize users, look up user attributes, and validate certificates against third-party Identity Management servers. This guide describes how to configure API Gateway to integrate with the following products: CA SiteMinder see CA SiteMinder integration on page 8. IBM Tivoli Access Manager for e-business see IBM Tivoli Access Manager integration on page 20 Who should read this guide The intended audience for this guide is personnel in charge of the technical integration of an API Gateway solution. Related documentation The following reference documents are available on the Axway Documentation portal at API Management Concepts Guide This guide describes how API Gateway, API Manager, and API Portal are used to publish, promote, and manage APIs in a secure and scalable environment. API Management Plus Concepts Guide This guide describes how AxwayAPI Management Plus is used to create APIs from cloud applications and on-premise services, control the use of APIs, and enable self-service consumption of APIs. Axway API Gateway Authentication and Authorization Integration Guide 5

6 Preface Axway Supported Platforms Lists the different operating systems, databases, browsers, and thick client platforms supported by each Axway product. Axway Interoperability Matrix Provides product version and interoperability information for Axway products. Support services The Axway Global Support team provides worldwide 24 x 7 support for customers with active support agreements. support@axway.com or visit Axway Support at See "Troubleshoot your API Gateway installation" in the API Gateway Administrator Guide for the information that you should be prepared to provide when you contact Axway Support. Training services Axway offers training across the globe, including on-site instructor-led classes and self-paced online learning. For details, go to: Axway API Gateway Authentication and Authorization Integration Guide 6

7 Accessibility Axway strives to create accessible products and documentation for users. This documentation provides the following accessibility features: Screen reader support on page 7 Support for high contrast and accessible use of colors on page 7 Screen reader support Alternative text is provided for images whenever necessary. The PDF documents are tagged to provide a logical reading order. Support for high contrast and accessible use of colors The documentation can be used in high-contrast mode. There is sufficient contrast between the text and the background color. The graphics have the right level of contrast and take into account the way color-blind people perceive colors. Axway API Gateway Authentication and Authorization Integration Guide 7

8 CA SiteMinder integration 1 CA SiteMinder is a centralized web access management system that provides user authentication and single sign-on, policy-based authorization, identity federation, and auditing of access to web applications and portals. This section describes how to configure API Gateway to authenticate and authorize end users using CA SiteMinder CA SiteMinder authenticates end users and authorizes them to access protected web resources. API Gateway can request SiteMinder to authenticate end users using the user profiles stored in the SiteMinder server. SiteMinder decides whether the user should be authenticated, and API Gateway then enforces this decision. API Gateway can also request SiteMinder to make authorization decisions on behalf of end users that have successfully authenticated to API Gateway. For more information on CA SiteMinder, go to the CA Technologies website. Flow description SiteMinder authentication flow starts when an end user uses browser to attempt to access a resource protected with CA SiteMinder on API Gateway. First, API Gateway checks if the request from the user contains a valid session cookie for SiteMinder. If API Gateway does not find a valid session cookie the flow is as follows: 1. End user is prompted to provide the login credentials. 2. API Gateway forwards the credentials to SiteMinder. 3. SiteMinder decides whether the user is authenticated and authorized for the requested resource. If the authentication is successful, SiteMinder returns a session cookie and a response to API Gateway. 4. API Gateway stores the session cookie from SiteMinder in the siteminder.session message attribute and creates a custom cookie. 5. API Gateway returns a message with the cookie and a success response to the end user, and authorizes the user to access the requested resource. On subsequent requests to access the protected resource, the end user sends the cookie to API Gateway in the request message. API Gateway retrieves the cookie and validates it against SiteMinder. The end user stays authenticated for the entire lifetime of the session cookie. As long as the session cookie is valid, API Gateway does not need to re-authenticate the end user against SiteMinder for every request. This increases throughput and performance considerably. Prerequisites Before you start, you must have the following: Axway API Gateway Authentication and Authorization Integration Guide 8

9 1 CA SiteMinder integration API Gateway installed CA SiteMinder installed and configured For more details on the installation and the initial configuration of CA SiteMinder, see the CA SiteMinder documention. It is recommended you familiarize yourself with this documentation before you start integrating API Gateway with CA SiteMinder. Configuration process The example policy is build in stages, starting with a simple authentication and authorization policy for SiteMinder that is then refined by adding further filters. The example policy uses HTTP Basic to authenticate the end user, but you can replace it with another authentication mechanism, if required. The following steps are required to integrate API Gateway with CA SiteMinder: 1. Configure API Gateway as the SiteMinder agent on page 9. Configure API Gateway as the SiteMinder agent on page 9. Register API Gateway as the SiteMinder agent on page Configure SiteMinder connection on page Configure SiteMinder authentication policy on page 12. Create an authentication repository on page 12. Configure routing to the protected resource on page 13. Configure the SiteMinder authentication and authorization policy on page Configure single sign-on on page 14. Configure custom cookie creation on page 14. Configure the cookie check on page 15. Configure SiteMinder session validation on page 16. Configure API Gateway as the SiteMinder agent This section describes how to configure API Gateway to act as an agent for CA SiteMinder. Add CA binaries to API Gateway on page 10 Register API Gateway as the SiteMinder agent on page 10 o Register agent on Windows on page 10 o Register agent on UNIX/Linux on page 11 Axway API Gateway Authentication and Authorization Integration Guide 9

10 1 CA SiteMinder integration Add CA binaries to API Gateway Integration with CA SiteMinder requires CA SiteMinder SDK version sp02 or later. You must add the required third-party binaries to your API Gateway installation. 1. Ensure that any SiteMinder binaries you may have previously added to API Gateway have been deleted. 2. Install CA SiteMinder SDK. 3. Copy the following jar files from the java directory of the CA SDK : cryptoj.jar smagentapi.jar smjavasdk2.jar 4. Add the files to the following directory on API Gateway: On Windows: INSTALL_DIR\apigateway\ext\lib On UNIX/Linux: INSTALL_DIR/apigateway/<platform>/lib 5. Restart API Gateway. Register API Gateway as the SiteMinder agent Before API Gateway can act as a Policy Enforcement Point (PEP) for SiteMinder, you must register API Gateway as an agent for CA SiteMinder Policy Server. With the smreghost tool, you can register the agent from the command line, and create the SmHost.conf file. The agent needs to be registered on the machine running the API Gateway instance. You must run the smreghost tool separately on each individual API Gateway instance. The SmHost.conf file is generated in the same directory as the smreghost tool. Before you start, you need the following information on your CA SiteMinder Policy Server: IP address Login credentials (user name and password) Host Configuration Object name To obtain this information, contact your SiteMinder administrator. Register agent on Windows 1. Open a command prompt to INSTALL_DIR\apigateway\ext\lib. 2. Run the smreghost tool as follows: smreghost -i <CA SiteMinder host> -u <user name> -p Axway API Gateway Authentication and Authorization Integration Guide 10

11 1 CA SiteMinder integration <password> -hc <Host Configuration Object name> hn <hostname> For example: smreghost -i u GatewayAgent -p XXXXXX - hc V6HostConfObject hn apigateway.axway.int The hostname must be the fully qualified machine name of the host machine running API Gateway. 3. To enable debug output from the Siteminder agent, add the following to jvm.xml if needed: <ConfigurationFragment> <VMArg name="-dsmjavasdk_log_info=true"/> </ConfigurationFragment> Register agent on UNIX/Linux 1. Go to INSTALL_DIR/apigateway/<platform>/lib. 2. Run the following: export LD_LIBRARY_PATH=INSTALL_ DIR/apigateway/<platform>/lib 3. Run the smreghost tool as follows: smreghost -i <CA SiteMinder IP address> -u <user name> -p <password> -hc <Host Configuration Object name> hn <hostname For example: smreghost -i u GatewayAgent -p XXXXXX - hc V6HostConfObject hn apigateway.axway.int The hostname must be the fully qualified machine name of the host machine running API Gateway. 4. To enable debug output from the Siteminder agent, add the following to jvm.xml if needed: <ConfigurationFragment> Axway API Gateway Authentication and Authorization Integration Guide 11

12 1 CA SiteMinder integration <VMArg name="-dsmjavasdk_log_info=true"/> </ConfigurationFragment> Configure SiteMinder connection This section describes how to configure API Gateway to connect to CA SiteMinder using Policy Studio. For more details on working in Policy Studio, see API Gateway Policy Developer Guide. Before you start, you need the following information for your CA SiteMinder Policy Server: Web Agent name Agent Configuration Object name To obtain this information, contact your SiteMinder administrator. 1. In the node tree, click Environment Configuration > External Connections > SiteMinder/SOA Security Manager Connections. 2. Select Add a SiteMinder connection. 3. Enter your agent name (apigateway.axway.int) and agent configuration object name (V6HostConfObject) you created in Register API Gateway as the SiteMinder agent on page Click Browse, select the SmHost.conf file for your agent, and click OK. For more details on the fields and options in this configuration window, see "Configure SiteMinder/SOA Security Manager connections" in API Gateway Policy Developer Guide. Configure SiteMinder authentication policy This section describes how to configure an authentication policy in Policy Studio for API Gateway to authenticate to CA SiteMinder. For more details on working in Policy Studio, see API Gateway Policy Developer Guide. Create an authentication repository 1. In the node tree, click Environment Configuration > Authentication Repositories> SiteMinder Repositories. 2. Select Add a new Repository, and enter a name for your repository (for example, SiteMinder repository). 3. Set Agent Name to the agent you registered (GatewayAgent), and click OK. For more details on the fields and options in this configuration window, see "CA SiteMinder repositories" in API Gateway Policy Developer Guide. Axway API Gateway Authentication and Authorization Integration Guide 12

13 1 CA SiteMinder integration Configure routing to the protected resource 1. In the node tree, click Policies. 2. Add a new policy, and enter a name for it (Route to protected resource). 3. Open the Routing category in the palette, drag a Connect to URL filter onto the policy canvas, and enter a name for your filter (Route to protected resource). 4. Enter the URL for your protected resource, and click Finish. 5. Right click the filter, and select Set as Start. The SiteMinder authentication and authorization policy calls to this protected routing policy using a Policy Shortcut filter. For more details on the fields and options in this configuration window, see "Connect to URL" in API Gateway Policy Developer Guide. Configure the SiteMinder authentication and authorization policy This sections describes how to configure a policy to authenticate and authorize an end user existing in a CA SiteMinder repository. To start, add a new policy named, for example, SiteMinder. 1. Open the Authentication category, and drag a HTTP Basic filter onto the policy canvas. 2. Set the following, and click Finish: Credential Format: User name Repository name: <your SiteMinder repository> (SiteMinder repository) For more details on the fields and options in this configuration window, see "HTTP Basic authentication" in API Gateway Policy Developer Guide. 3. Open the CA SiteMinder category, and drag a Authorization filter onto the policy canvas. 4. Enter a name for the filter (for example, Authorize user with SiteMinder), and click Finish. For more details on the fields and options in this configuration window, see "SiteMinder authorization" in API Gateway Policy Developer Guide. 5. Open the Utility category, drag a Policy Shortcut filter onto the policy canvas. 6. Set Policy Shortcut to the routing policy you created (Route to protected resource), and click Finish. 7. Connect the filters with a success path. Axway API Gateway Authentication and Authorization Integration Guide 13

14 1 CA SiteMinder integration 8. Click on the Add Relative Path icon to create a new relative path (for example, /siteminder) that links to this policy. 9. Deploy the new configuration to API Gateway. The policy looks like this: The policy has the following flow: API Gateway authenticates the end user using HTTP Basic. API Gateway passes the end user s credentials to SiteMinder. SiteMinder authenticates the end user, authorizes the end user for the particular resource, and sends a response to API Gateway. API Gateway routes the request to a policy shortcut calling the protected resource. Configure single sign-on In a production deployment, it is not practical to authenticate and authorize each user for each request. Instead, you can configure API Gateway to store the SiteMinder session cookie for single sign-on (SSO). After an end user is successfully authenticated, API Gateway can create a custom cookie and place the SiteMinder session cookie validated for that end user as the cookie value. On later request, instead of re-authenticating the user every time, API Gateway can check if the request contains a valid session cookie. If a valid session cookie is found, the end user does not have to be authenticate again. API Gateway can also insert a SAML authorization assertion for downstream web services to consume. This section expands the previously configured SiteMinder authentication policy. To start, copy your SiteMinder authentication and authorization policy (SiteMinder), and rename it (for example, SiteMinder Single Sign-On. Configure custom cookie creation 1. Open the Conversion category, and drag a Create Cookie filter onto the policy canvas. 2. Set the following: Cookie Name: smcookie Axway API Gateway Authentication and Authorization Integration Guide 14

15 1 CA SiteMinder integration Cookie Value: ${siteminder.session} Path: / 3. Set Max-Age to how long you want the cookie to remain valid, and click Finish. 4. Connect the Authorization filter (Authorize user with SiteMinder) to the Create Cookie filter with a success path. The message attribute ${siteminder.session} was specified in Create an authentication repository on page 12. After the end user is successfully authenticated to SiteMinder, this is the message attribute that contains the end user s SiteMinder session cookie. For more details on the fields and options in this configuration window, see "Create cookie" in API Gateway Policy Developer Guide. Configure the cookie check 1. Open the Attributes category, and drag a Get Cookie filter onto the policy canvas. 2. Set the Cookie Name to smcookie. 3. Select Fail if cookie not found in the message, and click Finish. 4. Right-click the Get Cookie filter, and select Set as Start. Axway API Gateway Authentication and Authorization Integration Guide 15

16 1 CA SiteMinder integration 5. Connect the Get Cookie filter to the HTTP Basic filter with a failure path. If the request from then end user does not contain a valid SiteMinder cookie, the end user is prompted to provide login credentials. For more details on the fields and options in this configuration window, see "Get cookie" in API Gateway Policy Developer Guide. Configure SiteMinder session validation If API Gateway finds a valid session cookie from an incoming request, it uses the cookie value to validate the end user's SiteMinder session. 1. Open the CA SiteMinder category, and drag a Session Validation filter onto the policy canvas. 2. Set Agent Name to your registered SiteMinder agent (GatewayAgent). 3. Set Selector Expression to retrieve session to ${cookie.smcookie.value}, and click Finish. 4. Connect the Get Cookie filter to the Session Validation filter with a success path. 5. Connect the Session Validation filter to the Authorization filter (Authorize user with SiteMinder) with a success path. Axway API Gateway Authentication and Authorization Integration Guide 16

17 1 CA SiteMinder integration 6. Connect the Session Validation filter to the HTTP Basic filter with a failure path. If the SiteMinder session cannot be validated, the end user is prompted to provide login credentials. For more details on the fields and options in this configuration window, see "SiteMinder session validation" in API Gateway Policy Developer Guide Deploy the policy 1. Click on the Add Relative Path icon to create a new relative path (for example, /siteminder_sso) that links to this policy. 2. Deploy the new configuration to API Gateway. You have now configured a simple policy for single sign-on in SiteMinder authentication. The policy has the following flow: API Gateway checks if the request contains a valid custom cookie. If a valid custom cookie is not found, the end user is prompted to provide login credentials. If a valid custom cookie is found, API Gateway retrieves the value of the cookie and uses that to check if the end user's session cookie in SiteMinder is still valid. If the session cookie is no longer valid, the end user is prompted to provide login credentials. SiteMinder authorizes the user to access the requested resource and sends response with the SiteMinder cookie back to API Gateway. API Gateway creates a custom cookie to hold the end user's SiteMinder session cookie. API Gateway calls to the protected resource using the routing policy. API Gateway sends the response along with the custom cookie to the end user. Axway API Gateway Authentication and Authorization Integration Guide 17

18 1 CA SiteMinder integration This policy can be part of a larger policy, including features such as XML threat detection and conditional routing (not described in this guide). You can also authenticate the user with some other authentication method instead of HTTP Basic. In addition, you can add additional filters, such as messages in case of failures: Configure inserting a SAML authentication assertion You can extend the single sign-on to downstream web services, if required. After the end user is successfully authenticated and authorized, API Gateway adds a SAML authentication assertion that the web services can consume to the response message. 1. Open the Authorization category, and drag a Insert SAML Authentication Assertion filter onto the policy canvas. 2. On the Assertion details tab, select any issuer on the Issuer Name list, and set the expiry date for the SAML authentication assertion. 3. On the Assertion Location tab, make sure that Add to WS-Security Block with SOAP Actor/Role is selected and SOAP Actor/Role set to Current Actor/Role Only. 4. On the Advanced tab, select Insert SAML Attribute Statement and Indent, then click Finish. 5. Connect the filter between the Create Cookie and the Policy Shortcut filters with success Axway API Gateway Authentication and Authorization Integration Guide 18

19 1 CA SiteMinder integration paths. For more details on the fields and options in this configuration window, see "Insert SAML authorization assertion" in API Gateway Policy Developer Guide. Test the policy This section describe how to test your SiteMinder policy using a standard browser. 1. Open a web browser in private (incognito) mode to ensure no user is yet logged in. 2. Enter the URL to call your policy: address>:<port>/<path> For example: 3. Enter the login credentials. API Gateway authenticates the user against SiteMinder and returns the response along with the SiteMinder session cookie. 4. Refresh the browser to access the protected resource. Because the custom cookie (smcookie) is available this time, API Gateway does not prompt for credentials. Instead of reauthentication, API Gateway validates the cookie against the SiteMinder. The Traffic Monitor tab on the API Gateway Manager ( is an excellent place to view and troubleshoot the message flows. For more details, see "Monitor services in API Gateway Manager" in API Gateway Administrator Guide. Axway API Gateway Authentication and Authorization Integration Guide 19

20 IBM Tivoli Access Manager integration 2 IBM Tivoli Access Manager for e-business (TAM) is a commonly used product for securing web resources. You can integrate API Gateway with TAM and leverage your existing access management policies, so you do not have to maintain duplicate policies in both products. All authentication filters can pass identity credentials to TAM for authorization. At runtime, the Tivoli filters in API Gateway can delegate authentication and authorization decisions to TAM, and can also retrieve user attributes. In integration with TAM, a message filter in API Gateway forwards policy decisions to TAM. TAM makes the policy decision, and API Gateway then enforces the decision. The architecture can be seen in the following diagram. API Gateway supports integration with IBM Tivoli Access Manager for e-business v6.1 on Windows. Note Each API Gateway instance can connect to a single Tivoli server. Flow description 1. A client sends a message to API Gateway using, for example, SOAP over HTTPS. 2. API Gateway allocates the message to the appropriate policy and executes the filters. 3. Using Tivoli filters in the policy, API Gateway requests TAM to authenticate, authorize, or retrieve attributes for a given user. Axway API Gateway Authentication and Authorization Integration Guide 20

21 2 IBM Tivoli Access Manager integration 4. TAM makes the security decision based on the user information, and returns the decision to API Gateway. 5. API Gateway enforces the security decision. On success, API Gateway routes the message on to a configured target system. On failure, API Gateway blocks the message and returns an error to the client. Prerequisites IBM Tivoli Access Manager integration has the following prerequisites. An existing API Gateway installation with SP 1 installed An existing IBM Tivoli Access Manager for e-business 6.1 configuration Configuration process The example policy uses HTTP Basic to authenticate the end user, but you can replace it with another authentication mechanism, if required. The following steps are required to integrate API Gateway with IBM Tivoli Access Manager for e- business: 1. Configure API Gateway for IBM Tivoli Access Manager on page 21 Install the Tivoli Access Manager runtime environment on page 22 Generate Tivoli configuration files on page Configure Tivoli connection on page Configure Tivoli repository on page Configure API Gateway policy on page 27 Configure a Tivoli authorization policy on page 27 Configure a Tivoli attribute retrieval policy on page 28 Configure API Gateway for IBM Tivoli Access Manager This section describes how configure API Gateway for integration with IBM Tivoli Access Manager. Axway API Gateway Authentication and Authorization Integration Guide 21

22 2 IBM Tivoli Access Manager integration Install the Tivoli Access Manager runtime environment You must install the Tivoli Access Manager runtime environment on the machine running API Gateway. The runtime environment is not packaged with API Gateway, so you must install it separately. Note The Tivoli Access Manager Java runtime environment is not required. It is recommend to install the Tivoli Access Manager runtime environment using the native utilities instead of the installation wizard to ensure the Tivoli Access Manager Java runtime environment is not installed. The installation wizard requires the Tivoli Access Manager Java runtime environment even though the runtime software does not. Generate Tivoli configuration files API Gateway uses information stored in the Tivoli configuration files to connect to a Tivoli server. You can generate these configuration files using the svrsslcfg command line utility included in the Tivoli Access Manager runtime environment. For more details on this utility, see the Tivoli documentation. 1. Run the svrsslcfg utility. For example: svrsslcfg -config -f "C:\conf\config.conf" -d "C:\conf" -n apigateway -s remote -P XXXXXXXX -S YYYYYYYY -r h test.axway.com The available arguments are as follows: Argument -config Description The command that creates the configuration files required API Gateway uses to communicate with Tivoli. -f The directory and name of the main Tivoli configuration file. This command generates the file in the specified location. -d The directory where to generate the SSL key file (.kdb) for the Tivoli server. This command generates the file in the specified location. -n The name of the application connecting to the Tivoli server (API Gateway). -s The mode how the application (API Gateway) runs. The most likely scenario is that API Gateway runs remotely. Axway API Gateway Authentication and Authorization Integration Guide 22

23 2 IBM Tivoli Access Manager integration Argument Description -P The password of the Tivoli administrator. -S The password for API Gateway. This command sets the password for API Gateway on the Tivoli server. -r The listening port on API Gateway. -h The name of the host running API Gateway. 2. To add a Tivoli authorization server replica, run the following command: svrsslcfg -add_replica -f <main Tivoli config file> -h <Tivoli authorization server> For example: svrsslcfg -add_replica -f "C:\conf\config.conf" -h tivoli.axway.com API Gateway contacts this server to make authorization decisions. The following files are generated in the directory you specified: <name>.conf: the main Tivoli configuration file <name>.kdb: the SSL key file <name>.sth: the stash file for the SSL key file <name>.conf.obf: the database configuration file The files are named as you define for the main configuration file. For example: config.conf: the main Tivoli configuration file config.kdb: the SSL key file config.sth: the stash file for the SSL key file config.conf.obf: the database configuration file Note Depending on the version of API Gateway you are running, the file names might have spaces in them. After creating the configuration files you must upload them to API Gateway using Policy Studio, or manually copy the files to a location on API Gateway's file system. See Configure Tivoli connection on page 24. Axway API Gateway Authentication and Authorization Integration Guide 23

24 2 IBM Tivoli Access Manager integration Configure Tivoli connection Tivoli connections use the Tivoli configuration files to determine how a particular API Gateway instance connects to an instance of a Tivoli server. You can upload the Tivoli configuration files you generated to API Gateway and add the required connection details in the Tivoli Configuration dialog. This section describes how to configure the IBM Tivoli Access Manager (TAM) connection using Policy Studio. For more information on working in Policy Studio, see the API Gateway Policy Developer Guide. Note Each API Gateway instance can connect to a single Tivoli server. The is configured globally under the Server Settings, so it can be reused in filters and policies without the need to reconfigure details again. Upload Tivoli configuration files in Policy Studio 1. In the node tree, click Environment Configuration > Server Settings > Security > Tivoli, and select Add a Tivoli Connection. 2. Select Tivoli Connections > Add a Tivoli Connection, and enter a name on the Tivoli Configuration dialog, or select an existing Tivoli connection to base the new configuration on. 3. Set the following, and click Next: Upload Tivoli configuration files: Select this. Connection enabled: Select this to immediately enable the connection. 4. Click Load File, and select your main Tivoli configuration file (.conf). The contents of the file are displayed in the text area. 5. Change all directory paths of the configuration files in the main configuration file to the absolute paths on API Gateway, then click Next. For example: Axway API Gateway Authentication and Authorization Integration Guide 24

25 2 IBM Tivoli Access Manager integration 6. Click Load File, select the Tivoli SSL key file (.kdb), and click Next. Note The (base-64 encoded) SSL keys cannot be edited in the text area. 7. Click Load File, select the Tivoli SSL stash file (.sth), and click Next. 8. Click Load File, select Tivoli Configuration database configuration file (.conf.obf), and click Finish. 9. In the node tree, click Environment Configuration > Server Settings > Security > Tivoli, ensure the Tivoli connection you just created is selected in the drop-down list, and click Save. 10. Deploy the configuration to API Gateway to upload the files. Note When you upload the configuration files, on each startup and refresh (for example, when configuration updates are deployed), API Gateway overwrites the configuration files to INSTALL_DIR\apigateway\groups\GROUP-NUMBER\PROCESS_ NAME\conf\plugin\tivoli\PROCESS_NAME, where PROCESS_NAME is API Gateway instance. This means that any changes to the main configuration file must be made in Policy Studio, not directly to the file on the disk. Spaces in the API Gateway instance name are substituted with -, and API Gateway names each file as config.<extension>. For example, the directory, INSTALL_ DIR\apigateway\groups\group-2\instance- 1\conf\plugin\tivoli\instance-1 contains config.conf, config.kdb, config.sth, and config.conf.obf. To later disable or enable configured Tivoli connections, select the connection you want, click Edit Tivoli connection, and deselect or select Connection enabled as needed. For more details on the fields and options in this configuration window, see "Configure Tivoli connections" in API Gateway Policy Developer Guide. Upload Tivoli configuration files manually Alternatively, you can manually copy the configuration files to a location on API Gateway to upload the files and create a new Tivoli connection. To configure API Gateway to pick up the uploaded files, perform the following steps: 1. Copy the files to API Gateway's file system. Ensure that the settings in the main configuration file (.conf) pointing to the other configuration files point to the right locations. You must use the full paths to the files. For example: Axway API Gateway Authentication and Authorization Integration Guide 25

26 2 IBM Tivoli Access Manager integration 2. In the node tree in Policy Studio, click Environment Configuration > Server Settings > Security > Tivoli, and select Add a Tivoli Connection. 3. Select Tivoli Connections > Add a Tivoli Connection, and enter a name on the Tivoli Configuration dialog, or select an existing Tivoli connection to base the new configuration on. 4. Enter a name on the Tivoli Configuration dialog. 5. Set the following, and click Next: Set file location for main Tivoli Configuration file: Select this. Connection enabled: Select this to immediately enable the connection. 6. In Server-side Tivoli configuration, enter the full path to the main Tivoli configuration file (for example, INSTALL_DIR\apigateway\groups\group-2\instance- 1\conf\plugin\tivoli\instance-1\config.conf) on the API Gateway's file system, and click Finish. 7. In the node tree, click Environment Configuration > Server Settings > Security > Tivoli, ensure the Tivoli connection you just created is selected in the drop-down list, and click Save. 8. Deploy the configuration to API Gateway to upload the files. Note When the Set file location option is selected, API Gateway does not overwrite the files at startup or refresh time. You can edit the main configuration file directly using an editor of your choice. Configure Tivoli repository A Tivoli repository is used to authenticate clients against a running instance of a Tivoli server. All authentication filters can pass identity credentials to the Tivoli repository in order to authenticate clients. The Tivoli server decides if the client is authenticated, and API Gateway subsequently enforces the decision. Axway API Gateway Authentication and Authorization Integration Guide 26

27 2 IBM Tivoli Access Manager integration This section describes how to configure the IBM Tivoli Access Manager (TAM) repository using Policy Studio. For more information on working in Policy Studio, see the API Gateway Policy Developer Guide. 1. In the node tree, click Environment Configuration > External Connections > Authentication Repositories > Tivoli Repositories, and select Add a new Repository. 2. Enter a name for the repository (for example, Tivoli Repository). 3. Click Settings, ensure the correct Tivoli connection is selected, and click Finish. When configuring an authentication filter, you can select the Tivoli repository to authenticate clients against. The authentication filter uses the connection details of the API Gateway instance was selected for the repository. For more details on the fields and options in this configuration window, see "Tivoli repositories" in API Gateway Policy Developer Guide. Configure API Gateway policy This section describes how to configure policies that leverage IBM Tivoli Access Manager (TAM) in Policy Studio. For more information on working in Policy Studio, see the API Gateway Policy Developer Guide. The Tivoli authentication repository is available from all authentication filters. Here, the example policy uses the HTTP Basic authentication filter to authenticate a client against a Tivoli repository using a user name and password combination. You can configure a different authentication mechanism as required. Configure a Tivoli authorization policy 1. Add a new policy named, for example, IBM Tivoli Authorization. 2. Open the Authentication category in the palette, and drag a HTTP Basic filter onto the policy canvas. 3. Set the following, and click Finish: Credential Format: User Name. Allow client challenge: Select this. Repository Name: The repository you configured (Tivoli Repository). For more details on the fields and options in this configuration window, see "HTTP Basic authentication" in API Gateway Policy Developer Guide. 4. Right-click the HTTP Basic filter, and select Set as Start. 5. Open the Authorization category in the palette, and drag a Tivoli filter onto the policy canvas. 6. Set Object Space to your Tivoli objectspace (for example, axway/test). Axway API Gateway Authentication and Authorization Integration Guide 27

28 2 IBM Tivoli Access Manager integration 7. In Permissions, set the permissions for the client. A client is only authorized to access the requested resource if it has the relevant permissions checked in the table. 8. In Attributes, specify what user attributes, if any, to retrieve from the Tivoli server, and click Finish. For more details on the fields and options in this configuration window, see "Tivoli authorization" in API Gateway Policy Developer Guide. 9. Connect the filters with a success path. 10. Click on the Add Relative Path icon to create a new relative path (for example, /ibm_ tivoli_authorize) that links to this policy, and deploy the policy to API Gateway. Configure a Tivoli attribute retrieval policy You can use the Retrieve from Tivoli filter to retrieve user attributes independently from authorizing the user against Tivoli Access Manager. This example policy is based on the previously configured Tivoli policy. The user is authenticated, but not authorized using Tivoli. Instead, Tivoli is used just to retrieve attributes. 1. Copy the Tivoli policy you created (IBM Tivoli Authorization). 2. Rename it (for example, IBM Tivoli Attribute), and delete the Tivoli filter. 3. Open the Attributes category in the palette, and drag a Retrieve from Tivoli filter onto the policy canvas. 4. Set User ID to ${authentication.subject.id}. Using a selector here enables you to retrieve attributes for multiple end users. 5. Specify what user attributes to retrieve from the Tivoli server, and click Finish. For more details on the fields and options in this configuration window, see "Retrieve attribute from Tivoli" in API Gateway Policy Developer Guide. 6. Connect the filters with a success path. 7. Click on the Add Relative Path icon to create a new relative path (for example, /ibm_ tivoli_attribute) that links to this policy, and deploy the policy to API Gateway. Axway API Gateway Authentication and Authorization Integration Guide 28

29 2 IBM Tivoli Access Manager integration Configure a Tivoli demo setup To test or demonstrate Tivoli Access Manager integration in API Gateway, you may want to configure a test Tivoli objectspace as well as sample users and web services using the pdadmin tool. For more details on the pdadmin tool, see the pdadmin commands. Create a Tivoli objectspace 1. Open a terminal window on the machine running the Tivoli authorization server and management server. 2. Start the pdadmin tool using the following command, where mypwd is the password for the management server: > pdadmin -a sec_master -p mypwd 3. Use the objectspace create command to add a user: pdadmin> objectspace create <objectspace name> <description> 9 The parameter 9 indicates that you are adding a web resource. As the Policy Decision Point (PDP), API Gateway is responsible of mapping an attempt to access a web service to a given object. The Tivoli authorization server does not contain any mapping between its objectspace nodes and URLs. For example: pdadmin> objectspace create /axway/test "For testing purposes" 9 Add users and web services to Tivoli To authorize a user to access a web service, you must first add the user to Tivoli as follows: 1. Add the user as before using the user create command: pdadmin> user create <username> <dn> <cn> <sn> <password> Note Ensure that the DName you assign the user is identical to the DName in the user's certificate. 2. Insert the server that runs your web service into Tivoli's objectspace using the following command: pdadmin> object create /apigateway/<object-name> <description> 9 Axway API Gateway Authentication and Authorization Integration Guide 29

30 2 IBM Tivoli Access Manager integration 3. To bind the user and the object, create an ACL for the object, and add the user to that list: pdadmin> acl create <acl-name> pdadmin> acl modify <acl-name> set user <username> rx pdadmin> acl attach <object-name> <acl-name> 4. To view the details of a user, use the following commands: >user show <username> >objectspace list >acl show <acl-name> For more details on this utility, see the pdadmin commands. Axway API Gateway Authentication and Authorization Integration Guide 30