Merge pull request #989 from mandy-chessell/code2024

Add more on the YAML File Secrets Connector

Author: mandy-chessell

CODEOWNERS

@@ -52,7 +52,7 @@ site/docs/services/omas/enterprise-architecture/ @mandy-chessell
 site/docs/services/omas/glossary-view/ @lcpopa
 site/docs/services/omas/stewardship-action/ @mandy-chessell
 site/docs/services/omas/governance-program/ @mandy-chessell
-site/docs/services/omas/governance-engine/ @mandy-chessell
+site/docs/services/omas/governance-server/ @mandy-chessell
 site/docs/services/omas/subject-area/ @davidradl
 site/docs/services/omas/asset-lineage/ @lcpopa @popa-raluca
 

site/docs/concepts/index.md

@@ -299,6 +299,7 @@
 - [Platform Metadata Security Connector](/concepts/platform-metadata-security-connector)
 - [Platform Security](/features/metadata-security/overview)
 - [Platform URL Root](/concepts/platform-url-root)
+- [Process](/concepts/process)
 - [Project](/concepts/project)
 - [Project Manager OMVS](/services/omvs/project-manager/overview)
 - [Project Management OMAS](/services/omas/project-management/overview)

site/docs/concepts/process.md

@@ -0,0 +1,17 @@
+---
+hide:
+- toc
+---
+
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+<!-- Copyright Contributors to the Egeria project. -->
+
+# Process
+
+A *process* describes a well-defined set of processing steps and decisions that drive a particular aspect of the organization's business. Most processes are automated with software, but they may also be a manual procedure. An automated process can be invoked from a remote server through an API.
+
+A process is a type of [asset](/concepts/asset).  Egeria uses [Governance Action Processes](/concepts/governance-action-process) to automate governance.
+
+
+
+--8<-- "snippets/abbr.md"

site/docs/connectors/connector-catalog.drawio

@@ -1,4 +1,4 @@
-<mxfile host="Electron" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/24.7.8 Chrome/128.0.6613.36 Electron/32.0.1 Safari/537.36" version="24.7.8" pages="27">
+<mxfile host="Electron" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/24.7.17 Chrome/128.0.6613.36 Electron/32.0.1 Safari/537.36" version="24.7.17" pages="27">
   <diagram id="zwH0E6yuSuxNEa-D1nxI" name="compare-use-of-connectors">
     <mxGraphModel dx="1242" dy="822" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1169" pageHeight="827" math="0" shadow="0">
       <root>
@@ -3777,17 +3777,31 @@
         <mxCell id="jxgSa6bsgg5_kzLXStgE-6" value="Environment variable" style="shape=process;whiteSpace=wrap;html=1;backgroundOutline=1;fillColor=#e1d5e7;strokeColor=#9673a6;" parent="1" vertex="1">
           <mxGeometry x="145" y="280" width="120" height="60" as="geometry" />
         </mxCell>
-        <mxCell id="smZqJnJgsjUjO1HoDnpI-2" value="Consuming Connector" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#76608a;strokeColor=#432D57;fontColor=#ffffff;verticalAlign=top;" vertex="1" parent="1">
+        <mxCell id="smZqJnJgsjUjO1HoDnpI-2" value="Consuming Connector" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#76608a;strokeColor=#432D57;fontColor=#ffffff;verticalAlign=top;" parent="1" vertex="1">
           <mxGeometry x="414" y="100" width="170" height="120" as="geometry" />
         </mxCell>
-        <mxCell id="smZqJnJgsjUjO1HoDnpI-3" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;entryPerimeter=0;" edge="1" parent="1" source="smZqJnJgsjUjO1HoDnpI-4" target="smZqJnJgsjUjO1HoDnpI-8">
-          <mxGeometry relative="1" as="geometry" />
+        <mxCell id="smZqJnJgsjUjO1HoDnpI-3" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0;entryY=0;entryDx=88.5;entryDy=0;entryPerimeter=0;" parent="1" source="smZqJnJgsjUjO1HoDnpI-4" target="bS2VUSNe2yy4efDYJTGr-1" edge="1">
+          <mxGeometry relative="1" as="geometry">
+            <mxPoint x="499.01" y="260" as="targetPoint" />
+          </mxGeometry>
         </mxCell>
-        <mxCell id="smZqJnJgsjUjO1HoDnpI-4" value="YAML File&lt;div&gt;Secrets Store Connector&lt;/div&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#e1d5e7;strokeColor=#9673a6;" vertex="1" parent="1">
+        <mxCell id="smZqJnJgsjUjO1HoDnpI-4" value="YAML File&lt;div&gt;Secrets Store Connector&lt;/div&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#e1d5e7;strokeColor=#9673a6;" parent="1" vertex="1">
           <mxGeometry x="428.88" y="140" width="140.25" height="65" as="geometry" />
         </mxCell>
-        <mxCell id="smZqJnJgsjUjO1HoDnpI-8" value="mySecrets.&lt;div&gt;omsecrets&lt;/div&gt;" style="shape=note;whiteSpace=wrap;html=1;backgroundOutline=1;darkOpacity=0.05;" vertex="1" parent="1">
-          <mxGeometry x="459.01" y="260" width="80" height="100" as="geometry" />
+        <mxCell id="bS2VUSNe2yy4efDYJTGr-1" value="" style="shape=note;whiteSpace=wrap;html=1;backgroundOutline=1;darkOpacity=0.05;size=23;" vertex="1" parent="1">
+          <mxGeometry x="410" y="260" width="200" height="120" as="geometry" />
+        </mxCell>
+        <mxCell id="bS2VUSNe2yy4efDYJTGr-2" value="&lt;span style=&quot;text-wrap: wrap;&quot;&gt;mySecrets.&lt;/span&gt;&lt;span style=&quot;text-wrap: wrap; background-color: initial;&quot;&gt;omsecrets&lt;/span&gt;" style="text;html=1;align=center;verticalAlign=middle;resizable=0;points=[];autosize=1;strokeColor=none;fillColor=none;" vertex="1" parent="1">
+          <mxGeometry x="439" y="380" width="140" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="bS2VUSNe2yy4efDYJTGr-3" value="SecretsCollection" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;" vertex="1" parent="1">
+          <mxGeometry x="439" y="280" width="120" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="bS2VUSNe2yy4efDYJTGr-4" value="SecretsCollection" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;" vertex="1" parent="1">
+          <mxGeometry x="449" y="290" width="120" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="bS2VUSNe2yy4efDYJTGr-5" value="SecretsCollection" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;verticalAlign=middle;" vertex="1" parent="1">
+          <mxGeometry x="459" y="300" width="120" height="60" as="geometry" />
         </mxCell>
       </root>
     </mxGraphModel>

site/docs/connectors/secrets/yaml-file-secrets-store-connector.md

@@ -12,15 +12,28 @@
 
 ## Overview
 
-The *YAML File Secrets Store Connector* retrieves secrets from environment variables.  The name of the secret requested is the name of the environment variable it tries to retrieve.  It returns null if the environment variable is not defined.
+The *YAML File Secrets Store Connector* is a [Secrets Store Connector](/concepts/secret-store-connector) that retrieves secrets from a named YAML file.  By convention, these YAML files have a file extension of `omsecrets`. 
 
 ![Figure 1](yaml-file-secrets-store-connector.svg)
 > **Figure 1:** Operation of the YAML File Secrets Store Connector
 
+Secrets within the YAML file are organized into collections. Each collection represents a set of secrets needed by a particular type of caller. When the YAML File Secrets Store Connector starts up, it opens the YAML file using the address passed in the endpoint of its connection.  It located the appropriate collection using the name specified in the `secretsCollectionName` property found in the connection's `configurationProperties`.  The connector will fail if either of these two values are missing.
+
+
+
+Inside a collection are:
+
+* A refresh time interval (`refreshTimeInterval`) that defines how long the secrets can be cached.  When the time expires, the connector retrieves the secrets from the cache.
+* A map of named secrets (`secrets`) - such as details of certificates or userId and passwords.  These secrets are used by other connectors, and automated services to log on to remote services.
+* The details of an API to call to retrieve a token (`tokenAPI`).  This includes the HTTP request type, URL and details fo the request and response body.  This supplements the secrets map allowing certain secrets to be retrieved dynamically.
+* A map of userIds to user account details (`users`).  This is needed by a connector that is supporting a user authentication service.
+* A map of named lists (`namedLists`) that is used to represent organizational units, security roles and groups needed by an authorization service.
+
+Complete details of this structure can be found in [Egeria's Javadoc](https://odpi.github.io/egeria/org/odpi/openmetadata/adapters/connectors/secretsstore/yaml/secretsstore/package-summary.html) and an example can be found in [GitHub](https://github.com/odpi/egeria/tree/main/open-metadata-resources/open-metadata-deployment/secrets).
 
 ## Configuration
 
-This is its connection definition to embed into a connector's connection object.
+This is its connection definition to embed into a calling connector's connection object.
 
 !!! example "Connection configuration for the environment variable secrets store connector"
     ```json linenums="1" hl_lines="14"
@@ -33,6 +46,15 @@ This is its connection definition to embed into a connector's connection object.
             {
                 "class" : "ConnectorType",
                 "connectorProviderClassName" : "org.odpi.openmetadata.adapters.connectors.secretsstore.yaml.YAMLSecretsStoreProvider"
+            },
+            "endpoint" :
+            {
+                "class" : "Endpoint",
+                "address" : {{secretsStoreFileLocation}}
+            },
+            "configurationProperties" :
+            {
+                "secretsCollectionName" : {{secretsCollectionName}}
             }
         }
     }

site/docs/connectors/secrets/yaml-file-secrets-store-connector.svg

@@ -20,6 +20,6 @@ An context event engine hosts specialized governance services called [context ev
 
 The Context Event OMES is capable of hosting one or more [context event engines](/concepts/context-event-engine).
 
-The context event engine services call the [Governance Engine Open Metadata Access Service (OMAS)](/services/omas/governance-engine/overview) running in an open metadata server to retrieve information about events and to store the results of the context event services' work.
+The context event engine services call the [Stewardship Action Open Metadata Access Service (OMAS)](/services/omas/stewardship-action/overview) running in an open metadata server to retrieve information about events and to store the results of the context event services' work.
 
 --8<-- "snippets/abbr.md"

site/docs/services/omes/context-event/overview.md

@@ -14,7 +14,7 @@ The engine services run in the [engine host](/concepts/engine-host).  They provi
 |-----------------------------------------------------------------------------|--------------------------------------------------------------------------|-----------------------------------------------------------------------|
 | [Survey Action OMES](/services/omes/survey-action/overview)                 | [Survey Action Service](/concepts/survey-action-service)                 | [Asset Owner OMAS](/services/omas/asset-owner/overview)               |
 | [Governance Action OMES](/services/omes/governance-action/overview)         | [Governance Action Service](/concepts/governance-action-service)         | [Governance Server OMAS](/services/omas/governance-server/overview)   |
-| [Context Event OMES](/services/omes/context-event/overview)                   | [Context Event Service](/concepts/context-event-service)                   | [Stewardship Action OMAS](/services/omas/stewardship-action/overview) |
+| [Context Event OMES](/services/omes/context-event/overview)                 | [Context Event Service](/concepts/context-event-service)                 | [Stewardship Action OMAS](/services/omas/stewardship-action/overview) |
 | [Repository Governance OMES](/services/omes/repository-governance/overview) | [Repository Governance Service](/concepts/repository-governance-service) | [Repository Governance OMAS](/services/omrs)                          |
 
 

site/docs/services/omes/index.md

@@ -48,6 +48,7 @@ nav:
           - Connector Catalog:
               - Connector Overview: connectors/index.md
               - Secrets Store:
+                    - YAML File: connectors/secrets/yaml-file-secrets-store-connector.md
                     - Environment Variables: connectors/secrets/environment-variable-secrets-store-connector.md
               - Files:
                     - Any File:
@@ -545,7 +546,7 @@ nav:
               - Engine Services (OMES):
                   - Open Metadata Engine Services: services/omes/index.md
                   - Governance Action: services/omes/governance-action/overview.md
-                  - Context Event: services/omes/event-action/overview.md
+                  - Context Event: services/omes/context-event/overview.md
                   - Survey Action: services/omes/survey-action/overview.md
                   - Repository Governance: services/omes/repository-governance/overview.md
               - Integration Services (OMIS):
@@ -768,6 +769,7 @@ nav:
       - Placeholders: concepts/placeholder.md
       - Platform Metadata Security Connector: concepts/platform-metadata-security-connector.md
       - Platform URL Root: concepts/platform-url-root.md
+      - Process: concepts/process.md
       - Project: concepts/project.md
       - pyegeria: concepts/pyegeria.md
       - Referenceable: concepts/referenceable.md

site/mkdocs.yml

@@ -2,7 +2,13 @@
 <!-- Copyright Contributors to the Egeria project. -->
 
 
-The *secrets store connector* provides access to secrets such as passwords and certificates that are stored in a secure location.  Its purpose is to remove the need to store secrets in Egeria's [configuration document](/concepts/configuration-document) or [open metadata repository](/concepts/open-metadata-repository).  With the secrets store connector, it is possible to manage secrets relating to a resource or service connected to the open metadata ecosystem in secure vaults or services managed by the security team.
+The *secrets store connector* provides access to secrets such as passwords and certificates that are stored in a secure location.  Its purpose is to remove the need to store secrets in Egeria's [configuration document](/concepts/configuration-document) or [open metadata repository](/concepts/open-metadata-repository).  
+
+With the secrets store connector, it is possible to manage:
+
+* A user directory containing log-on information (userId, password), groups and roles to support an authentication service, such as a token issuing service.
+* Secrets needed by a connector or other type of automated service in order to connect to a remote service.  This includes a description of the token API to call and the secret values to use.
+* Named lists of users, roles and groups that define access to specific resources.  These list are used to to support a service that is providing authorization control, such as the [Open Metadata Security Connectors](/features/metadata-security/overview/).
 
 The secrets store connector is typically embedded in a connector that needs one or more secrets to perform its tasks.  Both connectors are initialised together by the [ConnectorBroker](/concepts/connector-broker).  The secrets store connector is called by the surrounding connector to extract the needed secrets.
 
@@ -16,11 +22,11 @@ When the *ConnectorBroker* detects that there is a secrets connector embedded in
 
 This means that even if the outer connector is written to expect these secrets in its connection object, they do not need to be stored in the connection object (ie in the configuration document or in the metadata store) but will be placed in the right fields by the [ConnectorBroker](/concepts/connector-broker).
 
-If the name(s) of the secret(s) needed by the connector must be configured, they can be stored in the securedProperties.  The connector code knows the logical name and it looks up the real secret's name in secured properties.  Then the real secret's name is passed to the secrets store connector to do the look up for the secret value.
+If the name(s) of the secret(s) needed by the connector must be configured, they can be stored in the securedProperties.  The connector code knows the logical name and it looks up the real secret's name in secured properties.  Then the real secret's name is passed to the secrets store connector to do the look-up for the secret value.
 
-![Secrets store connector](/connectors/secrets/secured-properties.svg)
+![Secured properties](/connectors/secrets/secured-properties.svg)
 
-The picture below shows a practical example of using the secrets store connector.  It is embedded in an [integration connector](/concepts/integration-connector) which is deployed in a secured data centre to harvest metadata which is stored in an external cloud service.  The secrets store connector is initialized with the integration connector, both running in the secured data centre.  The secrets store connector uses a secrets store located in the secured data centre and managed by the data centre's team.  The data centre's team has complete control of the secrets that are being used by the integration connector and only the name of the secret is known outside of the secured data centre.
+The picture below shows a practical example of using the secrets store connector.  It is embedded in an [integration connector](/concepts/integration-connector) which is deployed in a secured data centre to harvest metadata into a metadata repository running in an external cloud service.  The secrets store connector is initialized with the integration connector, both running in the secured data centre.  The secrets store connector uses a secrets store located in the secured data centre and managed by the data centre's team.  The data centre's team has complete control of the secrets that are being used by the integration connector and only the name of the secret is known outside of the secured data centre.
 
 ![Secured data centre](/connectors/secrets/secrets-store-connector-example.svg)