Skip to content

API Management

OAuth and OpenId Overview

Peregrine Management Suite implements security using Identity Server 4 by default (You have option to use Azure Active Directory also). The Management Suite extends the Identity Server 4 for use by Neuron Applications. Client Connectors in Neuron applications can have authentication and authorization enabled using the API management functionality.

When configured this way, a calling application or user that accesses the configured client connector, it will have to obtain and attach a token to the request. This token will be validated at runtime by Neuron ESB platform to allow or deny requests depending on the values of Scope item in it. The content of the token can be used to further control what functionality of client connector is available to which consumer application using Scopes.

To get started with API Management, you must create at-least one API resource per application and include the client connectors in that application under this API resource. API Resource can simply be defined as a group of Client Connectors that share the same values for Scope.

To grant access to the API resource, you must create a consumer application for the API resource and assign a consumer Id and consumer secret. Alternatively, if you have added your consumers as Management Suite users or you are using Azure Active Directory and have added your consumers as Management Suite users, then the consumer users can use the same token they obtained to log in to Management Suite. The first method is called Client Credentials grant type and the second method is called PKCE or Hybrid Grant Type.

For more details on OAuth and OpenId refer to the whitepaper, “Securing Client Connectors with OAuth”.

Also, for developers refer to “Client OAuth Provider Setup Documentation”.

Client Connectors and API Resources

API resources can be defined using the menu option API management.

Start by selecting the API button on top bar and selecting the desired application in the application dropdown. Then click the + icon in the top right corner as shown below. You have option to switch between card view and list view by selecting the appropriate option to the left of search.

This launches a wizard and that will step through the process of setting up API resource. You need to add some client connectors, scopes and consumers to the API resource. If you have not created a consumer for the API resource, you may add consumers later.

In the first tab, select the application that has the client connectors. After that you create the API Name, Description and the API secret value. The API secret value is used by Neuron ESB internally to validate the tokens presented to it. You select the client connectors you want to include in this API by dragging and dropping them to the right.

Figure 1: API Management – Card View
Figure 2: Create API Wizard – Connectors
Figure 3: Create API Wizard – Scopes

In the scopes tab, enter the name and description of the scope to be added, the checkboxes for Required, Emphasize, Discovery indicate whether the scope is a required value in the token, whether it should be emphasized when prompting user for permission and whether the scope should appear in the discovery document for the identity server.

You can add multiple scopes to the API.

User claims are applicable when the consumer grant type is Hybrid or PKCE. This indicates that the token presented by the consumer application user will make the email, name or id information available to the Neuron Client Connector. You may also enter your own value in User Claims. This value will then be included in all the user tokens issued by Identity Server 4.

In the last tab, you may assign one of the existing consumers to the API resource. If you haven’t created consumer yet, you can finish and assign the consumer later after you have created the consumer.

In the following screen, you can see that there are no applicable consumers. You can finish creating the API and come back to this after you have created a consumer. You can then assign the consumer to the API as shown in the screen following the next one.

Figure 4: Create API Wizard – Consumers
Figure 5: Create API wizard – Consumers, cont.

In the above screen, you can drag and drop consumer from left hand side into the selected consumers on the right-hand side to assign the API to the consumer.

Consumer Applications

Consumer application means the application that will call the Neuron Client Connector. Consumer application can have different grant type. For a consumer application that has a backend server like ASP.NET, the grant type client credential is most common. If you need to pass specific user information, then a grant type of Hybrid or PKCE is more appropriate.

For creating a consumer, generally the consumer name, description, id, api resource and consumer secret needs to be added. API to which consumers can have access can be added from API box below by clicking the plus sign. Similarly, consumer secret can also be added. Note that you can assign consumers to API from the API screen also.

Additional properties and URIs/CORS are applicable with Hybrid or PKCE grant type. For more details on these, consult Identity Server documentation.

Figure 6: Consumer Application Detailed View

Click the plus sign under API to add access for another API.

Figure 7: Consumer Application Card View
Figure 8: Adding API Resource

Click the plus sign under consumer secret to add another consumer secret. Consumer secret should be noted by the consumers and stored in a safe way because there is no way to retrieve existing consumer secret.

Figure 9: Adding Consumer Secret

In the consumer screen, other fields that require more explanation are listed in the table below. These fields are applicable when the grant type is Hybrid or PKCE. Developers of consumer application should specify these values. This is because they control how the authorization service responds to their application requests for token and token validations. The information about these fields is taken from Identity Server Documentation.

Name Purpose Applies To
Redirect URIs URL that specifies where to redirect the user after successful authentication All Grant Types
Post Logout URIs URL that specifies where to redirect the user after logout is completed All Grant Types
CORS origin URLs from which the token endpoint can be invoked. When using Javascript clients from URLs of a domain other than that of Authorization service can result in errors unless those URLs are listed under this section. Hybrid and PKCE grant types with javascript clients
Enabled Unless the consumer is enabled, token validation will not succeed. All types
Required Client Secret

This option should always be check unless you want the consumer application to get token without needing a secret. Can be used if the consumer application is trusted. It is essentially treating the consumer application Id as the password.

Client Credentials grant type
Allow remember consent In the Hybrid flow and PKCE flow, the authorization endpoint remembers the consent when this flag is set. Consent of the user is requested when the flow is invoked for the first time. It prompts the user to the effect that application x wants to access your email, id and other information, do you want to allow it.? If consent is remembered, then it doesn’t prompt for the same to user every time. Hybrid and PKCE flow.
Include Jwt Id Includes a unique id in the token. Applies to all types. Caching of tokens depends on it, so it should be checked to keep the token cached for the specified duration.
Require Consent Prompts the user for consent when the application requests for user token first time. Hybrid and PKCE grant types
Front channel logout session required Specifies if the user’s session id should be sent to the FrontChannelLogoutUri. Defaults to true. All Grant types.
Allow include user claims in Id Token When requesting both an id token and access token, should the user claims always be added to the id token instead of requiring the client to use the userinfo endpoint. Default is false. Hybrid and PKCE grant types
Update access token claims on refresh Gets or sets a value indicating whether the access token (and its claims) should be updated on a refresh token request. All grant types
Back channel logout session required Specifies if the user’s session id should be sent in the request to the BackChannelLogoutUri. Defaults to true. All grant types.
Allow offline access Specifies whether this client can request refresh tokens (be requesting the offline_access scope) All grant types
Enable local login Specifies if this client can use local accounts, or external IdPs only. Defaults to true. All grant types
Allow access tokens via browser Specifies whether this client is allowed to receive access tokens via the browser. This is useful to harden flows that allow multiple response types (e.g. by disallowing a hybrid flow client that is supposed to use code id_token to add the token response type and thus leaking the token to the browser. Hybrid flow
Allow plain text pkce Specifies whether clients using PKCE can use a plain text code challenge (not recommended – and default to false) PKCE flow
Always send client claims If set, the client claims will be sent for every flow. If not, only for client credentials flow (default is false) All grant types. This should be set to true if using Hybrid and PKCE flow and you need to cache tokens.
Protocol Type This cannot be changed. It is only there for information All Grant types
Client URI URI to further information about client (used on consent screen) Hybrid and PKCE
Logo URI URI to client logo (used on consent screen) Hybrid and PKCE
Front channel logout URI Specifies logout URI at client for HTTP based front-channel logout. See the OIDC Front-Channel spec for more details. Hybrid and PKCE
Back channel logout URI Specifies logout URI at client for HTTP based back-channel logout. See the OIDC Back-Channel spec for more details. All grant types
Identity token life Lifetime to identity token in seconds (defaults to 300 seconds / 5 minutes) Hybrid and PKCE
Access token life Lifetime of access token in seconds (defaults to 3600 seconds / 1 hour) All grant types
Authorization code life Lifetime of authorization code in seconds (defaults to 300 seconds / 5 minutes) All grant types
Consent life Lifetime of a user consent in seconds. Defaults to null (no expiration). Hybrid and PKCE
Absolute refresh token life Maximum lifetime of a refresh token in seconds. Defaults to 2592000 seconds / 30 days All grant types
Sliding refresh token life Sliding lifetime of a refresh token in seconds. Defaults to 1296000 seconds / 15 days All grant types
Validation Cache Duration This is a custom claim used to cache tokens in Neuron ESB. Its value is in minutes. Caching tokens is done to reduce latency by not validating the cached token everytime. All grant types
Device code life This is for future use. Currently we do not support Device code Grant type Device code grant type
User code type This is for future use. Currently we do not support Device Code Grant type. Specifies the type of user code to use for the client. Otherwise falls back to default. Device code grant type
Pair wise subject salt   
Refresh Token Expiration Absolute or Relative the refresh token will expire on a fixed point in time (specified by the AbsoluteRefreshTokenLifetime) otherwise as per sliding refresh token lifetime All grant types
Access Token Type Specifies whether the access token is a reference token or a self contained JWT token (defaults to Jwt). All grant types

If reference token, then validation method will be introspection and that increases latency

Refresh Token Usage ReUse the refresh token handle will stay the same when refreshing tokens

OneTime the refresh token handle will be updated when refreshing tokens. This is the default.

All grant types
User Sso Life time The maximum duration (in seconds) since the last time the user authenticated. Defaults to null. You can adjust the lifetime of a session token to control when and how often a user is required to reenter credentials instead of being silently authenticated, when using a web application. Hybrid and PKCE
Client claims prefix Cannot change this setting. It is used by Neuron ESB for some internal process All Grant Types
Created Internal use for auditing All Grant types
Updated Internal use for auditing All Grant types
Last accessed Internal use for auditing All Grant types

Note that by default all scopes in the API are assigned to the consumer when you add the wizard interface to assign Consumer to API or API to consumer, but you can change the consumer and API scope assignments from either the API screen or Consumer screen. When an API has three different available scopes and consumer has been assigned only two of them, the two scopes will be included in the consumer token. This mechanism can be used to enforce selective access to client connector functionality based on scope.

Following screens show how you can assign selective scopes.

Figure 10: Scope Assignments

In the above screen Click the + sign in the Consumer box shown, to add consumer to API, when the following pop-up appears, click assign, you can then check or uncheck scope boxes that you need assigned and then click save. If consumer is already assigned and you are not sure, delete the consumer and re-add to reassign the scopes as needed.

Figure 11: Add Consumer

Similarly, when you are in Consumer view, you can remove and add API assignments with selected scopes. In this case you click the + button next to API box in the below screen. Also note that the add consumer to API or add API to consumer button also functions for editing the scope assignments. You can change scopes of existing assignments using the same pop-up that is shown when you use this option.

Figure 12: Consumers – Add/Remove API Assignments
Figure 13: Add API Resource

API Monitoring

API management adds a nice capability to monitor number of requests, successes and failures by API or Consumer. In addition to overall application monitoring, this capability provides a window into how individual consumer applications and API resources are utilized and whether they are running successfully or not.

You can see the rate of requests, success and failure on the API or Consumer page card view in the first tab below.

Figure 14: Consumer Card View
Figure 15: Endpoint Card View

Alternate views of API Management (List view and Carousel view) show the same data in a more expanded format.

List view

Figure 16: List View

Carousel view

Figure 17: Carousel View
Was this article helpful?
Dislike 0