Versions Compared

Old Version 31

changes.mady.by.user Annegret Bernhardt

Saved on

compared with

New Version 32

changes.mady.by.user Annegret Bernhardt

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: page format changed

api_contracts_and_keys

Info
titleUsed on:


Multiexcerpt
MultiExcerptNameapi_contracts_and_keys

Only public APIs can be accessed by any consumer. The only way for a client to consume a private API is by using an API contract. An API contract is a link between a client and an API through a plan offered by that API.

API contracts can only be created between clients and published APIs which are offered through at least one plan. An API contract cannot be created between a client and a public API.

When a client version is created, the system generates a unique API Key. This key is unique per client version and the same for all contracts of this version. All requests made to the API by a client through the gateway must include this API Key to identify the used client version.

Info

You can forward the X-API-Key to the service using the API Key policy. However, you cannot define your own value for the X-API-Key, since the gateway uses the key to identify the clients.

However, the API Key is not a security feature! API Keys are not encrypted and visible:

  • in the request header,
  • to people who have access to API Management metrics/the Log Analyzer,
  • in the logs of the integration component (Bridge) if you are using theAPI Key policy.

So, API Keys need to be handled in a secure way - otherwise attackers may be able to use the API Key to gain access to your system.

Note

As per definition, API Keys are used to identify technical clients only and, subsequently, to apply related policies. Do not use API Keys to authenticate users.

Authentication should always be implemented via a dedicated security policy (refer to Policy Configuration > Security Policies and API Security: Authentication and Authorization).


unable_to_render_definition

Info
titleUsed on:


Multiexcerpt
MultiExcerptNameunable_to_render_definition


Note

Please note that the autosave is not triggered after the upload of an invalid file.
If the definition content shows the message Unable to render this definition, your changes are not saved but discarded if you leave the page.

Image Modified


keycloak_tokens_get_secret

Info
titleUsed on:


Multiexcerpt
MultiExcerptNamekeycloak_tokens_get_secret

To retrieve a Keycloak token, you need to know the secret of the used client.

Image Modified

Open the Identity Managament (Keycloak).

Info

If your user has no permission for the identity management, contact an administrator and ask him to provide the secret.


Image Modified

You will find the secret of the client in the PAS realm:

Clients > Credentials > Client Authenticator: Client Id and Secret > Client secret

Info

If field Client secret does not contain any content, click Regenerate once.



keycloak_tokens_retrieve_token

Info
titleUsed on:


Multiexcerpt
MultiExcerptNamekeycloak_tokens_retrieve_token

The token exchange in Keycloak is a very loose implementation of the IETF's OAuth Token Exchange specification. It is a simple grant call on the OpenID Connect token endpoint of a realm. It accepts form parameters (application/x-www-form-urlencoded) as input. The output depends on the type of token for which you requested an exchange. The token exchange is a client endpoint, so requests must include authentication information for the calling client.

The client_secret parameter is required for clients that use form parameters for authentication and use a client secret as credentials. A list of all form parameters can be found in the official Keycloak documentation > Form parameters.

The token URL is composed as follows:

  • https://<system name>/<client name>/keycloak/realms/<realm name>/ protocol/openid-connect/token

Example:

Send your request to the token URL.

Example:

Code Block
titleExample Request
curl --location 'https://scheer-acme.com/acme-test/keycloak/realms/PAS/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=<username>' \
--data-urlencode 'password=<password>' \
--data-urlencode 'client_id=api-management-oauth' \
--data-urlencode 'client_secret=<client-secret>' \
--data-urlencode 'grant_type=password'

A successful response from an exchange call returns the HTTP 200 response code with a content type that depends on the requested-token-type and requested_issuer. Clients requesting a refresh token receive both an access token and refresh token back in the response. Clients requesting only an access token receive only an access token in the response.

Expand
titleClick here to view an example response


Code Block
titleExample Response
{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
    "expires_in": 300,
    "refresh_expires_in": 7200,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "f5dd0490-aaf8-42f7-87b5-df0c7b1cb4a7",
    "scope": "email profile pas_user"
}



Tip
titleExpert Advice

For detailed information about the token exchange, refer to the official Keycloak documentation > Using token exchange.


policy_overview

Info
titleUsed on:


Multiexcerpt
MultiExcerptNamepolicy_overview


Security Policies

Policy SymbolPolicy NameDescription
Image Modified
 BASIC Authentication Enables HTTP BASIC Authentication on an API. Use this policy to require clients to provide HTTP BASIC authentication credentials when making requests to the managed API.
Image Modified
 CORS Use this policy to enable and configure Cross Origin Resource Sharing on an API. This allows to access resources outside the originating domain.
Image Modified
 Authorization Allows to add a list of fine-grained authorization rules. Use this policy to control precisely who is allowed to access the API.
Image Modified
 Header Allow/DenyAllows you to control which incoming requests may be forwarded to the backend service. Permission is granted by adding values for a header.
Image Modified
 HTTP SecurityEnforces transport security when using HTTP to mitigate a range of common web vulnerabilities. Contains also a sophisticated mechanism to precisely define the types and sources of content that may be loaded, with violation reporting and the ability to restrict the availability and scope of many security-sensitive features.
Image Modified
 Ignored Resources Enables the user to shield some API’s resources from being accessed, without blocking access to all the API’s resources. Requests made to API resources designated as ignored result in an HTTP 404 (not found ) error code. This policy allows fine-grained control over which of an API’s resources are accessible.
Image Modified
 IP Allowlist

This policy allows access to an API’s resource based on the IP address of the client. The user must specify the IP address ranges to be included from being able to access the API. Any addresses that are not explicitly allowed are not able to access the API. It is possible to use wildcard characters to specify the allowed IP addresses. It is also possible to define the return error code sent in the response to the client in case a request fails due to the violation of this policy.

Image Modified
 IP Blocklist

This policy blocks access to an API’s resource based on the IP address of the client. The user must specify the IP address ranges to be excluded from being able to access the API. Any addresses that are not explicitly excluded are able to access the API. It is possible to use wildcard characters to specify the IP addresses to be blocked. It is also possible to define the return error code sent in the response to the client in case a request fails due to the violation of this policy.

Note
An IP Blocklist policy overrides an IP Allowlist policy.


Image Modified
 JWT
This policy can set headers as claim values or whole access token. It's main purpose is the validation of JWT tokens for authentication.
Image Modified
 Keycloak OAuth

This Keycloak-specific OAuth2 policy regulates access to APIs. It enables a wide range of sophisticated auth facilities in combination with, for instance, Keycloak’s federation, brokering and user management capabilities. Keycloak’s token format and auth mechanism facilitate excellent performance characteristics, with users able to easily tune the setup to meet their security requirements.

Tip

In general, this is one of the best approaches for achieving security without greatly impacting performance. Refer to API Security: Authentication and Authorization for more detailed information.


Image Modified
 SOAP Authorization

Nearly identical to the Authorization Policy with the exception that it accepts a SOAP action in the HTTP header.

Note

This policy will only accept a single SOAP action header. It will not extract the operation name from the SOAP body.


Image Modified
 Time Restricted Access Manages a list of API routes that can be accessed at specific time and date. This policy allows to control when client and users are allowed to access your API.

Limiting Policies

Image Modified
 Rate Limiting Governs the number of times requests are made to an API within a specified time period. The requests can be filtered by user, client or API and can set the level of granularity for the time period to second, minute, hour, day, month, or year. The intended use of this policy type is for fine grained processing.
Image Modified
 Transfer Quota Tracks the number of bytes transferred. Enables the user to set a transfer quota (data) in B, KB, MB or GB for upload, download or both per client, user or API in a definable period of time. The response header can also be freely defined. The intended use of this policy type is for fine grained processing.

Modification Policies

Image Modified
 JSONP

Turns a standard REST endpoint into a JSONP compatible endpoint. The caller must provide a JSONP callback function name via the URL.

Note

If the API client does not send the JSONP callback function name in the URL, this policy will do nothing. This allows managed endpoints to support both standard REST and JSONP at the same time.


Image Modified
 Simple Header Headers can be set and removed on request, response or both. The values can be literal strings, environment or system properties. Headers can be removed by simple string equality or regular expression.
Image Modified
 URL Rewriting With this policy, URLs in the request URL, the request header, the response body or the response header can be changed during a request.

Other Policies

Image Modified
 API Key Passes the API Key through to the back-end service by adding it to a customizable HTTP header.
Image Modified
 Caching Resources With this policy it is possible to cache requests based on their URL path, HTTP method and HTTP status code. This allows reducing overall traffic to the backend API.
Image Modified
 Timeout Allows you to determine timeouts for your API. You can differentiate between a timeout for the initial connection and a timeout for the entire request.





Panel
titleOn this Page:
Table of Contents