Prerequisites

Please consider the following prerequisites regarding Scheer PAS API Management.

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-<VERSION>.zip
   api-mgmt-devportal-<VERSION>.tar API Mgmt 7.6.0
   api-mgmt-gateway-<VERSION>.tar
   api-mgmt-keycloak-<VERSION>.tar
   api-mgmt-ui-<VERSION>.tar

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

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:
   

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\.

Step 3: Prepare the Certificate

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.
   Refer to Certificates and Keystores for some hints on certificate handling.

3. Update the following entries in the Docker .env file (see table above for details):

   • Update entry TRUSTSTORE_KEYSTORE_PASSWORD with the store password.

   • Set entry SELF_SIGNED to false.

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

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. Check the folder permissions. Docker should be able to write to the folder and execute programs in the folder (Linux folder permission 300).

2. Generate a keystore. To do this, run the following command from folder api-mgmt/single-host-setup (folder containing the file docker-compose.yml):

   docker-compose run --no-deps --rm --entrypoint '/opt/api-mgmt/create-self-signed-certificates.sh' keycloak

   Some shells (e.g. git bash) have problems with the path so you may have to escape the slashes with backslash like \/opt\/api-mgmt\/create-self-signed-certificates.sh.

3. Copy the following generated files from folder api-mgmt/configs/ self-signed-certificates to folder api-mgmt/configs/:

   • apiman.jks

   • tls.crt
   • tls.key

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):

   docker-compose up keycloak

   Keycloak has been started when the log reads something like

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

2. 

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

   Navigate to Clients. You will have to change the settings for the following clients: apiman apimanui devportal kibana

   Open tab Settings for each of the clients by clicking on the client ID in the list, 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/* For client devportal, e.g. https://api.acme-corp.com:8447/* For client kibana, e.g. https://api.acme-corp.com:8446 /oauth/callback

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

   Setting	Description	Default Value	Since Version
   KEYCLOAK_APIMAN_SECRET	Provide the secret for client apiman generated in Keycloak.	password
   KEYCLOAK_GATEWAY_SECRET	Provide the secret for client apiman-gateway-api generated in Keycloak.	password
   KEYCLOAK_APIMANUI_SECRET	Provide the secret for client apimanui generated in Keycloak.	password
   KEYCLOAK_REALM_PUBLIC_KEY	Provide the realm public key generated in Keycloak.	MIGfMA0GCSqGSIb3DQEBAQU[...]
   KEYCLOAK_KIBANA_SECRET	Provide the secret for client kibana generated in Keycloak.	password	API Mgmt 7.4.0

   Do this as follows:

   	Navigate to Clients. You will have to change the settings for the following clients: apiman apiman-gateway-api apimanui kibana
   	For each client, go to tab Credentials and click Regenerate Secret. In the Docker .env file, set the generated secret for client apiman to entry KEYCLOAK_APIMAN_SECRET. set the generated secret for client apiman-gateway-api to entry KEYCLOAK_GATEWAY_SECRET. set the generated secret for client apimanui to entry KEYCLOAK_APIMANUI_SECRET. set the generated secret for client kibana to entry KEYCLOAK_KIBANA_SECRET.
   	In Realm Settings go to tab Keys. Navigate to tab Providers and delete provider rsa.
   	Next, choose rsa-generated from select box Add keystore.
   	In the upcoming dialog, set Key size to the maximum available value and save your changes.
   	Go back to tab Active and click Public key.
   	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.

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.

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

3. Now start the containers. You can start all containers (including Kibana) or all containers except Kibana.

   Go to folder api-mgmt/single-host-setup (folder that contains the file docker-compose.yml).

   To start all containers except Kibana, use:

   docker-compose up ui gateway

   or

   docker-compose up -d ui gateway

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. Change the admin password to a new one of your choice as demanded on first login.

3. 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, transfer this file now.

   If you want to restore a backup, use the backup file instead of the default configuration (see page API Management Backup and Restore for details).

4. 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.

   

   

   

   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.

Further Configurations

• Advanced Settings
  Please refer to Advanced API Management Settings for an explanation of some additional advanced settings that can be configured for API Management.

• Kibana
  If you want to use Kibana for your reports on API Management metrics, you may want to proceed with Setting-up Kibana.

  However, as Kibana get be setup any time after having installed API Management, we recommend to configure API Management first and record some API data, before using Kibana.