Applications

Overview

The ability of API Gateway to relate a message to a specific application enables it to:

• Control access to an API at run time (that is, allow only authorized applications to invoke an API).

• Monitor an API for violations of a Service-Level Agreement (SLA) for a specified application.

• Indicate the application to which a logged transaction event belongs.

An application has the following attributes for specifying the identifiers:

• IP address, which specifies one or more IP addresses that identify requests from a particular application. Example: 192.168.0.10
  This attribute is queried when the Identify and Authorize Application policy is configured to identify applications using IP address.

• Claims set, which specifies one or more claims that identify requests from a particular application. The claims are a set of name-value pairs that provide sufficient information about the application. Example: sub = Administrator.
  This attribute is queried when the Identify and Authorize Application policy is configured to identify applications using a JWT token or an OpenID token.

• Client certificate, which specifies the X.509 certificates that identify requests from a particular application.
  This attribute is queried when the Identify and Authorize Application policy is configured to identify the applications by a client certificate.

• Identification token, which specifies the host names, user names or other distinguishing strings that identify requests from a particular application.
  This attribute is queried when the Identify and Authorize Application policy is configured to identify applications by host name, token, HTTP user name, and WSS user name.

You can configure various authentication strategies to authenticate an incoming request to the application. You can create multiple strategies authorized by an API for an application. These strategies provide multiple authentication mechanisms or multiple authorization servers for a single authentication scheme. For example, in case of OAuth authentication scheme, you want the application to support both OKTA and PINGFederate or OKTA with multiple tenants. This can be configured as OAuth strategy for the application.

If you have the Manage Application functional privilege assigned, you can create and manage applications, and register applications with the APIs.

These are the high level stages of managing and using an application:

1. API developers request the API Gateway administrators to create an application for access as per the required identification criteria.

2. API Gateway provider or administrator validates the request and creates a new application, there by provisioning the application specific access tokens (API access key and OAuth credentials).

3. API Developer, upon finding a suitable API, sends a request to API Gateway for consumption by providing the application details.

4. After validating the request, API Gateway provider or administrator associates the application with the API. Keys are generated for applications and not for every API that the application consumes.

   Note: The approval process, if any, is handled by the requesting application and not handled by API Gateway.

5. The API developer can then use the application with the proper identifier (such as the access key or identifier) to access the API.

API key expiration date

An API Gateway application has an optional expiration date for its API key. When the API access key expires, the application cannot be identified. The API Gateway Administrator can configure the apiKeyExpirationPeriod parameter from the General > Extended settings page. If the expiration date is not specified, then the API key never expires.

Suspended Applications

You can suspend applications so as to disable the identification of requests temporarily. If a suspended application is identified while processing a request the request is rejected with HTTP 403 (Forbidden) error. The response body has the following content:

Application has been identified but it is currently suspended. Please contact
the  administrator for further details.	

You can resume the suspended applications to enable the identification again.

Creating an Application

You must have the API Gateway’s manage applications functional privilege assigned to perform this task.

To create an application

1. Click Applications in the title navigation bar.

2. Click Create application.

3. Provide the following information in the Basic information section:

   • Name. Type a name for the application.
   • Version. Version of the application. By default it is 1.0 but can be modified to a required value.
   • Team. This field is visible when the enableTeamWork is set to true in the Administration > General > Extended Settings section.Team to which the application must be assigned to. You can select more than one team. To remove a team, click the icon next to the team.
   • Description. Type a description of the application.
   • Requestor comment. This field is visible when Approval configuration for Create application is enabled in the Administration > General > Approval Configuration > Create application section.Type a comment, if required.
     
     

4. Click Continue to Identifiers >.
   Alternatively, you can click Identifiers in the left navigation panel.
   You can save the application by clicking Save at this stage and add the Identifiers and APIs at a later time.

5. Provide the following information in the Identifiers section:

   Field	Description
   IP address range	Provide the IP address range or range of trusted IPv4 or IPv6 addresses that identify requests from a particular application. You can add more range options by clicking +Add and adding the required information.
   Partner identifier	Specifies the third-party partner’s identity.
   Client certificates	Click Browse and select the client certificate or certificate chain to be uploaded. The client certificate specifies the X.509 certificates that requests from a particular application. Note: API Gateway supports .cer and .pem certificates for identifying consumer applications. You can add multiple certificates by clicking +Add
   Claims	Provide a set of claims for the JWT and OpenID clients. A claim is a unique identifying information that identify requests from a particular consumer application. The claim set is identified by a unique Name and is defined as a name-value pair that consists of a Claim name and a Claim value. You can add more claims and claims sets by clicking +Add and adding the required information.
   Header key	Specify the HTTP header key to identify the requests from an application.
   Header value	Specify the HTTP header value to identify the requests from an application. You can add multiple header key and value by clicking +Add.
   Other identifiers	Select one of the options to identify requests from a particular application and provide the required value: Hostname. Specify the host name. Token. The token that is required to identify requests from an application. Username. The username credential to identify requests from an application. WS-Security username. The WSS username to identify requests from an application. Payload identifier. The payload identifier that is required to identify requests from an application.

6. Click Continue to APIs >.
   Alternatively you can click APIs in the left navigation panel.
   You can save the application by clicking Save at this stage and add the APIs at a later time.

7. Type a keyword to find the required API and click + to add the API.
   Adding an API to the application enables the application to access the API. An API developer while invoking the API at runtime, has to provide the access token or identification token for API Gateway to identify the application.

8. Type the required Requestor comment.

9. Click Continue to Advanced >
   Alternatively you can click Advanced in the left navigation panel.
   You can save the application by clicking Save at this stage and add the APIs at a later time.

10. Specify the origin from which the responses originating are allowed during response processing for the application.

11. Click +Add to add the origin.
    You can add multiple origins using .

12. Click Continue to Authentication >
    Alternatively you can click Authentication in the left navigation panel.
    You can save the application by clicking Save at this stage and add the Authentication strategy at a later time.

13. Click Create strategy.
    A strategy is a way to authenticate the incoming request and provides multiple authentication mechanisms or multiple authorization servers for a single authentication scheme. You can create multiple strategies authorized by an API for an application.

14. Select one of the Authentication schemes:

    • OAUTH2. Provide the following information:

      Field	Description
      Name	Provide the name for the strategy.
      Description	Provide a description to describe the strategy.
      Authentication server	Specify the authentication server. The available values are local, which is the default server or any other configured external authorization server.
      Audience	Provide a value or URI, the intended recipient of the authorization server scope. The application that receives the token verifies that the audience value is correct and rejects any tokens intended for a different audience.
      Generate Credentials	Enable the toggle button to generate the client dynamically in the authorization server and provide the following information: Type. Select one of the client types: Confidential. A confidential client is an application that is capable of keeping a client password confidential to the world. This client password is assigned to the client app by the authorization server. This password is used to identify the client to the authorization server, to avoid fraud. An example of a confidential client could be a web app, where no one but the administrator can get access to the server, and see the client password. Public. A public client is an application that is not capable of keeping a client password confidential. For instance, a mobile phone application or a desktop application that has the client password embedded inside it. Such an application could get cracked, and this could reveal the password. The same is true for a JavaScript application running in the users browser. The user could use a JavaScript debugger to look into the application, and see the client password. Application type. Specify the application type. WEB. A web application is an application running on a web server. In reality, a web application typically consists of both a browser part and a server part. The client password could be stored on the server. The password would thus be confidential. USER_AGENT. A user agent application is for instance a JavaScript application running in a browser. The browser is the user agent. A user agent application may be stored on a web server, but the application is only running in the user agent once downloaded. NATIVE. A native application is for instance a desktop application or a mobile phone application. Native applications are typically installed on the users computer or device (phone, tablet etc.). Thus, the client password will be stored on the users computer or device too. Token lifetime. Specify the token lifetime in seconds for which the token is active. Token refresh limit. Specify the number of times you can use the refresh token to get a new access token. Redirect URIs. Specify the URIs that the authorization server can use to redirect the resource owner’s browser during the grant process. You can add multiple URIs by clicking +Add. Grant type. Specify the grant type to be used to generate the credentials. Available options can be authorization_code, passeord, client_credentials, refresh_token, and implicit which are dynamically populated from the authorization server. For example, if the authorization server does not support client credentials, the option is not available in the options list. Scopes. Select the scopes that are to mapped for the authentication strategy. Note: in API Gateway 10.2, the scopes are automatically created when you associate an API to an application. From API Gateway 10.3 onwards you have to select scopes from the authorization server that have to be associated with the strategy.
      Client id	Specify the Client identifier for a client application available in the authorization server that identifies the client application in the authorization server to map the client to the API Gateway application. This is required if you have a client application available in the authorization server and do not want to dynamically create a client.

    • JWT. Provide the following information:

      Field	Description
      Name	Provide the name for the strategy.
      Description	Provide a description to describe the strategy.
      Authentication server	Specify the authentication server. The possible values are local, which is the default server or any other configured external authorization server.
      Audience	Provide a value or URI, the intended recipient of the authorization server scope. The application that receives the token verifies that the audience value is correct and rejects any tokens intended for a different audience.
      HMAC algorithm	Select if the authorization server is returning a JWT with HMAC algorithm and provide the shared secret value to validate the JWT.

    • OPENID. Provide the following information:

      Field	Description
      Name	Provide the name for the strategy.
      Description	Provide a description to describe the strategy.
      Authentication server	Specify the authentication server. The available values are local, which is the default server or any other configured external authorization server.
      Audience	Provide a value or URI, the intended recipient of the authorization server scope. The application that receives the token verifies that the audience value is correct and rejects any tokens intended for a different audience.
      Generate Credentials	Enable the toggle button to generate the credentials required to identify the client application and provide the following information: Type. Select the client type, Public or Confidential. Confidential. A confidential client is an application that is capable of keeping a client password confidential to the world. This client password is assigned to the client app by the authorization server. This password is used to identify the client to the authorization server, to avoid fraud. An example of a confidential client could be a web app, where no one but the administrator can get access to the server, and see the client password. Public. A public client is an application that is not capable of keeping a client password confidential. For instance, a mobile phone application or a desktop application that has the client password embedded inside it. Such an application could get cracked, and this could reveal the password. The same is true for a JavaScript application running in the users browser. The user could use a JavaScript debugger to look into the application, and see the client password. Application type. Specify the application type. WEB. A web application is an application running on a web server. In reality, a web application typically consists of both a browser part and a server part. The client password could be stored on the server. The password would thus be confidential. USER_AGENT. A user agent application is for instance a JavaScript application running in a browser. The browser is the user agent. A user agent application may be stored on a web server, but the application is only running in the user agent once downloaded. NATIVE. A native application is for instance a desktop application or a mobile phone application. Native applications are typically installed on the users computer or device (phone, tablet etc.). Thus, the client password will be stored on the users computer or device too. Token lifetime. Specify the token lifetime in seconds for which the token is active. Token refresh limit. Specify the time in seconds for which the token refresh is applicable. Redirect URIs. Specify the URIs that the authorization server can use to redirect the resource owner’s browser during the grant process. You can add multiple URIs by clicking +Add. Grant type. Specify the grant type to be used to generate the credentials. Available options are Authorization code, Implicit, Resource owner, Client credentials. Scopes. Select the scopes that are to be associated to the generated client. Note: in API Gateway 10.2, the scopes are automatically created when you associate an API to an application. From API Gateway 10.3 onwards you have to select scopes from the authorization server that have to be associated with the strategy.
      Client id	Specify the Client identifier that identifies the client application in the authorization server to map the client to the API Gateway application. This is required if you do not choose to generate credentials to identify the client application.

15. Click Add.
    The strategy is configured and listed in the Strategies table.

    Note: API Gateway allows you to generate a new Client ID and Client Secret for an existing strategy. However, once the credentials are generated for a strategy, it can no longer be removed. The Generate credentials toggle is disabled in the UI when you update a strategy.

16. Click Save.
    The application is created and listed in the list of applications in the Manage applications page, once approved.

Viewing List of Applications and Subscriptions

You can view the list of applications in the Manage applications page from where you can create, delete, and select an application to view its details.

To view the application list and application and subscription details

1. Click Applications in the title navigation bar.
   A list of all registered applications and subscriptions appear.

   • denotes application.
   • denotes subscription.
   
   

2. Select an application.
   
   The application details page displays the following information: basic information that contains details such as name, description, owner, and creation time, identifiers, access tokens, APIs registered for the application, advanced configurations, and authentication strategies configured for the application.

   Application credentials, such as, API Keys or OAuth client secrets are visible only to the application owner. All other users can only see an encrypted value. Since API Portal and API Gateway do not support a central user management, API Gateway users cannot see the application credentials of the application requested through API Portal.

3. Select a subscription.
   
   You can view the applications and the associated package, plan, used quota, start time, end time, and the remaining period of the subscription.

   Note: You cannot create a subscription from this page. To create a subscription, use the subscription API. For details about creating subscriptions using a REST API, see Subscription Management. You can also create a subscription from the API Portal.

Regenerating API Access Key

You must have the API Gateway’s Manage applications functional privilege assigned to perform this task.

You can regenerate an API access key in the application details page from where you can view application details.

To regenerate an API key

1. Click Applications in the title navigation bar.
   A list of all registered applications is displayed.

2. Select an application.
   The application details page displays the basic information, identifiers, access tokens, API key, APIs registered and strategies configured for that application.

3. Click .
   The API access key is regenerated and the new API access key appears in the API access key field.

Modifying Application Details

You can modify the details of an application as required from the application details page.

To modify application details

1. Click Applications in the title navigation bar.
   A list of registered applications is displayed.

2. Select an application.

3. Click Edit in the application details page.

4. Modify the required fields in the Basic information section.

5. Click Identifiers.

6. Modify the required fields in the Identifiers section.

7. Click APIs.

8. Add or delete the APIs that are registered.

9. Modify the strategies or create a new strategy.

10. Modify the required values.

11. Click Save.

Registering an API with Consumer Applications from API Details Page

Consumer applications created in API Gateway can be associated with APIs from the API details page.

To register APIs with consumer applications

1. Click APIs in the title navigation bar.
   A list of APIs is displayed.

2. Select an API.

3. Click Edit in the API details page.

4. Click Application tab in the API details page.

5. Type characters in the search field and click the Search icon.
   This field displays the only list of applications that are assigned to the teams that you are a part of.

6. Select the required applications and click +.
   You can add more applications in a similar way.

7. Click Save.

Registering APIs with Consumer Applications from Application Details Page

Consumer applications created in API Gateway can be associated with the APIs from the application details page.

To register APIs with consumer applications

1. Click Applications in the title navigation bar.
   A list of registered applications is displayed.

2. Select an application.

3. Click Edit in the application details page.

4. Click APIs in the left navigation panel.

5. Type characters in the search field and click the Search icon.
   This field displays the only list of applications that are assigned to the teams that you are a part of.

6. Select the required API and click +.
   You can add more APIs in a similar way.

7. Click Save.

Suspending an Application

You must have the API Gateway’s Manage applications functional privilege assigned or you must be the owner of the application to perform this task.

To suspend an application

1. Click Applications in the title navigation bar.
   A list of all the available applications are displayed.

2. Click the toggle button (Active state), in the action column for the respective application, to suspend the application.
   Alternatively, you can click Suspend in the application details page.

3. Click Yes in the confirmation dialog box.
   The application is suspended. The toggle button in the Applications page changes to (suspended state) and the option in the application details page changes to Suspend.

Activating a Suspended Application

You must have the API Gateway’s Manage applications functional privilege assigned or you must be the owner of the application to perform this task.

You can activate a suspended application, from the application details page.

To activate a suspended application

1. Click Applications in the title navigation bar.
   A list of all the available applications are displayed.

2. Click the toggle button (suspended state), in the action column for the respective application, to activate the application.
   Alternatively, you can click Activate in the application details page.

3. Click Yes in the confirmation dialog box.
   The application resumes. The toggle button in the Applications page changes to (active state) and the option in the application details page changes to Suspend.