In the Host field, enter the IP address. The API Proxy can be a host within the network or external to the network.
The administrator portal is a platform to manage and administer properties and functionality of the ColdFusion API Manager. Through the administrator portal, you can manage all published APIs, and their functional and non-functional information.
As an administrator, you can perform the following tasks:
- Add and manage all users and their roles with respect to single or multiple published APIs.
- View and manage all SLA plans.
- View and manage tier plans of all published APIs.
Logging in to the administrator portal
To log in to the administrator portal:
- Enter the user name and password in the fields provided.
- Click Login.
If you want to change the password, navigate to <API Manager Installation Directory>/conf and open the file password.properties. Change the password in the file. You can only change the default administrator password using the password.properties file.
Steps to reset admin password:
1. Edit the password.properties file at <apimanager_home/conf>with entries as:
adminname=<User name while installing API Manager>
adminpassword=<Your new preferred password>
2. Make readDefault to true in default_conf.xml.
3. Restart "ColdFusion 2016 API Manager" service.
You cannot delete or edit this account to remove administrator privileges.
You cannot change the password of other users except the default user.
Changing the header logo and title
You can change the logo and title on the header area of the administrator portal.
Navigate to the <API Manager Installation Directory>/wwwroot/portal/conf folder and open the file config.json. Modify the following properties:
{
"headerTitle": "API Manager Portal",
"adminHeaderTitle": "API Manager Administrator",
"headerLogoPath": "images/CF-Logo.png"
}
Specifying server settings
You can configure the settings for the API Manager server from the following screens:
- General
- API Datastore
- API Analytics Server
General
On this page, you can set up an API Proxy or an API Portal to host your APIs.
API Proxy
In an enterprise, you communicate with existing and new customers. Consumers use a range of devices from phones to desktops. One of the ways to interact with the devices is through an API. But, there are some concerns, for example, security, availability, and monitoring of the APIs. In such situations, you define an API proxy. An API proxy performs the following:
- Transports security
- Monitors SLAs, performance, and so on, of the API
- Defines access levels of an API
An API proxy makes your API independent from your back end services. Whenever you change your back end services, for example, changes in code, the application runs without interruptions.
Setting up an API Proxy
-
-
In the Port field, enter the port of the API Proxy. For example, http://localhost:5100, where 5100 is the port number.
-
To enable the port on the API Proxy when the proxy restarts (manually or scheduled), select the Enable check-box.
-
In the Context Root field, enter the name of the context root. A context root identifies an application on the server. For example, if your application's context root is mycontextroot , and the application is hosted on http://localhost:5100, you can access the application at http://localhost:5100/mycontextroot.
Note:
If you change your connector settings in ColdFusion, reconfigure the connector settings in both Proxy and Portal.
If the proxy context is "/" and selecting to configure connector to CF, you can see a message regarding restrictions in default document.
If the proxy content is "/ something-else " and selecting to configure connector to CF, there is no message.
-
In the AJP Port field, enter the port number of the Apache JServ Protocol (AJP) connector. AJP allows Tomcat to communicate with an Apache web server.
-
To enable the AJP Port on the server, select the Enable check-box adjacent to the AJP Port field. To save the changes, click Save.
-
In the Domain URL field, enter the URL of the domain that hosts the API endpoints.
Advanced Request Settings section
- Max Header Size (in bytes): Maximum allowable size for an API request header.
- Max Body Size (in bytes): Maximum allowable size for the body of an API request.
- Max Total Files Upload Size (in bytes): Maximum size allocated to a file for upload.
- Max No. of Headers: Maximum allowed count of headers in a request.
- Max No. of Parameters: Maximum allowed count of query parameters in a request.
Setting up a Portal
Publishers use portals to create APIs for subscribers to consume. On a portal, a publisher can create the APIs and can restrict the APIs to certain nodes. Portals can run on multiple nodes. On the other hand, you can configure an API proxy on any node.
-
In the Port field, enter the port of the API Portal.
-
To enable the port on the API Portal when the proxy restarts (manually or scheduled), select the Enable check-box.
-
In the AJP Port field, enter the port number of the Apache JServ Protocol (AJP) connector. AJP allows Tomcat to communicate with an Apache web server.
-
To enable the AJP Port on the server, select the Enable check-box adjacent to the AJP Port field. To save the changes, click Save.
API Datastore
The Datastore is a distributed configuration system and an in-memory cache used in the API Manager. The API Datastore has the following advantages:
- Distributed
- Fast
- Scalable
- Failsafe
Configuring datastore settings
-
In the Host field, enter the host name or IP address of the Data store. The Data store can be local or external to a network.
-
In the Port field, enter the port number of the Data Store.
-
In the Password field, enter the password of the Data Store.
-
In the Timeout field, enter the timeout duration in seconds.
API Analytics Server
Configure the settings for the number of API requests for which to generate metrics. For more information, refer to Metrics and Logging.
Configuring metric settings
-
In the Cluster Name field, enter the name of the Elastic Search cluster. The analytics of these requests are then published into a portal. For more details, refer to Setting up Cluster Support.
-
Specify the ElasticSearch node address along with the HTTP Port and Cluster Port.
- API Manager uses Cluster port to send the metrics related data to the ElasticSearch.
- API Manager uses HTTP port to fetch the data from ElasticSearch to render it on Analytics Dashboard.
-
To manually add the other nodes of ElasticSearch cluster, click Add Address.
-
Enter the ElasticSearch node address and enter the port number in the HTTP Port and Cluster Port fields.
-
In the Socket Timeout field, enter the timeout for receiving individual packets from ElasticSearch Server.
If a large amount of data is retrieved in a single request from ElasticSearch server and network latency is high, increase the timeout.
-
In Analytics Server configuration, the client allows to sniff the rest of the cluster, which lists all nodes that the cluster can use. To enable this feature, select Sniff.
When you select Sniff and specify an Analytics Server address in the configuration, the API Manager automatically finds the other cluster nodes and balances load among them in a round-robin fashion.
-
In the Flush Interval field, enter the time interval (in seconds). This is the time after which the Analytics Server receives a specified number of API requests to flush the data to the disk.
-
In the Refresh Interval field, enter the time interval (in seconds). This is the time after which the Analytics Server refreshes all indices and in-memory buffer is written to a new segment, without committing those changes to the disk.
-
In the Maximum Actions Per Bulk Request field, enter the number of actions that are collectively sent to the Analytics Server for metrics calculation and visualization. If you enter 1000 in the field, no more than 1000 actions can be sent to the Analytics Server. The default value is 1000 actions per bulk request.
-
In the Maximum Concurrent Bulk Request field, enter the number of concurrent bulk requests that are sent to the Analytics Server. For example, if you enter 2 in the field, no more than two concurrent bulk requests can be sent to the Analytics Server.
-
In the Maximum Volume Per Bulk Request field, enter the size of the each bulk request in this field. The size is calculated in Megabytes. For example, if you enter 5 in the field, the size of bulk request cannot exceed 5 MB.
Specifying security settings
Configuration
You can configure the OAuth2 settings on this screen. This protocol allows third-party applications to grant limited access to an HTTP REST service, either on behalf of a resource owner, or by allowing the third-party application to obtain access on its own behalf.
Configuring OAuth2 settings
-
Click Security > Configuration.
-
In the Encryption Seed field, enter a random string as new seed value to encrypt application keys, user store connection passwords, and mail server passwords. This string is always a random value.
Opmerking:If you change the encryption seed, restart the API Manager application server.
-
In the Portal Session Timeout field, enter the number of seconds after which the session of an API publisher or administrator portal application expires.
-
In the Password Reset Timeout field, enter the number of seconds within which a user can submit a request to change the password.
-
In the Max Invalid Login Attempts Before Lockout field, enter the maximum attempts to log in before you are locked out. For example, if you enter five in the field, you can enter an incorrect password only five times.
If you enter zero in the field, a user can make unlimited login attempts. Entering zero is not recommended.
-
To permanently lock an account, select the Lockout Forever check-box. By default, it is unchecked. If you choose this option, a user is locked out permanently as soon as he exhausts the maximum attempts to log in to the portal.
-
In the Account Lockout Duration field, enter the time in seconds after which a user can request for a new password after exhausting the maximum invalid login attempts.
-
In the OAuth2 Session Timeout field, enter the number of seconds after which your OAuth2 session gets expires. After the session, you will enter your user name and password for obtaining access tokens and authorization codes.
-
In the OAuth2 Access Token Default Timeout field, enter the duration of the default OAuth2 access token after which the original access token expires. A subscriber can override this value in the application configuration.
-
In the OAuth2 Refresh Token Default Timeout field, enter the default OAuth2 refresh token duration after which the ioriginal refresh token expires. A subscriber can override this value in the application configuration.
-
In the Authorization Code Timeout field, enter the number of seconds after which the OAuth2 authorization code expires.
-
To allow only HTTPS on OAuth2 and token endpoints, select the Mandate HTTPS check-box. If you select this check-box, you reject plain HTTP connections.
User Store
A user store is a database to store information about users and user roles. The database stores login id, password, first name, last name, email address, and so on.
You can create a user store through LDAP or a database connection, such as, JDBC and ODBC. The API Manager comes with an internal user store.
To add a user store:
Creating a user store
-
Click Security > User Store.
-
Click Add User Store.
-
From the Connector Type drop-down list, select the type of connector - LDAP Connector or Database Table Connector.
Database Table Connector
You can create a user store using JDBC. You can create a connection string in the database to store the information that an application uses to connect to the database.
Details tab
The Details tab contains the following fields:
Field |
Description |
Name |
The name identifies the user store. |
Logon Identifier |
The unique identifier for a user store. Prefix this identifier when you log in to a portal. |
Description |
The information about the user store. |
Disabled check-box |
Select to enable users in the store access consumer applications. |
Connection tab
The Connection tab contains the following fields:
Field |
Description |
Database Server Name |
The name of the host from where the database runs. |
Database Port |
The port number of the database server. |
Database User Name |
The name of the user that has permission to a table. |
Database User Password |
The password of the user. |
Database Name |
The name of the database server that contains the table. |
JDBC Driver |
The name of the class of the JDBC driver. |
JDBC Connection URL |
The URL of the JDBC driver. For more information, refer to the JDBC Driver documentation. |
Datasource Path |
The path to the source of JDBC data. For example, jdbc/SampleDataSource. |
Initial JNDI Properties |
The list of JNDI standard environment properties. |
Configuration tab
The Configuration tab contains the following fields:
Field | Description |
User Table | The name of the table that contains the user accounts. |
Key Column | The value of the column that uniquely identifies the rows in the table. |
User First Name Column | The first name of the user. |
User Last Name Column | The last name of the user. |
User Email Column | The email of the user. |
Password Column | The name of the column in the table that holds the values of the passwords of a user. |
Roles Table | The name of the table in the database that contain user roles. |
Roles Table Key Column | The name of the table that contains the mapping between users and their roles. |
User Roles Mapping Table User Key Column | The value of the column that associates user account in the table. |
User Roles Mapping Table Role Key Column | The value of the column that associates roles of users in the table. |
Pooling tab
The Pooling tab contains the following fields:
Field |
Description |
Maximum Idle Connections |
The maximum number of connections to the database that can be idle. |
Minimum Idle Connections |
The minimum number of connections to the database that can be idle. |
Connection Wait Timeout |
The time (in milliseconds) that the pool can wait for a connection before it times out. |
Maximum Active Connections |
The maximum number of connections that are allocated from the pool concurrently. |
Idle Connection Evict Timeout |
The time (in milliseconds) to wait before removing an idle connection. |
Advanced tab
The Advanced tab contains the following fields:
Field |
Description |
Enable writing empty string |
Select this check-box to write an empty string instead of a null value in columns defined as not-null in the table schema. |
Name Quoting |
Select this check-box if you want the column names for the database to be within quotes. |
Validate Connection Query |
The SQL query to validate the database connection. |
JavaScript connector
You can write JavaScript code to connect to any database and authenticate users, fetch users, and perform other tasks.
Details tab
The Details tab contains the following details:
Field |
Description |
---|---|
Name |
The name of the user store. |
Logon Identifier |
The identifier to the user store. |
Description |
More information about the user store. |
Disabled |
If disabled, users are unable to access applications. |
Scripts tab
The Scripts tab contains the following details:
Script Mode: Write all your events in the script mode.
Events mode: Add a JS event, for example, searchUsers, getUser, from a list of events. For example, add the event getUser. The following screenshot displays a sample code to retrieve a list of users from the user store:
Upload JS file: When uploading a file, the content of the file gets displayed in the Scripts tab. You can edit the file and save it. The changes you make do not reflect in your original file.
JavaScript Variables: Declare your variables in the section.
List of JavaScript events
onStoreStart
Initialize variables, set properties, or declare helper functions. For example,
var http = require("http"); // USe HTTP as client var pool = http.configure().pool({ "total" : 30, "perRoute": 20 }).proxy("localhost:8080").timeout({ "readtimeout": 20, "requesttimeout": 100 }).ssl({ "truststorename": "namegiveninadmin", "keystore": "admin" }).build(); var url = "Your URL"; var apiKey = "Your API key";
auth
Authorize users of a user store, when the user store is configured for OAuth2. Also onboard publishers, subscribers, or administrators to a user store.
function auth(username, password) { r authMap = { "username": username, "password": password, "options": { "multiOptionalFactorEnroll": false, "warnBeforePasswordExpired": false } }; print("response: " + JSON.stringify(authMap)); var response = pool.post(url + "authn") .header("accept","application/json") .header("Content-Type","application/json") .body(JSON.stringify(authMap)).asString(); if(response.status == 401) throw new Error("Invalid Username/Password"); if(response.status == 200) { //parse Response print("received response " + response.body); var json = JSON.parse(response.body); if(json.status == "SUCCESS") {//save profile return true; } throw new Error("Unknown Error"); } else throw new Error("Internal Server Error"); }
searchUsers
Search for users in a user store, specify a search filter, and specify the number of search results to be returned in a page.
function searchUsers(settings) { print("inside search users"); var response = pool.get(url + "users") .header("accept","application/json") .header("Content-Type","application/json") .header("Authorization","SSWS " + apiKey) .queryString("q",settings.filter) .queryString("limit", settings.pageSize) .asString(); print("received response " + response); if(response.status == 200){ var json = JSON.parse(response.body); if(json.length) { var users = []; for each (var user in json) { users.push(toAccount(user)); } return users; } return []; } else if(response.status == 401) { log.info("Okta API Key " + apiKey + " is invalid/expired. Unable to search for the users"); } throw new Error("Internal server error."); }
Returns array of users with the following properties:
- uniqueid
- username
- firstname
- lastname
- accountenabled
searchRoles
Search for scopes for both OAuth2 or basic authentication where you want to tag your scopes with roles.
function searchRoles(settings) { print("inside search groups"); var response = pool.get(url + "groups") .header("accept","application/json") .header("Content-Type","application/json") .header("Authorization","SSWS " + apiKey) .queryString("q",settings.filter) .queryString("limit", settings.pageSize) .asString(); print("received response " + response); if(response.status == 200){ var json = JSON.parse(response.body); if(json.length) { var groups = []; for each (var group in json) { groups.push(toGroup(group)); } return groups; } return []; } else if(response.status == 401) { log.info("Okta API Key " + apiKey + " is invalid/expired. Unable to search for the groups"); } throw new Error("Internal server error."); }
The search results are returned with the following:
- uniqueidrolename
- rolename
- description
getUser
Retrieves a user belonging to any role or roles.
function getUser(username, needgroups) { // needgroups=True or false print("inside get user"); var response = pool.get(url + "users/" + username) .header("accept","application/json") .header("Content-Type","application/json") .header("Authorization","SSWS " + apiKey) .asString(); print("received response " + response); if(response.status == 200) { print(response.body); var acc = toAccount(JSON.parse(response.body)); if(needgroups) { var groups = getUserRoles(username); acc.userRoles = groups; // userRoles- list of unique ids of roles. } return acc; } else if(response.status == 401) { log.info("Okta API Key " + apiKey + " is invalid/expired. Unable to search for the users"); } else if(response.status == 404) { return null; } throw new Error("Internal server error."); }
getUserRoles
Retrieves a list of roles for a user.
function getUserRoles(username) { print("inside get user roles"); var response = pool.get(url + "users/" + username + "/groups") .header("accept","application/json") .header("Content-Type","application/json") .header("Authorization","SSWS " + apiKey) .asString(); if(response.status == 200){ var json = JSON.parse(response.body); if(json.length) { var groups = []; for each (var group in json) { groups.push(toGroup(group)); } return groups; } return []; } else if(response.status == 401) { log.info("Okta API Key " + apiKey + " is invalid/expired. Unable to search for the groups"); } throw new Error("Internal server error."); }
The search results are returned with the following:
- uniqueid
- rolename
- description
getRoleMembers
Retrieves users belonging to a role in the user store.
function getRoleMembers(rolename) { print("inside get role members"); var response = pool.get(url + "groups/" + rolename + "/users") .header("accept","application/json") .header("Content-Type","application/json") .header("Authorization","SSWS " + apiKey) .asString(); if(response.status == 200){ var json = JSON.parse(response.body); if(json.length) { var users = []; for each (var user in json) { users.push(toAccount(user)); } return users; } return []; } else if(response.status == 401) { log.info("Okta API Key " + apiKey + " is invalid/expired. Unable to search for the users of group"); } throw new Error("Internal server error."); }
Returns array of users with the following properties:
- uniqueid
- username
- firstname
- lastname
- accountenabled
onStartEnd
Any helper function you want to execute before exiting the JavaScript connector. For example, creating a log file, storing values in memory, or terminating a session.
function onstoreend(){ pool.shutdown(); }
For more information, see the Nashorn documentation.
LDAP Connector
You can configure the API Manager to leverage an LDAP server for user authentication. In this case, the LDAP server creates and manages users.
Details tab
The Details tab contains the following fields:
Field |
Description |
Name |
The name of the user store. The name identifies this user store. |
Logon Identifier |
The identifier of the user store in LDAP. |
Description |
The information about this user store. |
Disabled |
Select this check-box to enable users in the store access the consumer applications. |
Connection tab
The Connection tab contains the following fields:
Field |
Description |
Host |
The name or IP address of the LDAP server. |
TCP Port |
The port number of the LDAP server. This port is the same as the port on which the LDAP listens for SSL connections. |
User Bind DN |
The bind Distinguished Name (DN) to connect to the LDAP server. The bind DN is the user on the external LDAP server permitted to search the LDAP directory within the defined search base. The role of the bind DN is to query the directory using the LDAP query filter and search for a user. For example, some possible bind DNs are cn=administrator, cn=Users, dc=domain, or c=com. |
User Bind DN Password |
The password to connect to the LDAP server. |
SSL/TLS Enabled |
Select this check-box to use a secure connection. |
StartTLS Enabled |
Select this check-box to allow an application to send secure requests to an LDAP server. |
Base Contexts |
The points in the LDAP tree for searching the tree. |
Failover Servers |
The name of all the servers that act as failover servers. For example, "ldap://ldap.example.com:389/" represents a list of failover servers. If the primary server fails, Java Naming and Directory Interface (JNDI) connects to the next available server in the list. |
Configuration tab
The Configuration tab contains the following fields:
Field | Description |
User Configuration | The object classes for creating user objects in LDAP. An object class represents the type of data in an LDAP. An objects class contains attributes of an entry in an LDAP. An objectclass is defined in a schema. |
LDAP Filter for Retrieving Accounts | The filter attribute to retrieve user accounts from LDAP. |
Account User Name Attributes | The attribute or attributes that represent a user name of an account. An attribute authenticates a user name in an LDAP entry. |
User First Name Attribute | The attribute that represents the first name of the user in an LDAP account. |
User Last Name Attribute | The attribute that represents the last name of the user in an LDAP account. |
User Email Attribute | The attribute that represents the email of the user in an LDAP account. |
Group Configuration | The object classes for creating groups in LDAP. |
LDAP Filter for Retrieving Groups | The filter attribute to retrieve user groups from LDAP. |
Group Name Attribute | The attribute that represents the name of the group in an LDAP account. |
Group Membership Attribute | The attribute that contains users in an LDAP group. |
Advanced tab
The Advanced tab contains the following fields:
Field |
Description |
Use Paged Result Control |
Select this check-box to ensure that the LDAP uses paged results instead of Virtual List View (VLV) when retrieving user accounts. VLV lets you query a large directory in chunks. For example, let there be a directory with a large number of users, "ou": dc=demo,dc=local + ou=DemoGroups (100,000 groups) + ou=DemoUsers (100,000 users) If you want to present the information in the user group "ou" in a scrollable or paged window in an application, retrieving 1000 pages of 100 results each is an inefficient way. This method is resource-intensive and wastes bandwidth. On the other hand, VLV queries a large data-set with a sorting rule. For example, using VLV, you can sort the first 50 users ordered by organizationName in an LDAP. |
LDAP Referral Handling |
Either follow or ignore LDAP referrals. LDAP referrals enable an LDAP tree to be distributed across multiple LDAP servers. Therefore, an LDAP server can reference other LDAP servers even though it does not store the full Directory Information Tree (DIT). When you browse a particular directory, an LDAP server returns referrals after referring you to another server in the tree. |
Adding users
User management in the API Manager involves defining and managing users, roles, and their access levels. You can add or delete users, assign roles, search for users, manage user stores, and import external users from LDAP or database connection.
To add a user:
-
Click Security > Users
-
Click Import External Users to retrieve users from a database or an LDAP connection.
-
To add a user, select a user store and click Add User. The following page displays.
-
- In the User Name field, enter the unique identifier of the new user.
- Enter the attributes of the user in the rest of the fields.
- Select the appropriate role for the new user- Publisher, Subscriber, or Administrator. For more details, see Roles.
- Click Add User to add the user in the user store.
SAML Identity Provider
In this scenario, the user tries to access a service provider configured in API Manager. API Manager the sends a SAML token to the service provider. The service provider then identifies the user and authenticates the token. If the user is identified successfully, the user logs in to the service provider.
To set up API Manager as identity provider:
-
Log in to the API Manager as Administrator. Click Security > Identity Providers > SAML.
-
In the General tab, enter the following details:
Name
Name of the SAML identity provider.
Display Name
The name of the IdP to be displayed.
Enabled
Enable or disable the IDP.
Description
The description of the IDP.
Service Provider
Select the SP already created.
-
In the Metadata tab, you have three options to import SAML metadata. enter the following details:
SAML URL
The URL through which you get the metadata.
SSO URL
The URL through which you log in.
Sign Authentication Assertions
Enable if you want to sign before sending the assertions.
Sign Certificate
The certificate used for signing.
-
In the Attribute Mappings tab, enter the following details:
Default Roles
Choose from the following – Publisher, Subscriber, or Administrator
Role Attribute Name
Role identifier between API Manager and the IDP.
Role Attribute Delimiter
Delimiter for role attributes.
Attribute Mappings
Enter the same values that you had entered when configuring the application in Okta.
-
In the Advanced Settings tab, enter the following details.
User ID Location
Identifier for the user name defined in the metadata.
Clock Skew (seconds)
Offset between the API Manager and the IDP local times.
SAML Service Provider
In this scenario, the service provider sends a SAML token to the API Manager as identity provider. API Manager then sends the appropriate response to the service provider, which then authenticates the SAML metadata and allows the user to log in to the application.
Enabling API Manager as an identity provider, you need a key pair that is signed by an external certificate authority. You can generate a key pair either by:
- Using a keystore GUI-based tool
- Using the Java command line. See https://helpx.adobe.com/coldfusion/api-manager/configuring-ssl.html#Generatingkeypairsandcertificates for more information.
To set up the service provider:
Click Security > Service Providers > SAML. Enter the following details:
Name |
The name of the service provider. |
Display Name |
The name to be displayed. |
Enabled |
Enable or disable the service provider.
|
Description |
The description of the service provider. |
Entity Id |
Globally unique name for the SAML entity, which in this case is the Service Provider. |
SSO URL |
The location where your Identity Provider receives SSO messages. |
ACS URL |
The location where the SAML assertion is sent. |
Sign Requests |
|
Assertions Signed |
|
Enable IDP SSO |
Enable the check-box to allow the Identity Provider's single-sign on service to receive a signed auth request. |
Signing Keystore name |
|
|
|
Encryption Keystore name |
|
|
|
Key Stores
A Key Store is a repository of security certificates – either authorization certificates or public key certificates – plus corresponding private keys, used for instance in SSL encryption.
You can use a key store in one of the following ways:
- The keystore contains private keys and certificates used by SSL servers to authenticate themselves to SSL clients. By convention, such files are referred to as keystores .
- When used as a truststore , the file contains certificates of trusted SSL servers, or of Certificate Authorities trusted to identify servers. There are no private keys in the truststore .
To create a key store: |
To import a key store: |
1. Click Create Key Store. 2. Set a name and password for the key store. 3. Click Create. 4. Click Import Certificate. 5. Enter the alias for the certificate and choose the certificate file that you had created using keytool command line or GUI. 6. Click Import Certificate. |
1. Click Import Key Store. 2. Enter the following details: a. Name of the key store b. Password of the key store c. Choose the certificate you had created previously d. Choose the type of key store – JKS or PKCS e. (Optional) Enter an alias for the certificate 3. Click Create. |
Setting up SAML Identity Provider (IDP)
For this example, you can set up Okta as Identity Provider with the details of your SAML Service Provider (SP). The first step is to set up an application in Okta.
-
Log in to your Okta organization with administrative privileges.
-
Create an application using SAML 2.0 as the integration type.
-
In the Configure SAML tab, enter the following details:
a. Enter http://localhost:9000/amp/saml/SSO/default/localhost in the Single sign on URL field. This is the same URL as ACS URL as specified in the SAML SP settings in API Manager.
b. Enter http://localhost/amp/apimanager as the Entity ID. This is the same URL as specified in the SAML SP settings in API Manager.
c. In the Attribute Statements section, add the following attributes:
i. firstname set to "user.firstName"
ii. lastname set to "user.lastName"
iii. email set to "user.email"
-
Click Next and click Finish. To create a group and assign users, click Directory > Groups.
-
To add a group and assign members, click Add Group.
Configuring SLAs
In the API Manager, an application or a resource can be available to a consumer at different levels of service. SLA configuration enforces access control through rate limiting and throttling. Throttling tiers limit the number of hits to an API over a certain time, due to monetization of the API, security restrictions, infrastructure issues, and so on.
For example, you can set throttling tiers to the APIs to limit access to it accordingly. Each tier defines a maximum number of requests per day or week or month.
You can also set the rate limit for an SLA per second or minute or hour.
You can then add your own tiers to the API Manager using the instructions below:
Adding an SLA
-
Click SLA Configuration. The following page displays.
-
Select the rate limiting algorithm. In API manager, two types of algorithms can be used to limit the rate: Rolling and Fixed.
In fixed window algorithm, the period is considered from the starting of the time unit to the end of the time unit. For example, a period is considered as 0-60 seconds for a minute irrespective of the time frame at which the API request has been made.
In rolling window algorithm, the period is considered from the fraction of the time at which the request has been made to the end of the time unit. For example, if two requests for API calls are made at 30th second and 40th second of a minute it is considered as two requests from 30th second of that minute up to the 30th second of next minute.
For more details, refer to Rate-limiting.
-
In the SLA Name field, enter the name of the new SLA.
In the Rate Limit field, enter the API request rate limit in the SLA. You can only limit an API request rate to number of requests per second, minute, or hour.
In the Throttle Limit field, enter the API throttle limit in the SLA. You can only limit an API request rate to number of requests per second, minute, or hour.
Select the type of throttle limit- Hard or Soft.
- Hard: If you select this option, the number of API requests cannot exceed the throttle limit.
- Soft: If you select this option, you can set the API request limit exceed a percentage. For example, if you set the Exceed Limit to 90%, the number of API requests can exceed 90% of the prescribed limit.
-
In the Notify Limit field, enter the limits (in percentage) at which you receive notifications when the number of API requests approach the limit.
-
In the Exceed Limit field, enter the limits (in percentage) by which the number of API requests can exceed.
-
If the SLA requires an approval from the API publisher, select the Approval Required check-box.
Editing an SLA
You can edit an SLA and modify its properties. Choose an SLA from the Existing SLAs list.
-
Click Edit. The following page displays.
-
Update all the properties of the SLA and click Update SLA.
Creating a multi-tenant organization
To create a multi-tenant organization, click Organizations on the left pane and then click Create Organization.
Enter the following details.
Click Create.
For more information, see Multi-tenancy in API Manager.
Viewing cluster information
You can see a list of all clusters configured in API Manager. You can also see a cluster's proxy port, portal port, and so on.
Caching
Set the maximum response size to define the maximum size, in bytes, of the response that can be stored in the output cache. Also specify the timeout, in seconds.
ColdFusion discovery server
If you want to discover REST services published in a ColdFusion non-InVM environment, configure the ColdFusion server on the CF Discovery Server Configuration page.
-
In the Protocol drop-down list, select HTTP or HTTPS.
-
In the Name field, enter the name of the ColdFusion server.
-
In the Address field, enter the host and port number of the CF server.
-
In the Context field, enter the REST servlet context of the CF server.
-
In the Username and Password fields, enter the credentials to log in to the ColdFusion server.
Configuring notifications
The API Manager sends notifications for any alerts or user events that require attention. You can configure the settings for email notifications for publishers and consumers.
Configuring mail settings
-
Click Notifications > Mail. The following page displays.
-
In the Mail Server field, enter the name of the server that sends Simple Mail Transfer Protocol (SMTP) messages. Alternatively, you can enter the mail server (for example, mail.company.com) or the IP address of the mail server (for example, 127.0.0.1).
-
In the Port field, enter the port number of the mail server.
-
In the From E-Mail Address field, enter the email address from which all password reset notification mails are sent to users.
-
In the Username and Password fields, enter the credentials to authenticate a user in the mail server.
-
In the Timeout field, enter the time (in seconds) that the API Manager waits for a response from th email server.
-
In the Protocol field, enter the messaging protocol for the mail server, for example, SMTP.
-
To enable Transport Level Security (TSL) on the connection to the mail server, select the Enable TLS connection to mail server check-box. Transport Layer Security (TLS) is a protocol that ensures privacy between applications and their users within a network. When a server and client communicate, TLS ensures security of the communication.
Modifying the e-mail template for password reset
To modify the e-mail template for password reset, navigate to {API Manager HOME}/conf/templates and open the file resetpassword .vm.
You can modify the subject and the body.
Configure log
In this page, choose the modules for which you want to generate debug logs. For example,
- Messages logged during startup, shutdown, and cluster updates.
- Messages logged when a request is dispatched.
- Messages logged when an API resolves a request.
You can enable debugging for specific sections that you want to debug. For example, if you want to check for any issues while creating an API, enable the Publisher check-box in the Portal section.
This way you can manage your debug logs properly.
Viewing the analytics dashboard
Analytics dashboard helps you view the number of APIs that are run from a node, the number of API requests, and system statistics. The API Manager collects information as APIs process information. If you see a sudden spike on a graph or chart, you can take immediate measures.
By clicking a particular data (for example, API name or Publisher name or field in graph), you can filter the entire dashboard on that field.
Click Analytics to display the dashboard.
There are three types of dashboards in the Administrator portal:
- Home
- Publisher APIs
- Publishers
Home: On the Home dashboard panel, you can see the following dashboards:
Request Count for Nodes
You can view the node IP and port on which an API runs. You can also view the number of requests by the API. Hover the pointer on the visualization to see the details.
Total Request Count
You can view the count of requests by an API.
Consumed Metrics
You can view the avarage response time (in milliseconds) of an API, and the average incoming and outgoing data (in KB) of the API.
Average Request Count
You can view a line graph of the count of API requests. You can further filter the data according to the time range, for example, today, this week, this month, last minutes, last 30 minutes, last 5 years, and so on. Hover the pointer on an point on the axis to view the number of API requests within the time range.
Average Response Time
You can view the average response time of an API using this visualization. This time is in milliseconds. You can filter the data according to a time range.
Publisher APIs: On the Publisher APIs dashboard, you can see the details of each API from a publisher, the number of APIs, the number of publishers, the response times for APIs, and so on.
You can filter the requests and whole dashboard on the publishers.
Hover the pointer on a pie chart or a line chart to view more details.
1 |
Pie-chart for the number of API requests by publishers. |
2 |
The number of API requests by a publisher. |
3 |
The number of API requests. |
4 |
The number of APIs. |
5 |
The number of nodes in a cluster that contains the APIs. |
6 |
The number of publishers. |
Publishers: On the Publishers dashboard, you can see the visualization of the number of API requests, the number of publishers, average data consumption per publisher, and so on.
You can filter the requests and whole dashboard on the publishers.
Hover the pointer on a pie chart or a line chart to view more details.
1 |
Pie-chart for the number of API requests by publishers. |
2 |
The number of nodes in a cluster that contains the APIs. |
3 |
The number of API requests. |
4 |
The unique count of publishers that have made at least one request within the time range. |
5 |
The number of API requests from all publishers. |
6 |
The number of API requests by publishers according to time-range. |
Creating a visualization
You can create your custom visualizations and save it for further analysis. Follow the steps below to create a visualization:
-
To create a visualization, click the Visualize tab.
-
You can create visualizations in the form of area charts, data table, pie charts, and so on, from API information. As an example, create an area chart from the API analytics. Click Area chart from the list.
-
Select from the following:
-
Create a visualization from a new search. Select From a new search. You can see the following index patterns in the drop-down list:
-
Select the data point on the X-Axis and click Apply.
An area chart displays with number of API requests on the Y-axis and API time-stamp on the X-axis.
Filtering data according to time range
In the Analytics page, you can filter the results according to a time range.
There are three ways options:
- Quick
- Relative
- Absolute
-
Click the time filter as shown below:
-
Select any time range from the list, as shown below:
If you select Today, you can see the analytics of all APIs for the last 24 hours.
-
Click Relative. You can filter the data from a specified date and time to the current date and time.
-
Click Absolute. You can filter the results according to dates.
Filtering data according to fields
You can filter the dashboard according to fields and get complete analytic report of an API's activity. When you apply a filter, the dashboard changes accordingly and you can view the graphical results.
To filter dashboard information according to fields:
-
Click any dashboard type:
- Home
- Publisher APIs
- Publishers
-
Choose any dashboard and hover your mouse on the graph to view the field and its values. The snapshot below displays the field values for the request count for all publisher APIs within a particular time:
You can see a table that lists all field values for the API usweather and the number of times the API is called.
-
Click the graph. You can see a new dashboard listing all the attributes of the chosen API.
Organizations
As an Administrator, you can create organizations or tenants in the API Manager. The goal of multitenancy is to maximize resource sharing by allowing multiple users (tenants) to log in and use a single server/cluster at the same time, in a tenant-isolated manner.
To create organizations and manage tenants, refer Multitenancy in API Manager.
API Manager Updates
In the Update section, you can verify and make product updates from the browser-interface itself.
Verify if there are any product updates by clicking update in the left navigation panel of the Administrator console. The updates can include hot fixes and security hot fixes for ColdFusion 2016 API Manager.
Available Updates
Click Check Updates to see if any hotfix updates are available for installation.
You can either:
Download: Downloads and places the file in <api_manager_home>/hf-updates/ for installation at a later time.
Download and Install: Downloads the hot fix and performs a silent installation.
Installed Updates
Lists all hotfix updates to ColdFusion 2016 API Manager that you have installed.
Settings
Provides options to specify update preferences such as update notifications or if to automatically check for updates.
If you have set up a local update site, you can also specify URL of that site to get updates.
Notifications for API Manager Updates
In this release of ColdFusion 2016 API Manager, if there are any updates available, you can see the notifications on the top of the screen when you log in to the Administrator portal.
Click the notifications icon to go to the Updates screen to view all available updates.