API Manager Version May User Guide

Transcription

1 API Manager Version May 2018 User Guide

2 Copyright 2018 Axway All rights reserved. This documentation describes the following Axway software: Axway API Manager 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 9 Who should read this guide 9 How to use this guide 9 Related documentation 10 Support services 10 Training services 10 Accessibility 11 Screen reader support 11 Support for high contrast and accessible use of colors 11 Updates and revisions 12 Changes in Introduction to API management 13 API management concepts 13 Overview 13 API registration 13 API development 15 API management lifecycle 15 Introduction to API Management tools 16 API management tools 17 API Management architecture 19 API Management user roles 21 API registration and lifecycle management 23 2 API Manager configuration 25 Configure API Manager 25 Overview 25 Prerequisites 25 Enable API Manager 26 Log into API Manager 26 Configure signed certificates for API Manager ports 27 Configure a API Manager monitoring database 28 Further information 28 Configure API Manager settings in Policy Studio 29 Create a Policy Studio project with API Manager configuration 29 Configure API Manager server settings 29 Customize the default API Manager routing policy for all APIs 35 Axway API Manager User Guide 3

4 Configure API Manager in network protected by an HTTP proxy 35 Configure web-based settings in API Manager 36 Account settings 36 API Manager settings 37 Alerts 40 Remote hosts 40 Configure external LDAP identity providers 42 Overview 42 Configure an Apache Directory LDAP external identity provider 44 Configure a Microsoft Active Directory external identity provider 46 Account information policy 49 Further information 49 3 API management 50 API management workflow 50 Overview 50 Register a back-end REST API in API Manager 50 Virtualize a front-end REST API in API Manager 51 Register REST APIs in API Manager 52 Overview 52 Back-end and front-end APIs 53 Enable an organization for API development 54 Import an existing back-end REST API 54 Import an existing web service back-end API 55 Import an existing Cloud-based back-end API 56 Import an existing back-end API deployed on an API Gateway 56 Manually register a new back-end REST API 57 Create REST API methods 57 Create the REST API model 58 Manage back-end REST API lifecycle 58 Next steps 59 Virtualize REST APIs in API Manager 59 Virtualized REST API security 59 Virtualize a REST API as a front-end API 60 Import a previously exported API 60 Configure Inbound settings 61 Configure Outbound settings 70 Configure API information 74 Configure API method information 75 Configure Security Profiles 76 Configure Authentication Profiles 76 Configure CORS Profiles 76 Configure trusted certificates 77 Manage front-end REST API lifecycle 77 Axway API Manager User Guide 4

5 Administer APIs in API Manager 79 API administration concepts 79 API Manager access control 81 Ensure API Manager is configured correctly 84 Log in to API Manager 84 API administrator view 85 Organization administrator view 86 Manage quotas 87 Manage OAuth authorizations 89 Manage organizations 90 Manage users 92 Manage applications 93 Monitor APIs and applications in API Manager 93 Overview 93 Prerequisites 94 Monitor APIs in API Manager 95 Monitor applications in API Manager 95 Monitoring metrics 95 Filter metrics data 96 Further information 97 Consume APIs in API Manager 98 Overview 98 Consume REST APIs 98 Register an API Manager user account 98 API consumer view 99 Browse and retrieve APIs 100 Manage client applications 101 Manage the client application lifecycle 104 API Manager REST APIs 104 Import the API Manager REST API API deployment 106 Promote managed APIs between environments 106 Overview 106 Promote registered APIs with zero downtime using a script 106 Promote registered APIs using a promotion policy 110 Promote APIs developed in Policy Studio 112 Deploy sandbox and production APIs 112 Overview 112 Production environment topology 113 Promote configuration to sandbox and production APIs 114 Onboard to production APIs 115 Configure high availability 116 Customize API Manager 116 Axway API Manager User Guide 5

6 Overview 116 Customize API Manager data 117 Customize API Manager password validation 120 Customize API Gateway Manager URL 121 Further information 122 Configure custom API Manager routing policies 122 Configure a custom routing policy with API key authentication 122 Configure a custom routing policy with OAuth authentication Application connectors 135 Cloud application connectors 135 Overview 135 API Management for digital transformation 135 Hybrid application integration platform 137 Further information 138 Configure a connector for Salesforce APIs 139 Overview 139 Salesforce.com API use cases 139 Configure an API connector for Salesforce.com 139 Configure OAuth client credentials for Salesforce.com 141 Configure OAuth provider settings for Salesforce.com 142 Import Salesforce.com APIs in API Manager 143 Manage Salesforce.com APIs in API Manager 144 Further information 147 Configure a connector for ServiceNow APIs 147 Overview 147 ServiceNow API use cases 148 Configure an API connector for ServiceNow 148 Configure HTTP basic credentials for ServiceNow 149 Import ServiceNow APIs in API Manager 150 Manage ServiceNow APIs in API Manager 152 Submit XML requests to ServiceNow using API Gateway 154 Configure a connector for Axway API Runtime Services 157 Overview 157 API Builder use cases 157 Configure an API connector for API Runtime Services 158 Configure credentials for API Runtime Services 160 Import API Builder application APIs in API Manager 161 Manage API Builder application APIs in API Manager 163 Connect to Axway Mobile Backend Services 165 Overview 165 Mobile Backend Services use cases 165 Mobile Backend Services REST API 165 Create a Mobile Backend Services app 166 Axway API Manager User Guide 6

7 Virtualize the Mobile Backend Services API in API Manager 167 Generate an SDK for virtualized Mobile Backend Services APIs in API Portal 169 Further information API Manager single sign-on 170 Single sign-on using SAML 170 SSO concepts 170 SSO message flows 171 Authentication sequence 171 Logout sequence 172 Configure API Manager SSO 172 Prerequisites 173 API Manager implementation behavior 173 Configuration files 174 Sample files 174 Step 1 Set up a keystore 175 Step 2 Create a service-provider.xml file 175 Step 3 Specify the IdP 176 Step 4 Configure SSO in Policy Studio 177 Step 5 Configure SAML endpoint URLs 178 Manage IdP certificates 179 Configure the SSO cookie domain name 180 Mapping syntax 180 Examples 183 Filter syntax 185 Configuration file elements 186 SSO troubleshooting 189 Logging in both as administrator and SSO user 190 Cannot access API Manager after successful login 190 IdP site cannot be reached 190 Internal error if API Gateway and IdP clocks out of sync 190 LDAP response timeout during login 191 Invalid user or password error after successful login 191 Shibboleth IdP logout failure 192 Logout issues with Active Directory Federation Services 193 Enable traces for SSO 194 SAML assertion validation fails 194 Invalid requester in Keycloak page 194 Error on signing assertions 195 Keycloak fails to authenticate the user API alerting 196 API management alerts 196 Overview 196 Axway API Manager User Guide 7

8 Alert descriptions 196 Application alerts 196 API registration alerts 197 API catalog alerts 198 API consumer alerts 198 Organization alerts 199 Quota alerts 199 Enable or disable alerts 200 Change the alert policy to execute 201 Read API access 202 Overview 202 General settings 202 Further information 203 Read API proxy 203 Overview 203 General settings 203 Further information 204 Read application 204 Overview 204 General settings 204 Example policy 204 Further information 205 Read API consumer 205 Overview 205 General settings 205 Further information 205 Read organization 206 Overview 206 General settings 206 Further information 206 Axway API Manager User Guide 8

9 Preface This guide describes how to use the API Manager tools to register, virtualize, and manage web-based Application Programming Interfaces (APIs). API Manager is an additional licensable layered product that runs on API Gateway. Who should read this guide The intended audience for this guide includes API owners, API administrators, and API consumers. This guide explains each user role in detail. How to use this guide This guide should be used in conjunction with the other guides in the API Manager, API Gateway, and API Portal documentation sets. Before you begin, review this guide thoroughly. The following is a brief description of the contents: Introduction to API management on page 13: Provides an overview of API management concepts and user roles, and the API Manager tools. API Manager configuration on page 25: Explains how to access the web-based API Manager console, and how to configure API Manager settings. API Manager single sign-on on page 170: Describes API Manager single sign-on (SSO). API management on page 50: Explains how to use the API Manager web console to register, virtualize, administer, and consume existing REST-based APIs. API deployment on page 106: Explains how to promote and deploy managed APIs, and how to rebrand and customize the API Manager web console. Application connectors on page 135: Describes how to connect to and manage cloud-based applications, such as Salesforce.com and ServiceNow. API management alerts on page 196: Explains how to configure API Manager to generate alerts when specific events occur (for example, when an organization is created or deleted). Note For details on using the Policy Studio tool to create REST APIs or policies to virtualize existing non-rest APIs (for example, for SOAP to REST), see the API Gateway Policy Developer Guide. Axway API Manager User Guide 9

10 Preface Related documentation The API Management Plus solution enables you to create, publish, promote, and manage Application Programming Interfaces (APIs) in a secure and scalable environment. For more information, see the API Management Plus Getting Started Guide. The following reference documents are available on the Axway Documentation portal at Supported Platforms Lists the different operating systems, databases, browsers, and thick client platforms supported by each Axway product. 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 "Get help with API Gateway" 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 Manager User Guide 10

11 Accessibility Axway strives to create accessible products and documentation for users. This documentation provides the following accessibility features: Screen reader support on page 11 Support for high contrast and accessible use of colors on page 11 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 Manager User Guide 11

12 Updates and revisions Updates and revisions This guide includes the following documentation changes. Changes in Added a new topic on configuring cloud application connectors for API Builder application APIs. This describes how to configure connectors in Policy Studio and how to import API Builder application APIs in API Manager. The topic on API Manager monitoring includes an updated prerequisites section. This describes the metrics database requirements and the necessary configuration steps. Screenshots have been updated to reflect the new product branding in the API Manager web console. The topic on API management workflow has been updated to include RAML import. The topic on registering REST APIs in API Manager has been updated to clarify that importing RAML files with references to external files is not supported. The sections on rebranding the API Manager user interface have been removed from the topic on customizing API Manager The topic on configuring API Manager in Policy Studio includes a new section on customizing the default API Manager routing policy for all APIs. Axway API Manager User Guide 12

13 Introduction to API management 1 This part contains the following: API management concepts 13 Introduction to API Management tools 16 API management concepts Overview API management is the process of publishing, promoting and managing Application Programming Interfaces (APIs) in a secure, scalable environment. It includes the creation of API consumer support resources that define and document APIs to facilitate easy consumption. API management supports business initiatives to enable easy interaction with customers and partners. A well-executed API strategy helps create more selling channels, better engage with customers, and offer more value to partners. This practice of doing better business through the effective delivery of APIs enables the API economy. API management uses new Web-Oriented Architecture (WOA) technologies such as REST, JSON, and OAuth instead of traditional Service-Oriented Architecture (SOA) technologies. Axway API Manager and API Gateway provide a comprehensive solution for creating, virtualizing, and managing APIs of varying complexity and capability. This includes the following approaches: API registration virtualizing existing REST APIs and SOAP web services in API Manager API development developing new REST APIs in Policy Studio to be exposed in API Manager (for example, virtualizing non-rest APIs) This topic introduces API management, its overall architecture, and terms. It also explains the differences between API registration and API development, explains the overall API management lifecycle, and describes the main use cases. API registration API management focuses on registering existing REST APIs, and managing their consumption by customers and partners to support their business objectives. REST APIs are registered using the API Manager web console. REST APIs are managed directly by API Manager using authentication, Axway API Manager User Guide 13

14 1 Introduction to API management authorization, and quota policies defined in the client registry. API administrators can use API Manager to manage API consumption, and API consumers can consume the virtualized APIs using API Manager, or using a customized self-service API Portal. API management is performed by an API owner (a technical business or IT operational role). Registration of REST APIs in API Manager, and application of policies to those APIs, is a configuration task rather than a development task. It can be performed on a running API Gateway in a production environment. This approach enables you to manage and promote APIs more dynamically, more rapidly, and with less overhead than typical IT projects. API Manager provides a web-based interface that enables API owners to register existing back-end REST APIs, apply standard policies, and virtualize them on API Gateway as public front-end APIs. The APIs are immediately available for management in API Manager, and for consumption in API Manager, or in a self-service API Portal. The following diagram shows a simplified API management architecture: API registration terms The following terms are used to describe API registration using API Manager: Back-end API the actual REST API that is routed to, secured, and exposed on the network (for example, application server), or in the Cloud (for example, Twitter). This REST API can be registered manually in API Manager, or by importing a Swagger or Web Application Description Language (WADL) definition in API Manager. Front-end API the virtualized publicly exposed REST API in API Manager that is hosted on the API Gateway, and which client applications invoke (for example, iphone or Android client apps). By default, the front-end API is the same as the back-end API, proxying the API as is. However, you can edit the front-end API to present an enriched, public-facing API to client applications. Axway API Manager User Guide 14

15 1 Introduction to API management API package the complete package of artifacts associated with an API registered in API Manager. This is used to export and import the API in a single package to enable promotion from sandbox to production APIs. API development This approach focuses on developing new REST APIs from existing non-rest legacy back-end applications, cloud-based applications, and SOA or security infrastructure. For example, this includes exposing a SOAP Web service as a REST API, or combining multiple cloud application API calls into higher level business methods, or implementing an OAuth client. API development is performed by a policy developer using Policy Studio. The REST API development wizard is provided in the Policy Studio tool. This enables policy developers to create a REST API, and route it to a pre-built policy (for example, which connects to a back-end SOAP Web service, database, or cloud application). APIs developed using the REST API development wizard are then registered (by importing) as a back-end APIs in API Manager. This means that there is a single consistent approach for registering APIs, virtualizing as front-end APIs, and managing how APIs are consumed in API Manager, regardless of the back-end API. Registered APIs are virtualized by API Gateway, which protects the back-end services, and makes the APIs available for management and consumption in API Manager, and for consumption in the selfservice API Portal. For more details on creating APIs using the REST API development wizard, see the API Gateway Policy Developer Guide. API management lifecycle The following diagram summarizes the API management lifecycle: Axway API Manager User Guide 15

16 1 Introduction to API management The API management lifecycle is described in the diagram as follows: 1. API registration If the back-end API is an existing REST API, an API owner uses API Manager to register the APIs and apply standard policies. The registered APIs are virtualized by API Gateway, which protects the back-end services, and makes the APIs available for consumption. This describes the typical API management approach. For more details, see the following: Register REST APIs in API Manager on page 52 Virtualize REST APIs in API Manager on page 59 If the existing back-end API is not a REST API, or if custom policies are required, a policy developer uses Policy Studio to create a new API (for example, for SOAP to REST, or cloudbased applications). APIs developed in Policy Studio are then imported as back-end APIs in API Manager. For more details, see the API Gateway Policy Developer Guide. 2. API promotion When APIs are registered using API Manager, an API administrator can promote them between environments directly using API Manager (for example, from sandbox to production APIs). When APIs are created using the REST API development wizard in Policy Studio, an API Gateway administrator can promote them using the API Gateway mechanism for promotion and deployment of API Gateway configuration. For more details, see Promote managed APIs between environments on page API administration The API administrator manages and monitors the APIs at runtime using API Manager. For example, this includes all organizations and users registered to log into API Manager, client applications and their authentication credentials, and authorization and quota policies. The API administrator manages who can consume, what they can consume, and how much can they consume. For example, which business partners are permitted to consume which APIs, and what are their quota levels. For more details, see Administer APIs in API Manager on page API consumption API consumers can self-register in API Manager or API Portal. They browse and consume the managed APIs provided by API Gateway, and use them to develop and test their applications. The organization administrators in named organizations manage the applications and API consumer users. For example, API consumers might be internal developers or external business partners. They can log into API Manager or API Portal, and browse APIs and their associated documentation for consumption. They can then develop and test client applications that use these APIs. In this way, API Manager builds a community around the APIs, enabling organizations and consumers to register themselves, and to create and manage their own applications. For more details, see Consume APIs in API Manager on page 98. Introduction to API Management tools API Manager provides a web-based interface that enables an API owner (technical business or IT operational role) to easily register back-end REST APIs, apply policies, and to virtualize them on API Axway API Manager User Guide 16

17 1 Introduction to API management Gateway. Policy Studio also provides a REST API development wizard, which enables policy developers to virtualize non-rest back-end APIs as REST APIs (for example, virtualize a SOAP web service as a REST API). API Portal is a self-service web-based portal that enables API consumers to consume the APIs that you have exposed in API Manager. This topic explains the API management features provided by the API Manager and API Portal tools. It also includes the API Manager architecture, user roles, and API lifecycle states. API management tools Axway provides the following tools to enable you to virtualize and manage your APIs: API Manager The API Manager web interface enables business or operational users (API owners) to easily register REST APIs and apply standard policies defined in the client registry to virtualize the APIs. It enables organizations and API consumers to consume APIs, browse the API Catalog, and monitor their API use. It also enables business or operational users (API administrators) to manage API clients and their consumption of APIs. API Manager provides a role-based interface, in which API Manager users are assigned a role (for example, API consumer, API administrator, API owner, or organization administrator). The operations that a user can perform in API Manager depend on the role they are assigned. For example, a user assigned the API owner role can register and virtualize REST APIs. API Manager is implemented as a web application that is hosted on the API Gateway. The default API Manager has Axway branding, and can be customized to use different branding. API Manager also has a management API that enables organizations to integrate with custom portals and other existing systems. API Gateway This is the runtime gateway that proxies the REST APIs registered in API Manager, and that enforces configured policies on client requests and responses. API Manager is a layered product running on API Gateway, and which provides all the underlying gateway capabilities. API Gateway is a prerequisite product for API Manager. API Catalog This is the read-only catalog of APIs and their associated documentation registered in API Manager. Client application developers can browse API Catalog in API Manager and in API Portal. APIs can be tagged for classification and searching. API Catalog is represented in Swagger format for tool integration. Client Registry This is the repository of organizations and partners, API consumers, and client applications that consume the REST APIs. The Client Registry also contains the authentication credentials of the client applications, and authorization and quota policies defined at the organization and application level. The Client Registry is persisted in an Apache Cassandra backing store. Policy Studio includes API Management filters that provide read-only access to the Client Registry. These enable policy developers to develop policies in Policy Studio that leverage the information in the Client Registry. Write access to the Client Registry must be performed using the API Manager API because data consistency checks are required. Axway API Manager User Guide 17

18 1 Introduction to API management REST API development wizard This wizard in Policy Studio enables you to create new REST APIs that route to policies developed in Policy Studio. This enables you to develop REST APIs from non-rest back-end applications and services, integrating with them at the application and security levels. For more details on creating APIs using the REST API development wizard, see the API Gateway Policy Developer Guide. API Portal API Portal is a self-service web-based portal that enables API consumers to consume APIs that you have exposed for organizations API Manager. API consumers can register and manage their user profile, register applications, manage application credentials, browse front-end APIs and supporting documentation, monitor application API usage, and access blogs, forums, and so on. API Portal is implemented as a stand-alone CMS-based portal, which you can run using the default Axway branding and functionality, or customize and extend to meet your specific requirements and those of your target API consumers. You can deploy the internet-facing API Portal separately from the API Gateway and API Manager, with a dedicated web interface to limit potential security breaches. For more details, see API Portal Installation and Upgrade Guide. API Manager API This REST-based API provides the underlying capabilities supporting API Portal and API Manager. This API enables the management of the data in the Client Registry and the browsing of registered APIs, with API documentation returned in Swagger format. The API Manager API enables the development of custom API consumer portals and integration with external partner management systems. API Manager features The main API Manager features are API registration, API promotion, API administration, and API consumption. For details on these features in the API management lifecycle, see API management concepts on page 13. In addition to the main features, API Manager also provides the following features to enable you to manage your APIs: Partner organization management API Manager includes partner-based management of API consumers that browse the API Catalog and client applications that use the APIs. Delegated partner administration enables partner organizations to manage their own API consumers, easing the management of large partners, or a large number of partners. A wide range of client application credentials are supported, including OAuth 2.0 and API keys. Policy management API Manager enables you to apply authorization and quota policies to APIs at the partner and client application levels. Custom policies can also be developed in Policy Studio, and applied to APIs. Axway API Manager User Guide 18

19 1 Introduction to API management API alerting API Manager enables you to configure API, partner, policy and runtime events to generate alerts that trigger governance processes. For example, this includes sending an notification or starting application workflows. API import and export Registered APIs can be exported from API Manager and imported to another API Manager using a file-based package. This enables APIs to be promoted from a sandbox API group (where client applications are developed and tested) to the production API group. You can configure an API promotion policy to automate this process. API Portal features The main API Portal features are as follows: Developer self-registration and profile management Client application developers can self-register and manage their profiles. Browse and test APIs in the API Catalog The API Catalog contains the APIs that have been registered in API Manager and are available for use by client application developers. They can browse these APIs and their associated documentation, and invoke APIs using the built-in test capability. Create and manage applications Application developers can register their applications that will use the APIs, and obtain API key or OAuth credentials for the application. They can also monitor their application's use of APIs using graphical real-time data sourced from API Manager metrics. Content management, blogs, and discussion forums API Portal runs on Joomla!, which is an open source CMS platform for developing and deploying web sites. You can use the content management capabilities of Joomla to store additional content, such as PDF documents and video, for display in API Portal. Joomla also provides plugins for third-party blog and discussion forums. Customizable to provide a branded experience You can deploy API Portal with no customization, using the out-of-the-box Axway branding, which is suitable for internal-facing API deployments. For external-facing API deployments, you can customize API Portal to provide a branded developer portal experience. You can customize API Portal using Joomla configuration screens (upgradeable), or by editing the API Portal PHP source code (not upgradeable). For more details, see the API Portal User Guide. API Management architecture This section describes the overall architecture of Axway API Management. The main components in the diagram are described as follows: Axway API Manager User Guide 19

20 1 Introduction to API management The API provider is the enterprise that makes the virtualized APIs for back-end applications available for API clients to consume. The API provider runs API Gateway and API Manager. For example, the API provider could be a credit card company that provides payment services to various customers. The API clients are the end-user customer and partner organizations that consume the APIs made available by the API provider. For example, these could be specific hotel and retail organizations that enable their customers to make payments by credit card. Organization types include the following: Named organization This is an organization that is known, trusted, and preapproved (for example, a business partner of the API provider). This organization is defined in the client registry, and organizationspecific access to the APIs can be managed (for example, specifying which API consumers can browse, and which applications can invoke). Community organization This is the organization of unverified, untrusted API consumers that are not explicitly tied to any specific organization. These are API consumers that register to browse the APIs and develop applications. The Community organization is intended to be a mechanism to recruit API consumers to build client applications. Axway API Manager User Guide 20

21 1 Introduction to API management Community API consumers can subsequently be associated with a named organization and become trusted. It is not intended that production-level client applications run in the Community organization, but that these users and their applications move into trusted named organizations before the application goes into production. API owner organization This is an organization that is enabled in API Manager for registration of APIs. It supports all the capabilities of organizations for consuming APIs with the additional capability of supporting the registration of APIs. In API Manager, each organization includes an option to enable it as an API owner organization: o o If this is not selected, the organization only supports the consumption of APIs (the default). If this is selected, APIs can be registered in the organization The APIs that are displayed for an API owner organization are as follows: o o APIs that have been registered in that API owner organization. Other APIs that the API owner organization has been given authorization for by the API administrator. API Management user roles The following diagram shows where the API Management user roles fit into this architecture: Axway API Manager User Guide 21

22 1 Introduction to API management API provider user roles The API provider user roles in the diagram are described as follows: API owner The API owner uses API Manager to virtualize managed APIs and apply standard policies. This role has the privileges of the client-side API consumer role but with the additional privileges of API registration in the API owner organization that they are assigned to. This is a non-technical role, and is typically more of a business or operational user who has knowledge of what the APIs do, and why clients need to access them. However, in some organizations this role will be performed by an API developer. API administrator This is the administrator role responsible for managing the consumption of APIs by registered API clients. This role manages and monitors the virtualized APIs and the client applications that use those APIs. The tasks include managing organization and user registration, application authentication credentials, authorization and quota entitlement policies, and monitoring API use. These tasks are performed using API Manager. This administrator role is typically more of a business or operational user who has knowledge of what the APIs do, and why clients need to access them. API Gateway administrator This administrator role monitors, manages, and troubleshoots API Gateway using the API Gateway Manager web console. They have full administrative privileges, including deployment of API Gateway configurations. This is the system administration or operational role for API Gateway. It involves keeping API Gateway running, monitoring its operation, managing any settings, and performing any troubleshooting. For more details, see the API Gateway Administrator Guide. Policy developer This is the API Gateway developer who uses the REST API development wizard in Policy Studio to virtualize APIs and create API Gateway policies. Policies are rules used to govern or manage an API (for example, for security, integration, SLA monitoring, or transformation). This is a technical developer role. For more details, see the API Gateway Policy Developer Guide. API client user roles The API client user roles in the diagram are described as follows: API consumer The API consumer or client application developer implements and tests client applications that consume some managed APIs. API consumers can be from named organizations or from the Community organization. This role can also include operator users who are responsible for managing client applications in production, and need to monitor their API use. Each user has an account on API Manager. API consumers can create applications, manage their registration details, and monitor API use by their applications. Axway API Manager User Guide 22

23 1 Introduction to API management Organization administrator This is the onsite administrator responsible for managing the API consumers and applications in a particular named organization. The API administrator may delegate administrative privileges to the organization administrator allowing them to use API Manager to manage API consumers and applications in their organization (for example, assigning application privileges to a new API consumer). In addition, the organization administrator in an API owner organization also has API registration capabilities. Finally, a community organization does not have an organization administrator, and is managed by the API administrator. Note In this architecture, client applications are authenticated by API Gateway. The end users of client applications are not authenticated by API Gateway. To authenticate end users, you must build additional request policy logic when virtualizing the REST API. API registration and lifecycle management API Manager enables you to register APIs and manage their lifecycle from registration through publishing and retirement. Delegated API registration enables different teams of API owners to register and test their own APIs in isolation prior to publishing to other organizations in the API Catalog. In API Manager, the lifecycle of an API includes the following states: 1. Unpublished The API is registered and tested in isolation in an API owner organization. The API is available to the API administrator and API owners who are members of that organization. The API can be edited, or be moved to the published state, or deleted. These actions can only be performed by the API owner or the API administrator. Unpublished APIs are displayed in the API Catalog view to users in the same organization. The users in this organization are the API owners and developers on the same team working on these APIs. However, an unpublished API is not displayed to users in other organizations. The API must first be published, and then that organization must be authorized to access the API. The API is then displayed in the API Catalog for users in that organization. Note All APIs published and unpublished are displayed in the API Catalog for the API administrator. 2. Published When an API is ready to be consumed by other organizations, it is published in the API Catalog by the API owner. The API administrator must then approve the API as the final step to publish to other organizations in the API Catalog. When the API is published, the API administrator can authorize other organizations to access the API. This displays the API in API Manager and API Portal to API consumers who are members of the authorized organization. When an API is published, only the API administrator can make changes. The published API can only be deprecated or unpublished, and cannot be deleted. Unpublishing an API stops client applications in other organizations using the API. A published API cannot be edited, and must first be unpublished. However, the API administrator can edit the API documentation of a published API. This allows changes in the API documentation without impacting the API availability. Axway API Manager User Guide 23

24 1 Introduction to API management 3. Deprecated The published API in API Manager is flagged with a date when it will be unpublished in the API Catalog, and is no longer available to client applications in other organizations. The retirement date is displayed to API consumers in API Manager and API Portal. Retiring the API is achieved by unpublishing the API in the API Catalog. Only a published API can be deprecated and unpublished. When the API is unpublished, it is then available for API owners to edit. When an API is deprecated, it is still in the published state, and clients can continue to discover and use the API. This gives API consumers time to port their existing applications to adopt a newer version of the API. You can undeprecate an API by selecting the undeprecate option, which removes the retirement date flag in the API Catalog. Axway API Manager User Guide 24

25 API Manager configuration 2 This part contains the following: Configure API Manager 25 Configure API Manager settings in Policy Studio 29 Configure web-based settings in API Manager 36 Configure external LDAP identity providers 42 Configure API Manager Overview This topic describes the steps required to configure the API management features available in Axway API Manager. For an introduction to Axway API Management features, see the API Management Concepts Guide. Note API Manager is enabled by default when you install a Complete setup type, or install API Manager and the Quick Start tutorial as part of a Custom setup type. You only need to enable API Manager if Quick Start is not installed with API Manager. Prerequisites Before you begin, you must ensure the following: Ensure that both API Manager and API Gateway and are installed. API Manager is a layered product running on API Gateway, which provides the underlying gateway capabilities. API Gateway is a prerequisite product for API Manager. Ensure that an API Gateway Admin Node Manager and an API Gateway instance have been created and started. Ensure that Apache Cassandra is installed and running, and that the Cassandra hosts have been configured in Policy Studio. For more information on installing and configuring Cassandra, see "Install Apache Cassandra" in the API Gateway Installation Guide. For more details on installing and starting API Gateway and API Manager, see the API Gateway Installation Guide. Axway API Manager User Guide 25

26 2 API Manager configuration Enable API Manager Note If you selected to install API Manager and the Quick Start tutorial, API Manager is enabled by default, and you can skip to the next section. However, if you installed API Manager, but did not install the Quick Start tutorial, you must perform the following steps: 1. Change to the following directory: UNIX/Linux INSTALL_DIR/apigateway/posix/bin Windows INSTALL_DIR\apigateway\Win32\bin 2. Run the following command: setup-apimanager -n "SERVER_INSTANCE_NAME" -g "GROUP_NAME" For example: setup-apimanager -n "Test Server" -g "Test Group" For more details on available options, enter the following: setup-apimanager --help 3. Enter the Admin Node Manager credentials that you specified when installing the Admin Node Manager. 4. Enter the API administrator credentials that you specified when installing API Manager. After the script completes, the API Gateway instance restarts automatically. Note You must run setup-apimanager on a newly created API Gateway instance with no group passphrase. You can set a new API Gateway group passphrase after running setup-apimanager on a group configuration without the passphrase. After changing the group passphrase, you must re-encrypt the API Manager KPS collections using the kpsadmin tool. For more details, see the API Gateway Key Property Store User Guide. Log into API Manager 1. Enter the following URL in your browser: Axway API Manager User Guide 26

27 2 API Manager configuration 2. Log in using the API administrator credentials that you specified when installing API Manager, or when prompted by setup-apimanager. Note For security reasons, it is recommended that you change the default credentials. For more details, see Administer APIs in API Manager on page 79. Configure signed certificates for API Manager ports The default certificates used to secure the ports for API Manager and its runtime traffic are selfsigned and must not be used in a production system. Instead, you must use a server certificate signed by a trusted Certificate Authority (for example, Verisign). The default certificates are signed by Axway and are for demonstration purposes only. To configure signed server certificates for these API Manager ports, perform the following steps in Policy Studio: 1. Add the server certificates signed by a trusted Certificate Authority to the API Gateway certificate store, and ensure that their start and expiry dates are valid. For more details, see "Manage X.509 certificates and keys" in the API Gateway Policy Developer Guide. 2. Configure the API Manager port to use the signed server certificate: i. Select Environment Configuration > Listeners > API Gateway > API Portal > Ports. ii. Double-click API Portal Port on the right to open the Configure HTTPS Interface dialog. The default port is iii. On the Network tab, click X.509 Certificate to select the signed server certificate. 3. Configure the API Manager runtime traffic port to use the signed server certificate: i. Select Environment Configuration > Listeners > API Gateway > API Manager Traffic > Ports. ii. Double-click Portal Traffic HTTPS Interface on the right to open the Configure HTTPS Interface dialog. The default port is iii. On the Network tab, click X.509 Certificate to select the signed server certificate. The default self-signed certificate is named CN=Change this for production. The following example shows the default certificate for the API Manager runtime traffic port that you need to change: Axway API Manager User Guide 27

28 2 API Manager configuration For more details on configuring certificates for HTTPS interface ports, see the "Configure HTTP services" in the API Gateway Policy Developer Guide. Configure a API Manager monitoring database To monitor and report on APIs in API Manager, you must perform the following steps: 1. Configure a JDBC-compliant database used to store historic reports. The following databases are supported: Oracle MySQL Microsoft SQL Server IBM DB2 2. Configure the API Gateway for monitoring. For example, you must ensure that real-time monitoring is enabled on the API Gateway, and that writing metrics data to the database is enabled. For more details, see the API Gateway Installation Guide. Further information For more details on API Manager configuration, see the following topics: Configure API Manager settings in Policy Studio on page 29 Configure web-based settings in API Manager on page 36 Axway API Manager User Guide 28

29 2 API Manager configuration Configure API Manager settings in Policy Studio Policy Studio enables you to configure a range of settings that apply to API Manager and the underlying API Gateway. This topic describes how to create a Policy Studio project with API Manager configuration, and how to configure each of the API Manager settings. Create a Policy Studio project with API Manager configuration To create a Policy Studio project with API Manager configuration, perform the following steps: 1. Ensure that your API Gateway installation has already been configured for API Manager using the setup-apimanager script. For more details, see Configure API Manager settings in Policy Studio on page Create a project from one of the following: API Gateway instance API Gateway configuration directory.fed,.pol, or.env file For more details on creating projects, see the Get Started section in the API Gateway Policy Developer Guide. Configure API Manager server settings In the Policy Studio tree, select Environment Configuration > Server Settings > API Manager to configure the settings described in this topic. Alerts The Alerts settings enable you to configure runtime alerts, which call specified policies to handle the alert event. For example, the policy might send an to an interested party, or forward the alert to an external notification system. Sample policies are provided as a starting point for custom development. You can enable or disable alerts in the API Manager web interface. You can change the policy that is executed when an alert is generated on this screen. For more details, see API management alerts on page 196. Axway API Manager User Guide 29

30 2 API Manager configuration API Listeners The API Listeners settings enable you to configure API Gateway listeners to service API Managerregistered APIs. Defaults to Portal Listener. Note This screen only displays listeners that do not have a relative path resolver on the / relative path. For more details on API Gateway listeners, relative paths, and resolvers, see the API Gateway Policy Developer Guide. API Promotion The API Promotion settings enable you to configure an optional policy that is invoked when APIs registered in API Manager are promoted between environments (for example, from a test or sandbox environment to a live production environment). To select a promotion policy, click the browse button on the right, and select a policy that you have already created. By default, no API promotion policy is selected. For more details, see Promote managed APIs between environments on page 106. API Connectors The API Connectors settings enable you to configure client authentication profiles to use with specific API connectors and plugins. For example, this includes connecting to Cloud APIs such as Salesforce.com and Google. A preconfigured plugin for Salesforce.com APIs is provided by default. For more details, see Cloud application connectors on page 135. Identity Provider The Identity Provider settings enable you to integrate API Manager with a wide range of external user repositories. For example, this includes third-party identity providers such as Apache Directory, OpenLDAP, Microsoft Active Directory, and so on. To enable integration, select Use external identity provider, and configure the following set of custom policies: Account authentication policy: Click the browse button, and select the required authentication policy that is invoked whenever a user tries to log in to API Manager. This setting is mandatory. Account information policy: Click the browse button, and select the required information policy that is invoked on first login to seed the user profile in API Manager. This setting is mandatory. For more details, see Configure external LDAP identity providers on page 42. Account creation success (optional): Click the browse button, and select an optional policy that is invoked when a new user has been registered with API Manager. Axway API Manager User Guide 30

31 2 API Manager configuration Account creation failure (optional): Click the browse button, and select an optional policy that is invoked when an attempt to register a new account with API Manager has failed. API Manager provides sample external identity provider configuration. For more details, see Configure external LDAP identity providers on page 42. Note The Identity Provider settings are used only to configure integration of API Manager with external user repositories. All other API Manager data is stored using a Key Property Store (KPS) in an Apache Cassandra cluster. For more details, see the API Gateway Key Property Store User Guide. Monitoring The Monitoring settings allow you to configure monitoring metrics in API Manager: Enable monitoring: Select whether to enable monitoring metrics displayed on the Monitoring tab in API Manager. Monitoring is enabled by default. Use the following database: Click the browse button to configure the connection to the database that stores the monitoring metrics. For more details, see "Configure database connections" in the API Gateway Policy Developer Guide. For more details on monitoring, see Monitor APIs and applications in API Manager on page 93. OAuth Outbound Credentials The OAuth Outbound Credentials setting enables you to configure optional client credentials for use with OAuth outbound authentication. These enable clients to request an OAuth access token using only their client credentials with the authorization specified in the header. By default, no credentials are configured. For more details, see the following: Configure custom API Manager routing policies on page 122 provides a detailed example of using these credentials with a custom OAuth routing policy API Gateway OAuth User Guide provides more details on OAuth API Gateway Policy Developer Guide explains how to create policies OAuth Token Information Policies The OAuth Token Information Policies setting enables you to configure optional policies used by external OAuth security devices in API Manager. These include custom policies used to obtain and extract token information from external OAuth providers. By default, no policies are configured. For more details, see the following: Axway API Manager User Guide 31

32 2 API Manager configuration Virtualize REST APIs in API Manager on page 59 explains how to configure security devices API Gateway OAuth User Guide provides more details on OAuth API Gateway Policy Developer Guide explains how to create policies OAuth Token Stores The OAuth Token Stores settings enable you to configure OAuth token stores for the OAuth security devices used by API Manager-registered APIs. Click Add to configure an OAuth access token store. To add a store, right-click Access Token Stores, and select Add Access Token Store. Defaults to OAuth Access Token Cache. For more details on OAuth, see the API Gateway OAuth User Guide. Quota Settings The Quota Settings enable you to configure how quota information is stored. Quotas enable you to manage the maximum message traffic rate that can be sent by applications to APIs. For more details on configure quotas in API Manager, see Administer APIs in API Manager on page 79. You can configure the following settings in Policy Studio: Send warning if API usage reaches: Enter the % of System Quota and % of Application Quota that must be reached before warnings are sent to the API administrator. Both API usage values default to 80 per cent. For more details, see Manage quotas on page 87. Where to store quota data: Select In external storage or In memory only. This setting defaults to In external storage, and to keep the quota in memory only if the time window is below 30 seconds. In this case, if the API administrator configures a quota in API Manager with a time window below 30 seconds, the data is stored in memory instead of in external storage. Alternatively, to never use external storage, select In memory only to store data in memory in all cases. If you select In external storage, you must specify an external storage mechanism: o o o Automatic (adapt to KPS storage configuration): The data is stored externally as configured in the Key Property Store (KPS). This is the default option. For more details, see the API Gateway Key Property Store User Guide. Use database: To store your data in a relational database, select this option, and specify the database connection that you want to use in Environment Configuration > External Connections > Database Connections. For more details, see the API Gateway Policy Developer Guide. Use Cassandra: To store your data in an Apache Cassandra database, select this option. For more details, see "Install Apache Cassandra" in the API Gateway Installation Guide. Axway API Manager User Guide 32

33 2 API Manager configuration Cassandra consistency levels: When Use Cassandra is selected, you can configure Read and Write consistency levels for the Cassandra database. These settings control how up-to-date and synchronized a row of data is on all of its replicas. For high availability, you must ensure that the Cassandra read and write consistency levels are both set to QUORUM. For more details on consistency levels, see the following tml Note Quota data is not shared for those quotas created in API Manager with a time window less than the value configured in Policy Studio, irrespective of the storage selected. This could impact on throttling in an HA environment, where multiple API Gateways are servicing requests and contributing to total message counts. Inbound Security Policies The Inbound Security Policies settings enable you to configure the custom security policies that can be applied to APIs registered in API Manager. These policies enable you to perform custom policy-based authentication on front-end APIs. API Manager provides a number of built-in authentication policies to secure APIs (for example, API keys and OAuth 2.0), which you can select when creating front-end APIs. You can extend the builtin authentication policies with custom authentication policies that have been developed in Policy Studio. For example, a custom policy could use CA SiteMinder to authenticate client application requests to APIs. In addition, custom authentication policies can specify a message that is displayed in the API Catalog informing application developers of the authentication mechanism to use when accessing the API. To configure your custom inbound security policies, click Add, and select the appropriate policies in the dialog. The configured polices are added to the list. Note Inbound security policies must set the authentication.subject.id message attribute to match the client ID set in the external credentials of the application. For details on how to create polices, see the API Gateway Policy Developer Guide. For details on applying inbound security policies to front-end APIs, see Virtualize REST APIs in API Manager on page 59 Request Policies The Request Policies settings enable you to configure optional request processing policies for virtualized APIs in API Manager. For example, you could use the configured policies to check request messages for authentication or authorization. To configure request policies, click Add, and select policies in the dialog. By default, no request policies are configured. Axway API Manager User Guide 33

34 2 API Manager configuration Note Request Policies, Response Policies, and Routing Policies apply to APIs registered using the API Manager, and do not apply to policies registered using Policy Studio. These policies enable policy developers to implement enterprise-specific request policies in Policy Studio that can be applied to multiple APIs in API Manager. For details on how to create polices, see the API Gateway Policy Developer Guide. Response Policies The Response Policies settings enable you to configure optional response processing policies for virtualized APIs in API Manager. For example, you could use the configured policies to validate or transform outbound response messages. To configure response policies, click Add, and select policies in the dialog. By default, no response policies are configured. For details on how to create polices, see the API Gateway Policy Developer Guide. Routing Policies The Routing Policies settings enable you to configure custom routing policies for virtualized APIs in API Manager. For example, you could use the configured policies to route to a back-end JMS service. To configure routing policies, click Add, and select policies in the dialog. By default, no routing policies are configured, and the default URL-based routing policy is used. For more details, see Customize the default API Manager routing policy for all APIs on page 35. For detailed examples of using custom routing policies based on API key and OAuth, see Configure custom API Manager routing policies on page 122. For more details on how to create API Gateway polices in Policy Studio, see the API Gateway Policy Developer Guide. SMTP Server Under SMTP Server settings, to send s (for example, for user registration or client application approval), you must configure an SMTP server for API Manager in the Policy Studio. The default setting is Portal SMTP server on localhost. Note You must ensure that API Manager is configured with the SMTP server used by your organization to generate s for user registration or client application approval. For example, to configure your SMTP server, perform the following steps: 1. Click the browse button on the on the right of the SMTP Server field. 2. Right-click Portal SMTP, and select Edit. 3. Complete the SMTP settings in the dialog. The following example settings use the Gmail SMTP server: Name: Name for your SMTP server (for example, Acme Portal SMTP Server). Axway API Manager User Guide 34

35 2 API Manager configuration SMTP Server Hostname: Hostname of your SMTP server (for example, smtp.gmail.com). Port: SMTP server port number (for example, 465). User Name: Your user name (for example, Password: Your password. For more details on SMTP configuration, see the API Gateway Policy Developer Guide. Note When finished updating your API Manager configuration, remember to click Apply Changes at the bottom of the window, and then Deploy in the toolbar. Customize the default API Manager routing policy for all APIs You can customize the default URL-based routing used by API Manager by modifying the default Connect To URL filter in Policy Studio. To edit this default policy, select Policies > Generated Policies > REST APIs > Templates > Default URL-based Routing, and double-click the Connect to URL filter in the policy canvas on the right. For example, under Settings > Failure > Call connection policy on failure, you could configure a custom policy with a Reflect message filter that modifies the default 500 response code to 503 when the API Manager runtime cannot connect to a back-end service. Updating this default routing policy modifies how API Manager manages connection failures globally for all APIs, without needing to modify each API. Note After updating this default routing policy, you do not need to restart the underlying API Gateway, redeploying the updated configuration is sufficient. For more details on how to create API Gateway polices in Policy Studio, see the API Gateway Policy Developer Guide. Configure API Manager in network protected by an HTTP proxy If you are using API Manager in a network protected by an HTTP proxy that requires authentication, you must perform some additional configuration steps. Configure a proxy server For API Manager to connect to the back-end API through a proxy, the routing policy used must be configured with a proxy server. For example, perform the following steps: 1. In the Policy Studio tree, select Policies > Generated Policies > REST APIs > Templates > Default URL-based Routing. 2. Double-click the Connect to URL filter to edit it, and select the Settings tab. Axway API Manager User Guide 35

36 2 API Manager configuration 3. Select Proxy > Send via proxy. 4. In the Proxy Server field, browse to the configured proxy server. If a proxy server has not already been configured, right-click Proxy Servers, and select Add a Proxy Server. For more details, see the API Gateway Policy Developer Guide. 5. Click Deploy in the toolbar to deploy the updated configuration. Update the JVM settings The following JVM setting is also required when importing the API in API Manager. This is because API Manager uses Java to download the API: <ConfigurationFragment> <VMArg name="-dhttp.proxyhost=ip_address" /> <VMArg name="-dhttp.proxyport=1234" /> <VMArg name="-dhttp.nonproxyhosts=localhost " /> <VMArg name="-dhttp.proxyuser=some_name" /> <VMArg name="-dhttp.proxypassword=some_password" /> </ConfigurationFragment> Configure web-based settings in API Manager This topic describes how to configure the options available on the Settings tab in the API Manager web console. Account settings You can configure the following settings for your account: General Configure the following: Image: Click to add a graphical image for the account (for example,.png,.gif, or.jpeg file). Login name: Enter a user login name for the account. The default is apiadmin. This is the default API administrator user suplied by API Manager. Enter an address for the account. The default is apiadmin@localhost. Enabled: Select whether the account is enabled. The apiadmin account is enabled by default. Created on: Displays the date and time at which the account was created. Current state: Displays the state of the account. The apiadmin account is Approved by default. Axway API Manager User Guide 36

37 2 API Manager configuration Membership Configure the following: Role: Displays the membership role of the account. The default apiadmin account has an API Manager Administrator role. Additional attributes Configure the following: Phone: Enter a contact phone number for the account. Description: Enter a description for the account. The default apiadmin account is described as API Administrator. Password Configure the following: Change password: Click to change the current password for the account. Note It is strongly recommended that you change the default password for security reasons. API administrators can change the password for any internal (non-on-boarded) API Manager user. Organization administrators can change the password for any internal user associated with their organization. External user passwords on-boarded from external identity providers cannot be changed. Further information For more details on user and application management, see Administer APIs in API Manager on page 79. API Manager settings You can configure the following settings on the API Manager tab: API Manager settings Configure the following: API Manager name: Enter the name displayed for API Manager in the notifications sent to API providers (for example, your company name or website). Defaults to Axway API Manager. This setting is required. Axway API Manager User Guide 37

38 2 API Manager configuration API Manager host: Enter the host name that API Manager is available on. Defaults to the API Manager IP address. Note It is not recommended to have spaces or the URL encoded %20 in the host name. reply to: Enter the reply to address for sent from API Manager (for example, the automatically generated s sent when user accounts are created). Defaults to bounce: Enter the address used to receive messages about the non-delivery of automatically generated . Defaults to Demo mode: Select whether demo mode is enabled. When this setting is enabled, API Manager automatically generates random data, and displays metrics on the Monitoring tab without needing to send traffic through the API Gateway. Demo mode is disabled by default. Trial mode: Select whether trail mode is enabled for all organizations. Trial mode allows the API administrator to manage the lifespan of the organization, including any resources that belong to that organization (for example, users or applications). When this setting is enabled, API Manager displays TRIAL settings for the administrator when editing the organization on the Client Registry > Organizations page. Trial mode is disabled by default. For more details on managing organizations, see Manage organizations on page 90. Default trial duration: When Trial mode is enabled, enter the duration of the trial in days. Defaults to 30 days. When the trial has ended, the organization expires, and users of the expired organization can no longer log in. API Portal settings Configure the following: API Portal: Select whether to enable API Portal. You should enable this setting when you have an existing API Portal installation working with API Manager. When enabled, links in notifications are addressed to the API Portal host (specified in API Portal host and port), or to the API Manager host (specified in API Manager settings on page 37), depending on whether you are an API consumer or API provider. This setting is disabled by default. API Portal name: Enter the name displayed for API Portal in notifications sent to API consumers (for example, your company name or website). Defaults to Axway API Portal. This setting is required. API Portal host and port: Enter the host name or IP address and port used in autogenerated links sent to API consumers (for example, The host is required, and the port is optional. If you do not enter a value, the default port is 443. Note Enter the host and port (optional), but not the scheme. For example, example.com:443 or example.com is correct, but or is incorrect. For more details on API Portal, see the API Portal User Guide. Axway API Manager User Guide 38

39 2 API Manager configuration General settings Configure the following: User registration: Select whether to enable automatic user registration. This is enabled by default. Forgot password: Select whether to enable the Forgot Password tab on the main API Manager login page. For some user-providers (for example, LDAP), you cannot reset the user password, so you may need to disable this feature. This is enabled by default. Minimum password length: Select the minimum number of characters required for user passwords. Defaults to 6. Auto-approve user registration: Select whether automatic approval of user registration requests is enabled. This is enabled by default. Auto-approve applications: Select whether automatic approval of client applications is enabled. This is enabled by default. Login name regular expression: Enter a valid regular expression to restrict the login names that you can enter. This does not retrospectively enforce login names. If you change the default setting, you must update the loginnamevalidationmessage in app.config. Defaults to [^;,\\/?#<>&;!]{1,}. Enable OAuth scopes per application: Select whether to enable OAuth scopes at the level of the client application. This allows the API administrator to create application-level scopes to permit access to OAuth resources that are not covered by API-level scopes. This is not enabled by default. For more details, see the API Gateway OAuth User Guide. Idle session timeout (minutes): Enter the number of minutes after which idle API Manager sessions time out. Defaults to 60 minutes. Changing this value only affects logins made after the change. Organization administrator delegation Configure the following: Delegate user management: Select whether organization administrators can create or remove applications, and approve requests from users to create applications. This is enabled by default. Delegate application management: Select whether organization administrators can create or remove applications, and approve requests from users to create applications. This is enabled by default. API registration Configure the following: Axway API Manager User Guide 39

40 2 API Manager configuration API default virtual host: Enter a host and port on which all registered and published APIs are available. The specified host must be DNS resolvable. API promotion via policy: Select whether APIs can be promoted using a policy specified in Policy Studio. For more details, see API Promotion on page 30 in Policy Studio. Enabling the API promotion via policy setting forces a reload of API Manager, and you must log in again. A Promote API option is also then added to the Frontend API management menu. This setting is disabled by default. For an overview of API promotion, see Promote managed APIs between environments on page 106. Further information For more details on user and application management workflows, see Administer APIs in API Manager on page 79. Alerts You can use API Manager to enable or disable alert notifications for specific events (for example, when an application request is created, or an organization is created). When an alert is generated by API Manager, you can execute a custom policy to handle the alert (for example, to send an to an interested party, or to forward the alert to an external notification system). You can use the alert settings in Policy Studio to select which policies are configured to handle each event. For more details, see API management alerts on page 196. Remote hosts The remote host settings enable you to dynamically configure connection settings to back-end servers that are invoked by front-end APIs. API Administrators can edit all remote hosts in all organizations. Required settings Configure the following required settings: Name: Enter the remote host name (for example, Port: Enter the TCP port to connect to on the remote host. Defaults to 80. Maximum connections: Enter the maximum number of connections to the remote host. If the maximum number of connections is reached, the underlying API Gateway waits for a connection to drop or become idle before making another request. Defaults to -1, which means there is no limit. Axway API Manager User Guide 40

41 2 API Manager configuration Organization: The organization to which the remote host belongs. This is only displayed for API administrators. General settings Configure the following optional settings: Allow HTTP 1.1: The underlying API Gateway uses HTTP 1.0 by default to send requests to a remote host. This prevents any anomalies if the destination server does not fully support HTTP 1.1. If the API Gateway is routing to a remote host that fully supports HTTP 1.1, you can use this setting to enable the API Gateway to use HTTP 1.1. This is disabled by default. Include Content-Length in request: When this option selected, the underlying API Gateway includes the Content-Length HTTP header in all requests to this remote host. This is disabled by default. Include Content-Length in response: When this option selected, the underlying API Gateway includes the Content-Length HTTP header in all responses to this remote host. This is disabled by default. Send SNI TLS extension to server: Adds a Server Name Indication (SNI) field to outbound TLS/SSL calls that shows the name the client used to connect. For example, this is useful if the server handles several different domains, and needs to present different certificates depending on the name the client used to connect. This is disabled by default. Verify server's certificate matches requested hostname: Ensures that the certificate presented by the server matches the name of the remote host connected to. This prevents host spoofing and man-in-the-middle attacks. This setting is enabled by default. Advanced settings Configure the following advanced settings: Connection timeout: If a connection to this remote host is not established within the time specified in this field, the connection times out and fails. Defaults to milliseconds (30 seconds). This setting is required. Active timeout: When the underlying API Gateway receives a large HTTP request, it reads the request off the network when it becomes available. If the time between reading successive blocks of data exceeds the active timeout, the API Gateway closes the connection. This prevents a remote host from closing the connection while sending data. Defaults to milliseconds (30 seconds). This setting is required. Transaction timeout: A configurable transaction timeout that detects slow HTTP attacks (slow header write, slow body write, slow read) and rejects any transaction that keeps the worker threads occupied for an excessive amount of time. The default value is milliseconds. This setting is required. Idle timeout: The underlying API Gateway supports HTTP 1.1 persistent connections. The idle timeout is the time that API Gateway waits after sending a message over a persistent connection to the remote host before it closes the connection. Defaults to milliseconds Axway API Manager User Guide 41

42 2 API Manager configuration (15 seconds). Typically, the remote host tells the API Gateway that it wants to use a persistent connection. The API Gateway acknowledges this, and keeps the connection open for a specified period of time after sending the message to the host. If the connection is not reused by within the Idle Timeout period, the API Gateway closes the connection. This setting is required. Include correlation ID in headers: Specifies whether to insert the correlation ID in outbound messages. This means that an X-CorrelationID header is added to the outbound message. This is a transaction ID that is attached to each message transaction that passes through API Gateway, and which is used for traffic monitoring in the API Gateway Manager web console. You can use the correlation ID to search for messages in the web console, and you can also access its value from a policy using the id message attribute. This setting is selected by default. This setting is enabled by default. Further information The remote host settings available in API Manager are a subset of the settings available in Policy Studio. For more details on remote hosts, see the API Gateway Policy Developer Guide. Configure external LDAP identity providers Overview API Manager provides policy-based integration with external identity providers using Lightweight Directory Access Protocol (LDAP). For example, this enables internal API Manager users such as API administrators to use their existing LDAP user account to log into API Manager. However, they must still use their LDAP identity provider to perform tasks such as changing their LDAP password. API Manager supports a hybrid mix of external LDAP and API Manager identity providers. For example, you can configure an external LDAP identity provider such as Apache Directory or Microsoft Active Directory, and also create external users in API Manager. Users created in API Manager are authenticated against the Key Property Store (KPS) and stored in the Apache Cassandra database. Typically, in this hybrid setup, users are managed as follows: External LDAP identity provider stores existing internal corporate users and administrators API Manager uses the Cassandra database to store external users and developers using the API Manager on-boarding process You can also use your existing external LDAP identity provider to store external users and developers. Axway API Manager User Guide 42

43 2 API Manager configuration User registration When using both Cassandra users and external LDAP users with API Manager: Users managed in the external identity provider do not need to be created in API Manager, and are automatically created on first user login. API Manager does not store passwords for these users. Users not managed in the external identity provider are created in API Manager by the API administrator or by self-registration. API Manager stores the full user profiles and passwords for these users in Cassandra. User login When a user logs into API Manager: If the user exists in Cassandra, API Manager checks the password for the user stored in Cassandra, and grants access. If the user does not exist in Cassandra, API Manager checks if the user exists in the configured external identity store. If the user exists, the behavior is as follows: 1. At first login, API Manager automatically creates the user in Cassandra, stores the login as a read only field (the credentials remain in the external identity store), and a role is automatically assigned using the configured policy. 2. For subsequent logins, API Manager will have the user login in Cassandra, and will check the user credentials in the external identity store. Roles can also be changed by the API administrator in API Manager. Sample configuration API Manager provides sample external identity providers for LDAP based on Apache Directory and Microsoft Active Directory. This topic explains how to configure these sample providers using the Policy Studio and API Manager tools. The following sample external identity provider configuration is available in the Policy Studio tree: Apache Directory LDAP authentication and account retrieval policies in Policies > Sample Policies > API Management Identity Provider > LDAP Active Directory authentication and account retrieval policies in Policies >Sample Policies > API Management Identity Provider > Active Directory Common account creation success and failure policies in Policies > Sample Policies > API Management Identity Provider Sample LDAP repositories in Environment Configuration > External Connections > Authentication Repositories > LDAP Repositories Axway API Manager User Guide 43

44 2 API Manager configuration Sample LDAP Connections in Environment Configuration > External Connections > LDAP Connections Configure an Apache Directory LDAP external identity provider This section explains how to configure an Apache Directory LDAP external identity provider. Prerequisites The sample LDAP configuration assumes that an Apache Directory LDAP server is running locally (on localhost:10389), and configured with a sample partition (Seven Seas). This sample partition is available from: When the partition has been configured, you must import the sample LDAP Data Interchange Format (LDIF) data to populate the directory with users. The sample LDIF data is available from: Note All user passwords are set to pass. For more details, see the Apache Directory Studio User Guide. Configuration steps To set up LDAP as an external identity provider, perform the following steps: 1. In the Policy Studio tree, select Server Settings > API Manager > Identity Provider > Use external identity provider. 2. Ensure that the sample LDAP account policies are configured. These policies are selected by default. For example: Axway API Manager User Guide 44

45 2 API Manager configuration 3. Click Apply Changes at the bottom right. 4. Optionally, if the community organization is not named Community, or if you wish to onboard users to a specific organization, edit the Set.extidentity.organization filter in the Read LDAP Account Information policy. For example: 5. Enter the appropriate value in the Organization selector field (for example, Community). 6. Click Deploy in the toolbar to deploy the updated configuration. 7. Connect to API Manager in your browser: Axway API Manager User Guide 45

46 2 API Manager configuration 8. On-board a user from the Apache Directory LDAP server by logging in with the appropriate user credentials (for example, the wbligh user). 9. Select Settings > Account to view the on-boarded account details. For example: Note The Login name for an external user (provisioned by an external identity provider) is read-only and cannot be changed. Configure a Microsoft Active Directory external identity provider This section explains how to configure a Microsoft Active Directory external identity provider. To set up Active Directory as an external identity provider, perform the following steps: 1. In the Policy Studio tree, select Server Settings >API Manager > Identity Provider > Use external identity provider. 2. Ensure that the sample Active Directory account policies are configured. For example: Axway API Manager User Guide 46

47 2 API Manager configuration 3. Click Apply Changes at the bottom right. 4. In the Policy Studio tree, select Environment Configuration > External Connections >LDAP Connections > API Management Sample Active Directory Connection. 5. Right-click, select Edit, and enter the following settings: URL: Enter the URL for your LDAP server (for example, ldap:// :389). User Name: Enter the distinguished name of the user to connect to the Active Directory (for example, CN=Joe Bloggs,OU=DUBL,OU=IE,OU=Employees,DC=company,DC=com). Note This user must have Read MemberOf (search) privileges. Password: Enter the user password. 6. Click Test Connection to verify that the configuration details are correct. Axway API Manager User Guide 47

48 2 API Manager configuration 7. Select Environment Configuration > External Connections > Authentication Repositories > LDAP Repositories > API Management Sample Active Directory Repository. 8. Right-click, select Edit Repository, and enter the Base Criteria (for example, OU=Employees,DC=company,DC=com). This is the starting point in the Active Directory hierarchy at which the search for users will begin. 9. Optionally, if the community organization is not named Community, or if you wish to onboard users to a specific organization, edit the Set.extidentity.organization filter in the Read Active Directory Account Information policy. 10. Enter the appropriate value in the Organization selector field (for example, Community). 11. Click Deploy in the toolbar to deploy the updated configuration. 12. Connect to API Manager in your browser: On-board a user from the Active Directory server by logging in with the appropriate user credentials (for example, a jbloggs user). 14. Select Settings > Account to view the on-boarded account details. For example: Note The Login name for an external user (provisioned by an external identity provider) is read-only and cannot be changed. Axway API Manager User Guide 48

49 2 API Manager configuration Account information policy You can configure the Account information policy in Policy Studio in Environment Configuration > Server Settings > API Manager > Identity Provider. This policy returns the user information to API Manager using the following attributes: Attribute extidentity.organization.id extidentity.role Description The organization ID (required). The user s role (required). This is one of the following: user: Client appplication developer oadmin: Organization administrator admin: API administrator extidentity.enabled extidentity.name extidentity.description extidentity. extidentity.phone User is enabled only if the selector evaluates to 1 or true. The user s name (required). A description of the user. The user s address. The user s phone number. Further information For more details, see Configure API Manager settings in Policy Studio on page 29. For details on how to create custom policies, see the API Gateway Policy Developer Guide. Axway API Manager User Guide 49

50 API management 3 This part contains the following: API management workflow 50 Register REST APIs in API Manager 52 Virtualize REST APIs in API Manager 59 Administer APIs in API Manager 79 Monitor APIs and applications in API Manager 93 Consume APIs in API Manager 98 API Manager REST APIs 104 API management workflow Overview This topic provides a quick workflow summary of the steps required to register and virtualize APIs in API Manager. It shows simple configuration options to help get started. The topics that follow explain concepts such as back-end and front-end APIs, provide detailed steps with examples, and describe the advanced options. Note Before you can register APIs in API Manager, you must first enable an organization for API registration and development. The API Manager welcome screen prompts you to automatically create an API Development organization, which is enabled for API development by default. For more details, see Register REST APIs in API Manager on page 52. Register a back-end REST API in API Manager To register a back-end API in API Manager, perform the following steps: 1. In API Manager, select API Registration > Backend API. 2. Click New API, and select one of the following: Import API from Topology: Import a REST API deployed on an API Gateway. Import RAML API: Import a REST API in RAML format. Axway API Manager User Guide 50

51 3 API management Import Swagger API: Import a REST API in JSON format. Import WADL API: Import a REST API in WADL format. Import WSDL API: Import a web service in WSDL format. 3. Specify the API details (for example, location, name, and organization), and click Import. 4. When the API is imported, click OK. For more details, see Register REST APIs in API Manager on page 52. The following example shows imported APIs based on RAML, Swagger, and Web service definitions: Alternatively, if you do not have a Swagger or WADL file to import for an existing API, see Manually register a new back-end REST API on page 57. Virtualize a front-end REST API in API Manager To virtualize a front-end API in API Manager, perform the following steps: 1. In API Manager, select API Registration > Frontend API. 2. Click New API, and select New API from backend API. 3. Select the existing back-end API, and click OK. 4. Select an Inbound security device from the list. The most commonly used security devices are as follows: API key Enables API Manager to control and monitor client applications that can access APIs by requiring users to authenticate with an API key. Pass through API Manager does not control and monitor access to the API, and does not use its client registry for the API, which is effectively public. However, the backend API may have its own authentication mechanism. 5. Specify the settings for the security device in the dialog, and click OK. 6. If the back-end API is accessed using HTTPS, click the Trusted Certificates tab, and click the plus icon on the left. In the dialog, you can specify the URL to valid back-end content, and authentication parameters (if required). For example, you can use the URL for the Swagger or WADL file that you already used to import the back-end API. 7. When finished, click Save. Axway API Manager User Guide 51

52 3 API management For more details, see Virtualize REST APIs in API Manager on page 59. The following example shows an existing Swagger-based back-end API virtualized as a front-end API: Register REST APIs in API Manager Overview API owners can use the API Manager web interface to register back-end REST APIs. You can manually create a new back-end API, or import a definition for an existing API (for example, in Swagger or WADL format). Using API Manager to register REST APIs means that you can register APIs in a browser, in multiple formats, without any service outage. When a back-end API is registered, you can then virtualize it as a publicly exposed front-end API. Registered and virtualized APIs are governed by the API Gateway using configured policies. API administrators can use API Manager to manage registered APIs, and API consumers can use API Manager or API Portal to consume virtualized APIs in their applications. Note You must first register a back-end REST API before you can virtualize a front-end REST API. For more details, see Virtualize REST APIs in API Manager on page 59. Axway API Manager User Guide 52

53 3 API management Back-end and front-end APIs In API Manager, the back-end API is the actual REST API that is routed to, and that is exposed by an application server on the network, or in the Cloud (for example, Twitter). You can use in API Manager to register a new back-end REST API manually, or to import a definition for an existing REST API in Swagger or WADL format. The following example shows a manually registered back-end API in API Manager: In API Manager, the front-end API is the virtualized publicly exposed REST API that is hosted on the API Gateway, and which is invoked by client applications (for example, iphone or Android apps). The following shows the example back-end API virtualized as a front-end API in API Manager: By default, the front-end API is the same as the back-end API, proxying the API as is. However, you can edit the front-end API to present an enriched, public-facing API to client applications. For example, you can change the URL path, change and map parameters, or improve the documentation. Axway API Manager User Guide 53

54 3 API management In addition, this separation of front-end API and back-end API definitions allows the back-end API to change over time. This means that you can control how changes are exposed to client applications, thus minimizing or eliminating the potential impact these applications. For more details, see Virtualize REST APIs in API Manager on page 59. Enable an organization for API development Before you can begin registering REST APIs for an organization in API Manager, you must first enable an organization for API registration and development. The API Manager welcome dialog prompts you to automatically create an API Development organization, which is enabled for API development by default. If you do not create the default API Development organization, you must perform the following steps: 1. Click the Client Registry > Organizations view in API Manager. 2. Click the name of the organization to enable (for example, Acme Inc). 3. In the API Development field, click On. You can now register back-end APIs and virtualize front-end APIs for this organization. Import an existing back-end REST API To automatically register an existing back-end REST API in API Manager, perform the following steps: 1. Click the API Registration > Backend API view in API Manager. 2. Click New API and select one of the following: Import Swagger API: Import an API in Swagger format. Only JSON format is supported for Swagger API definition files. For more details on Swagger, see Import RAML API: Import an API in RESTful API Modeling Language (RAML) format. Importing RAML files that include references to external files is not supported. For more details on RAML, see Import WADL API: Import an API in Web Application Description Language (WADL) format. For more details on WADL, see 3. In the Import API dialog, complete the following: o o o Source: Select the source type from the list (for example, Swagger, RAML, WADL definition file or URL). File or URL: Click the browse button to select the definition file, or enter the URL. API Name: A user-friendly name for the API (for example, Test API). Axway API Manager User Guide 54

55 3 API management o o Organization: Select the organization from the list (for example, Acme Inc). Authentication: For URL-based APIs only, enter a User name and Password if required. When the REST API has been imported, it is displayed as read only in API Manager. The following example shows two imported APIs based on WADL and Swagger definitions: You can click an API name in the list to view its general details, methods, and schema model. The following example shows the details displayed for the Petstore Swagger API: Note It is not recommended to have spaces or the URL encoded %20 in the base path URL. Import an existing web service back-end API To import an existing web service-based back-end API in API Manager, perform the following steps: 1. Click the API Registration > Backend API view in API Manager. 2. Click New API > Import WSDL API. 3. In the Import Web Service dialog, complete the following: o URL: Enter the URL for the web service. For example: o API Name: A user-friendly name for the API (for example, Weather API). Axway API Manager User Guide 55

56 3 API management o o Organization: Select the organization from the list (for example, Acme Inc). Authentication: For URL-based APIs only, enter a User name and Password if required. 4. Click Import to import the API into the catalog. Import an existing Cloud-based back-end API Note Before importing a Cloud API, you must first ensure that the API connector and OAuth profile for the Cloud API have been configured. For example, see Configure OAuth client credentials for Salesforce.com on page 141. To import a Cloud-based back-end API for existing Cloud-based APIs in API Manager, perform the following steps: 1. Select API Registration > Backend API. 2. Click New API, and select Import from Salesforce.com or Import from ServiceNow 3. Enter your login credentials from your Cloud API provider (for example, Salesforce.com) in the dialog (if prompted). 4. Select the Cloud APIs that you require in the dialog. 5. Click Import to import the selected APIs as a single back-end API in API Manager. For a detailed example, see Cloud application connectors on page 135. Import an existing back-end API deployed on an API Gateway To import an existing back-end REST or SOAP API that is already deployed on an API Gateway, perform the following steps: 1. Click the API Registration > Backend API view in API Manager. 2. Click New API > Import API from Topology. 3. In the Import from Topology dialog, complete the following required settings: o Host: Enter the Admin Node Manager host name (for example, localhost). o Port: Enter the Admin Node Manager port number (for example, 8090). o o o o o Login Name: Enter your Admin Node Manager login name. Password: Enter your Admin Node Manager password. Group: Select the API Gateway group name (for example, AcmeGatewayGroup). Instance: Select the API Gateway instance name (for example, AcmeGateway). Service Type: Select REST API or SOAP service. Axway API Manager User Guide 56

57 3 API management o o o Service: Select the API Gateway service name (for example, AcmePayment. API name: Enter the API name (for example, Acme Payment API). Organization: Select the organization (for example Acme Inc). 4. Click Import to import the API into the catalog. Manually register a new back-end REST API To manually register a new back-end REST API in API Manager, perform the following steps: 1. Click the API Registration > Backend API view in API Manager. 2. Click New API > New. 3. In the API tab, complete the following general details: API name: Enter a required name for the API (for example, Acme API). Service type: Enter a service type for the API (for example, defaults to REST). Organization: Select a required organization for the API (for example, Acme Inc). See also Enable an organization for API development on page 54. Base path URL: Enter a resource path. Defaults to Summary: Enter an optional summary for the API to display in the API Catalog. Resource path: Enter a resource path for the API. Defaults to /api. API version: Enter an optional version number for the API. Defaults to 1.0. Description: Click the Edit tab, and enter an optional description for the API. Create REST API methods To add a REST API method to a newly registered API, perform the following steps: 1. On the API Methods tab, complete the following details: Method Name: Enter a required name for the API method (for example, GetProducts), and enter an optional Method summary. Verb: Enter a required HTTP verb for the API method. Defaults to GET. Path: Enter the path for the method. Defaults to /. API version: Enter an optional response type for the API method (for example, a general type like int or string, or a custom type in the schema model for the API) Defaults to void. Description: Click the Edit tab, and enter an optional description for the API. Axway API Manager User Guide 57

58 3 API management 2. To add a parameter exposed by the API method, click the add button in the PARAMETERS section, and complete the following details: NAME: Enter a required name for the parameter (for example, customer_name). DESCRIPTION: Enter an optional description for the parameter. TYPE: Select the parameter type (for example, query, path, form, body, or header). Defaults to query. DATA TYPE: Select the parameter data type (for example, string, int, boolean, and so on). Defaults to string. REQUIRED: Select whether the parameter is required. Defaults to No. ALLOW MULTIPLE: Select whether multiple parameters are allowed. Defaults to No. To add more method parameters, click the add button in the PARAMETERS section. 3. To specify content types that can be consumed by the API method, click the plus (+) button in the CONSUMES CONTENT-TYPE section, and enter the content type. For example, application/xml, text/plain, and so on. Defaults to application/json. 4. To specify content types that can be produced by the API method, click the plus (+) button in the PRODUCES CONTENT-TYPE section, and enter the content type. For example, application/xml, text/plain, and so on. Defaults to application/json. 5. To specify response codes that can be produced by the API method, click the plus (+) button in the RESPONSE CODES section, and select the response codes (for example, Create codes (201, 403, 500)). 6. To add more API methods, click the add button on the top left. Create the REST API model Alternatively, for JSON-based APIs, you can directly enter the JSON schema model for the API on the Models tab. For more details, see Manage back-end REST API lifecycle When you have registered the back-end REST API, you can select it in the list of registered APIs, click Manage selected, and chose one of the following options: Delete: Deletes the selected REST API(s) registered in the API Registration > Backend API view. You can delete APIs created as front-end REST APIs in the Frontend API view. Clone API: Creates a copy of the selected REST API, which you can then edit as required. Note You cannot clone a back-end API imported from a WSDL-based web service. You can clone REST-based APIs only. Export API: Exports a copy of the selected back-end REST API (in.json format). You can then import this into another API Manager environment as required as a back-end REST API. Axway API Manager User Guide 58

59 3 API management Download original API description: For APIs imported from Swagger or WADL definitions, downloads a copy of the original API definition. Next steps When you have registered a back-end REST API, the next step is to virtualize it as a publicly exposed front-end API. For more details, see Virtualize REST APIs in API Manager on page 59. Virtualize REST APIs in API Manager When you have registered a back-end REST API, you can then virtualize it as a publicly exposed front-end API. The API Catalog stores information about the REST APIs that have been virtualized as front-end APIs. Virtualized REST APIs published in the API Catalog can be made available in API Manager for consumption by API consumers, and for administration by API administrators. Note You must first register a back-end REST API before you can virtualize a front-end REST API. For more details, see Register REST APIs in API Manager on page 52. Virtualized REST API security When you virtualize a REST API, you can configure it with security devices, which provide prebuilt authentication and authorization mechanisms for the REST API. The following security devices are supported: API Key Amazon Web Services Signing - Authorization Amazon Web Services Signing - Query String HTTP Basic Authentication Invoke Policy (custom authentication) OAuth OAuth (External) Pass Through Two-way SSL This enables you to control the authentication and authorization mechanisms that are supported for the API. For example, an API with higher security requirements can be more restrictive in the authentication mechanism that it supports. You can also configure custom profiles to suit your requirements. You can also configure virtualized REST APIs and API methods with custom policies if required (for example, for request, routing, and response processing). Axway API Manager User Guide 59

60 3 API management Virtualize a REST API as a front-end API When you have first registered a back-end REST API in API Manager, you can then virtualize it as a publicly exposed front-end API. To virtualize a back-end REST API as a front-end API, perform the following steps: 1. Click the API Registration > Frontend API view in API Manager. 2. Click New API > New API from backend API. 3. Select an existing back-end API in the dialog (for example, Petstore), and click Create. This displays the following page: Note If the virtualized API is not a Swagger 2.0-compatible REST API, API Manager displays a message that Swagger download will not be available in the API Catalog. For more details, see Consume APIs in API Manager on page 98. Import a previously exported API Alternatively, you can virtualize an existing API by importing a previously exported front-end API (for example, from another API Manager environment). For details on how to export APIs, see Manage front-end REST API lifecycle on page 77 To import a previously exported API, perform the following steps: 1. Click the API Registration > Frontend API view in API Manager. 2. Click New API > Import API collection. 3. In the Import from dialog, complete the following: File: Click to browse to the previously exported API (.dat file). Password: Enter the password if required. Organization: Select the organization from the list (for example, API Development). 4. Click Import. 5. Press F5 to reload the API Manager web console. Axway API Manager User Guide 60

61 3 API management Configure Inbound settings When you have virtualized a REST API to create a front-end API, you can edit and configure the inbound request settings between the client and the API Gateway (for example, for customized authentication, authorization, or monitoring). To configure inbound settings, perform the following steps in API Manager: 1. Select the Inbound tab. 2. Edit the resource path in the text box under the API name. Defaults to /api. 3. Select a required security device from the Inbound Security list. This enables you to configure pre-built inbound authentication and authorization mechanisms for the virtualized API. The most commonly used devices are API Key and Pass Through. The available options are as follows: Security Device Settings API Key Configure the following to enable API key authentication: API key field name: Enter a required name used to store the API key field in the inbound request. Defaults to KeyId. API key location: Select the required location of the API key in the inbound request (Request Headers or Query string/form body). Defaults to Request Headers. Remove credentials on success: Select whether to remove the user credentials from the message after successful authentication. This is selected by default. AWS Signing (Authorizatio n Header) Configure the following to enable access to the API using an Amazon Web Services authorization header: Name: Enter a required name for the device. Defaults to AWS Signing Device (Authorization Header). Remove credentials on success: Select whether to remove user credentials from the message after successful authentication. This is selected by default. Axway API Manager User Guide 61

62 3 API management Security Device Settings AWS Signing (Query String) Configure the following to enable access to the API using an Amazon Web Services query string: Name: Enter a required name for the device. Defaults to AWS Signing Device (Query String). API key field name: Enter a required name of the query-string parameter used to store the API key field in the inbound request. Defaults to AWSAccessKeyId. HTTP Basic Configure the following to enable HTTP Basic authentication: Name: Enter a required name for the device. Defaults to HTTP Basic Device. Realm: Enter the realm required for HTTP basic authentication purposes (for example, Flickr). This enables clients to identify the zone that they are accessing. For example, the browser can then cache user credentials on a per-realm basis. The realm is required for all authentication schemes that issue an authentication challenge. Remove credentials on success: Select whether to remove user credentials from the message after successful authentication. This is selected by default. Note When using HTTP basic authentication, the client application invoking the API must use the API key as username and the API secret as password, formatted as Base64Encode("APIKey:APISecret"). Axway API Manager User Guide 62

63 3 API management Security Device Settings Invoke Policy Configure the following to use a custom authentication policy: Name: Enter the name of the custom security device. Defaults to Invoke Policy. Policy to invoke: Select the authentication policy that this security device invokes. This lists policies already configured in Policy Studio in Environment Configuration > Server Settings > API Manager > Inbound Security Policies. For more details, see Configure API Manager settings in Policy Studio on page 29. Use client registry: Select whether the authentication.subject.id identifier must match one of the application's external credentials in the Client Registry in API Manager. This is selected by default. Traffic Monitor subject: If Use client registry is not selected, the API has no client information. Enter the subject name to display in the Traffic tab in API Gateway Manager. Defaults to ${authentication.subject.id}. Description: Select where the Markdown description for this security device is located. For details on writing documentation with Markdown, see Select one of the following: o o o Use original policy description: Use the policy description specified when creating the policy in Policy Studio. Use manual description: Get the description from the contents of a field. Enter the description in the Manual Description field. Use markdown file location: Get the description from a file located on the server. Enter the path to this file in the Markdown file location field. Note For security reasons, this file must start with an environmentalized variable and cannot attempt directory traversal. For example, the following path is valid: ${env.documents}/markdown/ Axway API Manager User Guide 63

64 3 API management Security Device Settings api.md The following paths are invalid: /opt/documents/api.md ${env.documents}/../markdo wn/api.md o Use external URL: Get the description from an external URL. Enter the URL in the External URL location field. Note Invoke Policy security devices generate an Authentication section in the API Catalog that displays the description entered when creating the security device. Axway API Manager User Guide 64

65 3 API management Security Device Settings OAuth Configure the following to enable OAuth authorization: General: Authorization: Grant Type: Implicit: Access token store: Select a required OAuth access token store from the list. For details on how to add OAuth access token stores to this list, see Configure API Manager settings in Policy Studio on page 29. Scopes must match: Select whether the OAuth scopes match Any or All of the OAuth scopes configured in the next field. OAuth scopes are used to control how access tokens are accepted. For more details on OAuth scopes, see the API Gateway OAuth User Guide. Scopes: Enter a comma-separated list of OAuth scopes used to manage how access tokens are accepted. In addition, these tokens are used as default scopes for applications that use this API and do not send the scope parameter in the access token request. You can also configure additional default scopes for an application if enabled in API Manager settings. For details, see Enable OAuth scopes per application in Configure web-based settings in API Manager on page 36. Defaults to resource.write, resource.read. Remove credentials on success: Select whether to remove user credentials from the message after successful authentication and authorization. Enabled by default. Access token location: Select the required location of the OAuth access token in the inbound request (Request Header or Query string/form body). Defaults to Request Header. Authorization header prefix: Select the header prefix used to authorize the request (Bearer or OAuth). Defaults to Bearer. Enabled: Select whether to enable this simplified authorization code flow optimized for browser-based clients. Enabling advertises this grant type in the API Catalog. It is the role of the OAuth authorization server to support it. Disabling excludes this grant type from the API Catalog. Login endpoint URL: Enter the authorization endpoint where resource owners can interact with the OAuth service Axway API Manager User Guide 65

66 3 API management Security Device Settings to authorize access for the client application. This is the URL where client applications will redirect end users. Defaults to ize. Login token name: Enter the response parameter name that will contain the access token. Defaults to access_ token. Grant Type: Authorization Code: Enabled: Select whether the authorization code is obtained using an authorization server as an intermediary between the client and resource owner. Enabling advertises this grant type in the API Catalog. It is the role of the OAuth authorization server to support it. Disabling excludes this grant type from the API Catalog. Request endpoint URL: Enter the authorization endpoint where resource owners can interact with the OAuth service to authorize access for client application. This is the URL where client application will redirect end users. Defaults to ize. Request client ID name: Enter the name of the request parameter that will contain the client application ID. Defaults to client_id. Request client secret name: Enter the name of the request parameter that will contain the client application secret. Defaults to client_secret. Token URL: Enter the token endpoint URL where the client application will exchange an authorization code for an access token. Defaults to Token name: Enter the request parameter name that will contain the access code. Defaults to access_token. Axway API Manager User Guide 66

67 3 API management Security Device OAuth (External) Settings Configure the following to enable OAuth authorization: General: Token information policy: Select a required OAuth token information policy from the list. This is a custom policy used to obtain and extract token information from the external OAuth provider. For details on how to add OAuth token information policies to the list, see Configure API Manager on page 25. Scopes must match: Select whether the OAuth scopes match Any or All of the OAuth scopes configured in the next field. OAuth scopes are used to control how access tokens are accepted. For more details on OAuth scopes, see the API Gateway OAuth User Guide. Scopes: Enter a comma-separated list of OAuth scopes used to manage how access tokens are accepted. Defaults to resource.write, resource.read. Remove credentials on success: Select whether to remove user credentials from the message after successful authentication and authorization. Enabled by default. Use client registry: Select whether to use the Client Registry in API Manager. If this is not selected, the API is effectively pass-through and the Client Registry does not apply API access or enforce quotas. If this is selected, API Manager can use OAuth external credentials to identify the client application, apply quotas, and assign a subject identifier for traffic monitoring. This is not selected by default because external OAuth providers typically use their own client registries. Traffic monitor subject: Enter the identifier name used for clients from the external OAuth provider, which is displayed on the Traffic tab in the API Gateway Manager console. This value can be a selector. Defaults to ${oauth.token.client_id}. Extract token attributes: Click the add button to specify OAuth token attributes to be extracted from the configured Token information policy and copied to the message whiteboard. For example, these can then be passed to request, response, or routing policies downstream. Specifying attributes ensures their values are retained on the whiteboard after invoking the policy. By default, the following attributes are extracted: o oauth.token.client_id Axway API Manager User Guide 67

68 3 API management Security Device Settings o o oauth.token.scopes oauth.token.valid Authorization: See the OAuth security device settings. Grant Type: Implicit: See the OAuth security device settings. Grant Type: Authorization Code: See the OAuthsecurity device settings. Pass Through Configure the following to enable pass-through authentication where the API Gateway passes the user credentials through to an authenticating server: Name: Enter a required name for the device. Defaults to Pass Through Device. Subject ID: Enter a required authentication subject ID. Defaults to Pass Through. This will be displayed in the Traffic view in the API Gateway Manager when the API is invoked using this device. Note When you enable pass-through authentication, there is no client application context so application quotas cannot be enforced. Two-way SSL To enable two-way (mutual) SSL authentication, the client must supply a certificate (signed by the server CA). By default, the client certificate must contain a Subject Common Name (CN) set to the API Key generated by API Manager. The CN value is evaluated at runtime using a selector, and used to look up the Key Property Store (KPS) to retrieve or validate the API key and application. You can configure the following settings: Name: Enter a required name for the device. Defaults to Two-way SSL Device. API key field: Enter the name of the selector used to look up the KPS to retrieve and/or validate the API key and application details. Defaults to ${certificate.subject.cn}. 4. Click the Advanced button on the right to configure settings such as monitoring, sharing resources across domains, and per-api method overrides. The following shows an example: Axway API Manager User Guide 68

69 3 API management Configure Advanced Inbound settings When you click the Advanced button on the right, the following options are displayed in API Manager: Advanced Setting Description Monitor API usage Enable CORS from all domains Select whether to enable monitoring metrics for the REST API in the Monitoring > API Usage view. Select whether to enable Cross Origin Resource Sharing (CORS) from all domains. When enabled, this means that requests to this API are allowed from all domains (which corresponds to a CORS setting of *). To add more advanced CORS configuration (for example, allowed or exposed headers), disable this setting, and add a specific CORS profile for this API. For more details, see Configure CORS Profiles on page 76. Axway API Manager User Guide 69

70 3 API management Advanced Setting Description PER- METHOD OVERRIDE You can click to override the REST API level settings for specified REST API methods. Click the add button, select an API method from the list, and override the following settings as required: INBOUND SECURITY PROFILE: Select a preconfigured security profile for the API method. For more details, see Configure Security Profiles on page 76. CORS PROFILE: Select a preconfigured CORS profile for the API method. For more details, see Configure CORS Profiles on page 76. Configure Outbound settings When you have virtualized a back-end REST API to create a front-end API, you can edit and configure the outbound request settings between the API Gateway and the back-end API. For example, this enables you to customize authentication, and request or response processing. The following page shows configuring an API key authentication profile: To configure outbound settings, perform the following steps in API Manager: 1. Select the Outbound tab. 2. Select an optional profile from the Outbound authentication profile list. This enables you to configure a pre-built authentication mechanism for outbound communication between the API Gateway and the virtualized API: Authentication profile Settings No authentication No authentication is performed between the API Gateway and the backend API. Axway API Manager User Guide 70

71 3 API management Authentication profile Settings HTTP Basic Configure the following to enable HTTP Basic authentication: Name: Enter a required name for the profile. Defaults to HTTP Basic. Username: Enter the required username (API key) used to access the API. Password: Enter the optional password (API secret) used to access the API. HTTP Digest Configure the following to enable HTTP Digest authentication: Name: Enter a required name for the profile. Defaults to HTTP Digest. Username: Enter the required username (API key) used to access the API. Password: Enter the optional password (API secret) used to access the API. OAuth Configure the following to enable OAuth authentication: Provider Profile: Select the OAuth service provider profile from the list. Token Key (Owner ID): Enter the message attribute to be used as the key to look up the token. The token key must be set to the authentication value you require for the OAuth token. Defaults to ${authentication.subject.id}. Axway API Manager User Guide 71

72 3 API management Authentication profile Settings API Key Configure the following to enable API key authentication: Name: Enter a required name for the profile. Defaults to API key. API key field name: Enter a required name used to store the API key field in the outbound request (for example, KeyId). API key: Enter the API key required to access the API (for example, AIzaSyB6CzrBlkzuzDKJw0QaZhW9WwBV5IxXM S7). Pass credentials as HTTP: Select the required location of the API key in the outbound request (Header, Query string, or Form). SSL To enable SSL authentication, the API Gateway must supply a certificate signed by the Certificate Authority (CA) used by the API. You can configure the following settings: Name: Enter a required name for the profile. Defaults to SSL. PFX/P12 Source: Select whether to specify the certificate using a.pfx or.p12 file, or using a URL. PFX/P12 File or PFX/P12 URL: Browse to the PFX/P12 file, or enter the PFX/P12 URL. PFX/P12 Password: Enter the password for the certificate. Trust all certificates in chain: Select whether to trust all the CA certificates in the certificate chain. If this is not selected, only the top-level CA is trusted. This setting is selected by default. 3. Click the Advanced button on the right to configure settings such as request or response processing, routing, and per-api method overrides. The following shows an example: Axway API Manager User Guide 72

73 3 API management Configure Advanced Outbound settings When you click the Advanced button on the right, the following options are displayed in API Manager: Advanced Setting Request policy Response policy Description Select an optional request processing policy for the API. For example, you could use this pre-configured policy to check the request message for additional authentication, authorization, or validation. No request policies are configured by default. For details on how to make custom request policies available in the list, see Configure API Manager on page 25. Select an optional response processing policy for the API. For example, you could use this pre-configured policy to validate or transform outbound response messages. No response policies are configured by default. For details on how to make custom response policies available in the list, see Configure API Manager settings in Policy Studio on page 29. Axway API Manager User Guide 73

74 3 API management Advanced Setting Default method routing PER- METHOD OVERRIDE Description Select an optional routing policy for virtualized API method calls. For example, you could use this pre-configured policy to route to a back-end JMS service. API method calls are routed to the API proxy in API Manager by default. For details on how to make custom routing policies available in the list, see Configure API Manager settings in Policy Studio on page 29. For detailed examples using API key and OAuth, see Configure custom API Manager routing policies on page 122. You can click to override the REST API level settings for specified REST API methods. Click the add button, select an API method from the list, and override the following settings as required: REQUEST POLICY: Select an optional request processing policy for the API method (for more details, see Configure API Manager settings in Policy Studio on page 29). RESPONSE POLICY: Select an optional response processing policy for the API method (for more details, see Configure API Manager settings in Policy Studio on page 29). DEFAULT METHOD ROUTING: Select an optional routing policy for the API method (for more details, see Configure API Manager settings in Policy Studio on page 29). EDIT API PROXY: Click Edit to add parameters to the API method. To add parameters, click the add button, and configure the following settings: o o o o o o o OUTBOUND PARAMETER: Enter the parameter name (for example, customer_name). PARAMETER TYPE: Enter the parameter type (for example, query, path, form, or header). DATA TYPE: Enter the parameter name (for example, string, int, and so on). REQUIRED: Select whether the parameter is required. OUTBOUND VALUE: Enter the parameter value (for example, john doe or ${params.path.id}). EXCLUDE: Select whether to exclude the parameter. DEFAULT MAPPING: Select whether the parameter is mapped by default. AUTHENTICATION PROFILE: Select an optional authentication profile for the API method. Configure API information The API tab enables you to view and edit the API information to be displayed in the API Catalog. For example, this includes general settings such as the API name, version, graphic, documentation, and tags. Axway API Manager User Guide 74

75 3 API management Configure general API information You can configure the following settings in the GENERAL section: Image: Click the Add Image box, and browse to the location of the graphic file for your API. API Name: Enter a value to edit your API name. API Version: Enter a value to edit your API version. Other details such as the API state, owner, date are read-only. Configure API documentation You can configure the following in DOCUMENTATION > Description: Use original description: Uses the description specified when the back-end API was registered. Use manual description: Click the Edit tab, and enter a description. Use markdown file location: Enter the location in Markdown file location (for example, ${environment.vinstdir}/../markdown/api/api.md). Use external URL: Enter the location in External URL location (for example, Configure API tags The TAGS section enables you to add tags to categorize and help find your API in the API Catalog. Click the add button, and enter a tag name (for example, Department) and values (for example, Engineering,Testing). You can add multiple tags for your API. Tip You can enter multiple tag values in a comma-separated list without any spaces between each value. For examples of using tags in the API Catalog, see Consume APIs in API Manager on page 98. Configure API method information You can use the Method tab to configure the API method information to be displayed in the API Catalog. For example, this includes testing the method, configuring its documentation, and adding tags. For example, click Try method to invoke the method for test purposes. Authentication credentials are automatically formatted and passed in the test request. Other settings such as method parameters and content types are displayed as read-only. You can configure API method documentation and tags in the same way that you configure API documentation and tags. Axway API Manager User Guide 75

76 3 API management Configure Security Profiles You can use the Security Profiles tab to create custom security profiles with multiple security devices, which can then be applied as per-method override in the Inbound settings for the frontend API. To create a security profile, perform the following steps: 1. Click the add button on the left. 2. In GENERAL, enter a Name for the security profile. 3. In DEVICES, click the add button, select a security device from the list, and configure its settings. For details on configuring each security device type, see Configure Inbound settings on page Repeat to add multiple security devices if required. 5. You can click Up or Down to change the order in which security devices are invoked, or Edit to change any settings as required. Note Multiple security devices are combined using an OR logic. This means that if authentication to the first security device fails, authentication to the second security device is attempted, and so on. Configure Authentication Profiles You can use the Authentication Profiles tab to create custom authentication profiles, which can then be applied to the front-end API in the Outbound settings. To create an authentication profile, click the add button on the left, select an authentication profile from the list, and configure its settings. For details on configuring each authentication profile type, see Configure Advanced Outbound settings on page 73. Configure CORS Profiles You can use the CORS Profiles tab to create profiles for Cross Origin Resource Sharing, which can then be applied to the front-end API in the Inbound settings. To create an authentication profile, click the add button on the left, and configure the following settings: GENERAL: Enter a descriptive Name for the profile. ORIGINS: Click the add button, and enter the list of domains allowed to access this API (for example, or a wild-carded value such as Defaults to * to allow all domains. ALLOWED HEADERS: Click the add button, and enter the list of HTTP headers that can be used when invoking this API. This list of headers is defined by the value of the Access- Control-Request-Headers CORS header. Axway API Manager User Guide 76

77 3 API management EXPOSED HEADERS: Click the add button, and enter the list of HTTP headers to be exposed to the client in response to an invocation of this API. Note This does not include simple headers such as Cache-Control, Content- Language, Content-Type, Expires, Last-Modified, and Pragma. CREDENTIALS SUPPORT: Select whether the API advertises that it supports user credentials. When selected, the Access-Control-Allow-Credentials CORS header is sent in the response, with a value of true. This setting is not selected by default. PREFLIGHT RESULT CACHE: Enter how long the results of a CORS preflight OPTIONS request can be stored in the client preflight result cache. When configured, the Access- Control-Max-Age CORS header is sent in the response. For more details on using CORS, see the API Gateway Policy Developer Guide. This provides more background information and explains how to configure CORS for specific HTTP services and relative paths in Policy Studio. For example, this may be useful when using a third-party load balancer, and you need to configure a CORS profile for the default API Portal HTTP service in Policy Studio. Configure trusted certificates You can use the Trusted Certificates tab to add X.509 certificates, which can be used for the Outbound and Inbound SSL settings. To add a new certificate, perform the following steps: 1. Click the add button on the left, and configure the following: Source: Select the source of the certificate (X.509 Certificate file or URL). File or URL: Browse to the certificate source file (PKCS12, PEM, DER file), and enter a password if required. Alternatively, enter the URL for the certificate. Use for outbound: Select whether is certificate is used for outbound security between the API Gateway and the back-end API. This is selected by default. Use for inbound: Select whether is certificate is used for inbound security between the client and the API Gateway. This is not selected by default. 2. If you selected a URL certificate source, enter your User name and Password if required. 3. Click Import. Manage front-end REST API lifecycle When you have registered the back-end REST API, you can select it in the list of registered APIs, click Manage selected, and chose one of the following options: Delete: Deletes the selected REST API(s) from the API Registration > Frontend API view. You can delete APIs registered as back-end REST APIs in the Backend API view. Publish: Publishes the selected REST API to be consumed by API consumers. You can edit the API Name, and enter an optional Virtual host name. When published, the API can be assigned to any organization or application. The API is locked, and no further edits are allowed. Axway API Manager User Guide 77

78 3 API management Unpublish: Unpublishes the selected REST API. When unpublished, the API is only available to the API administrator and to API owners in their organization, and not to other organizations. The API can be edited, published, or deleted. Deprecate: Select whether to Retire API at specific date, and enter a Retirement date. When selected, the published API is displayed with a date when it will be retired (unpublished) from the API Catalog, and is no longer available to client applications. When deprecated, the API is still published and clients can continue to discover and use the API. Only a published API can be deprecated and unpublished. Undeprecate: Undeprecates the selected deprecated REST API. Upgrade access to newer API: Upgrades all organizations and applications that had access to the original API to a more recent version of the API (if one exists). You can also deprecate and retire the original API as options. Grant Access: Grants organizations access to the selected APIs. You can select whether to Grant API access to all organizations, specific organizations, or organizations with access to specific APIs. Export API collection: Exports a copy of the selected front-end REST APIs to your chosen directory. The APIs are exported in JSON format in a.dat file, which combines the front-end API, back-end API, security profiles, and so on. You must specify the following in the dialog: o o Export file name: Specify a file name to export (defaults to api-export.dat) Password: Add a mandatory password to encrypt the export file (see also Encryption of exported API collections on page 78) You can then import this file into API Manager as required (for example, when promoting between environments). See also Import a previously exported API on page 60 and Promote managed APIs between environments on page 106. Tip For more details on API lifecycle, see API registration and lifecycle management on page 23. Encryption of exported API collections In earlier API Manager versions, you could export API collections as a plaintext file. Now, by default, you can no longer export API collections as plaintext. You must supply a password and the generated file is encrypted. If you wish to generate a plaintext export file, the administrator must add the following lines towards the start of INSTALL_ DIR/apigateway/webapps/apiportal/vordel/apiportal/app/app.config (for example, before the nodemanager setting): /* Flag to determine if API collections can be exported as clear text: - Set to false if API export as clear text is not allowed (exported file is always encrypted) - Set to true if API export as clear text is allowed (you can choose to encrypt the file or not)*/ allowapiexportascleartext: true, Axway API Manager User Guide 78

79 3 API management Note If you change this setting, you must clear your browser cache so that the old setting is removed. When allowapiexportascleartext is set to true, the Export API dialog also includes an Encrypt option, which enables you to select whether to encrypt the export file using the specified password. For example: Administer APIs in API Manager API administrators use API Manager to administer the managed APIs that are exposed to API consumers. The API administrator is a business or operational role who understands the business capability of the APIs, which clients want to access them, and for what reasons. The API administrator does not necessarily have deep knowledge of the API Gateway, and is not familiar with the Policy Studio developer tool. The API administrator role is responsible for API Manager. This role manages and monitors the virtualized APIs and the clients that use those APIs. API administrator tasks include the following: Managing organizations registering organizations and defining which APIs they are authorized to access Managing client applications managing client application credentials and API authorizations Managing users API consumers, organization administrators, and API administrators Managing API quotas system-level and client application-level quotas Monitoring and reporting on API usage These tasks are performed using the intuitive API Manager web interface. This topic focuses on the concepts and workflows in API administration, and shows some examples of using the API Manager web interface. API administration concepts This section describes the main components and concepts in API administration. Axway API Manager User Guide 79

80 3 API management Applications Applications invoke the virtualized APIs exposed by the API Gateway. Applications are registered by API consumers or by the API administrator using API Manager. Application authentication credentials are also defined and managed this way. Application entitlements determine which APIs the application is authorized to access and the quota management (throttling rate) for each API. Entitlements are determined by the organization that the application is part of, and any applicationspecific entitlements. Application entitlements are managed by the API administrator using API Manager. In the Community organization, only users that create an application and the API administrator have management privileges for that application (for example, managing application details, or deleting the application). In a named organization, multiple users can have management privileges for an application, and management privileges can be moved from one user to another (for example, from an API consumer to an operational user, or to a team of API consumers working on the application). The API administrator has full management privileges over all applications. The following rules apply to managing which users have management privileges for an application: A user with management privileges can add another user, but not remove another user. A user with management privileges can remove themselves, unless they are the last user to have management privileges. An application must always have one user with management privileges. If delegated by the API administrator, the organization administrator can add and remove users. The API administrator can add and remove users. Quotas The API administrator can manage the maximum message traffic rate that can be sent by applications to APIs using the following types of quotas: System quota: The maximum message rate that can be sent to APIs and their methods, aggregated across all client applications, regardless of organization. This controls the amount of incoming traffic that can be sent to any API and its methods, regardless of the client application. For example, if a system quota is configured for API A and method B, and the API is called by two different applications, both calls have the same effect on the system-wide quota. The system quota is a global setting designed to protect back-end systems (for example, if the system can only process 100 messages per second). Application-default quota: The default quota that applies on a per-application basis to all applications unless an application-specific quota is configured. This quota specifies the default maximum message rate that any application can send to APIs and methods (for example, 25 messages per second). Application-specific quota: This overrides the application-default quota. This quota specifies the maximum message rate that the specific application can send to APIs and methods (for example, 15 messages per second). Note API administrators can specify all quotas at the API and at API method level. For more details, see Manage quotas on page 87. Axway API Manager User Guide 80

81 3 API management Authorization The API administrator can manage the APIs that organizations and applications can access using the following: Organization authorization the API administrator can define the APIs that the organization is allowed to access. For example, a named hotel organization can only access the reservation and payment APIs. Application authorization the API administrator can define the APIs that the application is allowed to access. For example, a specific client application in the hotel organization can only access the reservation API. User management the API administrator can assign users a specific organization (Community or named) and user role (API consumer user, organization administrator, or API administrator). Note The API administrator must first specify the APIs that an organization is allowed to access before any of its client applications can have access to them. In API Manager, you can only add APIs to an application when you have first added them to the organization. Authentication You can define the authentication mechanisms required by the API (for example, Two-Way SSL, HTTP Basic, API Key/Secret, OAuth, or AWS Signing Query String) using security profiles in API Manager. You can specify which security profiles are associated with the API to define the level of security required. The client applications can then use credentials to authenticate and identify the client application to API Gateway. This also enables the API administrator to see which client applications have used the API. API Manager access control The API Manager user roles have the following access rights: API administrator The API administrator has full access to API Manager, and can create, read, update, and delete organizations, users, and applications. The API administrator has management responsibility for applications and users. When users are being registered, the API administrator can approve or reject new users. Users can create applications, but they must first be approved by the API administrator. If users want to request access to another API for an approved application, the API access must also be approved. User and application management can be automatically approved. In addition, the API administrator can delegate the user and application management responsibility to organization administrators. But only the API administrator can edit quotas. Organization administrator Axway API Manager User Guide 81

82 3 API management The organization administrator has full read access to users and applications in their organization. If application management is delegated, they can also create, update, and delete. The organization administrator can monitor all applications in their organization. They also have the same permissions as API consumers or application developer users. API consumer The API consumer can create, read, update, and delete their applications. They can also give shared access to other users, granting permissions to view and monitor, or full access. If autoapproval is disabled, the user must wait for approval for new applications from the API administrator, or organization administrator if they have been delegated management responsibility. A user has full read access to all other users in the organization. API consumer user registration workflow The use cases for the API consumer user registration workflow are: Case 1: Automatic approval, delegated user management An API consumer registers in API Manager. The user is not created, and is placed in a pending queue. The user receives a security to prove they own the address. When they click a link, the user is created, and they receive a created . Case 2: Automatic approval, no delegated user management Same behavior as case 1. Case 3: No automatic approval, no delegated user management Same behavior as case 1 and 2, except when the user clicks the link in the security , they receive a pending , and remain in the pending queue. An notification is sent to the API administrator address specified in the API Manager settings, and the API administrator approves or rejects the registration. When approved, the user is created, and receives a created . Case 4: No automatic approval, delegated user management Same behavior as case 3, except that the notification is sent to the contact address for the organization, and the API administrator or organization administrator approves or rejects the registration. The following table shows the difference between case 3 and 4 when the appropriate settings are selected in API Manager: Auto- Delegate API Portal Output approve user user management registration Disabled Disabled Enabled sent to API admin address for approval by API admin, and directed to API Manager. Axway API Manager User Guide 82

83 3 API management Auto- Delegate API Portal Output approve user user management registration Disabled Enabled Enabled sent to the organization address for approval by the API admin or organization admin, and directed to API Portal. If API Portal is disabled, the admin is directed to API Manager in all cases. For more details, see API Manager settings on page 37. Application creation workflow The use cases for the application creation workflow are: Case 1: Automatic approval, delegated application management A user creates a new application, requesting access to specific APIs. The application is automatically approved and created. Case 2: Automatic approval, no delegated application management Same behavior as case 1. Case 3: No automatic approval, no delegated application management Same behavior as case 1 and 2, except the application is not created, and enters a pending queue. An notification is sent to the contact address for the organization, and the API administrator approves or rejects the registration. When approved, the user receives a created . Case 4: No automatic approval, delegated application management Same behavior as case 3, except that the API administrator or organization administrator approves or rejects the registration. The following table shows the difference between case 3 and 4 when the appropriate settings are selected in API Manager: Auto- Delegate API Portal Output approve application applications management Disabled Disabled Enabled sent to the organization address for approval by API admin, and directed to API Manager. Disabled Enabled Enabled sent to the organization address for approval by API admin or organization admin, and directed to API Manager in all cases. Axway API Manager User Guide 83

84 3 API management For more details, see API Manager settings on page 37. API access workflow The use cases for the API access workflow are: Case 1: Organization wants new API access Only the API administrator can assign API access to organizations. Case 2: User wants new API access to an existing application, automatic approval The user adds a new API, and the API access is granted immediately. Case 3: User wants new API access to an existing application, no automatic approval, no delegated application management The user adds a new API, and the API access request is placed in a pending queue. An notification is sent to the contact address for the organization, and the API administrator approves or rejects the API access request. When approved, the access is granted. Case 4: User wants new API Access to an existing application, no automatic approval, delegated application management Same behavior as case 3, except that the API administrator or organization administrator approves or rejects the API access request. Note When an organization administrator adds a new front-end API, the API enters the pending queue, and the API administrator receives an to approve or reject publishing the API. Ensure API Manager is configured correctly Before you begin using API Manager as an API administrator, you must ensure that API Manager has been enabled and configured correctly for your environment. For example, this includes configuring API Manager settings such as the following: Monitoring metrics Identity provider Quota storage SMTP server Note You must ensure that API Manager is configured with the SMTP server used by your organization. For example, this enables you to generate s for user registration or client application approval. For more details, see Configure API Manager settings in Policy Studio on page 29. Log in to API Manager The API administrator can use the following URL to log in to API Manager: Axway API Manager User Guide 84

85 3 API management This displays the following login dialog: Enter the API administrator credentials that you specified when installing API Manager: Login name Password Note If you selected the default login name and password, you should change these after logging in for the first time. When logged into API Manager, select Settings > Account settings > PASSWORD. For more details, see Configure web-based settings in API Manager on page 36. API administrator view When an API administrator logs on to API Manager, it displays a specific view for the API administrator. This includes the following: API: Register a Backend API, then virtualize it as a Frontend API, and browse all virtualized APIs in the API Catalog. For more details, see API management workflow on page 50. Clients: Manage client Organizations, Application Developers, and Applications in the domain. For example, this includes assigning users to specific organizations (named or Community), and to specific roles (API administrator, organization administrator, or API consumer user). Axway API Manager User Guide 85

86 3 API management Manage system and application Default Quotas, and OAuth Authorizations. Quotas are maximum message rates for APIs and methods (for example, the number of messages or megabytes in a specified time period). For more details, see Manage quotas on page 87.This view also enables you to manage stored OAuth authorizations made by protected resource owners. Monitoring: View historical reports and statistics on all client applications in the domain. For more details, see Monitor APIs and applications in API Manager on page 93. Settings: Manage the following settings: Account User account details, role, and password (in this case, for the API administrator). API Manager settings API Manager host details, and settings such as whether API consumer users or client applications are auto-approved, and whether organization administrators can approve users or applications. Alerts Remote hosts Alert notifications for specific events (for example, when an application request is created, or an organization is created). Connection settings for back-end servers invoked by front-end APIs. For details on how to configure each of these settings, see Configure web-based settings in API Manager on page 36. The following shows an example API administrator view in API Manager. This shows setting a System quota of 30 messages per second: Organization administrator view The view displayed for organization administrator is a subset of the view displayed for the API administrator. For example, the organization administrator cannot view OAuth Authorizations, Default Quotas, API Manager Settings, or Alerts. The following shows an example view: Axway API Manager User Guide 86

87 3 API management Manage quotas API administrators can use the Clients > Default Quotas tab to manage the maximum message traffic rate sent by applications to APIs using application-default or system-level quotas. Alternatively, API administrators can set application-specific quotas in the Clients > Applications > Quota tab. For more details on quota types, see Quotas on page 80. Note API administrators can set system and application-level quotas only in API Manager. Policy developers can create custom throttling policies for user or organization-level quotas in Policy Studio. For details on creating policies, see the API Gateway Policy Developer Guide. System and application-default quotas To create a system or application-default quota, perform the following steps: 1. On the Default Quotas tab, click Application Default or System, depending on the quota type you want to create. 2. Click Add API, and select an API from the list (for example, a Swagger-based Petstore API). Alternatively, select All API. For details on registering APIs, see Register REST APIs in API Manager on page If you selected a specific API, you can select whether the quota applies to All Methods or to a specific method (for example, updatepet). 4. Select Throttle and enter a number of messages, or select Throttle MB and enter a number of megabytes. 5. Enter the amount of time, and select the time unit (for example 5 seconds). For more details, see Quota time windows on page 89. The following example system quota plan shows a mix of quotas that apply to all APIs and specific APIs (for all methods and a specific method): Axway API Manager User Guide 87

88 3 API management If an application-specific quota is defined, this completely overrides the application-default quota and its associated rules. The APIs > API Catalog view in the API Manager console only shows application-default quotas. Application-specific quotas Note If your front-end API uses pass-through authentication for the inbound request, there is no client application context so application quotas cannot be enforced. To create an application-specific quota, perform the following steps: 1. In the API Manager menu, click Clients > Applications. 2. Click the application name (for example, Test Application), and click the Quota tab. 3. Select Override default application quota. 4. Click Add API, and select an API from the list (for example, a Swagger-based Petstore API). Alternatively, select All API. For details on registering APIs, see Register REST APIs in API Manager on page If you selected a specific API, you can select whether the quota applies to All Methods or to a specific method (for example, deletepet). 6. Select Throttle and enter a number of messages, or Throttle MB and enter a number of megabytes. 7. Enter the amount of time, and select the time unit (for example 5 seconds). For more details, see Quota time windows on page 89. The following example shows an application-specific quota plan that includes a mix of quotas that apply to all APIs and methods, and to a specific API and method: Axway API Manager User Guide 88

89 3 API management Quota time windows When specifying time windows in quota rules, the quota opens when the API is called at the current second, minute, day, or week, depending on the time unit specified in the quota rule. For example, you have defined a quota rule on API A and method B that throttles the message count to N messages per hour. Then assume API A and method B was invoked at 14:33 for the first time. The specified rule is activated at the time of the first API call, setting the time window to start at the hour (14:00:00.000). If you get another call at 14:35, the counter is incremented, and its value is validated against the limit (N). If you get another call at 17:33, the new time window start will start at the hour (17:00:00.000), and the counter is reset to 0 before reflecting the API call from 17:33. Multiple quota rules per method You can also specify quotas with multiple rules for the same API methods for all quota types (system, application default, and application specific). For example, a system-level quota for a pet store API is specified with the following rules for the addpet method: 10 messages every 5 seconds 1000 messages every 1 day Both quota rules apply to the same API method. Configure quota storage settings You can configure how quota information is stored using Policy Studio in Server Settings > API Manager > Quota Settings. For more details, see Quota Settings on page 32 Manage OAuth authorizations API Manager enables API administrators to view and revoke OAuth authorizations made by protected resource owners. This enables you to manage all client application authorizations to access OAuthprotected APIs. This also means that resource owners do not need to re-authorize application requests. Axway API Manager User Guide 89

90 3 API management When client applications are authorized to access OAuth-protected APIs, they are issued with an access token and optionally a refresh token. API Manager displays the authorizations granted to each client application, including the scope. Revoking an OAuth authorization means that the access and refresh tokens that the client application has are no longer valid. The Clients > OAuth Authorizations tab enables you to manage the stored OAuth authorizations made by protected resource owners. The following details are displayed: SUBJECT: The name of the OAuth resource owner (for example, sample_user). SCOPES: The OAuth scopes used to managed access to the protected resource (for example, resource.write, openid). CREATED: When the authorization was first made. To revoke a stored authorization, and block further requests from the client application, select the resource owner name under SUBJECT, and click Remove. For more details, see the API Gateway OAuth User Guide. Manage organizations API administrators can use the Clients > Organizations tab to create and edit organizations. Create an organization To create an organization, perform the following steps: 1. Click New organization in the toolbar. 2. Configure the following general fields: Image: Click to add a graphical image for the organization (for example,.png,.gif, or.jpeg file). Organization name: Enter a name for the organization. This field is required. Enter an address for the organization. Enabled: Select whether the organization is enabled. The organization is enabled by default. API Development: Select whether the organization is enabled for API development. This setting is disabled by default. Note You must first enable an organization for API development before you can begin registering REST APIs for that organization. For more details, see Register REST APIs in API Manager on page 52. When the organization has registered APIs, you cannot disable this setting. Virtual host: Enter the virtual host and port on which unpublished APIs belonging to this organization are available. The host name should be DNS resolvable. Axway API Manager User Guide 90

91 3 API management 3. If Trial mode is enabled on the Settings > API Manager Settings page, the following settings are displayed to enable you to manage the lifespan of the organization: Trial Status: Select one of the following: o o o No Trial: The organization is not in trial mode. In Trial: The organization is in trial mode. Trial Ended: The trial for this organization has ended, the organization expires, and users in the organization can no longer log in. Trial Start: When the trial started. The trial starts when a member of the organization logs in. Trial End: When the trial will end. Trial Duration: Duration of the trial in days. Defaults to 30 days. Extend Trial: Click to extend the duration of the trial. Restart Trial: Click to reset a trial that has ended. The trial restarts when a member of the organization logs in. For more details on Trial mode, see API Manager settings on page Configure the following additional attributes: Phone: Enter a phone number for the organization if available. Description: Enter a short description of the organization. 5. Click Add API to select the APIs that the organization can access. 6. Click Generate code to generate optional registration codes used to simplify onboarding of new users into the organization. You can specify the Maximum number of users per code and The code is valid until. These codes are provided to new users who can input them when self-registering in API Manager. These users are then automatically registered in the organization. 7. Click Create in the toolbar. Edit an organization When organizations have been created, you can click an organization name in the Managing organizations screen to edit its settings. You can also perform the following tasks: Click Add API to select the APIs that the organization can access. Click Generate code to generate optional registration codes used to onboard new users into the organization. You can specify the Maximum number of users per code and when The code is valid until. You can provide these registration codes to new users who can input them when self-registering in API Manager. Click to view the Users and Applications in that organization. Axway API Manager User Guide 91

92 3 API management Manage users API administrators and organization administrators can use the Clients > Application Developers tab to create and edit the administrator users and the API consumers that use the APIs virtualized in APIs > API Catalog. Create a user To create a user, perform the following steps: 1. Click New user in the toolbar. 2. Configure the following general fields: Image: Click to add a graphical image for the user (for example,.png,.gif, or.jpeg file). Login Name: Enter a globally unique name to identify the user when logging in to API Manager. This can be changed only by an API administrator, and is read-only for all other users. This field is required. Note Changing a user s login name prevents that user from logging in. You must ensure that the user is notified of any change. Name: Enter the user's first name and surname to be used as a display name. This field is required. Enter an address for the user. This field is required, and the address must be globally unique. Enabled: Select whether the user is enabled. The user is enabled by default. 3. Configure the following membership fields: Organization: Select the organization that the user belongs to. The default list includes the API Development organization only. For details on creating organizations, see Manage organizations on page 90. Role: Select one of the following required roles for the user: o o o API Manager Administrator: This is the API administrator with full access rights. Organization Administrator: This administrator has a subset of access rights within an organization. User: This is the client application developer user (API consumer). For more details on roles, see API Management user roles on page Configure the following additional attributes: Phone: Enter a phone number for the user. Axway API Manager User Guide 92

93 3 API management 5. Click Create in the toolbar. Description: Enter a short description of the user. Edit a user When users have been created, you can click a user name in the Managing users screen to edit its settings. You can also do the following: Click to view the user's Organization and Applications. Click Reset password to generate a random password and send it to the user's address. Click Change password to enter a new user password in the dialog. Note When you delete a user, their applications are reassigned to the API administrator. Manage applications API administrators, organization administrators, and application developers (API consumers) can use the Clients > Applications tab. This enables you to create and edit the client applications that use the APIs virtualized in APIs > API Catalog. For details on managing applications, see Consume APIs in API Manager on page 98. Monitor APIs and applications in API Manager Overview API administrators and organization administrators can use the Monitoring tab in API Manager to view metrics on all invoked APIs and client applications in the system. For example, the metrics displayed on the Monitoring tab include the number of messages, successes, failures, and processing time per-invoked API, or per-client application, over a userdefined time range. This view shows the APIs and client applications that you manage, or have access to view. It only shows APIs and applications when there is data for these APIs and applications in the user-defined time range. The monitoring data is obtained from the metrics database, and the data points are written to the database in 5 minute and 1 hour intervals. At a minimum, applications invoking APIs do not have data available until the end of a 5 minute time window. Similarly, hourly data only becomes available at the start of every hour. You can filter the metrics displayed on the Monitoring tab based on specified APIs, methods, organizations, and applications. Axway API Manager User Guide 93

94 3 API management Prerequisites To enable monitoring in API Manager, perform the following steps: 1. Add the JDBC driver files for your chosen metrics database to your API Gateway installation. For example: INSTALL_DIR/apigateway/ext/lib/mysql-connector-java-5.x-bin.jar For more details, see "Configure the metrics database" in the API Gateway Installation Guide. 2. Ensure that your metrics database is running, and run the following command to configure your metrics database tables: INSTALL_DIR/apigateway/PLATFORM_OS/bin/dbsetup In this path, PLATFORM_OS can be Win32 or posix, depending on your environment. The following shows an example command: dbsetup --dburl=jdbc:mysql://localhost:3306/defaultdb -- dbuser=root --dbpass=changeme --reinstall For more details, see "Configure the metrics database" in the API Gateway Installation Guide. 3. Use the managedomain command to enable metrics for your Admin Node Manager host. For example: managedomain --edit_host --host=admin_node_mngr_host --metrics_ enabled=true --metrics_ dburl=jdbc:mysql://localhost:3306//defaultdb --metrics_ dbuser=root --metrics_dbpass=changeme --username MY_NAME -- password MY_PWD 4. In the Policy Studio tree, select Environment Configuration > Server Settings > API Manager > Monitoring to enable API Manager monitoring and configure your metrics database. Remember to click Save at the bottom, and click Deploy in the toolbar. For more details, see Configure API Manager settings in Policy Studio on page 29. Alternatively, you can automate this using a preconfigured.fed file. For example: managedomain --deploy -g GROUP_NAME --username admin --password changeme --archive_filename /tmp/deploy2.fed 5. Restart the API Gateway instance and Admin Node Manager. Axway API Manager User Guide 94

95 3 API management Monitor APIs in API Manager The Monitoring > API Usage view enables you to monitor the number of messages, successes, failures, and average processing time per-invoked API, over a specified time range. The following shows the metrics displayed for some example banking APIs: For more details on the metrics displayed, see Monitoring metrics on page 95. Monitor applications in API Manager The Monitoring > Application Usage view enables you to monitor the number of messages, successes, failures, and average processing time per-invoked client application, over a specified time range. The following shows the metrics displayed for a selected client application: For more details on the metrics displayed, see the next section. Monitoring metrics You can monitor the following metrics in both the API Usage and Application Usage views: Axway API Manager User Guide 95

96 3 API management Messages: The number of messages processed by the selected API or client application. Successes: The number of successful messages processed (that generated a success in an API Gateway policy). Failures: The number of failed messages processed (that generated a failure in an API Gateway policy). Exceptions: The number of messages that generated an exception in an API Gateway policy. Processing Time (Avg ms): The average time taken to process a message, including all calls to remote servers. Filter metrics data In both the API Usage and Application Usage views, you can use the FILTER panel on the left to filter the metrics data displayed in the graph and table on the right. By default, today s data for all APIs, methods, organizations, and applications is displayed. Date interval You can select a date interval instead of the default value of Today (for example, Last 7 days, Last 30 days, or a custom date range). Note You must click Apply or Reset to update the metrics graph and table on the right. APIs and methods You can use the API field to display data for All APIs or for a specific API. If you select a specific API, this enables the Method field. You can select All Methods or a specific method associated with the selected API. Organizations and applications You can use the Organization field to display data for All organizations or for specific organization. If you select a specific organization, this enables the Application field. You can select All Applications or a specific application associated with the selected organization. Note When filter fields are selected, you can start typing characters. All entries in the list that match on the starting characters are displayed. The search is not case-sensitive. If there are many entries in a list, the data is paginated, and the first 10 elements are displayed along with the option of viewing more entries. Show breakdown per API method In the API Usage view, when the Show breakdown per API method option is selected, the table on the bottom right displays totals grouped by API Name and Method Name. This option is selected by default. Axway API Manager User Guide 96

97 3 API management When Show breakdown per application is not selected, the table displays totals grouped by API Name only. There is no breakdown by Method Name and the method name is not displayed in the table. Show breakdown per application In the Application Usage view, when the Show breakdown per application option is selected, the table on the bottom right displays totals grouped by Organization Name and Application Name. This option is selected by default. When Show breakdown per application is not selected, the table displays totals grouped by Organization Name only. There is no breakdown by Application Name and the application name is not displayed in the table. Note Unlike the table, the graph will display the same data, regardless of whether the show breakdown settings are selected. If you select an individual row in the table, the graph is automatically updated to contain data for the selected row only. If you deselect the row, the chart is automatically updated to contain data for all rows, which is the default behavior. Apply the filter When you click Apply, the graph and table on the right are refreshed to contain data associated with the selected search filters. The options available in the filter lists are also refreshed to include any new changes (for example, any new APIs added). Reset the filter When you click Reset, the default selections is restored. This includes data for Today, for All APIs, All Methods, All Organizations and All Applications.The options available in the filter lists are also refreshed to include any new changes (for example, any new APIs added). Note In all cases, the graph and table on the right are not refreshed until you select Apply or Reset. If you select an API that is not related to the selected organization, the graph and table will be empty and the grid will display No data. This is not an error. Further information The Monitoring tab displays similar information as the API Gateway Analytics web console. For more details, see the API Gateway Administrator Guide. Axway API Manager User Guide 97

98 3 API management Consume APIs in API Manager Overview API consumer users consume managed APIs exposed by the API Gateway, using them to build and test client applications. API consumers can be client application developers from named organizations or the community organization. They can also include operator users who are responsible for monitoring production applications that invoke managed APIs. API Manager provides an intuitive user interface to enable API consumers to consume the managed APIs exposed by the API Gateway. Note This topic assumes that API Manager has already been enabled and configured for your environment. For more details, see Configure API Manager on page 25. Consume REST APIs Each API consumer user has an account in API Manager. They can use API Manager to perform tasks such as the following: Create applications Manage application authentication credentials Give other API consumers permission to view or manage their applications Monitor application API usage Manage their own account settings API consumers are concerned only with applications, credentials, and APIs. They do not require detailed knowledge of the API Gateway Register an API Manager user account The API consumer can use to following URL to register an API Manager user account: This displays the following registration dialog: Axway API Manager User Guide 98

99 3 API management When the user account has been registered, an is sent to the user to enable them to activate their account. They can then log into API Manager using their registered user name and password. For details on optional registration codes for organizations, see Administer APIs in API Manager on page 79. API consumer view When an API consumer user logs in to API Manager, this displays a specific view for the API consumer. This includes the following subset of menu options: API Catalog: Browse all virtualized APIs available to the organization. Applications: Create, manage or delete client applications that invoke APIs. Monitoring: View historical reports and statistics on all client applications created by the API consumer. Settings: Manage user Account Settings (for example, change password or user details). Axway API Manager User Guide 99

100 3 API management Browse and retrieve APIs You can use the API Catalog view to browse and retrieve APIs in API Manager. For example: Retrieve APIs using tags When tags have been added in API Manager by the API administrator, you can use them to browse and retrieve APIs. For example, you can click the Tags button in the API Manager toolbar to select tags to filter: In this example, selecting the Swagger tag would display the Petstore API only. You can also filter tags manually by entering the tag: prefix followed by the tag value in the filter box (for example, tag:swagger). You can filter multiple tags by entering a comma-separated list without any spaces between values. For example, in this case, entering a filter of tag:rest,r+d would displays the Customer portal and Petstore APIs only, and not the Star wars API, which is tagged as QA. For details on creating tags, see Administer APIs in API Manager on page 79. Download APIs in Swagger format If the API is a REST API that is Swagger 2.0 compatible, you can download the API in Swagger format. The following example shows the Swagger download link displayed under the API name: Axway API Manager User Guide 100

101 3 API management For more details, see Manage client applications You can use the Applications tab to manage client applications (for example, create, update, or remove client applications that invoke specific APIs). When an application is created, API administrators can also set authentication, quota, and sharing settings on the appropriate tab. The following example shows editing a client application: Axway API Manager User Guide 101

102 3 API management Note The API administrator must first specify the APIs that an organization is allowed to access before any of its client applications can have access to them. In API Manager, you can only add APIs to an application when they have been added to the organization. For more details, see Administer APIs in API Manager on page 79. Create an application To create an application, perform the following steps: 1. Click New application in the toolbar, and configure the following general fields: Image: Click to add a graphical image for the application (for example,.png,.gif, or.jpeg file). Application name: Enter the name of the application. This field is required. Organization: Enter the name of the organization that the application belongs to. This field is required. The choice of organization determines which APIs are available to the application. For more details, see Administer APIs in API Manager on page 79. Enabled: Select whether the application is enabled. Applications are enabled by default. 2. Configure the following additional attributes: Enter an address for the application. Phone: Enter a phone number for the application. Description: Enter a short description of the application. 3. Click Add API to select the APIs and methods used by the application. You can add multiple APIs for an application. 4. Click Create in the toolbar. Edit an application When applications have been created, you can click an application name in the Managing applications screen to edit its existing settings on the Application tab. API administrators can also configure additional settings on the following tabs: Authentication The following settings are available on the Authentication tab: API KEYS: Click New API Key to create an API key for the application. API keys are enabled by default. Click Show Secret to obtain the associated secret key. You can also specify JavaScript Origins to allow the application to run on specific protocols or domains (for example, for Cross Origins Resource Sharing (CORS). You can enter * to allow all domains. For more details, see Virtualize REST APIs in API Manager on page 59. Axway API Manager User Guide 102

103 3 API management OAUTH CREDENTIALS: Click New client ID to create a client ID for the application, and enter the following settings in the dialog: o o Application Type: Applications set to Confidential must always send the generated secret along with their OAuth-Authorization request. Applications set to Public may ommit the secret, when not using the client_credentials grant type. Defaults to Confidential. Redirect URLs: You can enter optional redirect URLs for the application (one URL per line). The application can then redirect users only to the specified URLs, which helps prevent attacks. o X.509 Certificate: You can paste the contents of a Base64-encoded public X.509 certificate for the application. This certificate is used to verify the signature of JWT tokens and SAML assertions used in the appropriate OAuth grant types. Newly created client IDs are enabled by default. You can click Show Secret to obtain the associated secret key. You can specify JavaScript Origins to allow the application to run on specific protocols or domains for CORS. For more details, see Virtualize REST APIs in API Manager on page 59. OAUTH EXTERNAL CREDENTIALS: Click New client ID, and enter the external client ID for the application. Client IDs are enabled by default. You can specify JavaScript Origins to allow the application to run on specific protocols or domains for CORS. For more details, see Virtualize REST APIs in API Manager on page 59. OAUTH SCOPES: Click Add scope, and select one of the following scopes to manage application access to protected resources: o o o o resource.read: Read-only access to the resource. resource.write: Write access to the resource. openid: OpenID Connect access to the resource. Add New Scope: Enter a custom scope name to manage access to the resource. Note These OAuth scopes settings are displayed only when Enable OAuth scopes per application is selected in Settings > API Manager settings > General settings. For more details, see Configure web-based settings in API Manager on page 36. Tip For more details on OAuth, see the API Gateway OAuth User Guide. Quota The Quota tab enables API administrators to override the application-default quota and specify application-specific quota rules. For more details, see Administer APIs in API Manager on page 79. Sharing The Sharing tab enables API administrators to manage access to the application for specified users. Click Add User, select an existing user name from the list, and select whether the user can View or Manage the application. The default is View. Axway API Manager User Guide 103

104 3 API management You can add multiple existing users. For details on creating users, see Administer APIs in API Manager on page 79. To remove user access to the application, select the user name, and click Remove. Manage the client application lifecycle When you have created client applications, you can select them in the Applications view, click Manage selected, and chose one of the following options: Delete selected item(s): Permanently deletes the selected applications from the client registry. Disable: Disables the selected applications in the client registry. Applications are enabled by default. Enable: Enables the selected applications that have previously been disabled in the client registry. Export: Exports a copy of the selected applications to your chosen directory. The APIs are exported in JSON format in a default app-export.dat file. You can specify the following options in the dialog: o o o o Specify a different file name Select whether to encrypt the application data Add a password Export API keys, OAuth credentials, and quota overrides You can then import this file into API Manager as required (for example, when promoting between environments). See also Promote managed APIs between environments on page 106. Tip You can click Export all in the menu bar at the top to export all client applications in the client registry. You can click Import to import previously exported applications in the selected.dat file. API Manager REST APIs The API Manager REST APIs enable you to perform create, read, update, and delete (CRUD) operations on API Manager data. For example, this includes configured APIs, users, organizations, applications, quotas, metrics, alerts and events related to API Manager. The API Manager REST APIs are available from the following locations: INSTALL_DIR/apigateway/samples/swagger Axway Documentation Portal: API Manager REST API v1.2 API Manager REST API v1.3 Axway API Manager User Guide 104

105 3 API management Import the API Manager REST API You can import the API Manager REST API Swagger 2.0 definitions into API Manager in the same way that you import any other APIs. For example: 1. Click the API Registration > Backend API view in API Manager. 2. Click New API and select Import Swagger API. 3. In the Import API dialog, complete the following: o o o o o Source: Select Swagger definition file. File or URL: Click the browse button to select the definition file. For example: INSTALL_DIR/apigateway/samples/swagger/api-manager-V_1_3- swagger.json API Name: Enter a user-friendly name for the API. The default is api-manager-v_1_ 3-swagger.json. Organization: Select the organization from the list (for example, API Development). 4. Click Import to import the API Manager API. For more details, see Register REST APIs in API Manager on page 52. Axway API Manager User Guide 105

106 API deployment 4 This part contains the following: Promote managed APIs between environments 106 Deploy sandbox and production APIs 112 Customize API Manager 116 Configure custom API Manager routing policies 122 Promote managed APIs between environments Overview When APIs have been registered in API Manager, you can promote them directly between environments using the API Manager export/import mechanism. This exports registered APIs in JSON format, which you can then import into API Manager as required. For more details, see the Manage front-end REST API lifecycle on page 77. The following approaches to promoting managed APIs are also available: Use the apimanager-promote script to automatically promote APIs between environments with zero downtime for DevOps. Use a promotion policy that you have configured in Policy Studio to automate promotion between environments. When APIs have been developed using Policy Studio, you can also promote them between environments using the API Gateway mechanism for promotion and deployment of standard API Gateway configuration. This topic describes each of these approaches to API promotion. Promote registered APIs with zero downtime using a script The apimanager-promote script enables you to: Promote APIs and client applications registered in API Manager to another environment with zero downtime. For example, this ensures that you will not lose service due to any APIs that are unpublished. Axway API Manager User Guide 106

107 4 API deployment Perform automatic bulk import of APIs and applications previously exported using the API Manager REST API or web console. Ensure that pre-configured credentials continue to work between environments. Export a subset of APIs and applications and re-import with customized settings in a properties file. Handle updates of any conflicting APIs, applications, or application credentials without causing downtime for any published APIs. How to use the apimanager-promote script When using the apimanager-promote script, the high-level steps are as follows: 1. Export the APIs and applications that you wish to promote from API Manager (as a.dat file in JSON format). For example, select the front-end APIs that you wish to export, and click Manage selected > Export API collection. For more details, see Manage front-end REST API lifecycle on page 77 and Manage the client application lifecycle on page 104. Alternatively, you can export using the API Manager REST API. For more details, see API Manager REST APIs on page Create your promotion.properties file to specify how your APIs and applications are promoted. See Generate your promotion.properties file on page Place your exported API and application files (.dat) and your generated promotion.properties file in the same directory. Note You must ensure that the respective files names are api-*.dat, application- *.dat, and promotion.properties, and change the file names if necessary. 4. Run the apimanager-promote script to import the APIs into the target API Manager environment. This script is available in the following directory: UNIX/Linux INSTALL_DIR/apigateway/posix/bin Windows INSTALL_DIR\apigateway\Win32\bin Run the apimanager-promote command You must specify the target environment that you wish to promote into, your API administrator credentials, along with your source API data files and promotion properties file. For example: apimanager-promote --target -- Axway API Manager User Guide 107

108 4 API deployment username my_admin --passfile users/apiadmins/my_admin-pass <path/to/my_ api_data> Note The path/to/my_api_data directory must include the exported.dat file for the source APIs (and optional applications if exported) and your promotion.properties file. Specify apimanager-promote command options You can specify the following command options: Command option Description -? --help Print help message and exit. -f, --passfile <arg> Specify an API administrator password file. -p, --password <arg> Specify an API administrator password. -t, --target <arg> Specify the target API Manager environment URL. --template -u,--username <arg> Print out the promotion.properties template file to help specify the required data. Specify the API administrator user name. Generate your promotion.properties file You must create a promotion.properties file to specify options for the APIs and applications to be promoted. For example, this enables you to specify how to manage any conflicts and an optional virtual host for the target environment. You can use the apimanager-promote --template command to generate a default properties file, which you can then customize as needed. For example: >apimanager-promote --template # promotion.properties (generated 09/05/17 15:55) organization.apipromotion.import=api Development organization.target=community api.conflict.upgrade=false Axway API Manager User Guide 108

109 4 API deployment application.conflict.upgrade=false application.apikey.upgrade=false application.oauthclient.upgrade=false application.oauthresource.upgrade=false api.publish.virtualhost= api.unpublished.remove=false Note You must ensure that the target organizations specified in the promotion.properties file already exist in that instance before running the apimanager-promote command. The promotion properties are described as follows: Property organization.apipromotion.import organization.target api.conflict.upgrade application.conflict.upgrade application.apikey.upgrade application.oauthclient.upgrade application.oauthresource.upgrade Description Specify the target development organization that all the APIs are imported into (for example, the default API Development organization). Specify the target consumer organization that all the client applications are imported into. This organization is also given access to all the imported APIs (for example, the Community organization). Specify whether to promote an existing API if there is a conflict in the development organization (true or false). Specify whether to promote an existing application if there is a conflict in the consumer organization (true or false). Specify whether to promote an existing API key if there is a conflict in the consumer organization (true or false). Specify whether to promote an existing OAuth client application if there is a conflict in the consumer organization (true or false). Specify whether to promote an existing OAuth resource if there is a conflict in the consumer organization (true or false). Axway API Manager User Guide 109

110 4 API deployment Property api.publish.virtualhost api.unpublished.remove Description Specify an optional virtual host name and port on which the promoted APIs are available. The host name should be DNS resolvable. Specify whether to remove an old unpubished API from the development organization (true or false). This only applies when an upgrade occurs. For example, if there is a conflict and api.conflict.upgrade is set to true, this results in two APIs (existing and upgraded). The api.unpublished.remove option specifies whether to keep or delete the existing API that has been unpublished. Tip After running the apimanager-promote command, press F5 to reload the API Manager web console in the target environment. Promote registered APIs using a promotion policy APIs and applications registered using API Manager can be exported from one API Manager environment and imported into another API Manager environment using a file-based package (.dat file in JSON format). For example, this enables APIs to be promoted from a sandbox API group where client applications are developed and tested to the production API group. You can use a custom promotion policy that has already been developed in Policy Studio to automate this process in API Manager. Note If you use a custom promotion policy, you must also promote this policy as part of the standard API Gateway configuration. For more details, see Promote APIs developed in Policy Studio on page 112. Create the promotion policy in Policy Studio You must first create your custom promotion policy in Policy Studio to import APIs into a target environment. For example, the following promotion policy is based on the proxies/import method provided in the API Manager REST API: Axway API Manager User Guide 110

111 4 API deployment This policy imports a previously exported API as follows: If the API was exported using a password, the file is encrypted, and a password must be set to decrypt. The target API Manager environment is specified by setting the target organization ID. The import creates a virtualized API and all the back-end API definitions necessary for the frontend API in JSON format. This approach is similar to the proxies/importfromurl method except that it supports traditional form-based file upload to the target environment using multipart/formdata. For more details on the on the proxies/import method, see API Manager REST APIs on page 104. Tip You can also use the Set Attribute filter in your promotion policy to configure the errormessage message attribute with a meaningful error message. For example, when used in conjunction with a False filter, this message can then be displayed in API Manager if the API promotion policy fails. For more details on how to create policies, see the API Gateway Policy Developer Guide. Axway API Manager User Guide 111

112 4 API deployment Enable the promotion policy in Policy Studio To enable your custom promotion policy in Policy Studio, select Server Settings > API Manager > API Promotion in the Policy Studio tree. For more details, see Configure API Manager settings in Policy Studio on page 29. Enable the promotion policy in API Manager When you have configured and deployed a promotion policy in Policy Studio, you must also then enable the policy in API Manager. You can do this by selecting Settings > API Manager settings > API REGISTRATION > API promotion via policy. A Promote API option is then added to the Frontend API management menu when you log in again. For more details, see Configure webbased settings in API Manager on page 36. For details of onboarding a client application from sandbox APIs to production APIs, see Deploy sandbox and production APIs on page 112. Promote APIs developed in Policy Studio APIs created with the REST API development wizard in Policy Studio are part of the standard API Gateway configuration. This means that you can promote APIs between environments using the API Gateway mechanism for promotion and deployment of API Gateway configuration (using.fed,.pol, and.env packages). For example, you can use this mechanism to promote APIs from a testing environment to a production environment and to handle differences between each environment. For more details on the API Gateway mechanism for promoting configuration between environments, see the API Gateway DevOps Deployment Guide. For details of onboarding a client application from sandbox APIs to production APIs, see Deploy sandbox and production APIs on page 112. Deploy sandbox and production APIs Overview In a production environment, enterprises should create and deploy the following separate API Gateway groups: Sandbox API group the APIs that API consumers use against test back-end systems before going live (for example, a test credit card payment system) Production API group the production APIs that front the production back-end systems (for example, a live credit card payment system) Axway API Manager User Guide 112

113 4 API deployment This production environment topology is recommended by Axway. For details on creating a domain environment topology, see the API Gateway Administrator Guide. This topic shows an example production environment topology with Sandbox and Production API groups, and shows examples of promoting and onboarding Sandbox APIs to Production APIs. Production environment topology The following diagram shows the environment topology in a typical production domain. This environment topology includes two separate API Gateway groups, each of which includes two API Gateway instances with API Manager deployed on each, and its own Client Registry and API Manager. This enables the message traffic for the Sandbox API and the Production API to be kept separate. For example, in named organization X, when an API consumer builds a client application, they log into API Manager in the Sandbox API group. The development application sends requests to the API Gateway instances in the Sandbox API group. Similarly, when an operator manages the production application, they log in to API Manager in the Production API group. The production application sends requests to the API Gateway instances in Production API group. In this way, the Sandbox test traffic can be isolated from the live Production traffic. The Sandbox API group can support both the Community organization and named organizations, including self-registration. API consumers are registered to create applications, and applications are registered for testing prior to onboarding to the Production APIs. However, the Production API group should support named organizations only, and not the Community, with registration restricted to the API administrator and organization administrator. Axway API Manager User Guide 113

114 4 API deployment Tip Promote configuration to sandbox and production APIs The following diagram shows the process of promoting API Gateway policy-based configuration from the downstream environment (for example, development or testing) to both the Sandbox API and Production API groups in the production environment. Both the Sandbox API and Production API groups are virtualizing the same APIs and therefore must use the same policy package (.pol). During configuration promotion, the policy package from the downstream environment (for example, testing) is copied and deployed to both API groups. However, both API groups use different environment specific configuration (for example, to connect to different back-end systems, which require different connection information). Therefore each API group has a specific environment package (.env) that is deployed to the API group along with the common policy package. For more details on promoting API Gateway configuration between environments, see the API Gateway DevOps Deployment Guide. Axway API Manager User Guide 114

115 4 API deployment Tip If your deployment does not use API Gateway policy-based configuration, you can promote APIs from a downstream environment using the API Manager export/import mechanism. For more details, see Promote managed APIs between environments on page 106. Onboard to production APIs The following diagram shows the process of onboarding a client application from the Sandbox API group to the Production API group. For the API Provider, production onboarding involves registering the API Client in the Production API group, and copying or importing client application information from the Client Registry in the Sandbox API group. For the API Client, the client application is deployed into the API Client production environment, and is configured to invoke the Productions APIs. Axway API Manager User Guide 115

116 4 API deployment Note Production onboarding involves more than the technical task of onboarding information between API groups. Internal business processes, which are out of the scope of this document, also need to be considered. These include commercial or legal issues that need to be resolved when setting up a formal business partnership between an API Provider and API Client. For example, will the client be charged for API use, and what quotas are required to service the demand from the end users of client applications. Configure high availability Each API Gateway instance connects to an external Apache Cassandra for default persistent data storage. This Cassandra database is used by features such as API Manager, API keys, and OAuth. If you configure multiple API Gateways in a group, you should configure high availability in the Apache Cassandra database. For more details, see the API Gateway Installation Guide. Customize API Manager Overview This topic outlines how to customize features such as the following: Axway API Manager User Guide 116

117 4 API deployment Organization, user, and application data Password validation API Gateway Manager console for testing Typically, there should be little need to perform custom development to re-code API Manager. Any changes made to API Manager code are not supported by Axway. You should use an unmodified API Manager for internal system administration. Create a custom API portal For deeper customization and integration with your website, you should use Axway API Portal to create a heavily branded and customized self-service web portal, which enables API consumers to consume APIs that you have exposed. This portal enables API consumers to register user profiles and applications, manage credentials, browse front-end APIs and documentation, monitor application use of APIs, access blogs and forums, and so on. API Portal is implemented as a stand-alone CMS-based portal, which you can run using the default Axway branding and functionality, or customize and extend to meet your specific requirements and those of your target API consumers. You can deploy the internet-facing API Portal separately from API Gateway and API Manager, with a dedicated web interface to limit potential security breaches. For more details, see the following API Portal documentation: API Portal Installation and Upgrade Guide API Portal Administrator Guide Customize API Manager data API Manager organization, user, and application objects support user-defined fields called custom properties. These custom properties are stored with all other object properties in API Manager persistence layer (which defaults to Apache Cassandra). You can set and retrieve these custom properties in the same way as the default out-of-the-box Organization, User, or Application fields. You can extend the respective user interface screens to enable viewing and editing of these custom properties. For user objects, these custom properties can also be set during user registration. Add a custom property to organizations The following example adds a new field for organizations that enables the user to register the Skype ID for an organization. To add a custom property (in this case, Skype ID) to organizations, perform the following steps: 1. Edit the following file: INSTALL_DIR/apigateway/webapps/apiportal/vordel/apiportal/app/app.config 2. Insert the following code fragment marked in bold in the organizations property: Axway API Manager User Guide 117

118 4 API deployment custompropertiesconfig: { organization: { // custom properties skypeid: { label: 'Skype' } } } 3. After updating the file, log into API Manager. 4. Press Ctrl-F5 to refresh. The Managing Organizations screen now contains the new custom property. Using the skypeid custom property, the following example HTTP request creates an organization with this custom property: POST /api/portal/v1.0/organizations/ HTTP/1.1 content-type: application/json Authorization: Basic YXBpYWRtaW5AbG9jYWxob3N0OmNoYW5nZW1l User-Agent: Jakarta Commons-HttpClient/3.1 Host: localhost:8075 Content-Length: 145 { "name" : "MyOrg", "description" : "My organization.", "phone" : "+353 (1) ", " " : "myorg@axway.com", "skypeid" : "MYORG", "enabled" : true } The following example HTTP request updates an organization with this custom property: PUT /api/portal/v1.0/organizations/c85cf2e6-cb5e-4f37-afb2-5f0d250e40f2 HTTP/1.1 content-type: application/json Authorization: Basic YXBpYWRtaW5AbG9jYWxob3N0OmNoYW5nZW1l User-Agent: Jakarta Commons-HttpClient/3.1 Host: localhost:8075 Content-Length: 238 { "id" : "c85cf2e6-cb5e-4f37-afb2-5f0d250e40f2", "name" : "MyOrg", "description" : "My organization.", "phone" : "+353 (1) ", " " : "org2@axway.com", "skypeid" : "myorg", "enabled" : true, "restricted" : false, "createdon" : Axway API Manager User Guide 118

119 4 API deployment } Add a custom property to users To add a custom property to users, insert the following code fragment marked in bold to the user property in the app.config file: custompropertiesconfig: { user: { // custom properties skypeid: { label: 'Skype' } } } Add a custom property to applications Similarly, to add a custom property to applications, insert the following code fragment marked in bold to the application property in the app.config file: custompropertiesconfig: { application: { // custom properties skypeid: { label: 'Skype' } } } In both cases, after updating the file, log into API Manager, and press Ctrl-F5 to refresh. Specify custom property options Custom properties are custompropertiesconfig fragments with a unique name (for example, skypeid). You can specify the following options: Property Option label Description Required. Friendly name for the property displayed in API Manager (for example, label:'my Custom Property'). Axway API Manager User Guide 119

120 4 API deployment Property Option type Description Optional. Can be one of the following: custom: For text fields (the default) switch: For on/off switch fields select: For drop-down list fields For example, use type:select to specify a custom property as a dropdown list. disabled permissions Optional. Can be false or true. Overrides the permissions option. Defaults to disabled:false. Optional. Read/write permissions per-user role. By default, the property is read and write for all roles. The following shows an example: permissions:{ admin:{ read:true, write:true }, oadmin:{ read:true, write:true }, user:{ read:true, write:true } }, options Optional. But required for the switch and select options. The following shows an example: options:[ {value:true, label:'one'}, {value:'ii', label:'two'}, {value:3, label:'three'} ], Customize API Manager password validation API Manager enables you to perform custom password validation based on a specified regular expression. For example, you can test for a mix of lowercase, uppercase, and special characters for the API Manager user registration and change password features. If the password characters validate, this returns true. Otherwise, this returns a specified error message, or false. Validate password for user registration and change password features You can customize password validation for the API Manager user registration and change password features by editing the following files: User registration: Axway API Manager User Guide 120

121 4 API deployment INSTALL_DIR/apigateway/webapps/apiportal/vordel/apiportal/app-login/app.config Change password: INSTALL_DIR/apigateway/webapps/apiportal/vordel/apiportal/app/app.config Configuration steps In each of these app.config files, perform the following steps: 1. Specify a custom regular expression in the validatepassword method. For example: validatepassword:function(password) { }, return /(?=.*\d)(?=.*[a-z])(?=.*[a-z]).{6,}/.test(password); 2. Specify a custom validation message for invalid passwords in the next section. For example: invalidpasswordmessage:'password must include uppercase, lowercase, and special characters.', 3. After updating these files, enter the API Manager URL, for example: 4. Press Ctrl-F5 to refresh, and log into API Manager. Customize API Gateway Manager URL API Manager enables you to specify the location of the API Gateway Manager web console that is used for testing. For example, this enables the Try method button to link to the specified API Gateway Manager console for viewing the transaction log. For more details, see Virtualize REST APIs in API Manager on page 59. For more details on using API Gateway Manager, see the API Gateway Administrator Guide. To specify the location of the API Gateway Manager console, perform the following steps: 1. Edit the following file: INSTALL_DIR/apigateway/webapps/apiportal/vordel/apiportal/app/app.config 2. Enter the location of the API Gateway Manager console. For example: nodemanager:' Axway API Manager User Guide 121

122 4 API deployment 3. After updating the file, log into API Manager. 4. Press Ctrl-F5 to refresh. Further information Web application developers can use the API Manager REST API to perform custom development. For example, you can use this REST API to view and update the configured users, organizations, applications, and to monitor events related to API Portal and API Manager. For more details, see the API Manager REST APIs on page 104. Configure custom API Manager routing policies This topic explains the advanced use of case of how to configure custom API Manager routing policies. It shows examples of using API key and OAuth as the outbound authentication types. Note This topic assumes that you are already familiar with basic API Manager tasks such as importing an existing back-end API and virtualizing a front-end API and with authentication mechanisms such as API key and OAuth. Configure a custom routing policy with API key authentication This section explains how to setup a custom API Manager routing policy that uses API key as the outbound authentication type. It shows how to create the policy in Policy Studio, and how to configure it for use in API Manager. Create the custom routing policy in Policy Studio You must first create a new policy in Policy Studio that will be used as the custom routing policy in API Manager. Perform the following steps: 1. Right-click the Policies node in the tree, and select Add Policy. 2. Enter a meaningful Name for the new policy (for example, Custom routing policy for PetStore API). 3. Click the new policy in the tree to start configuring its filters. You can do this by dragging the required filters from the filter palette on the right, and dropping them on to the policy canvas. This example includes Trace and Connect to URL filters: Axway API Manager User Guide 122

123 4 API deployment 4. Open the Connect to URL filter, and in the URL field, enter ${destinationurl}. 5. On the Authentication tab, you will need to set the client credential profile to the ${params.authn} selector. To do this, click Finish, press Shift, and double-click the filter on the policy canvas to reopen it in advanced mode: 6. In the ^profile field, enter ${params.authn}, click Save Changes, and Close. The Authentication tab should now display this setting as follows: Axway API Manager User Guide 123

124 4 API deployment For more details on how to configure policies, see the API Gateway Policy Developer Guide. Configure the list of API Manager routing policies in Policy Studio You must add the new custom routing policy to the list of available routing policies that APIs registered in API Manager can use. Perform the following steps: 1. Select Server Settings in the tree, and select API Manager > Routing Policies. 2. Click Add on the right, and select the custom routing policy that you created (for example, Custom routing policy for PetStore API). 3. Click OK, and click Save at the bottom right. Axway API Manager User Guide 124

125 4 API deployment Configure the custom routing policy using API key in API Manager When the custom routing policy has been added to the list of available routing policies in Policy Studio, perform the following steps in API Manager: 1. Click API > Backend > New API to import a back-end API, and ensure the Base path URL is set to the API on the remote server. For more details, see Register REST APIs in API Manager on page Click API > Frontend > New API to create a front-end virtualized API from the back-end API. For more details, see Virtualize REST APIs in API Manager on page On the Inbound tab, set Inbound security to Pass Through. 4. On the Outbound tab, set Outbound authentication profile to API Key, click Edit and configure the following settings: API key field name: Use the default value of KeyId. API key: Enter the API key for your API. Pass credentials as HTTP: Select Header from the list. Axway API Manager User Guide 125

126 4 API deployment 5. Click Advanced on the right, and set Default method routing to use your custom routing policy. For example: Invoke the registered API and view the API key in the request You can now invoke the API registered in API Manager and view that the API key header is specified in the outbound request and that a successful response is returned. The following example in the API Gateway Manager web console shows the KeyId in the request at the bottom left: Axway API Manager User Guide 126

127 4 API deployment For more details on the API Gateway Manager web console, see the API Gateway Administrator Guide. Configure a custom routing policy with OAuth authentication This section describes how to use API Manager to invoke an API with outbound OAuth authentication using a custom routing policy. In this scenario, one API Gateway instance acts as an OAuth client and the other API Gateway instance acts as an OAuth server. This section shows how to configure both API Gateway instances appropriately using the Client Credentials OAuth flow. Note This section assumes that you are already familiar with the Client Credentials OAuth flow. For more details on configuring OAuth flows, see the API Gateway OAuth User Guide. Configure the remote API Gateway as OAuth server in API Manager To configure a remote API Gateway instance to act as an OAuth server, perform the following steps in API Manager: 1. Click Clients > Applications > New application. For more details, see Consume APIs in API Manager on page On the Authentication tab, under OAuth Credentials, click New client ID > Create, and use the default settings: Axway API Manager User Guide 127

128 4 API deployment 3. Click API > Backend > New API to import a back-end API. For more details, see Register REST APIs in API Manager on page Click API > Frontend > New API to create a front-end virtualized API from the back-end API. For more details, see Virtualize REST APIs in API Manager on page Set the Inbound security to OAuth. This example uses the default setting to obtain the access token from the header: Tip You must select an OAuth access token store on the General tab. For details on how to add OAuth access token stores, see Configure API Manager settings in Policy Studio on page Click Clients > Applications > API Access > Add API to add the virtualized front-end API to the list of APIs that the application can access. 7. Click Settings > API Manager Settings >General settings, and ensure that Enable OAuth scopes per application is set. 8. Click Clients > Applications > Authentication > OAuth Scopes > Add scopes, and select the resource.read and resource.write scopes: Tip You may need to refresh your browser if OAuth Scopes are not displayed. Axway API Manager User Guide 128

129 4 API deployment Configure the client credentials in Policy Studio When using the Client Credentials OAuth flow for the client, you must first configure the client credentials correctly in Policy Studio. This ensures that the client can request an OAuth access token using only its client credentials and that the authorization is specified in the header as expected. Perform the following steps: 1. In the Policy Studio tree, select Policies > OAuth 2.0 > Access Token Service > Client Credentials. 2. Right-click the Access Token using client credentials filter, and select Edit. 3. On the Application Validation tab, select the In Authorization Header option: For more details on OAuth flows, see the API Gateway OAuth User Guide. Configure the local API Gateway as OAuth client in Policy Studio To configure a local API Gateway instance to act as an OAuth client, perform the following steps: 1. To create an OAuth2 credentials application using the Client Credentials flow, select Environment Configuration > External Connections > Client Credentials > OAuth2, right-click and select Add OAuth2 Client Credential. For more details, see the API Gateway OAuth User Guide. 2. Click Add OAuth2 Application Settings on the right, and ensure the following settings are configured: Enter the Client ID and Client Secret that were generated on the remote API Gateway instance. See Configure the remote API Gateway as OAuth server in API Manager on page 127. Select an OAuth Flow Type of Client Credentials. On the Scopes tab, click Add to add the resource.read and resource.write scopes. Axway API Manager User Guide 129

130 4 API deployment 3. On the Advanced tab, you must also ensure that In Authorization Header is selected for the location of the client ID and client secret: 4. Click Save on the right to save the application. 5. On the OAuth2 Provider Settings tab, enter the IP address of the remote instance in the Authorization Endpoint and Token Endpoint: Axway API Manager User Guide 130

131 4 API deployment Create the custom routing policy using OAuth in Policy Studio To create a new policy to use as the OAuth custom routing policy in API Manager, perform the following steps in Policy Studio: 1. Right-click the Policies node in the tree, and select Add Policy. 2. Enter a meaningful Name for the new policy (for example, Custom routing policy with OAuth). 3. Click the new policy in the tree to start configuring the filters for this policy. You can do this by dragging the required filters from the filter palette on the right, and dropping them on to the policy canvas. This example includes Get OAuth Access Token and Connect to URL filters: 4. In the Get OAuth Access Token filter, the client credentials profile is obtained from the message whiteboard by default, so the token should now be available. 5. In the Connect to URL filter, you must specify that the destination URL and the client credentials application is obtained from the message whiteboard using the ${params.authn} selector. To do this, press Shift, and double-click the filter on the policy canvas to reopen it in advanced mode: Axway API Manager User Guide 131

132 4 API deployment 6. In the ^profile field, enter ${params.authn}. and click Save Changes and Close. For more details on how to configure policies, see the API Gateway Policy Developer Guide. Configure the list of API Manager routing policies and OAuth outbound credentials in Policy Studio You must add the new custom routing policy and OAuth credentials to the lists of available routing policies and credentials that APIs registered in API Manager can use. Perform the following steps: 1. Select Server Settings in the tree, and select API Manager > Routing Policies. 2. Click Add on the right, and select the custom routing policy that you created (for example, Custom routing policy with OAuth). 3. Select API Manager > OAuth Outbound Credentials. 4. Click Add on the right, and select the OAuth client credentials that you created (for example, Test OAuth). 5. Click OK, and click Save at the bottom right. Axway API Manager User Guide 132

133 4 API deployment Configure the custom routing policy using OAuth in API Manager When the custom routing policy and OAuth outbound credentials have been added in Policy Studio, perform the following steps in API Manager: 1. Click API > Backend > New API to import a back-end API, and ensure the Base path URL is set to the API on the remote server. For more details, see Register REST APIs in API Manager on page Click API > Frontend > New API to create a front-end virtualized API from the back-end API. For more details, see Virtualize REST APIs in API Manager on page On the Inbound tab, set the Inbound security to Pass Through. 4. On the Outbound tab, set the Outbound authentication profile to OAuth, and configure the following: Provider profile: Enter the OAuth outbound credentials profile that you created in Policy Studio (for example, Test OAuth). Token Key (Owner ID): Use the default ${authentication.subject.id} selector setting to obtain this value. 5. Click Advanced at the top right, and set the Default method routing to use your custom routing policy. For example: Axway API Manager User Guide 133

134 4 API deployment Invoke the registered API with OAuth authorization header in request You can now invoke the API registered in API Manager and view that the authorization header is specified in the outbound request and that a successful response is returned. The following example in the API Gateway Manager web console shows the OAuth custom routing policy in the execution path: The following example shows the Authorization Bearer header correctly displayed in the request in the bottom panel in API Gateway Manager: For more details on the API Gateway Manager web console, see the API Gateway Administrator Guide. Axway API Manager User Guide 134

135 Application connectors 5 This part contains the following: Cloud application connectors 135 Configure a connector for Salesforce APIs 139 Configure a connector for ServiceNow APIs 147 Configure a connector for Axway API Runtime Services 157 Connect to Axway Mobile Backend Services 165 Cloud application connectors Overview API Manager enables you to connect to and manage cloud-based applications, such as the following: Salesforce.com provides cloud-based customer relationship management (CRM) solutions ServiceNow provides cloud-based service management solutions (for example, IT, human resources, facilities, field service, and so on) Axway API Builder enables you to easily connect your mobile apps to any data source. This topic introduces the primary use cases for the cloud application connectors provided by API Manager: API Management for digital transformation on page 135 Hybrid application integration platform on page 137 API Management for digital transformation Companies are focusing on ways to open up their existing business, deliver new channels, and support new business models using REST APIs. They are adopting API management capabilities such as web service and REST API registration and API catalog. Companies need to deliver new initiatives much faster, reducing cost, and improve overall business performance. To deliver these new initiatives, companies need an easy and fast way to register their application APIs and expose them safely to their employees, customers, and partners. The following architecture diagram shows how companies can manage their cloud application APIs using API Manager: Axway API Manager User Guide 135

136 5 Application connectors The primary user role in this use case is the API administrator. The policy developer is a secondary role. In some organizations, both roles may be performed by the same person. API administrator role The API administrator performs the following tasks: Registers specific cloud application APIs o o Browses the APIs exposed by a selected cloud application Registers the required APIs for the business objects to expose Virtualizes the registered cloud application APIs o o Chooses the authentication profile to connect to the cloud application Sets the security profile to secure the exposed APIs to end users Policy developer role The policy developer performs the following tasks: Defines the cloud application connection details to enable API registration from the application o Defines the connection parameters to connect API Manager to the cloud application Axway API Manager User Guide 136

137 5 Application connectors Sets the authentication configuration to enable API Manager to connect to the cloud application o o Defines the cloud application connection details to enable end-user API consumption Sets the authentication configuration to enable API Manager to connect to the cloud application on behalf of the end user Hybrid application integration platform Companies are now more and more willing to extend their application integration across and beyond the firewall to leverage the benefits of their cloud services. They are now adopting simple and web-based approaches to integrate and hide the complexity of orchestration, data transformation, and error handling with pre-built application connectors. These support the most common integration patterns for both cloud services and on-premise applications. Cloud service integration The following architecture diagram shows an overview of using API Manager to integrate two cloud services: In this scenario, the target and source cloud applications both expose their APIs. The policy developer performs the following tasks: Defines the connection and authentication settings to connect API Manager to those applications for browsing, and registers their APIs so that applications can send and receive data Virtualizes and sets the runtime authentication configuration of both applications so that API requests can be sent by the source application to API Manager, and received by the target application from API Manager Links the source application API to the transformation policy, which sends transformed API requests to the target application API Axway API Manager User Guide 137

138 5 Application connectors Cloud service and on-premise application integration The following architecture diagram shows an overview of using API Manager to integrate a cloud service with an on-premise application: In this scenario, only the target cloud application exposes its APIs. The policy developer performs the following tasks: Defines connection and authentication settings to connect API Manager to the target cloud application so that it can browse and register its APIs and send it data Virtualizes and sets the runtime authentication configuration of the target cloud applications so that API requests can be received by the target application from API Manager Creates a new API to be exposed to the source application (specific development may be required in the source on-premise application to use the newly created API) Links this new API to the transformation policy, which will send transformed API requests to the target application API Registers, secures, and exposes this new API in API Manager so that it can be consumed by the source application Further information For more details, see the following topics: Configure a connector for Salesforce APIs on page 139 Configure a connector for ServiceNow APIs on page 147 Configure a connector for Axway API Runtime Services on page 157 Axway API Manager User Guide 138

139 5 Application connectors Configure a connector for Salesforce APIs Overview API Manager enables you to import and manage cloud application APIs such as Salesforce.com. The policy developer can configure client authentication profiles for use with the Salesforce.com API connector in Policy Studio. When the policy developer has connected to the Salesforce.com cloud API provider, the API administrator can then import and manage Salesforce.com application APIs in the API Manager web console. Salesforce.com API use cases Salesforce.com provides cloud-based customer relationship management (CRM) solutions. Salesforce.com provides the following types of API: Standard Object API: Used to manipulate business objects in the system. Bulk API: Provides a REST interface for importing and exporting a set of data. For example, the API administrator can use the Standard Object API to expose SalesForce.com opportunities to sales teams on their desktop and mobile devices. Salespeople can also create new opportunities while on-site with customers. The API administrator can use the Bulk API to extract a daily set of opportunities from SalesForce.com and store them in an archive. Configure an API connector for Salesforce.com The policy developer can configure an API connector in Policy Studio. To configure a connector, perform the following steps: 1. Select Server Settings > API Manager > API Connectors in the Policy Studio tree on the left. 2. Click Add to add a new connector. 3. Configure the following settings to suit your environment: Name: The name of the API connector: Salesforce.com. Resource Prefix: The resource prefix used for the API connector: salesforce. Description: A short description of the API connector. Axway API Manager User Guide 139

140 5 Application connectors URL: 4. Click OK. Leave this field blank for Salesforce.com (applies to SeviceNow only). Class: The Java class for the API connector: com.vordel.apiportal.api.connector.sf.salesforceconnector Client Credentials: Salesforce.com APIs require OAuth-based authentication. For more details, see Configure OAuth client credentials for Salesforce.com on page 141. You can also rightclick the parent Salesforce node to edit the OAuth provider settings (for example, provider URLs and token stores). For more details, see Configure OAuth provider settings for Salesforce.com on page 142. Max APIs/Import: Enter the maximum number of APIs that can be imported from the Salesforce.com cloud provider into a single API in API Manager. A very large number makes it harder for an API owner to manage. The Salesforce.com connector defaults to 100 APIs per import. For more details, see Import Salesforce.com APIs in API Manager on page 143 Custom Configuration: Enter custom configuration details if any. For example, the supported versions for Salesforce.com are {"apiversion":"33"} or {"apiversion":"34"}. The following example shows the API connector configuration for the Salesforce.com connector in Policy Studio: Axway API Manager User Guide 140

141 5 Application connectors Configure OAuth client credentials for Salesforce.com Under Environment Configuration > External Connections > Client Credentials > OAuth2 > Salesforce, the default Salesforce.com Connector OAuth Credentials client profile includes basic settings, which you can customize for your environment. The following shows an example when you click Edit on the OAuth2 Credentials tab, and select Advanced: API Manager behaves as an OAuth client to Salesforce.com APIs, so you must configure valid client application credentials. To configure client credentials for Salesforce.com, perform the following steps. 1. Your Salesforce.com administrator must first create a Connected app to represent API Manager in your Salesforce.com account. 2. When the Connected app is set up, Salesforce.com provides a Consumer Key and Consumer Secret for the app, which are used to configure the Saleforce.com connector in Policy Studio. Note When accessing data using its APIs, Salesforce.com asks its users to use their account password concatenated with a security token that is randomly generated and ed to users. You must ensure that the security token is added to the end of the password to log in. Axway API Manager User Guide 141

142 5 Application connectors 3. Update the Client Id and Client Secret fields with the Consumer Key and Consumer Secret values that you obtained from the Connected app. 4. Select an OAuth Flow Type of Resource Owner. API Manager does not support the Authz Code flow when accessing Salesforce.com APIs. Other flows are not supported by Salesforce.com. 5. On the Advanced tab, the Resource Owner Credentials settings are important. The default Salesforce.com OAuth profile is configured to use selectors for the Resource Owner ID and Password (${oauth.resource.owner.id} and ${oauth.resource.owner.password}). These settings cause the Salesforce.com connector in API Manager to prompt the user for their Salesforce.com credentials before importing APIs. Alternatively, you can configure the OAuth profile with a system account. In this case, the Resource Owner ID should have a literal value, and the Resource Owner Password should be set to Password, along with the corresponding password value. Configure OAuth provider settings for Salesforce.com Under Environment Configuration > External Connections > Client Credentials > OAuth2 > Salesforce, the default OAuth2 Provider Settings tab includes basic settings, which you can customize for your environment. The following shows an example on the OAuth2 Provider Settings tab: The OAuth provider settings are as follows: Profile Name: Enter a profile name for the OAuth provider settings. Defaults to SalesForce. Authorization Endpoint: Enter the Salesforce.com URL for the OAuth authorization endpoint. Defaults to Token Endpoint: Enter the Salesforce.com URL for the OAuth token endpoint. Defaults to Axway API Manager User Guide 142

143 5 Application connectors Click Advanced to configure the following: Token Store: Click browse to select the API Gateway OAuth token store. Defaults to OAuth Client Access Token Store. Store OAuth State in this cache: Click browse to select the cache in which API Gateway stores the OAuth client state. Defaults to OAuth Client State Cache. Click Save when finished editing these settings. Import Salesforce.com APIs in API Manager When the policy developer has configured the API connector and the associated client authentication credentials in Policy Studio, the API administrator can import the Salesforce.com cloud API in the API Manager web console. When importing APIs, the import dialog displays the list of available Salesforce.com APIs. For example, these include the standard object, Query, Query All, Search, and Bulk APIs. You can filter this list to display the required APIs. You can then select multiple different APIs to be part of an API definition imported in API Manager, and governed as a single back-end API. You can virtualize and manage the resulting back-end API just like any other API in API Manager. Note You can import the Salesfore.com Bulk API alone only, and not in combination with other APIs. To import a Salesforce.com API in API Manager, perform the following steps: 1. Select API Registration > Backend API. 2. Click New API, and select Import from Salesforce.com. 3. If the OAuth profile for Salesforce.com is configured with a wildcard resource owner password, you are prompted to enter valid Salesforce.com login credentials. Remember to add the Salesforce security token to the end of the password to log in. For more details, see Configure OAuth client credentials for Salesforce.com on page 141. Alternatively, if the OAuth profile for Salesforce.com is configured with a valid system account, the Salesforce.com connector automatically attempts to connect to Salesforce.com. 4. Complete the following details in the import dialog: API Name: Enter a name for the back-end API to display in API Manager. Description: Enter a short description for the back-end API. Organization: Select the organization name from the list. APIs Filter: Enter a filter string, and click Filter to display the results in the APIs tree. APIs: Select the Salesforce.com object API that you require in the tree. You can continue to filter and select multiple APIs. Selected APIs: View the APIs selected for import, and click to remove any that do not apply. The following example shows a completed import dialog: Axway API Manager User Guide 143

144 5 Application connectors 5. When you have selected all the APIs you require, click Import at the bottom. The imported APIs are displayed as a single back-end API in API Manager. For example: For more details on importing APIs, see Register REST APIs in API Manager on page 52. Manage Salesforce.com APIs in API Manager When you import a cloud API and register it as a back-end API, you can virtualize and manage it as a front-end API, just like any other API in API Manager. For example, this includes selecting different authentication mechanisms and testing API methods. Axway API Manager User Guide 144

145 5 Application connectors Virtualize Salesforce.com APIs When you have imported a set of Salesforce.com objects in API Manager as a back-end API, you can virtualize it as a front-end API and secure it in different ways. In the most common scenario, API Manager acts as an OAuth client to Salesforce.com APIs. To achieve this, you must configure the virtualized front-end API in API Manager to use OAuth as the outbound authentication profile. Configure the OAuth credentials in Policy Studio To use OAuth for authentication with Salesforce.com, you must first configure an OAuth credential profile in Policy Studio. You can use the same OAuth credential profile used for the Salesforce.com connector at runtime, or you can configure a new profile. For more details, see Configure OAuth provider settings for Salesforce.com on page 142. Note The OAuth credential profile must use the Resource Owner flow and send the Client Id and Client Secret in the Query String setting. After deciding which OAuth profile will be used in API Manager for authenticating against Salesforce.com at runtime, you must add the profile to the list of OAuth Outbound Credentials in Policy Studio. Perform the following steps: 1. In the Policy Studio tree, select Server Settings > API Manager > OAuth Outbound Credentials. 2. Click Add to add the profile (for example, the default Salesforce.com Connector OAuth Credentials). 3. Click Apply Changes at the bottom right. 4. Click Deploy in the toolbar. For example: When the profile has been added, it is available for use in API Manager. Using a system account If the Resource Owner Credentials configured in the OAuth profile are set to literal values (username and password), at runtime API Manager uses these credentials to negotiate an OAuth token with Salesforce.com. Note The front-end API exposed to consumers can use any application or end user authentication or authorization mechanism. The Salesforce.com access rights defined by the system account are shared equally by all consumers. Axway API Manager User Guide 145

146 5 Application connectors Using end user credentials If the Resource Owner Credentials configured in the OAuth profile are set to wildcard selector values (such as ${oauth.resource.owner.id} and ${oauth.resource.owner.password}), at runtime API Manager resolves these selectors, and dynamically determines the user credentials to negotiate an OAuth token with Salesforce.com. Note The front-end API exposed to consumers can use any application or end user authentication or authorization mechanism, as long as the configured selectors can be resolved to valid credentials. The Salesforce.com access rights defined by the credentials resolved at runtime are used. For more details on API Gateway selectors, see the API Gateway Policy Developer Guide. Create the front-end API in API Manager When you have configured the OAuth credentials in Policy Studio, you can virtualize the back-end Salesforce.com API as a front-end API in API Manager. Perform the following steps: 1. Select API Registration > Frontend API. 2. Click New API, and select New API from backend API. 3. Select the existing Salesforce back-end API in the dialog. 4. Enter a Resource Path (for example, /salesforce). 5. On the Inbound tab, select a security device for authentication from the Inbound security setting. For more details, see Configure Inbound settings on page 61. Note If the Resource Owner Credentials in the OAuth for Salesforce.com are configured as selectors (for example, ${oauth.resource.owner.id} and ${oauth.resource.owner.password}), these must be resolved by API Manager before calling Salesforce.com. The logic for resolving selectors depends on each use case, but an Invoke Policy security device is recommended. This enables you to use a custom policy to analyze incoming requests, and decide which resource owner credentials to use with Salesforce.com. The simplest case involves the client application sending the end user credentials in the request, and a policy mapping those credentials to the configured selectors. 6. On the Outbound tab, select the OAuth security device from the Outbound authentication profile setting. Salesforce.com users and resources are bound to instances (such as na1, ap1, eu1). Upon successful OAuth authentication, Salesforce.com indicates the instance to be used in the API endpoint (for example, eu5.salesforce.com). When OAuth is selected as the Outbound authentication profile, the back-end API URL is dynamically assigned based on the Salesforce.com indication. This ensures that API manager routes to the Salesforce.com instance according to the end user authentication credentials. 7. Select the OAuth credentials that you configured in Policy Studio as the OAuth Provider Profile (for example, the default Salesforce.com Connector OAuth Credentials). Axway API Manager User Guide 146

147 5 Application connectors 8. The response contents of Salesforce.com APIs can include relative links to other associated resources. Because the virtualized API in API Manager might present a different relative path to the consuming client application, URL rewriting might be necessary. A sample URL rewriting policy is available in Policy Studio under Sample Policies > API Management URL Rewriting. Click Advanced, and add this as a Response policy to leverage URL rewriting. For more details, see Configure Advanced Outbound settings on page 73). 9. Click Save or Apply. 10. On the API Methods tab, you can select a method, and click Try method to test it. For more details, see Configure API method information on page 75. The following example shows a virtualized front-end Salesforce API with OAuth selected for outbound authentication: For more details on managing APIs, see Administer APIs in API Manager on page 79. Further information For more details on Salesforce.com APIs, see Configure a connector for ServiceNow APIs Overview API Manager enables you to import and manage cloud application APIs such as ServiceNow. The policy developer can configure client authentication profiles for use with the ServiceNow API connector in Policy Studio. Axway API Manager User Guide 147

148 5 Application connectors When the policy developer has connected to the ServiceNow cloud API provider, the API administrator can then import and manage ServiceNow application APIs in the API Manager web console. For more details on ServiceNow APIs, see ServiceNow product documentation. ServiceNow API use cases ServiceNow provides cloud-based service management solutions (for example, IT, human resources, facilities, field service, and so on). ServiceNow provides the following types of API: Table API: Used to manipulate business objects in the system. Aggregate API: Used to compute statistics on business objects. Import Set API: Provides a REST interface for importing and exporting set of data. For example, the API administrator can use the Table API to expose ServiceNow incidents to support and service teams on their desktop and mobile devices. Each team member can collaborate and exchange information on the same incident using different tools in real time. The API administrator can use the Aggregate API to expose a set of statistics on customer incidents on a web dashboard. The support team manager and the customer account manager use the dashboard to manage the status of customer issues. The API administrator can use the Import Set API to extract a daily set of incidents from ServiceNow and store them in an archive. Configure an API connector for ServiceNow The policy developer can configure an API connector in Policy Studio. To configure a connector, perform the following steps: 1. Select Server Settings > API Manager > API Connectors in the Policy Studio tree on the left. 2. Click Add to add a new connector. 3. Configure the following settings to suit your environment: Name: The name of the API connector: ServiceNow. Resource Prefix: The resource prefix used for the API connector: servicenow. Description: A short description of the API connector:servicenow connector. URL: Enter the URL for the ServiceNow API connector. This setting is required for ServiceNow: Axway API Manager User Guide 148

149 5 Application connectors 4. Click OK. Class: The Java class for the API connector: com.vordel.apiportal.api.connector.sn.servicenowconnector Client Credentials: ServiceNow APIs use HTTP basic authentication. Click the browse button to select the client credential required for ServiceNow. For more details, see Configure HTTP basic credentials for ServiceNow on page 149. Max APIs/Import: Enter the maximum number of APIs that can be imported from the ServiceNow cloud API provider into a single API in API Manager. A very large number makes it harder for an API owner to manage. The ServiceNow connector defaults to 100 APIs per import. For more details, see Import ServiceNow APIs in API Manager on page 150 Custom Configuration: Enter custom configuration details: {"apiversion":"1.0"}. The following example shows the default API connector configuration for the ServiceNow connector in Policy Studio: Configure HTTP basic credentials for ServiceNow To configure client credentials for ServiceNow, perform the following steps: 1. Register an account with ServiceNow to obtain your ServiceNow credentials. 2. In the Policy Studio tree, select Environment Configuration > External Connections > Client Credentials > HTTP Basic, and click Add on the bottom right. Axway API Manager User Guide 149

150 5 Application connectors 3. Enter a Profile Name (for example, ServiceNow Credentials). 4. Ensure Choose Authentication Type is set to Basic. Connecting to ServiceNow with Digest authentication is not supported. 5. Enter your ServiceNow account credentials in the Username and Password fields. Note Alternatively, you can enter an API Gateway selector (${authentication.subject.id}) in the Username field. This setting causes the ServiceNow connector in API Manager to prompt you for your ServiceNow credentials before importing APIs. The following shows a completed example: For more details on configuring client credential profiles and API Gateway selectors, see the API Gateway Policy Developer Guide. Import ServiceNow APIs in API Manager When the policy developer has configured the API connector and the associated client authentication credentials in Policy Studio, the API administrator can import the ServiceNow cloud API in the API Manager web console. Note The ServiceNow connector must have read access to the sys_db_object and sys_ dictionary tables. The asset and itil roles in ServiceNow have this access level by default. To import the Import Set API, the ServiceNow connector also requires read access to the sys_import_set_row table. The import_admin and import_ transformer roles in ServiceNow have this access level by default. Ensure that you have configured HTTP basic credentials for a ServiceNow user that has the required role, and use those credentials for the import. If you have a custom role that fulfills these requirements, you can also use the HTTP basic credentials for that role. When importing APIs, the import dialog displays the list of available ServiceNow Table, Aggregate, and Import Set APIs. You can filter this list to display the required APIs. You can select multiple different APIs to be part of an API definition imported in API Manager, and governed as a single back-end API. You can virtualize and manage the resulting back-end API just like any other API in API Manager. Note Due to the large number of APIs available from ServiceNow, importing all of them is not possible with the default API Gateway configuration, and might take over an hour. It is recommended that you import only the APIs that will be used. Axway API Manager User Guide 150

151 5 Application connectors To import a ServiceNow API in API Manager, perform the following steps: 1. Select API Registration > Backend API. 2. Click New API, and select Import from ServiceNow. 3. If the client credentials profile for ServiceNow is configured with a wildcard resource owner password, you are prompted to enter valid ServiceNow login credentials. For more details, see Configure HTTP basic credentials for ServiceNow on page 149. Alternatively, if the credentials profile for ServiceNow is configured with a valid system account, the ServiceNow connector automatically attempts to connect to ServiceNow. 4. Complete the following details in the import dialog: API Name: Enter a name for the back-end API to display in API Manager. Description: Enter a short description for the back-end API. Organization: Select the organization name from the list. APIs Filter: Enter a filter string, and click Filter to display the results in the APIs tree. APIs: Select the ServiceNow object API that you require in the tree. You can continue to filter and select multiple APIs. Selected APIs: View the APIs selected for import, and click to remove any that do not Axway API Manager User Guide 151

152 5 Application connectors apply. The following example shows a completed import dialog: 5. When you have selected all the APIs you require, click Import at the bottom. The imported APIs are displayed as a single back-end API in API Manager. For more details on importing APIs, see Register REST APIs in API Manager on page 52. Manage ServiceNow APIs in API Manager When you import a cloud API and register it as a back-end API, you can virtualize and manage it as a front-end API, just like any other API in API Manager. For example, this includes selecting different authentication mechanisms and testing API methods. Axway API Manager User Guide 152

153 5 Application connectors Virtualize ServiceNow APIs When you have imported a set of ServiceNow objects into API Manager as a back-end API, you can then virtualize it as a front-end API and secure it in different ways. In one of the most common scenarios, API Manager acts as an HTTP basic authentication client to ServiceNow APIs. To achieve this, you should configure the virtualized front-end API in API Manager to use HTTP basic as the outbound authentication profile. Using a system account If the HTTP basic credentials are set to literal values (username and password), at runtime API Manager uses these credentials to authenticate with ServiceNow. For more details, see Configure HTTP basic credentials for ServiceNow on page 149. Note The front-end API exposed to consumers can use any application or end user authentication or authorization mechanism. The ServiceNow access rights defined by the system account are shared equally by all consumers. Using end user credentials If the HTTP basic credentials are set to a wildcard selector value (such as ${authentication.subject.id}), at runtime API Manager resolves the selector, and dynamically determines the user credentials to authenticate with ServiceNow. This is the default. For more details, see Configure HTTP basic credentials for ServiceNow on page 149. Note The front-end API exposed to consumers can use any application or end user authentication or authorization mechanism, as long as the configured selectors can be resolved to valid credentials. The ServiceNow access rights defined by the credentials resolved at runtime are used. Create the front-end API in API Manager When you have configured the HTTP basic credentials in Policy Studio, you can virtualize the backend ServiceNow API as a front-end API in API Manager. Perform the following steps: 1. Select API Registration > Frontend API. 2. Click New API, and select New API from backend API. 3. Select the existing ServiceNow back-end API in the dialog. 4. Enter a Resource Path (for example /servicenow). 5. On the Inbound tab, select a security device for authentication from the Inbound security setting. For more details, see Configure Inbound settings on page 61. Note If the HTTP basic credentials are set to a wildcard selector value (for example, ${authentication.subject.id}), this must be resolved by API Manager before calling ServiceNow. Axway API Manager User Guide 153

154 5 Application connectors 6. On the Outbound tab, select a security device from the Outbound authentication profile setting. For example, HTTP basic is a commonly used outbound authentication profile in this scenario. For more details, see Configure Outbound settings on page The response contents of ServiceNow APIs can include relative links to other associated resources. Because the virtualized API in API Manager might present a different relative path to the consuming client application, URL rewriting might be necessary. A sample URL rewriting policy is available in Policy Studio under Sample Policies > API Management URL Rewriting. Click Advanced, and add this as a Response policy to leverage URL rewriting. For more details, see Configure Advanced Outbound settings on page 73). 8. Click Save or Apply. 9. On the API Methods tab, you can select a method, and click Try method to test it. For more details, see Configure API method information on page 75. The following example shows a virtualized front-end ServiceNow API with HTTP basic selected for outbound authentication: For more details on managing APIs, see Administer APIs in API Manager on page 79. Submit XML requests to ServiceNow using API Gateway Currently, you cannot submit XML requests to ServiceNow through API Gateway out-of-the-box. This is because ServiceNow returns an error if there is whitespace at the end of an XML request. To workaround this issue, you can use either of the following approaches: Set the Content-Type of the XML request to the following: Axway API Manager User Guide 154

155 5 Application connectors Content-Type: charset= UTF-8 ; application/xml Create a custom request policy to remove all whitespace at the end of a request. For example: Custom policy to remove whitespace at end of request The custom request policy to remove all whitespace at the end of a request is described as follows: 1. A Set Attribute filter copies the contents of the request to a temporary variable: 2. A Trace filter is used for tracking purposes: Axway API Manager User Guide 155

156 5 Application connectors 3. A String Replace filter removes the whitespace at the end of the request body (using the \s*$ regular expression): 4. Another Trace filter is used for tracking purposes. Axway API Manager User Guide 156

157 5 Application connectors 5. A Set Message filter sets the contents of the temporary variable (in which the replacement took place) as a request body: Configure a connector for Axway API Runtime Services Overview API Manager enables you to import and manage cloud-based application APIs developed using Axway API Builder. Policy developers can configure client authentication profiles for use with the API Builder connector in Policy Studio. When the policy developer has connected to an API Builder cloud API provider, the API administrator can then import and manage API Builder application APIs in the API Manager web console. API Builder use cases API Builder enables you to create APIs as Node.js applications that run in different cloud environments. These include the API Runtime Services virtual private cloud (VPC) or on-premise cloud environments and the Appcelerator Public Cloud environment. You can create an API Builder project and add endpoints to define how client applications access your application API. API Builder generates a Swagger definition for the application API, which you can import into API Manager using the API Builder connector. API Builder also provides pre-built connectors for third-party cloud applications and services (for example, MS SQL, MySQL, or MongoDB). You can also create custom connectors for any data source, reuse third-party connectors in your application APIs, and optimize payload size and data format for integration with mobile apps. For more details, see Axway API Manager User Guide 157

158 5 Application connectors Configure an API connector for API Runtime Services Policy developers can configure an API connector in Policy Studio as follows: 1. Select Server Settings > API Manager > API Connectors in the Policy Studio tree on the left. 2. Click Add to add a new connector for API Builder. 3. Configure the following settings to suit your environment: Name: Enter the name of the API connector (for example, API Builder). This name will be displayed in API Manager in the menu option when importing application APIs. Resource Prefix: Enter the resource prefix required for the API Builder connector: apibuilder. Description: Enter the following description: Import API Builder application APIs. This description will be displayed in the API Manager dialog when importing application APIs. URL: Enter the URL required for your API Builder application API environment. For example, if your API Builder applications are hosted in the API Runtime Services virtual private cloud (VPC) or on-premise cloud environment, contact your system administrator to obtain the required URL. Alternatively, if your API Builder application APIs are hosted publicly, the Appcelerator Public Cloud environment is available the following URL: Class: Enter the Java class required for the API Builder connector: com.vordel.apiportal.api.connector.appc.appceleratorconnec tor Client Credentials: You must provide a username and password to connect to API Builder. Click the browse button to configure the client credential required for API Builder. To configure new credentials, right-click the Client Credentials > HTTP Basic node, and select Add HTTP Basic Credentials. For more details, see Configure credentials for API Runtime Services on page 160. Max APIs/Import: Enter the maximum number of application APIs that can be imported from the API Builder cloud API provider into API Manager. A very large number makes it harder Axway API Manager User Guide 158

159 5 Application connectors for an application API owner to manage. The API Builder connector defaults to 10 application APIs per import. For more details, see Import API Builder application APIs in API Manager on page 161. Merge APIs on import: You must deselect this setting for API Builder application APIs. Each API Builder application API will be imported into API Manager as a separate back-end API. Custom Configuration: Not all API Builder application APIs can be imported into API Manager by default. Enter the following custom configuration to filter the list of application APIs displayed in API Manager to show only active API Builder application APIs: {"filters" : [ { "status" : [ "online", "Deactivated" ]}, { "active" : [true]}, { "deploymentstatus": ["online"]} ] } 4. Click OK. This specifies filter attributes in JSON format to filter the list of available application APIs displayed in API Manager. This field can be blank or contain a JSON filters object that includes an array of objects. The following example shows the completed configuration for the API Builder cloud application connector in Policy Studio: Axway API Manager User Guide 159

160 5 Application connectors Configure credentials for API Runtime Services To configure client credentials for API Builder, perform the following steps: 1. Register an account for API Builder to obtain your API Builder credentials. For more details, see 2. In the Policy Studio tree, select Environment Configuration > External Connections > Client Credentials > HTTP Basic, and click Add on the bottom right. 3. Enter a Profile Name (for example, API Builder Credentials). 4. Ensure Choose Authentication Type is set to Basic. 5. Enter your API Builder account credentials in the Username and Password fields. Note Alternatively, you can enter an API Gateway selector (${authentication.subject.id}) in the Username field. This setting causes the API Builder connector in API Manager to prompt you for your API Builder credentials before importing application APIs. The following shows an example HTTP basic authentication profile: Axway API Manager User Guide 160

161 5 Application connectors For more details on configuring client credential profiles and API Gateway selectors, see the API Gateway Policy Developer Guide. Import API Builder application APIs in API Manager When the policy developer has configured the API connector and the associated client authentication credentials in Policy Studio, the API administrator can import the API Builder application API in the API Manager web console. When importing APIs, the import dialog displays the list of available API Builder application APIs. You can filter this list to display the required application APIs. You can then select multiple application APIs to import into API Manager. You can virtualize and manage the resulting back-end APIs just like any other APIs in API Manager. For example, to import a API Builder API, perform the following steps in API Manager: 1. Select API Registration > Backend API. 2. Click New API, and select Import from API Builder. 3. If the client credentials profile for API Builder is configured with a selector for the username, you are prompted to enter valid API Builder login credentials. For more details, see Configure credentials for API Runtime Services on page 160. Alternatively, if the credentials profile for API Builder is configured with a valid system account, the API Builder connector automatically attempts to connect to API Builder. Axway API Manager User Guide 161

162 5 Application connectors 4. Complete the following details in the import dialog: Organization: Select the organization name from the list. Filter: Enter a filter string, and click Filter to display the results in the APIs tree. APIs: Select the API Builder application API that you require in the tree. You can continue to filter and select multiple APIs. Selected APIs: View the application APIs selected for import, and click to remove any that do not apply. The following example shows a completed import dialog: 5. When you have selected all the application APIs you require, click Import at the bottom. Each imported application API is displayed as a separate back-end API in API Manager: For more details on importing APIs, see Register REST APIs in API Manager on page 52. Axway API Manager User Guide 162

163 5 Application connectors Manage API Builder application APIs in API Manager When you import a cloud-based application API and register it as a back-end API, you can virtualize and manage it as a front-end API, just like any other API in API Manager. For example, this includes selecting different authentication mechanisms and testing API methods. Virtualize API Builder application APIs When you have imported API Builder application APIs into API Manager as back-end APIs, you can then virtualize them as a front-end APIs and secure them in different ways. In a common scenario, API Manager acts as an HTTP basic authentication client to API Builder APIs. To achieve this, you should configure the virtualized front-end API in API Manager to use HTTP basic as the outbound authentication profile. Using a system account If the HTTP basic credentials are set to literal values (username and password), at runtime API Manager uses these credentials to authenticate with API Builder. For more details, see Configure credentials for API Runtime Services on page 160. Note The front-end API exposed to consumers can use any application or end user authentication or authorization mechanism. The API Builder access rights defined by the system account are shared equally by all consumers. Using end user credentials If the HTTP basic credentials are set to a selector value (for example, ${authentication.subject.id}), at runtime API Manager resolves the selector, and dynamically determines the user credentials to authenticate with API Builder. For more details, see Configure credentials for API Runtime Services on page 160. Note The front-end API exposed to consumers can use any application or end user authentication or authorization mechanism, as long as the configured selectors can be resolved to valid credentials. The API Builder access rights defined by the credentials resolved at runtime are used. Create the front-end API in API Manager When you have configured the HTTP basic credentials in Policy Studio, you can virtualize the backend API as a front-end API in API Manager. Perform the following steps: 1. Select API Registration > Frontend API. 2. Click New API, and select New API from backend API. 3. Select the existing API Builder back-end API in the dialog. 4. Enter a Resource Path (for example /api_builder). Axway API Manager User Guide 163

164 5 Application connectors 5. On the Inbound tab, select a security device for authentication from the Inbound security setting. For more details, see Configure Inbound settings on page 61. Note If the HTTP basic credentials are set to a selector value (for example, ${authentication.subject.id}), this must be resolved by API Manager before calling API Builder. 6. On the Outbound tab, select a security device from the Outbound authentication profile setting. For example, HTTP basic is a commonly used outbound authentication profile in this scenario. For more details, see Configure Outbound settings on page The response contents of API Builder APIs can include relative links to other associated resources. Because the virtualized API in API Manager might present a different relative path to the consuming client application, URL rewriting might be necessary. A sample URL rewriting policy is available in Policy Studio under Sample Policies > API Management URL Rewriting. Click Advanced, and add this as a Response policy to use URL rewriting. For more details, see Configure Advanced Outbound settings on page Click Save or Apply. 9. On the API Methods tab, you can select a method, and click Try method to test it. For more details, see Configure API method information on page 75. The following example shows a virtualized front-end API imported from API Builder with HTTP basic selected for outbound authentication: Further information For more details on managing APIs, see Administer APIs in API Manager on page 79. Axway API Manager User Guide 164

165 5 Application connectors Connect to Axway Mobile Backend Services Overview This topic explains how to connect to Axway Mobile Backend Services from API Manager to virtualize Mobile Backend Services APIs in your API Catalog and add an extra layer of security for your apps. For example, this includes adding quota, threat protection, and user authentication and authorization policies. Note Axway Mobile Backend Services were previously known as Appcelerator ArrowDB and ArrowPush services, and these names remain in some internal components and documentation. Mobile Backend Services use cases Axway Mobile Backend Services provide pre-built, scalable, cloud, and mobile-specific back-end services using REST APIs and data objects. For example, these include location-based services, social media integration, geo-location, photos, media handling, and so on. Mobile Backend Services also include the ability to send push notifications to Android and ios apps, and Software Development Kits (SDKs) for integration with the following mobile apps: Titanium Android ios Node.js Mobile app developers can call the Mobile Backend Services APIs to integrate with their apps. For example, this enables you to add important mobile features without server coding or administration. You can focus on client-side development, reducing overall app time to market. Mobile Backend Services also enable server-side hosting, scalability, and administration for Appcelerator public and VPC options. There is no need for installation, you can call Mobile Backend Services APIs and existing objects, and use features that apps need instead of providing generic data storage. Mobile Backend Services REST API The Mobile Backend Services REST API is accessible from any networked client device and enables creating, querying, updating, and deleting Mobile Backend Services objects. Each Mobile Backend Services object has its own URL and HTTP methods (GET, POST, PUT, or DELETE). To make an API call, you make an HTTP request, and API responses are returned as JSON objects. For example: Axway API Manager User Guide 165

166 5 Application connectors KEY>&checkin_id=4d8bc645d0afbe User sessions and cookies must be saved and reused with each API call (if login is required). For example, you can pass the session ID to the _session_id parameter in the URL: session_id=<session_id> For more details, see the following Mobile Backend Services documentation: Create a Mobile Backend Services app Before you can virtualize the Mobile Backend Services API in API Manager, you must first create a Mobile Backend Services app, and an app key and user for the Mobile Backend Services API. Perform the following steps: 1. Connect to the Mobile Backend Services dashboard in your browser, and enter your credentials. For example: 2. In the dashboard, click the + sign in the toolbar at the top, and select Create ArrowDB Datasource from the drop-down list. 3. Enter a meaningful Name for your app, and click OK. 4. When your new app is selected, click the Configuration tab on the left. Axway API Manager User Guide 166

167 5 Application connectors 5. On the Keys tab, under App Key, click Show. 6. Copy the app key and save for later use (for example, paste to a file). 7. Click Manage Data to display all the managed data objects for the app. 8. Click the Users link at the bottom of the Managed Data Objects table: 9. Click Create User on the top right, and enter the user details. For example, the Username, , and Password fields are required. You should also select Yes in the Admin field. 10. When finished, click Save Changes at the bottom left. Virtualize the Mobile Backend Services API in API Manager When you have created a Mobile Backend Services app, app key, and user, you can then virtualize the Mobile Backend Services API in API Manager. Perform the following steps: Axway API Manager User Guide 167

168 5 Application connectors 1. Get the Swagger URL for Mobile Backend Services APIs. For example: 2. To create a new back-end API from Swagger in API Manager, select API > Backend API > New API > Import Swagger API. 3. In the Import API dialog, complete the following: o o o o o Source: Select Swagger definition URL from the list. URL: Paste the Swagger URL (in this case, API Name: Enter a user-friendly name for the API (for example, MyTest MBS API). Organization: Select the organization from the list (for example, Acme Inc). Authentication: Enter the User name and Password for the API if required. 4. To create the front-end in API Manager, select API > Frontend API > New API > New API from backend API and select the existing API from the list (in this case, MyTest MBS API). 5. In the front-end API, click the Inbound tab, and in the Outbound security field, select API Key, and click OK. 6. Click the Outbound tab, and in the Outbound authentication profile field, select API Key. 7. In the API Key Authentication dialog, paste in the API key for your Mobile Backend Services app that you created in Create a Mobile Backend Services app on page 166, and click OK. 8. Click Save. The following example in API Manager shows the API key created earlier when creating the Mobile Backend Services app: For more details, see Virtualize REST APIs in API Manager on page 59. Axway API Manager User Guide 168

169 5 Application connectors Verify the Mobile Backend Services API virtualization in API Manager You can test the virtualization of the Mobile Backend Services API using the Try it feature in the API Manager API Catalog. Alternatively, you can use third-party test tools such as curl or Postman. Most of the Mobile Backend Services API methods require user authentication. Therefore you should call the login API before calling other APIs. The following example shows using curl to test user login with the virtualized URL: curl -X POST -H 'content-type: application/x-www-form-urlencoded' -d 'login=<username>&password=<password>' You can specify the Mobile Backend Services username and password that you created earlier in Create a Mobile Backend Services app on page 166. Generate an SDK for virtualized Mobile Backend Services APIs in API Portal Note You should use the API Portal SDK generator rather than Mobile Backend Services SDK. For details on how to generate an SDK for virtualized Mobile Backend Services APIs, see "Download the client SDK" in the API Portal User Guide. SDK generation must first be enabled in API Portal, see "Enable SDK generator" in the API Portal Administrator Guide. Further information For more details on Mobile Backend Services, see: Axway API Manager User Guide 169

170 API Manager single sign-on 6 API Manager supports single sign-on (SSO). This enables users to use the same login details for API Manager and other Axway platform products (for example, API Portal or Decision Insight) and eliminates the need to log in multiple times to different web-based UIs. This topic describes API Manager SSO. It contains the following sections: Single sign-on using SAML on page 170 SSO message flows on page 171 Configure API Manager SSO on page 172 Mapping syntax on page 180 Configuration file elements on page 186 SSO troubleshooting on page 189 Single sign-on using SAML Single sign-on (SSO) is a session/user authentication process in which a user enters one user name and password to access multiple applications. API Manager supports SAML-based single sign-on (SSO). SSO concepts The SAML 2.0 standard describes how to exchange authentication and authorization data between entities. This section describes some key concepts. Service Provider A Service Provider (SP) protects access to requested resources, such as web sites and applications by applying a security policy. For example, the SP blocks all access to an unauthenticated user and routes the request to the Identity Provider. API Manager acts as an SP. Identity Provider An Identity Provider (IdP) is a system that creates, maintains, and manages identity information for users, services, or systems, and provides authentication to other service providers (applications) within a network. An IdP is a trusted entity that users and servers can rely on when they are Axway API Manager User Guide 170

171 6 API Manager single sign-on establishing a dialog that must be authenticated. The IdP sends an attribute assertion containing trusted information about the user to the SP. In an Axway deployment, the IdP is a third-party product. User agent A user agent is usually a web browser. The person who uses the browser can be referred to as a user or as a principal. Security Assertion Markup Language (SAML) The Security Assertion Markup Language (SAML) is an XML-based solution for exchanging user security information (authentication, authorization) between an IdP and SP. SAML is a product of the OASIS Security Services Technical Committee. SAML assertion A SAML assertion is a package of information that contains one or more statements made by a SAML authority. The SAML standard defines three types of assertion statement: Authentication: The specified subject was authenticated by a particular means at a particular time. This kind of statement is typically generated by an IdP. Attribute: The specified subject is associated with the supplied attributes. Authorization: A decision to grant or deny the specified subject access to the specified resource. SSO message flows The following diagram shows a simplified message flow for SSO using SAML: The following sections describe the message flows between API Manager (acting as the SP) and the IdP. Authentication sequence When API Manager is configured for SSO, the following events occur during authentication between API Manager and the IdP: Axway API Manager User Guide 171

172 6 API Manager single sign-on 1. The end user tries to access the API Manager UI using a web browser: For non-sso login, access the API Manager on the default URL (for example, For SSO login, access the API Manager on the SSO URL (for example, Note The SSO login URL must be used even if the user has already logged in using SSO (for example, if they have already logged in to API Portal or Decision Insight). 2. API Manager builds a SAML Authentication Request message and sends it to the IdP. 3. The IdP receives the request and checks if there is an active session for the user. 4. If no session for this user exists on the IdP, the user is prompted to enter their credentials. 5. The IdP analyzes the credentials and sends a SAML Response message, asserting that the user is authenticated. 6. API Manager maps the user's IdP role to an API Manager-specific role. For more information, see Mapping syntax on page The user is presented with the appropriate view of API Manager, depending on their role. Logout sequence The logout sequence is as follows when logout is initiated by API Manager: 1. The end user tries to log out of API Manager by clicking the Logout button in the UI. 2. API Manager recognizes that the user has an active session, so it generates a SAML Logout Request message and sends it to the IdP. 3. The IdP removes the user session and returns a SAML Logout Response to the browser. 4. The browser posts the HTML form containing the SAML Logout Response to the API Manager single logout service URI. 5. API Manager removes the user session and redirects to the logout redirect URI. Configure API Manager SSO This topic describes how to configure API Manager single sign-on (SSO). It consists of the following: Prerequisites on page 173 API Manager implementation behavior on page 173 Configuration files on page 174 Sample files on page 174 Axway API Manager User Guide 172

173 6 API Manager single sign-on Configuration steps: o Step 1 Set up a keystore on page 175 o Step 2 Create a service-provider.xml file on page 175 o Step 3 Specify the IdP on page 176 o Step 4 Configure SSO in Policy Studio on page 177 o Step 5 Configure SAML endpoint URLs on page 178 Manage IdP certificates on page 179 Configure the SSO cookie domain name on page 180 Prerequisites To configure API Manager SSO: You must have a third-party IdP installed and running. You must always use fully qualified domain names (FQDNs) for the host name. Avoid using IP addresses or localhost in the configuration. The following prerequisites apply to organizations in API Manager: o o o Before a user can authenticate successfully using SSO, the API Manager organization associated with the SSO user must exist. An API Manager administrator user can add the organizations in advance. When configuring the file service-provider.xml, ensure that the SSO user only ever belongs to one organization. API Manager implementation behavior When using API Manager SSO, be aware of the following: SSO authenticated users cannot change their own passwords. To log in using SSO, users cannot use the standard login URL ( Instead, users must use the following API Manager SSO login URL: FQDN is the FQDN of the machine where API Gateway is running, and PORT is the API Manager listening port (for example, If a user has already authenticated using SSO (for example, by previously logging in to Decision Insight), they must still use the SSO login URL for API Manager. If they are already authenticated, they are automatically redirected to the API Manager home page at and presented with a view appropriate to their API Manager role. Axway API Manager User Guide 173

174 6 API Manager single sign-on The mapping of user roles between the IdP and API Manager must be configured manually. For more information, see Configure API Manager SSO on page 172. If the IdP does not return any role, a user is assigned the default role of User (API consumer) in API Manager. For more information on API Manager roles, see Manage users on page 92. Configuration files To configure API Manager SSO, create the following files in your API Gateway instance folder (for example, INSTALL_DIR/apigateway/groups/group-2/instance-1/conf). File name serviceprovider.xml A keystore (for example sso.jks) idp.xml (optional) jvm.xml Description This file defines the Service Provider (SP), the SAML Identity Provider (IdP), and the mappings that can be made by the SAML IdP. In this case the SP is API Manager. For more information, see Step 2 Create a serviceprovider.xml file on page 175. This is the truststore generated by an administrator and referenced in service-provider.xml. It contains the key that the SSO agent uses to sign requests. The exported public key must be stored by the IdP. For more information, see Manage IdP certificates on page 179. This file is required if you are specifying the IdP by file. For more information, see Specify the IdP by file on page 176. This file is located in the folder INSTALL_DIR/apigateway/conf and can be used to configure the SSO cookie domain name. This file is only required in a load balanced environment. Sample files The API Gateway installation includes sample files to help you configure API Manager SSO. These are located in the following folder: INSTALL_DIR/apigateway/samples/sso The following sample files are included: ShibbolethIDP folder This folder contains sample Shibboleth configuration files to help you configure Shibboleth as an IdP. These configuration files are part of the Shibboleth installation and can be found in the respective Shibboleth installation folders. For more information on Shibboleth, see the Shibboleth documentation. This folder also contains the following sample files for API Manager: Axway API Manager User Guide 174

175 6 API Manager single sign-on o o service-provider.xml A sample file where the IdP is specified by file using idp.xml. idp.xml keycloak folder - This folder contains a sample service-provider.xml file that uses a URL to specify the IdP, in this case Keycloak. For more information, see Specify the IdP by URL on page 177. The folder also contains a sample service-provider-apiportal.xml for configuring API Portal SSO. For more details, see "Configure API Portal for single sign-on" in the API Portal Administrator Guide. Step 1 Set up a keystore To set up a keystore containing a key pair, you can use the Java keytool utility. For more information on the keytool commands and options, see the Java keytool documentation. Follow these steps: 1. Change directory to your API Gateway instance folder (for example, INSTALL_ DIR/apigateway/groups/group-2/instance-1/conf). 2. Execute keytool to create a keystore. For example, the following command generates a keystore with the alias ssokey in the file sso.jks: keytool -genkey -alias ssokey -keyalg RSA -keystore sso.jks -keysize 2048 Tip The values ssokey and sso.jks are used in the sample files included in the API Gateway installation. You can use different values when generating the keystore, however, if you do this you must update the sample files with the new values. This certificate is used to configure your IdP. For more information, see Manage IdP certificates on page 179. Step 2 Create a service-provider.xml file To create a service-provider.xml file you can use either of the sample files included in the API Gateway installation. 1. In the ServiceProvider section, update the keystore, keystorepassphrase, and keyalias fields with the correct values for your keystore. <ServiceProvider... keystore="conf/keystore_file" keystorepassphrase="keystore_passphrase" keyalias="key_alias"... </ServiceProvider> Axway API Manager User Guide 175

176 6 API Manager single sign-on For example, if you generated a keystore called sso.jks with a passphrase abc123 and an alias called ssokey, the settings in service-provider.xml would be as follows: <ServiceProvider... keystore="conf/sso.jks" keystorepassphrase="abc123" keyalias="ssokey"... </ServiceProvider> 1. In the SAMLIdentityProvider section, update the Mappings section with the mapping of IdP attributes to API Manager attributes. For more information on the mapping syntax, see Mapping syntax on page In the SamlIdentityProvider section, set the metadataurl field as detailed in Step 3 Specify the IdP on page 176. For more information on the elements in the service-provider.xml configuration file, see Configuration file elements on page 186. Step 3 Specify the IdP There are two ways you can specify the IdP: Specify the IdP by file on page 176 Specify the IdP by URL on page 177 Specify the IdP by file When the IdP is specified by file, the idp.xml file must exist in your API Gateway instance folder (for example, INSTALL_DIR/apigateway/groups/group-2/instance-1/conf). In this case, service-provider.xml refers to this file on disk. To specify the IdP by file, follow these steps: 1. Set the metadataurl field of the SamlIdentityProvider section of the serviceprovider.xml file to the value./idp.xml. The following example shows a sample extract from the service-provider.xml file for Shibboleth. The metadataurl refers to the file idp.xml. <SamlIdentityProvider entityid=" metadataurl="./idp.xml"... </SamlIdentityProvider> Axway API Manager User Guide 176

177 6 API Manager single sign-on 2. Create an idp.xml file in the API Gateway instance folder using the template provided in INSTALL_DIR/apigateway/samples/sso/ShibbolethIDP/idp.xml. 3. In the idp.xml file: Replace the place holder CHANGE THIS : Replace this text with your IDP_CERTIFICATE with the certificate of your IdP that is used for signing SAML tokens. Replace all instances of the placeholders <IDP_FQDN>:<IDP_SOAP_PORT> and <IDP_FQDN>:<IDP_HTTP_PORT> with the fully qualified domain name and port of your IdP. Specify the IdP by URL In this case, the IdP file is not stored locally. Instead, the service-provider.xml file refers to it by URL. To use this method, set the metadataurl field to the metadata URL of the IdP in the SamlIdentityProvider section of the service-provider.xml file. The following example shows an extract from a service-provider.xml file for a Keycloak IdP. The metadataurl refers to a URL. <SamlIdentityProvider entityid=" metadataurl=" descriptor"... </SamlIdentityProvider> A sample of a service-provider.xml file that uses an IdP specified by URL is included in the INSTALL_DIR/apigateway/samples/sso/keycloak folder. When specifying an IdP by URL, you might need to set up a truststore JKS file: sso.jks Contains the key used by the SSO agent to sign requests. This key needs to go to the IdP. truststore.jks This is a separate truststore that is used for HTTPS communication between the SSO agent and the IdP while retrieving metadata online. Tip You can use the same keystore for all of the operations. Step 4 Configure SSO in Policy Studio Perform the following steps in Policy Studio: 1. Open the configuration of your API Manager-enabled API Gateway instance. For example, select File > New Project from an API Gateway instance. Axway API Manager User Guide 177

178 6 API Manager single sign-on 2. Navigate to Environment Configuration > Listeners > API Gateway > API Portal > Paths in the Policy Studio tree. 3. Click Add > Static File Provider. 4. Set Relative Path to /sso-login-failed and File to $VDISTDIR/webapps/apiportal/login.html. 5. Enter the following values to the additional headers table, and then click OK: HTTP Header Value Content-Security-Policy frame-ancestors 'none' X-Frame-Options DENY 6. Edit each of the servlets (API Portal v1.2 ( v1.2 ) and API Portal v1.3 ( v1.3 )) as follows: Edit the property jersey.config.server.provider.classnames. In the Value field add the class name com.vordel.common.apiserver.filter.ssobindingfeature to the existing comma-separated list of class names. Add a new property. In the Name field enter the name CsrfProtectionFilterFactory.refererWhitelist and in the Value field enter the URL of the IdP (for example, 7. Deploy the configuration to the API Manager-enabled API Gateway instance. Step 5 Configure SAML endpoint URLs After configuring the SSO, you must define the SAML endpoint of API Manager in the IdP. This endpoint is the URL that receives SAML assertions from the IdP. In the following example, the IdP is Keycloak. Depeding on your IdP, the UI might be different, but you must define the endpoint URLs regardless of which IdP you use. For more details, see the documentation of your IdP. Axway API Manager User Guide 178

179 6 API Manager single sign-on 1. Open your IdP client. 2. Locate and set the following: Assertion Consumer Service POST Binding URL: API Manager host FQDN>:8075/api/portal/v1.3/sso/login/post logout-service-post-binding-url: API Manager host FQDN>:8075/api/portal/v1.3/sso/logout/post Logout Service Redirect Binding URL: API Manager host FQDN>:8075/api/portal/v1.3/sso/logout/post If you are also configuring SSO for API Portal, you must configure the endpoint URLs separately for both API Manager and API Portal. For more details, see "Configure API Portal for single sign-on" in the API Portal Administrator Guide Manage IdP certificates API Manager uses a certificate to sign SAML requests. The IdP requires the public key to verify the validity and provenance of the SAML requests from API Manager. To configure the IdP, you must import the public key to the IdP. First, export the public key of the keystore you created in Step 1 Set up a keystore on page 175. For example, use one of the following commands to export it using Java keytool. This example exports it to publickey.txt: keytool -list -rfc -keystore sso.jks -alias ssokey > publickey.txt This example exports it to publickey.cer: keytool -export -keystore sso.jks -alias ssokey -file publickey.cer Next, import the public key to your IdP. Axway API Manager User Guide 179

180 6 API Manager single sign-on Configure the SSO cookie domain name This implementation of SSO uses a cookie, which is created on the API Gateway server and sent to the client's browser. One property of this cookie is the domain name. By default, the domain name is set to the API Gateway host name. For example, it the host name is apigateway.wks.us.axway.int, the domain name in the cookie contains the substring apigateway.wks.us.axway.int. If the API Gateway is hidden behind a load balancer, the cookie domain name might need to change as the client's browser is not aware of the internal API Gateway host name and therefore might not accept this cookie. The following example shows how to change the default domain name to a sample domain name such as axway.int: 1. Create a file called jvm.xml in the folder INSTALL_DIR/apigateway/conf (if it does not already exist). 2. Add the following setting: <ConfigurationFragment> <VMArg name="-dcom.axway.sso.domain.name=axway.int" /> </ConfigurationFragment> This setting assigns the value axway.int to the VMArg called com.axway.sso.domain.name. Note Do not prefix the domain name with a period (for example, do not use the value.axway.int). 3. Restart the API Gateway. Mapping syntax An IdP sends information about the SSO user to an SP (API Manager) using attributes. These attributes contain information about the user, such as the user's name, department, organization, address, phone number, and so on. This section describes how to define mappings from an IdP to API Manager. An IdP can name attributes associated with the authenticated user in a variety of different ways (for example, mail, , or ). API Manager expects attributes with specific names, so you might need to transform the IdP attributes to the API Manager attributes using a rename mapping. In addition, an IdP might not provide some attributes that API Manager requires, so you might need to use a filter mapping to assign required attributes based on a filter. The mappings are defined in the Mappings section of the SAMLIdentityProvider section in the service-provider.xml file. Two types of mappings are supported: Rename mapping This mapping enables you to rename an attribute from the IdP, keeping its value. Axway API Manager User Guide 180

181 6 API Manager single sign-on Filter mapping This mapping creates output attributes when a filter matches the input attributes from the IdP. The following table describes the mandatory and optional attributes expected by API Manager, and gives examples of mappings that you can use to provide them. Note API Manager attribute names are all lowercase. The attribute names are case-sensitive. Attribute name Descripti API Example on Manager require ment name The logged in user name. Mandator y Sample RenameMapping if the IdP provides an attribute which should be renamed: <RenameMapping source="user" target="name"/> organization The API Manager organizati on associated with the logged in user. The organizati on must already exist in API Manager. Organizati ons can be added by an API Manager administra tor. Mandator y The IdP does not need to provide this value. If it does and the IdP attribute has a different name, you can use a RenameMapping to transform it to an organization attribute. If the IdP does not provide the value associated with the organization at all, you can use an OutputAttribute to assign an organization to the logged in user. For example: <OutputAttribute name="organization">research</outputattribute> Axway API Manager User Guide 181

182 6 API Manager single sign-on Attribute name Descripti API Example on Manager require ment role The API Manager role associated with the logged in user. Permitted substring values: Mandator y The IdP does not need to provide this value. If it does and the IdP attribute has a different name, you can use a RenameMapping to transform it to a role attribute. If the IDP does not provide the value associated with the role at all, you can use an OutputAttribute to assign a role to the logged in user. For example: <OutputAttribute name="role">administrator</outputattribute> Administr ator Operator User mail The address associated with the logged in user. Optional Sample RenameMapping if the IdP provides an attribute which should be renamed: <RenameMapping source=" " target="mail"/> description The descriptio n text associated with the logged in user. Optional Sample RenameMapping if the IdP provides an attribute which should be renamed: <RenameMapping source="userdescription" target="description"/> department The departmen t that the logged in user belongs to. Optional Sample RenameMapping if the IdP provides an attribute which should be renamed: <RenameMapping source="businessunit" target="department"/> Axway API Manager User Guide 182

183 6 API Manager single sign-on Attribute name Descripti API Example on Manager require ment telephonenumber The telephone number associated with the logged in user. Optional Sample RenameMapping if the IdP provides an attribute which should be renamed: <RenameMapping source="phone" target="telephonenumber"/> Examples Rename mapping If the IdP generates a attribute name that is different to the attribute name expected by API Manager (for example, rather than mail), you can use a RenameMapping directive to effectively rename the IdP attribute to the API Manager attribute. For example, to rename the IdP attribute name to the API Manager attribute mail, use the following RenameMapping: <RenameMapping source=" " target="mail"/> The source attribute refers to the attribute supplied by the IdP that you want to rename. The target attribute refers to the name of the attribute after it has been renamed. Multiple rename mappings You can have multiple RenameMapping directives. In the following example, two rename mappings are used: The IdP presents an attribute called . Using the RenameMapping, this is transformed to mail. The IdP presents an attribute called phone. Using the RenameMapping, this is transformed to telephonenumber. In addition, a filter mapping is used to achieve the following: If a user logs in with the transformed mail attribute set to sjones@research.activedirectory2012.lab.chicago.acme.int the user is Axway API Manager User Guide 183

184 6 API Manager single sign-on assigned a role of User and an organization of Research. <Mappings> <RenameMapping source="phone" target="telephonenumber"/> <RenameMapping source=" " target="mail"/> <FilterMapping> <Filter> (mail=sjones@research.activedirectory2012.lab.chicago.acme.int)</filter> <OutputAttribute name="role">user</outputattribute> <OutputAttribute name="organization">research</outputattribute> </FilterMapping> </Mappings> Filter mappings Add the two required attributes when the department attribute from the IdP is set to RD Admin: <Mappings> <FilterMapping> <Filter>(department=RD Admin)</Filter> <OutputAttribute name="role">administrator</outputattribute> <OutputAttribute name="organization">rd</outputattribute> </FilterMapping> </Mappings> Add the two required attributes when the mail attribute from the IdP is set to john.doe@prov.org: <Mappings> <FilterMapping> <Filter>(mail=john.doe@prov.org)</Filter> <OutputAttribute name="role">operator</outputattribute> <OutputAttribute name="organization">prov</outputattribute> </FilterMapping> </Mappings> Add the two required attributes when the department attribute from the IdP is set to RD User: <Mappings> <FilterMapping> <Filter>(department=RD User)</Filter> <OutputAttribute name="role">user</outputattribute> <OutputAttribute name="organization">prov</outputattribute> </FilterMapping> </Mappings> Filter by the user s , and assign a role and an organization: Axway API Manager User Guide 184

185 6 API Manager single sign-on <Mappings> <RenameMapping source=" " target="mail"/> <FilterMapping> <OutputAttribute name="role">api Server Administrator</OutputAttribute> <OutputAttribute name="organization">production</outputattribute> </FilterMapping> </Mappings> Filter syntax A filter is specified using the LDAP Search Filter syntax. Only a subset of the full syntax is supported as detailed in this section. A filter consists of one or more criteria. If more than one criterion exists in one filter definition, they can be concatenated by logical operators. Criteria The criteria must be put in parentheses. A criteria can only be an equality. Example: (givenname=sandra) Operators The logical operators must be placed in front of the criteria. The whole term must be put in parentheses. AND operator criteria1 AND criteria2: (&(criteria1)(criteria2)) More than two criteria: (&(criteria1)(criteria2)(criteria3)...(criteria n) OR operator criteria1 OR criteria2: Axway API Manager User Guide 185

186 6 API Manager single sign-on ( (criteria1) (criteria2)) More than two criteria: ( (criteria1) (criteria2) (criteria3)...(criteria n)) NOT operator NOT criteria1: (!(criteria1)) Nested operators You can combine logical operators. (criteria1 OR criteria2) AND ( criteria3 OR criteria4): (&( (criteria1) (criteria2))( (criteria3) (criteria4))) Configuration file elements This section describes the elements in the service-provider.xml configuration file. <SSOConfiguration> This is the root element of the configuration descriptor. This section contains one <CertificateValidation> element (optional), one <ServiceProvider> element and one <IdentityProviders> element. <CertificateValidation> This element describes the certificate validation. You can configure certificate validation to validate the SP and IdP certificates at startup. The following attributes are supported: Attribute Description pathvalidation If set to true, the certification path for each certificate will be checked. If set to false, the agent verifies only the validity period of each certificate. A trust store must be specified if this attribute is true. enablerevocation If set to true, the agent also verifies if the certificates are not revoked. Axway API Manager User Guide 186

187 6 API Manager single sign-on Attribute Description truststorepath The path to the trust store containing the trusted certificates. truststorepassword The password to access the trust store. intermediatestorepath The path to a store containing intermediate certificates that can appear in certificate chains. intermediatestorepassword The password to access the intermediate certificates store. delaybetweenvalidations Defines at which interval certificate validation occurs, in hours. To disable certificate validation, set pathvalidation to false. For example: <CertificateValidation pathvalidation="false"... </CertificateValidation> <ServiceProvider> This element describes the SP. The following attributes are supported: Attribute Description entityid Sets the unique identifier of the SP. This identifier is sent to the IdP so it can know who is requesting an authentication or logging out. useappsessions Delegates the session management to the application. The default value is true. filtereduri Specifies the URI of the SSO filter entry point for authentication. Set this value to /sso/login. The SSO filter only manages login URI, for other requests the application must redirect to SSO filter to manage authentication. If the user is not authenticated, a SAML authentication request is built and sent to the IdP. Otherwise, the security token is forwarded to the application. logouturi Specifies the URI of the SSO filter entry point for logout process. Set this value to /sso/logout. The SSO filter generates a logout request and sends it to the IdP. Axway API Manager User Guide 187

188 6 API Manager single sign-on Attribute Description logoutredirecturi Specifies the URI where to redirect after the logout process. Set this value to /api/portal/v1.3/sso/login to redirect the user to the login page after logout. keystore Specifies the name of a keystore where the private key of the SP is stored. The default value is conf/sso.jks. The SP uses this private key to sign messages to the IdP, and to decrypt messages from the IdP that the IdP has encrypted with the SP's public key. When you set this attribute, you must also set the associated attributes keystorepassphrase and keyalias. The keystore must be in the classpath of the application or in its working directory. The keystore format must be.jks. keystorepassphrase Specifies the password of the keystore. keyalias Specifies the alias of the SP's private key in the keystore. sessionidcookiename Sets the name of the cookie where the SSO session identifier is stored if the SSO module is the session manager. The recommended value is spsessionid2. <AssertionConsumerService> This element specifies an entry point for receiving SAML assertions from the IdP. <SingleLogoutService> This element specifies the IdP URL where the logout responses are sent. Only HTTP-POST binding is managed. <IdentityProviders> This element describes the entity that exchanges SAML messages with the SSO filter. This section contains a section called <SamlIdentityProvider>, which supports the following attributes: Attribute Description entityid format Sets the unique identifier of the IdP. These values must match the entityid and format values of the Issuer element in the SAML assertions. If the SAML assertion does not have the format set, omit the format element. Axway API Manager User Guide 188

189 6 API Manager single sign-on Attribute Description metadataurl Specifies the URL of the metadata file. The default value is./idp.xml. usernameattribute Specifies the name of the IdP attribute that provides the user name. The default value is urn:oid: When a user is authenticated, the SSO filter sets a principal on the HttpServletRequest. By default, the name of this principal is extracted from the Subject element in the assertions of an authentication response. If usernameattribute is set, the name of the principal is set to the value of the specified IdP attribute. verifyassertionexpiration Verifies the validity period of a SAML assertion. The default value is false. <Mappings> This element contains the mappings to be applied on the IdP attributes. <Features> You can set extra features in the configuration file to fine-tune the SP and the IdPs. SSO troubleshooting This topic describes some common problems and solutions that you might encounter when configuring API Manager SSO. It also describes how to enable traces for SSO. Logging in both as administrator and SSO user on page 190 Cannot access API Manager after successful login on page 190 IdP site cannot be reached on page 190 Internal error if API Gateway and IdP clocks out of sync on page 190 LDAP response timeout during login on page 191 Invalid user or password error after successful login on page 191 Shibboleth IdP logout failure on page 192 Logout issues with Active Directory Federation Services on page 193 Enable traces for SSO on page 194 SAML assertion validation fails on page 194 Invalid requester in Keycloak page on page 194 Error on signing assertions on page 195 Keycloak fails to authenticate the user on page 195 Axway API Manager User Guide 189

190 6 API Manager single sign-on Logging in both as administrator and SSO user Problem: API Manager does not work properly when logging in both as administrator and SSO user. Solution: If an administrator wants to log in to API Manager both as an API administrator and an SSO user, it is recommended that the administrator uses separate browsers to do this. Using separate tabs in the same browser is not enough, because the tabs share the same session. Cannot access API Manager after successful login Problem: You cannot access API Manager after a successful login using SSO. Solution: Verify that there are no errors in the SSO agent log file due to a misconfiguration. Additionally, make sure you are accessing API Manager using the same host name or IP address as the one specified in the API Manager IdP metadata (idp.xml file) used by the Identity Provider: Do not use localhost because some browsers cannot create cookies for this host name. Do not mix host name and IP address. Because cookies are linked to the string used in the URL for the host, there is no IP address resolution. IdP site cannot be reached Problem: You attempt to log in to API Manager using SSO and the following message appears in your browser: This site can t be reached <HostName> refused to connect. ERR_CONNECTION_REFUSED The URL in the browser address bar contains the address of the IdP, for example, Solution: In this case, the Identity Provider (for example, Shibboleth, KeyCloak, Active Directory Federation Services, and so on) is either not running or not reachable. Contact your system administrator for support. The system administrator should confirm that the service is running and that there are no firewall restrictions preventing access to the service. Internal error if API Gateway and IdP clocks out of sync Problem: When attempting to log in to API Manager using SSO, an Internal Error appers if the clock of your API Gateway server and your IdP server are not correctly synchronized. Axway API Manager User Guide 190

191 6 API Manager single sign-on To confirm the cause of the error, check the trace file: ERROR 15/sept./2016:14:41: [3942:dd96da570400a4392aa28808] verifier: ERROR 15/sept./2016:14:41: [3942:dd96da570400a4392aa28808] Internal error: io.axway.commons.sso.agent.serviceprovidervalidationexception: Received response not valid. See log for details. Solution: Ensure that the time on the API Gateway server is synchronized with the IdP. LDAP response timeout during login Problem: When attempting to log in to API Manager using SSO, you see a message similar to: Login Failure: javax.naming.namingexception: LDAP response read timed out, timeout used:3000ms. Solution: This is due to a problem between the IdP and the LDAP service. Contact your network administrator. Invalid user or password error after successful login Problem: When attempting to log in to API Manager using SSO, you see the following message: Invalid user or password To confirm the cause of the error, check the trace file: ERROR 07/Sep/2016:17:11: [23b8:343cd0572c036c31ecc3f2f7] SSO - The user's organization could not be located. Check your service-provider.xml file to see if an OutputAttribute of type 'organization' has been setup. Also check the organization has already been setup in API Manager ERROR 07/Sep/2016:17:11: [23b8:343cd0572c036c31ecc3f2f7] SSO - Unexpected exception authenticating : javax.ws.rs.webapplicationexception: HTTP 401 Unauthorized In this scenario, you have logged in successfully using SSO, but the organization associated with your login is not set up. Either the organization is not configured correctly in the serviceprovider.xml file or the organization does not exist in API Manager. The following message appears in the browser page if the organization does not exist in API Manager: Axway API Manager User Guide 191

192 6 API Manager single sign-on {"errors":[{"code":403,"message":"user was logged in using SSO but failed on permission checks"}]} Solution: Ensure that the organization is configured correctly in the service.provider.xml file and that the organization exists in API Manager. For example, the service-provider.xml file contains the following FilterMapping section: <FilterMapping> <Filter>(name=RD Admin)</Filter> <OutputAttribute name="role">administrator</outputattribute> <OutputAttribute name="organization">research</outputattribute> </FilterMapping> In this example the organization name is Research. Log in to API Manager as the apiadmin user (using the non-sso login URL), and select Client Registry > Organizations. If the organization called Research does not exist, you must add it. Shibboleth IdP logout failure Problem: You are using Shibboleth as an IdP and a logout attempt fails with a message similar to the following: :40:23,678 - INFO [org.opensaml.saml.common.binding.security.impl.samlprotocolmessagexmlsignaturesecur ityhandler:134] - Message Handler: Validation of protocol message signature succeeded, message type: {urn:oasis:names:tc:saml:2.0:protocol}logoutrequest :40:23,688 - INFO [net.shibboleth.idp.saml.saml2.profile.impl.processlogoutrequest:315] - Profile Action ProcessLogoutRequest: No active session(s) found matching LogoutRequest :40:23,689 - WARN [org.opensaml.profile.action.impl.logevent:76] - An error event occurred while processing the request: SessionNotFound Solution: Set the following options for your Shibboleth IDP (as detailed in the sample file INSTALL_ DIR/apigateway/samples/sso/ShibbolethIDP/conf/idp.properties.forl ogout): idp.cookie.secure = true idp.cookie.path = "/" idp.errors.detailed = true idp.errors.signed = true idp.session.enabled = true Axway API Manager User Guide 192

193 6 API Manager single sign-on idp.session.storageservice = shibboleth.clientsessionstorageservice idp.session.trackspsessions = true idp.logout.elaboration = true idp.logout.authenticated = false idp.storage.htmllocalstorage = true # for troubleshooting idp.loglevel.idp=debug idp.loglevel.ldap=debug idp.loglevel.messages=debug idp.loglevel.opensaml=debug Logout issues with Active Directory Federation Services Problem: If your SAML IDP is Active Directory Federation Services (AD FS), you may have issues with the SSO logout. Solution: You must add the a claim rule to enable SSO logout: 1. In AD FS management, click Trust Relationships > Relying Party Trusts > Edit Claim Rules, and select Add Rule. 2. Set the Claim Rule Template Type to Send Claims Using a Custom Rule. 3. Give the claim rule a name, and add the following rule: c:[type == " => issue(type = " Issuer = c.issuer, OriginalIssuer = c.originalissuer, Value = c.value, ValueType = c.valuetype, Properties [" t"] = "urn:oasis:names:tc:saml:1.1:nameidformat: address", Properties [" ualifier"] = "<your SAML Relying Party Trust>", Properties [" lifier"] = " Active Directory server host>/adfs/services/trust"); Replace <your SAML Relying Party Trust> with the name of your SAML Relying Party Trust, and <your Active Directory server host> with the value of your Federation Service Identifier. To get the value of your Federation Service Identifier, click AD FS > Edit Federation Service Properties. Axway API Manager User Guide 193

194 6 API Manager single sign-on Enable traces for SSO To enable the traces for SSO, change the log level for log4j.logger.org.opensaml and log4j.logger.io.axway in the INSTALL_ DIR/apigateway/system/lib/log4j.properties file: # SSO log4j.logger.io.axway=debug, Vordel # Logging of OpenSAML library log4j.logger.org.opensaml=debug, Vordel You must also activate the traces in the API Gateway configuration in Policy Studio: 1. Navigate to Environment Configuration > Server Settings in the Policy Studio tree. 2. Click General and select the DEBUG level from the Tracing level field. 3. Deploy the changes. SAML assertion validation fails Problem: There are several possible reasons why the SAML assertion validation fails. To get more detailed information on this error, temporarily enable traces for SSO and restart API Gateway. If the detailed trace indicates that validation failed because the SAML assertion has expired, there is a conflict in server time between the IdP server and API Gateway, and the SAML assertion is deemed to have expired. Solution: Synchronize the IdP server time with API Gateway. On UNIX/Linux, check that the NTP service is running. Alternatively, open the service-provider.xml file, in the SamlIdentityProvider section, set verifyassertionexpiration to false, and save and redeploy serviceprovider.xml to API Gateway. After you have fixed the issue, disable the traces for SSO, and restart API Gateway. Invalid requester in Keycloak page Problem: On IdP's side in Events, the following LOGIN_ERROR event could be found: invalid signature error Solution: The key in sso.jks and the public key stored in Keycloak s SAML keys for the application do not match as a keypair. Check the SAML keys in the IdP client, and import the correct certificate. Axway API Manager User Guide 194

195 6 API Manager single sign-on Error on signing assertions Problem: After the user enters the credentials on the Keycloak page, the following error is seen: ERROR 14/Feb/2017:15:08: [22a1:621da aa13729] Assertion MUST be signed ERROR 14/Feb/2017:15:08: [22a1:621da aa13729] An error occurred during SSO processing: io.axway.commons.sso.agent.serviceprovidervalidationexception: Received response not valid. See log for details. at io.axway.commons.sso.agent.builders.authenticationresponsebuilder.verifyresponse (AuthenticationResponseBuilder.java:94) Solution: The Sign Assertions setting in Keycloak is switched off. Ensure that the setting is switched on. Keycloak fails to authenticate the user Problem: After the user enters the credentials on the Keycloak page, Keycloak fails to authenticate the user with a message similar to the following: ERROR 13/Feb/2017:17:39: [6831:4befa d4ae09eee1] SSO - The user's organization could not be located. Check your service-provider.xml file to see if an OutputAttribute of type 'organization' has been setup. Also check the organization has already been setup in API Manager ERROR 13/Feb/2017:17:39: [6831:4befa d4ae09eee1] SSO - Failed to authenticate user : [G-fb7c839b-a bae9-1c05e3ba6f04]. Exception: : javax.ws.rs.webapplicationexception: HTTP 401 Unauthorized Solution: The username G-fb7c839b-a bae9-1c05e3ba6f04 does not correspond to a real username, because the SAML response is not parsed correctly. This happens because the mappings are not set up in the IdP. Ensure the mappings are set correctly in Keycloak. The following shows shows an example on the mappings in Keycloak: Axway API Manager User Guide 195

196 API alerting 7 This part contains the following: API management alerts 196 Read API access 202 Read API proxy 203 Read application 204 Read API consumer 205 Read organization 206 API management alerts Overview API Manager can generate alerts when specific events occur. It can generate alerts for events relating to managing partner organizations (for example, when an organization is created or deleted), and for events relating to managing APIs (for example, when access is granted to an API). When an alert is generated by API Manager you can execute a custom policy to handle the alert (for example, to send an to an interested party, or to forward the alert to an external notification system). Sample policies are provided as a starting point for custom development. You can enable or disable alerts in the API Manager web interface. You can change the policy that is executed when an alert is generated in Policy Studio. Alert descriptions Alerts are categorized according to the type of event that generates the alert, for example, organization events are in a different category to application events. The following sections list the alerts in each category, and detail the event that triggers the alert, and the type of the alert (governance or runtime). Events initiated by a person (for example, an administrator approves an API consumer registration) are governance alerts. Events that occur during normal operation of the system are runtime alerts. Application alerts API Manager generates application alerts for events relating to managing applications. Axway API Manager User Guide 196

197 7 API alerting Alert Name Alert Type Trigger Event Approve Application Registration Governance When a new application has been registered but approval is needed (auto-approve disabled). Application Approved Governance When a new application registration is approved (including auto-approve). Delete Application Governance When an application is deleted. Except when the organization is deleted - do not generate an alert for each application in the organization. Enable Application Governance When an application is enabled. Disable Application Governance When an application is disabled. Approve Application API Access Request Governance When an application is requesting access to an API but approval is needed (auto-approve disabled). Application API Access Approved Governance When an application request to access an API is approved (including auto-approve). Remove Application API Access Governance When authorization to access an API is removed from an application. Enable Application API Access Governance When an application s API access is enabled. Disable Application API Access Governance When an application s API access is disabled. API registration alerts API Manager generates API registration alerts for events relating to managing APIs. Axway API Manager User Guide 197

198 7 API alerting Alert Name Alert Type Trigger Event API Proxy Published Governance API owner publishes API proxy. API Proxy Deprecated Governance When an API proxy is deprecated. API Proxy Retired Governance When an API proxy is retired (unpublished). API Proxy Promoted Governance API owner promotes API proxy. API Proxy Authentication Policy Change Governance Authentication policy of a published API proxy is changed. API Deleted Governance When an API proxy is deleted. API catalog alerts API Manager generates API catalog alerts for events relating to enabling and disabling APIs. Alert Name Alert Type Trigger Event Enable API Governance When an API is enabled in the API catalog. Disable API Governance When an API is disabled in the API catalog. API consumer alerts API Manager generates API consumer alerts for events relating to managing API consumers. Alert Name Alert Type Trigger Event Approve API Consumer Registration Governance When a new API consumer user is registered but approval is needed (auto-approve disabled). API Consumer Approved Governance When a new API consumer user registration is approved (including auto-approve). Delete API Consumer Governance When an API consumer user is deleted. Note This alert is not generated for each user when an organization is deleted. Axway API Manager User Guide 198

199 7 API alerting Alert Name Alert Type Trigger Event Enable API Consumer Governance When an API consumer is enabled. Disable API Consumer Governance When an API consumer is disabled. Reset API Consumer Password Governance When an API consumer password is reset (not changed). Organization alerts API Manager generates organization alerts for events relating to managing organizations. Alert Name Alert Type Trigger Event Create Organization Governance When an organization is created. Delete Organization Governance When an organization is deleted. Enable Organization Governance When an organization is enabled. Disable Organization Governance When an organization is disabled. Add Organization API Access Governance When authorization to access an API is granted to an organization. Remove Organization API Access Governance When authorization to access an API is removed from an organization. Enable Organization API Access Governance When an organization s API access is enabled. Disable Organization API Access Governance When an organization s API access is disabled. Quota alerts API Manager generates quota alerts for events relating to system or application quotas. Axway API Manager User Guide 199

200 7 API alerting Alert Name Alert Type Trigger Event System Quota Exceeded Runtime When a system quota is exceeded. System Quota Warning Exceeded Runtime When a system quota warning threshold is exceeded. System Quota Changed Governance When a system quota is changed. Application Quota Exceeded Runtime When an application quota is exceeded (application default quota or application specific quota). Application Quota Warning Exceeded Runtime When an application quota warning threshold is exceeded (application default quota or application specific quota). Application Default Quota Changed Governance When an application default quota is changed. Application Specific Quota Changed Governance When an application specific quota is changed. Application Specific Quota Deleted Governance When an application specific quota is deleted. Enable or disable alerts You can enable or disable alerts in the API Manager web interface. Click the Settings > Alerts view in API Manager. Alerts are disabled by default. The following figure shows the view of API management alerts in API Manager. Axway API Manager User Guide 200

201 7 API alerting To enable or disable an alert, click the On/Off button next to the alert. Changes are saved automatically. Change the alert policy to execute When an enabled alert is generated, the policy associated with that alert is executed. The alert context provides the policy with a number of message attributes. These are specific to the alert being generated (for example, alert.application, alert.appdev, alert.organization). By default, each alert is configured to execute a sample policy, and the sample policy demonstrates the attributes from the respective alert context. You can change what happens when an alert is generated, either by modifying the sample policy associated with the alert, or by creating a custom policy and associating that policy with the alert. You can change the policy that is executed when an alert is generated in Policy Studio. To view the API management alerts and the associated policies, click the Environment Configuration > Server Settings node in the Policy Studio tree view. On the Server Settings tab, expand the API Manager tree node and click Alerts. The following figure shows the view of API management alerts in Policy Studio. Axway API Manager User Guide 201

202 7 API alerting To modify the sample policy associated with an alert, click the sample policy link next to the alert. For more information on configuring policies, see the API Gateway Policy Developer Guide. To associate a different policy with an alert, click the row containing the alert, and click the Edit button. In the dialog, click the browse button to select a new Alert Policy and then click OK. To save any changes, click the Save button. Read API access Overview You can use the Read API Access filter to get information from the client registry about a particular organization's, or a particular application's, access to an API. This filter stores the information in a message attribute (for example, apimgmt.apiaccess). You can use this filter within an alert handling policy (or any other policy) to read an organization's or an application's API access easily. General settings Configure the following fields: Name: Enter an appropriate name for the filter. Axway API Manager User Guide 202

203 7 API alerting API ID selector: Enter a selector expression with the name of the message attribute that contains the API ID. The value of the selector is expanded at runtime. The default is ${apimgmt.apiproxy.id}. Entity ID selector: Enter a selector expression with the name of the message attribute that contains the application or organization entity ID. The value of the selector is expanded at runtime. The default is ${apimgmt.entity.id}. Type: Choose the type of the entity, Application or Organization. Name of attribute to set: Enter the name of the message attribute to set. The default is apimgmt.apiaccess. Further information For more details on configuring policies, see the API Gateway Policy Developer Guide. Read API proxy Overview You can use the Read API Proxy filter to get information from the client registry about an API proxy. This filter stores the information in a message attribute (for example, apimgmt.apiproxy). You can use this filter within an alert handling policy (or any other policy) to get information about an API proxy easily. General settings Configure the following fields: Name: Enter an appropriate name for the filter. API Proxy ID selector: Enter a selector expression with the name of the message attribute that contains the API proxy ID. The value of the selector is expanded at runtime. The default is ${apimgmt.apiproxy.id}. Name of attribute to set: Enter the name of the message attribute to set. The default is apimgmt.apiproxy. Axway API Manager User Guide 203

204 7 API alerting Further information For more details on configuring policies, see the API Gateway Policy Developer Guide. Read application Overview You can use the Read Application filter to get information from the client registry about an application. This filter stores the information in a message attribute (for example, apimgmt.application). You can use this filter within an alert handling policy (or any other policy) to get information about an application easily. General settings Configure the following fields: Name: Enter an appropriate name for the filter. Application ID selector: Enter a selector expression with the name of the message attribute that contains the application ID. The value of the selector is expanded at runtime. The default is ${apimgmt.application.id}. Name of attribute to set: Enter the name of the message attribute to set. The default is apimgmt.application. Example policy The following figure shows an example of an alert handling policy that uses the Read Application filter. This policy handles the alert generated when an application's access to an API is enabled. It uses the Read Application filter to get information about the application, which it then uses to populate an alert message. Axway API Manager User Guide 204

205 7 API alerting Further information For more details on configuring policies, see the API Gateway Policy Developer Guide. Read API consumer Overview You can use the Read API Consumer filter to get information from the client registry about an API consumer. This filter stores the information in a message attribute (for example, apimgmt.appdeveloper). You can use this filter within an alert handling policy (or any other policy) to get API Consumer information easily. General settings Configure the following fields: Name: Enter an appropriate name for the filter. API Consumer ID selector: Enter a selector expression with the name of the message attribute that contains the API consumer ID. The value of the selector is expanded at runtime. The default is ${apimgmt.appdeveloper.id}. Name of attribute to set: Enter the name of the message attribute to set. The default is apimgmt.appdeveloper. Further information For more details on configuring policies, see the API Gateway Policy Developer Guide. Axway API Manager User Guide 205