Security Guide¶

This guide is for the security expert who needs to assure an Egeria deployment. It walks through each layer of protection that Egeria provides, names the properties, classes and URLs that control it, and points to the pages that describe each mechanism in detail. It also lists the settings in the shipped samples that must be changed before a deployment holds real metadata, and the places where the code behaves differently from what a reader might expect.

Egeria's runtime is the OMAG Server Platform: a Spring Boot application that hosts a number of OMAG Servers. Everything a caller does - configuring a server, starting it, searching for metadata, updating a glossary term - is a REST call to the platform, and every server-to-server call is also a REST call or an event on Apache Kafka. Securing Egeria therefore means securing that platform and the connections it makes.

Layers of protection¶

A request to Egeria passes through the layers below. Each layer is independent, and each is optional in the code, so an assurance review needs to confirm that every one of them is switched on and configured.

flowchart LR
    caller["Caller<br/>(portal, hey_egeria,<br/>pyegeria, another server)"]
    subgraph platform["OMAG Server Platform"]
        direction TB
        tls["1. TLS<br/>server.ssl.*"]
        authn["2. Authentication<br/>/api/token and<br/>bearer token check"]
        psc["3. Platform metadata<br/>security connector"]
        ssc["4. Server metadata<br/>security connector<br/>(server, service, element,<br/>zones, repository, events)"]
        conn["5. Connectors with<br/>embedded secrets<br/>store connectors"]
        audit["6. Audit log<br/>(Security severity)"]
        tls --> authn --> psc --> ssc --> conn
        psc -. "denials" .-> audit
        ssc -. "denials" .-> audit
    end
    secrets[("Secrets stores<br/>user directory,<br/>server and connector<br/>secrets")]
    ext[("Kafka, PostgreSQL,<br/>catalogued systems")]
    dest[("Audit log<br/>destinations")]
    caller -- "HTTPS + Bearer token" --> tls
    authn -. "user accounts" .-> secrets
    psc -. "access controls" .-> secrets
    ssc -. "access controls" .-> secrets
    conn -. "credentials" .-> secrets
    conn -- "TLS" --> ext
    audit --> dest

Transport level security¶

The platform plays two network roles. It is a network server for the REST calls it receives, and a network client when it calls other platforms, Apache Kafka, databases and the systems that its connectors catalogue. Each role is configured separately. The background to TLS, one-way and mutual authentication, and the creation of certificates is in Transport Level Security (TLS) and Certificates.

server.port=9443
server.ssl.key-store=keystore.p12
server.ssl.key-store-password=egeria
server.ssl.keyStoreType=PKCS12
server.ssl.keyAlias=egeriaserverchassis
server.ssl.trust-store=truststore.p12
server.ssl.trust-store-password=egeria

Users, passwords and bearer tokens¶

Every REST call to the platform, apart from a short list of public endpoints, must carry a bearer token. The token is obtained by logging on with a userId and password.

How log on works¶

Authentication is provided by the user-authn module (package org.odpi.openmetadata.userauthn), which is built on Spring Security. It is switched on by these properties:

authentication.source=platform
authentication.mode=token
rsa.key-id=
bearerTokenTimeout=1

When authentication.source=platform, the PlatformSecurityConfig and PlatformUserDetailsService components look up user accounts through the platform metadata security connector - specifically its OpenMetadataUserSecurity interface, which the Open Metadata Access Security Connector passes on to its embedded secrets store. The user directory is therefore the platform security connector's secrets store collection. If no platform security connector is configured, there are no user accounts and every log on fails with User account not found.

sequenceDiagram
    participant C as Caller
    participant L as LoginController<br/>(/api/token)
    participant V as OpenMetadataPlatform<br/>SecurityVerifier
    participant S as Secrets store<br/>(user directory)
    participant T as TokenService
    C->>L: POST /api/token {userId, password}
    L->>V: getLogonUser(userId)
    V->>S: getUserAccount(userId)
    S-->>L: OpenMetadataUserAccount
    L->>L: check status and BCrypt password
    L->>T: generateToken()
    T-->>C: signed JWT
    C->>C: Authorization: Bearer {{token}} on each later call

###
# @name Token
POST {{baseURL}}/api/token
Content-Type: application/json

{
  "userId" : "garygeeke",
  "password" : "{{password}}"
}

###
# @name getServerStatus
GET {{baseURL}}/open-metadata/platform-services/server-platform/servers/qs-metadata-store/status
Authorization: Bearer {{token}}

The response to POST /api/token is the token itself, as plain text. The same service is also available at POST /servers/{serverName}/api/token; today it calls the platform's user directory too, so the server name makes no difference to the result.

User accounts and passwords¶

Each user account in the user directory has a userAccountStatus and a userAccountType:

The userAccountType is one of EMPLOYEE, CONTRACTOR, EXTERNAL or DIGITAL (a non-personal account used by automation). The security connector builds dynamic groups from it, so it can be used in access decisions.

A password is held in the account's secrets as either clearPassword or encryptedPassword. The encryptedPassword is a BCrypt hash, and is what the platform compares against. When a user changes their password through /api/token with a newPassword, the platform writes a new BCrypt encryptedPassword to the secrets store and removes the clearPassword. The sample user directories use clearPassword throughout: in production, store only encryptedPassword values.

Problems with logging on are diagnosed in Logon problems.

Endpoints that need no token¶

SecurityConfig.securityFilterChain() lets these paths through without a token:

All of these are read-only. If you do not want the API documentation published, set springdoc.api-docs.enabled=false.

Token lifetime, revocation and signing keys¶

Other properties that affect the HTTP layer¶

• cors.allowed-origins - the browser origins allowed to call the platform. Both the shipped and the quickstart properties set *. Set it to the origins of your user interfaces.
• authn.header.name.list - names of HTTP headers to copy from incoming requests into thread-local storage for connectors to use (* copies them all). Leave it empty unless a connector needs a header.
• springdoc.* - the OpenAPI documentation described above.
• management.endpoints.web.exposure.include - the Spring Boot actuator endpoints to expose. It is commented out in the shipped properties, so only the defaults are exposed.

Authorization with the metadata security connectors¶

Authorization is delegated to two kinds of connector, described in Open Metadata Security:

• the platform metadata security connector, one per platform, which secures the administration services, platform services and server operations; and
• the server metadata security connector, one per OMAG Server, which secures everything that server does.

Egeria supplies one implementation of both: the Open Metadata Access Security Connector (provider class org.odpi.openmetadata.metadatasecurity.accessconnector.OpenMetadataAccessSecurityProvider). It takes all its decisions from the user accounts, named lists and security access controls in an embedded secrets store, so a security team can control access by editing that store.

The platform metadata security connector¶

The platform connector is configured in application.properties. These are the values used by the quickstart:

platform.security.provider=org.odpi.openmetadata.metadatasecurity.accessconnector.OpenMetadataAccessSecurityProvider
platform.security.name=Coco Pharmaceuticals Platform @ 9443
platform.security.secrets.provider=org.odpi.openmetadata.adapters.connectors.secretsstore.yaml.YAMLSecretsStoreProvider
platform.security.secrets.location=/deployments/secrets/coco-user-directory.omsecrets
platform.security.secrets.collection=cocoUserDirectory

It can also be replaced while the platform is running with POST /open-metadata/platform-services/server-platform/security/connection (and read or removed with GET and DELETE on the same URL). Replacing it needs operator authority under the current connector.

The connector maps the platform roles to security access controls in the user directory. The names of these controls can be changed with the connector's configuration properties:

In the quickstart user directory, the DEFAULT list of admin-services names serverAdministrator, platform-services names serverOperator, and server-operations names serverInvestigator - with an extra addOpenMetadataArchiveFile entry that lets any openMetadataMember load an archive. Configuring the platform connector is described in Configuring the OMAG Server Platform.

The server metadata security connector¶

Each server's connector is held in the serverSecurityConnection property of its configuration document, and is set with the administration services. This is the call that the quickstart uses to configure qs-metadata-store. The ~{...}~ values are placeholder variables.

###
# @name setServerSecurityConnection
POST {{baseURL}}/open-metadata/admin-services/servers/qs-metadata-store/security/connection
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "class": "VirtualConnection",
  "connectorType": {
    "class": "ConnectorType",
    "connectorProviderClassName": "org.odpi.openmetadata.metadatasecurity.accessconnector.OpenMetadataAccessSecurityProvider"
  },
  "embeddedConnections" : [{
    "class": "EmbeddedConnection",
    "embeddedConnection" : {
      "class" : "Connection",
      "connectorType" : {
        "class" : "ConnectorType",
        "connectorProviderClassName" : "~{secretsStoreProvider}~"
      },
      "endpoint" : {
        "class" : "Endpoint",
        "networkAddress" : "~{userDirectorySecretsStore}~"
      },
      "configurationProperties" : {
        "secretsCollectionName" : "~{userDirectorySecretsCollectionName}~"
      }
    }
  }]
}

GET on the same URL shows the current setting and DELETE removes it, turning off all authorization in that server. Further detail is in Server Security Connection Section.

The server connector is called at several layers, and each layer is a separate interface (OpenMetadataServerSecurity, OpenMetadataServiceSecurity, OpenMetadataElementSecurity, OpenMetadataRepositorySecurity and OpenMetadataEventsSecurity). The Open Metadata Access Security Connector implements them like this:

Groups and roles¶

Access lists may name users, or named lists from the user directory. A named list has a listTypeName (such as SecurityRole or SecurityGroup) and its members are given in userMembers and listMembers. The connector also builds these dynamic groups itself; their names can be changed with the connector property shown:

Maintaining the user directory¶

The user directory can be changed in three ways:

• Edit the secrets store directly. The connector re-reads a collection when its refreshTimeInterval (in minutes) has passed - the quickstart user directory uses 10.
• Use the platform's security services under /open-metadata/platform-services/server-platform/security/: user-list, user-accounts (POST, and GET or DELETE on user-accounts/{accountUserId}) and security-access-controls (POST, and GET or DELETE on security-access-controls/{controlName}).
• Use the Security Officer API, which provides the same functions through a view server, along with statements of applicability.

Each addition or removal of a user account or access control is written to the audit log (see below).

Governance zones¶

Governance zones group metadata elements so that access can be controlled for the whole group. An element lists its zones in the zoneMembership property of its ZoneMembership classification, and each zone is defined by a security access control of type GovernanceZone in the user directory - for example the quickstart's egeria-runtime zone lets every openMetadataMember read its contents (READ list) but only runtimeManager and dataManagementProcess change them (DEFAULT list).

The rules applied by the Open Metadata Access Security Connector are set out in Access control through governance zones. The points that matter most for assurance are:

• An element with no zones is visible to every user with an active account. Elements that need protecting must be put in a zone - templates and the server's default zone settings help to do this consistently.
• Zone security fails closed. A zone without a security access control admits no one, so a misspelt zone name hides elements rather than exposing them. The OMAGServerPlatformCataloguer integration connector flags zones that are missing from the user directory with a MISSING-ZONE-ACCESS-CONTROL exception.
• A zone named after a userId is that user's personal zone.
• Searches are filtered in the repository using the zones the user may read (pushDownZoneFilter, default true). The filter relies on zone information held in each element's Anchors classification, which can be refreshed with the resynchronize-anchors-zones request type of the Egeria Governance Engine.

Secrets stores¶

A secrets store connector retrieves secrets - passwords, API keys, certificates, token API details - from a secure location at runtime, so that they need not be held in configuration documents or in the metadata repository. Egeria supplies the YAML File Secrets Store Connector (org.odpi.openmetadata.adapters.connectors.secretsstore.yaml.YAMLSecretsStoreProvider). Other secrets managers can be supported by writing a connector to the same interface.

Inside a secrets store¶

A YAML secrets store file holds named secretsCollections. Each collection may contain:

• refreshTimeInterval - minutes before the connector re-reads the collection, so rotated secrets are picked up without a restart;
• secrets - named values such as userId, clearPassword and encryptedPassword;
• tokenAPI - how to obtain a bearer token (httpRequestType, url, contentType and requestBody);
• users, namedLists and securityAccessControls - the user directory and access controls used by the security connectors.

A single YAML secrets store connector reads one collection, named by the secretsCollectionName configuration property of its connection; the file is named in the connection's endpoint networkAddress.

How the quickstart uses secrets stores¶

The quickstart separates its secrets into three files, each mounted into the platform container at /deployments/secrets:

A server's own identity is set with POST /open-metadata/admin-services/servers/{serverName}/server-properties. localServerUserId names its non-personal account (for example qsstorenpa), and secretsStoreProvider, secretsStoreLocation and secretsStoreCollection name the secrets store collection whose tokenAPI the server uses to obtain a bearer token when it calls other servers.

Secrets in connections¶

A secrets store connector is used by embedding its connection in the connection of the connector that needs the secrets, as the server security connector example above shows. The connector broker creates both together, and if the outer connection's userId, clearPassword or encryptedPassword are empty it fills them from the secrets store. If a connector needs other secrets, the connection's securedProperties hold the names of the secrets, not their values. Secrets that integration connectors need for third-party systems can be stored through the Automated Curation API - see Client-side secret.

Keeping secrets out of configuration documents¶

Configuration documents are stored by the configuration document store connector. The default FileBasedServerConfigStoreProvider writes each one as a clear text JSON file under data/servers/{serverName}/config/. Do not write passwords into a configuration document. Instead:

• refer to secrets stores, as above; and
• use placeholder variables such as ~{egeriaServersSecretsStore}~ in the configuration, which the platform replaces at server start up with the values in the platform.placeholder.variables property of application.properties.

Protecting the secrets stores¶

A YAML secrets store is an ordinary file, so its protection comes from the deployment: restrict the file system permissions to the account that runs the platform, keep the files out of source control and container images, and mount them at runtime (the quickstart mounts runtime-volumes/quickstart-platform-data/secrets). The YAML connector writes changes back to the file when user accounts, passwords or access controls are updated through the APIs, so the user directory file must be writable by the platform.

Security audit logging¶

Each OMAG Server has an audit log, and each audit log record has a severity. The Security severity is used for unauthorized access attempts and for changes to the security definitions. The records are routed by the server's audit log destination connectors, and each destination chooses the severities it receives.

What is logged¶

The security connectors log these messages (defined in OpenMetadataSecurityAuditCode):

Where the records go¶

Hardening checklist¶

The shipped application.properties and the egeria-workspaces samples are designed to be easy to start, not to be secure. Before a deployment holds real metadata:

In addition, follow the deployment guidance in Planning for security: run the platform on a patched operating system and Java runtime, place it in a private network segment behind a reverse proxy or API gateway, and secure the Kafka brokers and databases it uses.

Known gaps in the code¶

These behaviours of the code (branch oak2026) are worth recording in a security assessment because they differ from what a reader might expect.

Raise an issue or comment below