Prerequisites

Step 1: Download and Extract the Software

1. Download the following files provided by Scheer to the folder you want to install API Management to:

   api-mgmt-gateway-<VERSION>.tar
   api-mgmt-ui-<VERSION>.tar
   api-mgmt-keycloak-<VERSION>.tar
   api-mgmt-<VERSION>.zip

   Tip
   Later on, in step 6, you will need file apiman-default-config.json from the api-mgmt-<VERSION>.zip on an API Management client. You can copy the ZIP file to your client now (or later), or download the needed file from this page in step 6.

2. Extract api-mgmt-<VERSION>.zip.
   Extracting this file will create a folder api-mgmt which is required permanently. It contains configuration files with sensitive data such as passwords, so access to this folder should be restricted. The Docker container however must be able to read the data.

3. Load the Docker images:
   

   Multiexcerpt include
   MultiExcerptName load_docker_images PageWithExcerpt INTERNAL:_api_excerpts

Anchor
installation_settings installation_settings

Step 2: Configure the Installation Settings

Configure the installation settings in the Docker .env file as described below. This file resides in folder api-mgmt\single-host-setup\.

BRIDGE_URL

bridge.acme-corp.com

BRIDGE_USERNAME

username

BRIDGE_PASSWORD

password

ELASTICSEARCH_JAVA_MEMORY
              

ENDPOINT
              

api.acme-corp.com

GATEWAY_PORT

8444

username

password

KEYCLOAK_PORT

8445

MYSQL_PASSWORD

password

MYSQL_ROOT_PASSWORD

root_password

SELF_SIGNED

false

TRUSTSTORE_KEYSTORE_PASSWORD

secret

UI_PORT

8443

Anchor
certificate certificate

Step 3: Prepare the Certificate

Overview on the Docker Setup of API Management

Have a look at the figure below to get a technical overview on the Docker setup of Scheer PAS API Management.

Image Removed

Overview on the Installation Containers

Overview on the Installation Process

To install the Scheer PAS API Management, you need to got through the following steps:

Use Official Certificate

To use your official certificate, proceed as follows:

1. Copy apiman.jks and the tls files of your certificate (tls.crt and tls.key) to folder api-mgmt\configs (see example structure).

2. Create a Java keystore which includes the certificate. The keystore must be secured by a store password. Assign the name apiman.jks to the keystore file .

3. Exchange entry TRUSTSTORE_KEYSTORE_PASSWORD in the Docker .env file with the store password, see table above for details.

If you have certificates and intermediate certificates, please consult the keycloak documentation Keycloak Docker image > Setting up TLS(SSL).

Anchor
certificate_self-signed certificate_self-signed

Use Self-Signed Certificate

If you do not possess a valid certificate, you can create a self-signed one. You can use Java Keytool to do this.

1. Generate a keystore with the following command:

   Note
   Please note: Please replace secret, api.acme-corp.com, ACME-Development and ACME in the command as these are example settings only. The passwords must have at least 6 characters each.

   Code Block
   title Creation of a self-signed certificate with Java Keytool
   keytool -genkeypair \ -keyalg RSA \ -validity 365 \ -keysize 4096 \ -alias apimancert \ -keystore ./apiman.jks \ -storepass "secret" \ -keypass "secret" \ -dname "CN=api.acme-corp.com, OU=ACME-Development, O=ACME"

2. Copy the generated file apiman.jks to folder api-mgmt\configs\.

3. Export key and crt from the self generated keystore.

   Keycloak will generate his own keystore automatically at startup. Therefore we have to move the certificate and the corresponding key out of our generated keystore.
   Perfom the following commands in folder configs:

   Code Block
   keytool -importkeystore -srckeystore apiman.jks -destkeystore apiman.p12 -deststoretype PKCS12

   Code Block
   openssl pkcs12 -in apiman.p12 -nokeys -out tls.crt

   Code Block
   openssl pkcs12 -in apiman.p12 -nocerts -nodes -out tls.

   Start

   key

If you have certificates and intermediate certificates, please consult the keycloak documentation Keycloak Docker image > Setting up TLS(SSL).

Anchor
keycloak keycloak

Step 4: Configure the Authentication Service (Keycloak)

Before you can start the Docker containers, you need to change some of the Keycloak settings in the Docker configuration file .env . The values you need to replace the default values with, are to be obtained from your Keycloak instance.

1. Start Keycloak. To do this, run the following command from folder api-mgmt/single-host-setup (folder containing the file docker-compose.yml):

   Code Block
   docker-compose up keycloak

   Keycloak has been started when the log reads something like

   Code Block
   [...] Keycloak 7.3.0 (WildFly Core 6.0.2.Final) started in 50476ms - Started 673 of 933 services [...]

2. Open your Keycloak URL, e.g. https://api.acme-corp.com:8445/auth/admin, and login to the administration console. To login, use username and password as configured in the .env file.

3. Change the Valid Redirect URIs of the below listed clients.

   Image Added	Navigate to Clients. You will have to change the settings for the following clients: apiman apimanui
   Image Added	Open tab Settings for each of the two clients and change the entry in field Valid Redirect URIs to match your setup: For client apiman, e.g. https://api.acme-corp.com:8443/apiman/* For client apimanui, e.g. https://api.acme-corp.com:8443/apimanui/*

4. Now, change all default credentials for clients apiman, apimanui and apiman-gateway-api and copy the new passwords to the Docker configuration file.

   Setting	Description	Default Value
   KEYCLOAK_APIMAN_SECRET	Provide the password for client apiman generated in Keycloak.	password
   KEYCLOAK_GATEWAY_SECRET	Provide the password for client apiman-gateway-api generated in Keycloak.	password
   KEYCLOAK_APIMANUI_SECRET	Provide the password for client apiman_ui generated in Keycloak.	password
   KEYCLOAK_REALM_PUBLIC_KEY	Provide the realm public key generated in Keycloak.	MIGfMA0GCSqGSIb3DQEBAQU[...]

   Do this as follows:

   Image Added	Navigate to Clients. You will have to change the settings for the following clients: apiman apiman-gateway-api apimanui
   Image Added	For each client, go to tab Credentials and click Regenerate Secret. Set the generated secret for client apiman to entry KEYCLOAK_APIMAN_SECRET in the Docker .env file. Set the generated secret for client apiman-gateway-api to entry KEYCLOAK_GATEWAY_SECRET in the Docker .env file. Set the generated secret for client apimanui to entry KEYCLOAK_APIMANUI_SECRET in the Docker .env file.
   Image Added	In Realm Settings go to tab Keys. Navigate to tab Providers and delete provider rsa.
   Image Added	Next, choose rsa-generated from select box Add keystore.
   Image Added	In the upcoming dialog, set Key size to the maximum available value and save your changes.
   Image Added	Go back to tab Active and click Public key.
   Image Added	The key will be displayed in a separate pop-up window. Copy the key and paste it to variable KEYCLOAK_REALM-PUBLIC_KEY in the Docker .env file.

Anchor
start start

Step 5: Start All Services

All Keycloak-related settings have been configured now, and you need to stop docker-compose and restart all containers.

1. Stop the Keycloak container by pressing Ctrl-C.

2. Check the configuration, if necessary.

   Tip
   You can check, if everything has been configured, with Code Block docker-compose config This command will list the Docker configuration and will throw warnings, if something is still missing.

3. Multiexcerpt include
   MultiExcerptName start_all_containers PageWithExcerpt INTERNAL:_api_excerpts

   
   

Anchor
login login

Step 6: Login to API Management

1. Open the URL of your API Management, e.g. https://api.acme-corp.com:8443 and log in with the standard administration user, which is admin/admin.

2. Upload the initial configuration of API Management.
   To do this, go to Administration > Export/Import and import file api-mgmt/configs/bootstrap/apiman-default-config.json from api-mgmt-<VERSION>.zip. If you did not transfer the file to your client in step1, you can download the file here.

3. Test the connection between UI and gateway.
   To do this, go to Administration > Manage Gateways and click on the name of the gateway. Then, click Test Gateway.

   Image Added

   Multiexcerpt include
   MultiExcerptName test_gateway_ok PageWithExcerpt INTERNAL:_api_excerpts

   Multiexcerpt include
   MultiExcerptName test_gateway_nok PageWithExcerpt INTERNAL:_api_excerpts

   Note
   A technical user (gateway/gateway) connects the UI of API Management with the gateway. It is highly recommended to change the default passwords for both, the admin user and the gateway user. Both passwords can be changed in Keycloak.