- Created by Annegret Bernhardt, last modified by Kirstin Seidel-Gebert on Feb 04, 2019
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 7 Next »
Prerequisites
MultiExcerpt named prerequisites was not found -- Please check the page name and MultiExcerpt name used in the MultiExcerpt-Include macro
Step 1: Download and Extract the Software
API Management uses Docker to provide a simple setup which is easy to update and scalable if necessary.
Make sure you have network access during the installation, because you have to download images from Docker hub.
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>.zipLater 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.
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.Load the Docker images:
MultiExcerpt named load_docker_images was not found -- Please check the page name and MultiExcerpt name used in the MultiExcerpt-Include macro
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\.
.env is a hidden file.
This setup is designed to run on one host only. The SSL KeyStore is shared between all services.
Setting | Description | Default Value |
---|---|---|
BRIDGE_URL | Provide your BRIDGE hostname. | bridge.acme-corp.com |
BRIDGE_PORT | Provide the BRIDGE port. | 8080 |
BRIDGE_USERNAME | Provide the user name to access your BRIDGE. | username |
BRIDGE_PASSWORD | Provide the password to access your BRIDGE. | password |
ELASTICSEARCH_JAVA_MEMORY | Provide the amount of memory that Elasticsearch can allocate. 2 GB for Elasticsearch is the default value. Please refer to the official Elasticsearch documentation for more information on memory usage and how to determine the needs for your setup (see Install Elasticsearch with Docker > Notes for production use and defaults and Setting the heap size). | 2g |
ENDPOINT | Provide the hostname of your API Management HOST. Please note that you cannot use localhost as an endpoint. | api.acme-corp.com |
GATEWAY_PORT | Provide the port to access the published APIs. | 8444 |
KEYCLOAK_ADMIN_USERNAME | Define a Keycloak user. | username |
KEYCLOAK_ADMIN_PASSWORD | Set a password for the Keycloak user. | password |
KEYCLOAK_PORT | Provide the port to access Keycloak. | 8445 |
MYSQL_PASSWORD | Set a password for the Keycloak database connection. | password |
MYSQL_ROOT_PASSWORD | Set a root password for the MySQL installation. | root_password |
SELF_SIGNED | Specify certificate usage.
| false |
TRUSTSTORE_KEYSTORE_PASSWORD | Provide the password of the Java truststore file that contains the certificates. | secret |
UI_PORT | Provide the port to access the API Management user interface. | 8443 |
Step 3: Prepare the Certificate
You need a certificate to establish secure connections between clients and API Management, as well as between the different components of API Management itself. You can use an official certificate, or you can create a self-signed one.
We recommend using an official and valid certificate.
Folder api-mgmt\configs already contains an example structure of the needed files.
Use Official Certificate
To use your official certificate, proceed as follows:
- Copy apiman.jks and the tls files of your certificate (tls.crt and tls.key) to folder api-mgmt\configs (see example structure).
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 .
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).
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.
Generate a keystore with the following command:
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.
Creation of a self-signed certificate with Java Keytoolkeytool -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"
Copy the generated file apiman.jks to folder api-mgmt\configs\.
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:keytool -importkeystore -srckeystore apiman.jks -destkeystore apiman.p12 -deststoretype PKCS12
openssl pkcs12 -in apiman.p12 -nokeys -out tls.crt
openssl pkcs12 -in apiman.p12 -nocerts -nodes -out tls.key
If you have certificates and intermediate certificates, please consult the keycloak documentation Keycloak Docker image > Setting up TLS(SSL).
Step 4: Configure the Authentication Service (Keycloak)
Keycloak is an open source identity and access management solution and is used to create and manage the users of API Management and OAuth2 secured APIs. 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.
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 [...]
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.
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
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/*
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:
Navigate to Clients.
You will have to change the settings for the following clients:
- apiman
- apiman-gateway-api
- apimanui
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.
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.
Stop the Keycloak container by pressing Ctrl-C.
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.
MultiExcerpt named start_all_containers was not found -- Please check the page name and MultiExcerpt name used in the MultiExcerpt-Include macro
Step 6: Login to API Management
Starting all services (previous step) may take some time. If the UI is not available yet, just wait a moment.
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.
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.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.If the gateway configuration is correct, you will get a success message:
If the configuration is invalid, an error message will be shown including further information about the error itself:
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.
- No labels