Page tree
Skip to end of metadata
Go to start of metadata

Prerequisites

(tick)Ensure AIP Console and all Docker containers are up and running.
(tick)Ensure at least one AIP Node instance has been installed and is up and running.

Step 1 - Initial login to Keycloak and configure a redirect

The AIP Console authentication provider has been totally restructured and now uses the open-source OAuth2 compatible Keycloak system. Keycloak provides local authentication, and can also interact with other enterprise authentication systems such as LDAP and SAML. Before you start using AIP Console, you should configure a redirect in Keycloak to allow access to Keycloak using the AIP Console host name or IP address in addition to localhost (which is pre-configured). If you do not, users will not be able to login to AIP Console correctly. To do so, connect to Keycloak from the AIP Console machine:

http://localhost:8086/

Click the Administration Console option:

The default login credentials specified in the docker-compose.yml file are admin/admin - use these unless you have modified them as described in AIP Console - 2.x - Install process:

These credentials are specific to Keycloak and not AIP Console. You can change the default password if required, post installation, using the following URL:

http://localhost:8086/auth/realms/master/account/#/security/signingin

Now click the Clients option and then click aip-console-client:

Click to enlarge

Now add a new redirect:

You should a redirect for each URL you want AIP Console to be accessible on. For example:

  • http://<aip_console_server_hostname>:8081/*
  • http://<aip_console_server_IP_address>:8081/*

Ensure you save the changes:

Step 2 - configure authentication using Keycloak

Before you start using AIP Console, you will need to configure your authentication method. To do so, connect to Keycloak:

http://<aip_console_server>:8086/

Click the Administration Console option:

The default login credentials specified in the docker-compose.yml file are admin/admin - use these unless you have modified them as described in AIP Console - 2.x - Install process:

These credentials are specific to Keycloak and not AIP Console. You can change the default password if required, post installation, using the following URL:

http://192.168.200.19:8086/auth/realms/master/account/#/security/signingin

When logged in, you now have a choice depending on your how you want to authenticate:

Local authentication managed by Keycloak

To use the simple authentication mechanism provided by Keycloak, first create a new admin user for AIP Console:

Click to enlarge

Now click the Credentials tab and set a password for your new admin user:

Click to enlarge

Now click the Role Mappings tab to assign the pre-prepared admin role to the user (this will grant the global AIP Console admin role to the user):

Click to enlarge

LDAP authentication

To authenticate in AIP Console with your on premises LDAP identity provider, click the User Federation option on the left then choose the provider in the dropdown (LDAP):

Click to enlarge

Fill in the fields as instructed (https://www.keycloak.org/docs/latest/server_admin/#_ldap):

Click to enlarge

Use the Test connection button to test the configuration, and if successful, click Save. When Save has been clicked, additional buttons will appear: click Synchronize all users to import all the users to the Keycloak database:

To synchronize groups an LDAP mapper for the LDAP provider is required. When created, click Sync LDAP Groups to Keycloak and the groups will be imported:

Click to enlarge

By default users/groups from LDAP will not have any roles assigned, so at least one LDAP user (or group) will need to be granted the ADMIN role via the Keycloak role mappings section:

SAML authentication

To authenticate in AIP Console with your on premises SAML identity provider, click the Identity Providers option on the left then choose SAML 2.0 in the dropdown:

Click to enlarge

Enter the URL of the IDP metadata or import the metadata.xml file manually:

Click to enlarge

Keycloak will then automatically retrieve the information from metadata and display it in the UI:

Ensure the Backchannel Logout option is enabled if you require backend logout.

When fully configured, the login page for Keycloak will show an additional login button (highlighted below) with the alias defined when adding SAML as an identity provider:

When the "login with saml" button is clicked, you will be redirected to the SAML login page, and then when a successful login has occurred, the user will be redirected direct to the AIP Console home page.

Step 3 - Initial login to AIP Console

Browse to the following URL to check that AIP Console is running. You may wish to check that access is possible from an unrelated machine on the internal network. Ensure you specify the correct server (change "server") and port number (which was configured during the front-end installation):

http://<aip_console_server>:8081/

If the setup has been completed successfully, you will see the following:

Login with a user that has the admin role as defined in Keycloak. The startup wizard will be displayed (see below):

Step 4 - Complete start-up wizard

The start-up wizard is displayed the first time you login to AIP Console. The wizard provides a user-friendly method to configure various mandatory settings and options, such as:

  • Entering a license key
  • Configuring access to CAST Extend / use of a proxy caching server
  • Configuring a Measurement schema

Each step in the wizard is explained in detail below.

Validate License

This step enables you to enter your CAST AIP global license key. This key will be applied automatically to all AIP Node instances that you are managing with AIP Console. Click Next to continue to the next step of the wizard.

You can change the license key settings post-installation as described in Administration Center - Settings - License Key.

This step enables you to manage access to CAST Extend (this allows each AIP Node to automatically download any CAST AIP extension that you may want to use, or that may be required for an analysis) and an optional Proxy Configuration:

CAST Extend options

Choose one option (these settings can be managed post installation in Administration Center - Settings - CAST Extend):

Extend official service

When enabled, this mode configures each AIP Node to connect to CAST's publicly available extension server (https://extend.castsoftware.com/) over the internet on port 443 via TCP.

In this mode, the CAST Extend URL field will be automatically populated with the CAST Extend URL (https://extend.castsoftware.com/) in read-only mode (i.e. the URL cannot be changed). You will then need to input your CAST Extend API key (this can be generated in the CAST Extend UI - see CAST Extend. AIP Console will check that it can access Extend when you click Next.

If you do not have an account on CAST Extend, you can register for one, for free, using the following URL: https://extend.castsoftware.com/#/register
Extend proxy

In AIP Console ≥ 1.25, the minimum required release of Extend Proxy (Extend local server) is 1.1.0-funcrel.

When enabled, this mode configures each AIP Node to connect to an on-premises deployment of CAST Extend local server, therefore avoiding a connection to CAST's publicly available extension server over the internet. See Install CAST Extend Offline or Proxy - optional.

Enter the URL of your on-premises CAST Extend local server, enter the API Key and then click Next to continue - AIP Console will then check that it can access it:

API Key

The API Key will have been generated during the installation of CAST Extend Proxy and is displayed in the final summary screen of the installer:

 

Alternatively you can find the API key in the following location on the server on which CAST Extend Proxy is installed:

%PROGRAMFILES%\CAST\ExtendProxy\config.proxy.json

The key is located on the line APIKEY:

{
  "PORT": 8085,
  "STORAGE_DIR": "c:/ProgramData/CAST/Extend",
  "PACKAGE_DIR": null,
  "LOG_DIR": "C:/Program Files/CAST/Extend/logs",
  "PUBLIC_URL": "http://WIN10TEST:8085/",
  "EXTEND_URL": "https://extend.castsoftware.com",
  "APIKEY": "<api_key>",
  "ADMI": "admi1b878be2b185ff2ceada943c07b066c3bbfd9f9f5c5d931fe57da43e7b98dd4cad77ad4aacd95141ebb8b27d2edd666b5ab91f76cc95ae4b2e9c7c95121eb5322",
  "SYNC_TYPE": "auto"
}
Extend offline service

When enabled, this mode configures each AIP Node to connect to an on-premises deployment of CAST Extend Offline, therefore avoiding a connection to CAST's publicly available extension server over the internet. See Install CAST Extend Offline or Proxy - optional.

In this mode, the CAST Extend URL field will be empty and the CAST Extend Login (email) and CAST Extend Password fields will be hidden (no authentication is required for the on-premises CAST Extend Offline). Enter the URL of your on-premises CAST Extend Offline and then click Next to continue - AIP Console will then check that it can access it:

Allow CAST to automatically collect anonymous statistical dataSee Administration Center - Settings - Allow CAST to collect anonymous statistical data automatically for more information about this option.

Proxy Configuration (optional)

If your organization requires internal systems to use a proxy caching server (such as Squid) for all connections, you can use these options to configure AIP Console/AIP Nodes to use a proxy server for all communication (for example communication on AIP Nodes, Dashboards, CAST Extend, Maven repos, database servers etc.) as follows:

Extension Downloader limitation (for AIP Console ≤ 1.24)

The Extension Downloader (a tool present on each AIP Node which is used by AIP Console in ≤ 1.24 to download extensions) cannot be configured to obey a manual proxy configuration defined in AIP Console. Instead, if your organization uses a proxy, CAST recommends that:

  • you define the required proxy configuration at system level (i.e. operating system level) on all AIP Nodes
  • define a manual proxy configuration using the settings described below - this ensures that everything else will connect through the proxy

Extension Downloader was replaced with ExtendCli in AIP Console ≥ 1.25, therefore this limitation is no longer applicable for newer releases of AIP Console.

Windows Services

If the AIP Nodes packages are configured to run through Windows Services, it is important to ensure that the user login configured to run the Windows Services has permission to access any proxy that you define. If the user running the Windows Services cannot access the proxy, then the AIP Nodes will not be able to access the required resources.

No ProxyDefault setting. No proxy required.
Use system proxy settingsThis option will force AIP Console and all AIP Nodes to use the host machine's system proxy settings for all communication (i.e the proxy settings defined on each host server).
Manual proxy configuration

This option allows you to configure your own proxy settings specifically for AIP Console and all AIP Node communication (for example if you do not want to use the system proxy settings). These are applied to AIP Console and all AIP Nodes:

HostEnter the IP address/URL of the proxy server you need to use.
PortEnter the port number of the proxy server you need to pass through.
Username/passwordIf your proxy requires authentication, you can enter the required credentials in these fields.
Excluded Address

These options enable you to exclude certain destination addresses from using the manually configured proxy settings:

The value of this property is a list of hosts, separated by the semicolon ';'  character. In addition, the wildcard character '*' can be used for pattern matching. For example ”*.foo.com;localhost” will indicate that every host in the foo.com domain and the localhost should be accessed directly even if a proxy server is specified.

CAST highly recommends excluding the following URLs when you are using the Manual Proxy option:


You can change the CAST Extend/Proxy settings post-installation as described in:

Review

The final step in the wizard enables you to review the selections you have made. If anything requires changing, click the Back button to cycle back through the wizard and make any changes you need. Click Save and Finish when ready. You will then be directed to the AIP Console - Application Management page.

Step 5 - ensure your first AIP Node is registered

You should now ensure that your first AIP Node has been successfully registered in AIP Console. To do so, switch to the Admin Center:

Click the Nodes tab (1) and check that your node is present with a green icon to its left showing that is it connected and "up":

Step 6 - configure your CAST Storage Service/PostgreSQL instances

You should ensure that you configure any additional CAST Storage Service/PostgreSQL instances that will be used for your analysis/snapshot schema storage and for your Measurement schema. To do so, switch to the Admin Center:

Then click the Global Configurations tab:

Then, choose as per your requirement:

Analysis/snapshot schema storage

Expand the CAST Storage Service option. This option governs the CAST Storage Service/PostgreSQL instances that are available to your AIP Node instances for analysis/snapshot schema storage purposes for each Application that you create:

By default, one database connection will already be predefined. This is a connection to the PostgreSQL AIP Node database provided as a Docker container and is used to store options and settings common to all AIP Node instances. It is possible to use this database for your analysis/snapshot schema storage needs, however, CAST strongly recommends that you deploy additional standalone CAST Storage Service/PostgreSQL instances that are dedicated to analysis/snapshot schema storage only. To do so, click the Add Database Connection button:

Then fill in the required details and click Add when ready (AIP Console will check that the connection can be made using the parameters you enter):

HostThe host name of your target CAST Storage Service/PostgreSQL instance, e.g. a host name or IP address.
PortThe port which your target CAST Storage Service/PostgreSQL instance is running on.
UsernameThe login credentials for your target CAST Storage Service/PostgreSQL instance. For example operator/CastAIP for a CAST Storage Service in default configuration.
Password
Database nameThe PostgreSQL database used to store your schemas. For a CAST Storage Service in default configuration, this will be postgres (this will be prefilled) but if your target instance uses a different database name, please modify it as appropriate.
Use SSLTick this option if your target CAST Storage Service/PostgreSQL instance is running in SSL encrypted mode. XXXX to add!

The newly added CAST Storage Service/PostgreSQL instance will now be available in the drop down:

To make this newly added CAST Storage Service/PostgreSQL instance available to your AIP Nodes, you need to tick it and then click Save:

Now when you add a new Application, you will be able to chose the CAST Storage Service/PostgreSQL instance you require:

Measurement schema storage

The Measurement schema is required for consolidating snapshot data from all AIP Nodes for display in the CAST Health Dashboard. Only one Measurement schema is required for all AIP Nodes and this schema will be used by the CAST Health Dashboard exclusively. CAST recommends that you always deploy 1 x CAST Storage Service/PostgreSQL (on a dedicated Windows (CAST Storage Service) or Linux (PostgreSQL) server) only for the MEASUREMENT schema.

To manage the Measurement schema storage, expand the Measurement option:

By default, one database connection will already be predefined. This is a connection to the PostgreSQL AIP Node database provided as a Docker container and is used to store options and settings common to all AIP Node instances. It is possible to use this for your Measurement schema storage needs, however, CAST strongly recommends that you deploy an additional standalone CAST Storage Service/PostgreSQL instance that is dedicated to Measurement schema storage only.

If you have already added a CAST Storage Service/PostgreSQL instance for analysis schema storage requirements, this instance will also be available for selection (as shown below). It is possible to use this for your Measurement schema storage needs, however, CAST strongly recommends that you deploy an additional standalone CAST Storage Service/PostgreSQL instance that is dedicated to Measurement schema storage only.

To add a new instance, click the Add Database Connection button. Fill in the fields as follows and then click Next to continue - AIP Console will check that it can access the CAST Storage Service/PostgreSQL instance using the credentials you have defined:

HostThe host name of your target CAST Storage Service/PostgreSQL instance, e.g. a host name or IP address.
PortThe port which your target CAST Storage Service/PostgreSQL instance is running on.
UsernameThe login credentials for your target CAST Storage Service/PostgreSQL instance. For example operator/CastAIP for a CAST Storage Service in default configuration.
Password
Database nameThe PostgreSQL database used to store your schemas. For a CAST Storage Service in default configuration, this will be postgres (this will be prefilled) but if your target instance uses a different database name, please modify it as appropriate.
Use SSLTick this option if your target CAST Storage Service/PostgreSQL instance is running in SSL encrypted mode. XXXX to add!

The newly added CAST Storage Service/PostgreSQL instance will now be available in the drop down:

To use this newly added CAST Storage Service/PostgreSQL instance for your Measurement schema storage requirements, you need to specifically select it, name your Measurement schema and Save the changes:

For the Schema name:

Schema name

You can change the name of the schema, however CAST recommends using the predefined general_measure name since this means less work when performing the Embedded CAST Dashboard deployment process step. Authorized characters for the name are as follows:

  • 0-9
  • A-Z
  • _ (underscore)

A validation process is actioned and any unauthorized characters, such as -, # or $ will be rejected.

Step 7 - Determine Extension Strategy

Finally, ensure you determine your extension strategy, as described in Determine Extension Strategy. When complete, you can start to create Applications and deliver source code as normal.

  • No labels