Configuring the OMAG Server Platform¶

The OMAG Server Platform is a JVM process that includes a Tomcat web server and uses Spring Boot to support REST APIs.

Default setup¶

• REST APIs are registered at https://localhost:9443. This address is called the platform's platform's URL root and is configured in a number of places in the OMAG Server's configuration.
• The platform supports no specific security authorization.
• All configuration is stored in encrypted files - one for each OMAG Server configured to run on it.

Configuring other options¶

Configuration store¶

The configuration document is the place where the configuration for a single OMAG Server is stored. This may include security certificates and passwords.

By default, the configuration document is stored in its own encrypted file in the home directory of the OMAG Server Platform, named:

omag.server.{serverName}.config

As of v2.0 of Egeria, the contents of the configuration document are stored in an encrypted JSON format¹. The clear-text contents of the configuration document can still be retrieved by accessing the admin services endpoint for retrieving the configuration document; however, this ensures security is applied before a user is able to retrieve the configuration document's contents:

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{serverName}}/configuration/

You may also wish to:

• Move the location of the configuration documents
• Write you own alternative store for the configuration documents

All of these options are possible because the configuration document store is implemented in a configuration document store connector. It is therefore possible to change the implementation or behavior of this connector with a simple configuration change to the OMAG Server Platform.

The configuration document store connector is configured in the OMAG Server Platform using the following command:

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/stores/connection

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
    "class": "Connection",
    "connectorType": {
        "class": "ConnectorType",
        "connectorProviderClassName": "org.odpi.openmetadata.adapters.adminservices.configurationstore.file.FileBasedServerConfigStoreProvider"
    },
    "endpoint": {
        "class": "Endpoint",
        "address": "omag.server.{0}.config"
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
    "class": "Connection",
    "connectorType": {
        "class": "ConnectorType",
        "connectorProviderClassName": "org.odpi.openmetadata.adapters.adminservices.configurationstore.encryptedfile.EncryptedFileBasedServerConfigStoreProvider"
    },
    "endpoint": {
        "class": "Endpoint",
        "address": "/my-config/omag.server.{0}.config"
    }
}

Determine configured store¶

It is possible to query the setting of the configuration document store connector using the following command:

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/stores/connection

{
    "class": "ConnectionResponse",
    "relatedHTTPCode": 200
}

{
    "class": "ConnectionResponse",
    "relatedHTTPCode": 200,
    "connection": {
        "class": "Connection",
        "connectorType": {
            "class": "ConnectorType",
            "connectorProviderClassName": "org.odpi.openmetadata.adapters.adminservices.configurationstore.file.FileBasedServerConfigStoreProvider"
        },
        "endpoint": {
            "class": "Endpoint",
            "address": "omag.server.{0}.config"
        }
    }
}

Remove configured store¶

It is also possible to remove the configuration for the connector using the following command:

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/stores/connection

This reverts the store to the default encrypted JSON file store.

Platform security¶

The OMAG Server Platform provides both configuration and diagnostic services for OMAG Servers which in themselves provide access to a wide variety of information and control points.

Therefore, it is necessary to provide authorization services relating to the use of the platform services.

Egeria provides a platform security authorization capability. It is implemented in a platform metadata security connector that is called whenever requests are made to the server platform services.

Security is configured for a specific platform once it is running by using the following command.

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/platform/security/connection

{
    "class": "PlatformSecurityRequestBody",
    "urlRoot": "{{platformURLRoot}}",
    "platformSecurityConnection" : 
    {
        "class": "Connection",
        "connectorType": 
        {
            "class": "ConnectorType",
            "connectorProviderClassName": "org.odpi.openmetadata.metadatasecurity.samples.CocoPharmaPlatformSecurityProvider"
        }
    }
}

Determine configured security¶

It is possible to query the setting of the platform security connector using the following command:

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/platform/security/connection

{
    "class": "ConnectionResponse",
    "relatedHTTPCode": 200
}

{
    "class": "ConnectionResponse",
    "relatedHTTPCode": 200,
    "connection": {
        "class": "Connection",
        "connectorType": {
            "class": "ConnectorType",
            "connectorProviderClassName": "org.odpi.openmetadata.metadatasecurity.samples.CocoPharmaPlatformSecurityProvider"
        }
    }
}

Remove configured security¶

It is possible to remove the configuration for the connector using the following command:

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/platform/security/connection

This removes all authorization checking from the platform services.

application.properties¶

Since the OMAG Server Platform is a Spring Boot application, there are other values that can be set in its application.properties file found in the resources subdirectory:

• Defining the port that the OMAG Server Platform will listen on for REST API calls.
• Controlling the level of developer logging that the platform produces when it is running. See Configuring logging options for more details.
• Defining where the connector implementations should be loaded from.

Spring provides extensive documentation on its standard properties .

Auto-starting servers¶

An OMAG Server is typically started on the OMAG Server Platform using a command; however, it is possible to set up a list of servers that are automatically started whenever the platform is started. These servers are also automatically shutdown when the platform is shutdown.

OMAG Servers can be automatically activated at startup by setting spring-boot property startup.server.list, typically in the application.properties file. The server names are listed without quotes. For example:

startup.server.list=cocoMDS1, cocoMDS2

Each server is started with the administration user id set in the spring-boot property startup.user.

For example:

startup.user=garygeeke

By default, this user id is set to the user id system.

When the platform shuts down, if any of the servers that were in the startup list are still running, they will be shut down before the server completes.

startup.server.list=

Transport Layer Security (TLS)¶

Transport layer security describes the security applied to API calls made between servers. The most commonly known transport layer security is SSL.

Egeria uses TLS with certificates to secure the communication to and from the OMAG Server Platforms.

Brief background on TLS¶

Transport Layer Security (TLS) protects communications over network connections through encryption, authentication and integrity. It is just one layer of security of many.

One-way SSL exchange¶

One-way SSL exchange is typically in use when browsing the web - since as a user you are most concerned that the server you are connecting to is authentic.

With this approach, the server is not able to guarantee your authenticity at the transport level. This means you can be assured of the identity of the server, but it cannot be sure of who you are.

Two-way (mutual) SSL exchange¶

With two-way (mutual) SSL exchange, trust is established both ways. This mutual authentication is more typical when interconnecting different systems and applications which are known in advance.

Certificates for the OMAG Server Platform¶

An instance of the OMAG Server Platform services requests over a REST based API from other OMAG Server Platforms, UIs, tools and engines. In this regard its role in SSL network requests described above is that of a network server, with its callers performing the role of a network client.

However, since the OMAG Server Platform also makes requests to other systems (including other OMAG Server Platforms and Apache Kafka) it is also fulfilling a network client role.

As a Spring application, the OMAG Server Platform's configuration for its network server role allows the following Spring properties to be set:

For further details on these and other less common configuration options, refer to the Spring Docs.

Since the OMAG Server Platform is also a network client the settings in the next section for clients are also required.

Egeria Java clients¶

Standard Java properties need to be set within the JVM running the Egeria client code (this includes the OMAG Server Platform):

Note that in the case of Java clients, these are system properties, and do not use Spring conventions.

Other clients¶

Similar principles to those documented for Java should apply. If you need further assistance, please contact the team on Slack . A pull request (or issue) with contributed documentation is also very welcome!

Example to launch Egeria¶

Examples certificates are provided in the codebase under open-metadata-resources/open-metadata-deployment/certificates

As an example of running the Egeria server chassis with the certificates generated above, add the following options when launching the OMAG Server Platform jar file:

-Dserver.ssl.key-store=${KS}
-Dserver.ssl.key-alias=EgeriaServerChassis
-Dserver.ssl.key-store-password=egeria
-Dserver.ssl.trust-store=EgeriaCA.p12
-Dserver.ssl.trust-store-password=egeria
-Djavax.net.ssl.keyStore=EgeriaServerChassis
-Djavax.net.ssl.keyStorePassword=egeria
-Djavax.net.ssl.trustStore=EgeriaCA.p12
-Djavax.net.ssl.trustStorePassword=egeria

Creating your own certificates¶

The example certificates are fine for development; however, it is important to have your own certificates for a production environment.

An example script (MacOS/Linux) to create certificates is provided in gensamplecerts.sh . It is intended only as an example. It requires the openssl tool and keytool. Deployment frameworks in cloud services may also offer support to generate certificates, and it is likely an enterprise process will be in place in larger organizations.

The script creates a Certificate Authority and then specific certificates for different Egeria components. It could be extended to create certificates for other clients especially if using 2 way SSL.

When the script is run it also makes use of the configuration template openssl.cnf .

Together, both set some important characteristics that are needed to allow the certificate to work properly, especially with current browsers:

• ensuring basicConstraints are specified
• ensuring the certificate expiry time is not too far in the future
• ensuring subjectAltName is specified.

Raise an issue or comment below