Symantec Access Management

 View Only

RSSF - Symantec Directory Manager Tutorial - the CRUDs

  • 1.  RSSF - Symantec Directory Manager Tutorial - the CRUDs

    Broadcom Employee
    Posted Dec 21, 2021 06:35 PM

    Introduction

    This is the first Symantec Directory Manager RestAPI Shell Script Framework tutorial after the "Implementation and Getting Started" article. If you have gone through the "Getting Started" and the Self Registration operations there, this is your natural next step. You may also want to take a look at the "Registrar Proposal" article to get yourself more comfortable with the idea of having a designated "Registrar" Environment within a Directory Manager.

    Within this article, we explained the Authentication Module that allows all RestAPI endpoints, the conventions all the included samples observes and through the basic Create, Read, Update, and Delete operations, we also share with you some of the nuances when working with them.

    The Authentication Module

    The Authentication Module authn is located under the home directory. For this framework, it is invoked automatically right before a request is sent to an RestAPI endpoint. Within it, it contains the host name, port number and a base64 encoded Basic authentication header value.
    The utils/makeauthn.sh uses plain text values set in the utils/env.shlib to create this file. The utils/getstarted.sh actually invokes the makeauthn.sh to create the first authn file. If you need to change it, you can modify the utils//env.shlib and then issue

    bash utils/makeauthn.sh

    to make a new one. This allows you to connect to a different Directory Manager or change the admin password.

    Samples Conventions

    • Change Directry: to run any of the provided sample, we first need to change directory to the particluar subdirectory as all the samples are designed to run correctly that way.
    • README.md:  the README.md file describes what the operations the particular sample does.
    • env.shlib: Often we need to modify the env.shlib file provide the custom values we want to use to perform the operations designed by that example.
    • make.sh: We issue

      bash make.sh

      to perform the basic operation the particular sample offers. The make.sh is ususally designed to allow you to rerun it multiple times without ill effects.
    • unmake.sh: Similarly, the unmake.sh issued using

      bash unmake.sh

      is usually designed to undo what the make.sh does. This means that if you make mistakes when modifying the env.shlib, you usually can do the unmake.sh, correct the mistakes, and then redo the make.sh.
    • Other .sh scripts: there are may be other operations under a sample subdirectory. If so, these operations are described in the README.md.

    The Registrar Environment

    The samples/selfreg is designed to run on a Directory host with the dxagent installed and is suggested to run right after the installation. With the already configured Authentication Module, it creates the registrar Environment if necessary and register the Directory host as a dxagent on the registrar.

    We may want to modify the env.shlib to set NAME value and others. This Name becomes the dxagent name in the registrar Environment. 

    Since the make.sh needs to retrieve the dxagent client certificate/key pair and the CA certificate, it is easier to deploy and configure the framework after login using account dsa for a Linux host. For the Windows platform, just make sure the account you login has the privilege to access the three files.
    In addition to the creation of the registrar Environment and the addition of the dxagent to the Environment, this sample actually creates one Router DSA and one DATA DSA intended to be used as the sample DSAs for the particular Directory host. 

    Interactive Usage of the Framework

    This framework is designed to accept a single RestAPI invocation from the home directory of the deployment. It is one of the reasons why the jq command needs to be made available there. For example, the following command list all the dxagents that are registered in the registrar:

    bash dxagents/list.sh registrar

    Read Operations: read.sh, exist.sh, and list.sh

    • A read.sh is intended to retrieve the data through the Directory Manager RestAPI.
    • An exist.sh uses the corresponding read.sh to retrieve the data while interprets if the intended data actually exists. It uses the status code to indicate whether the data exists. When the data exists, the status code is 0, otherwise the status code is not 0.
    • list.sh uses exist.sh to determine its status code and a JSON array contains 0 or more objects.
    • For example,

      bash environments/read.sh registrar

      outputs a JSON representation of the registrar Environment. While

      bash environments/list.sh

      outputs a JSON array contains a list of Environments that exist in the Directory Manager the Authentication Module authn is configured.
    • Many of the read.sh's also accept a comma seperated attributes names so that instead of the default content, its output only includes the key attribute and the list of the attributes specified. For example:

      bash dxagents/read.sh registrar "" "host,port"

      outputs a JSON array where each element is a JSON object contains name, host, and port attributes.

    Create Operation and Templates

    One of the main challenges to use a JSON payload to create an object through RestAPI is to figure out a correct payload to use. Traditionlly, when we use a UI or a custom client program to perform the same task, many of the details are actually either hidden purposely or computed automatically through the tools we use.
    There are different types of templates included in this framewok. A typical template included is located under a temp subdirectory. A template file is often a bash shell script with a file name ending in .temp.
    The following is a snippet taken from the make.sh of the samples/selfreg:

    if ! EXIST=$(bash environments/exist.sh "$ENVNAME"); then
        JSON=$$.json
        bash environments/temp/****.temp "$ENVNAME" | \
            ./jq '. + { description: "Registrar Environment - do not edit"}' >$JSON
        EXIST=$(bash environments/create.sh "$JSON")
    fi
    echo "$EXIST" | ./jq '.'

    It first checks whether the Environment named in the ENVNANE variable exists. If not, it runs the bash shell script "environments/temp/****.temp" with the variable as an argument, modifies the output to set the description attribute using the jq command and stores the result into a JSON file. The environments/create.sh takes JSON file as a payload to create the registrar Environment.

    The following is the content of the environments/temp/****.temp:
    #!/bin/bash
    NAME=$1
    cat <<EOF
    {
      "name": "$NAME",
      "description": "$NAME Environment",
      "config": {
        "pollingInterval": 10
      }
    }
    EOF

    The environments/create.sh only needs a JSON file argument. Depends on the object we want to create, sometimes the create.sh needs other arguments. In general, the JSON file payload is set to be the last argument. For example the "bash dsas/create.sh envName dxaName JSONFile" is used to create a DSA.

    This framework and examples that comes with uses the template concept quite extensively and worths another tutorial of its own.

    Update Operation and JSON Payload Cleanse and Manipulation

    The update operation implemented by the Directory Manager RestAPI essentially requires all attributes to be included in the JSON payload. A typical update process starts with reading an object using read.sh or exist.sh to obtain its current JSON representation, changes the intended attributes, and then uses an update.sh with the object naming attributes and the JSON payload to update the intended object.

    In addition to the naming attributes, this RestAPI maintains a key attribute within a JSON representation and does not allow the key to be modified.  As a result, the key attibute in a JSON update payload is ignored and hence we can not rename an object.

    The read.sh sometimes retrieves more information than what is required to update an object or for that matter to create another object with a different key attribute. As an example, dxagents/temp/simple1.temp takes name, host, port, clientpem, clientkey, and capem to create a JSON payload suitable of adding a dxagent to an Environment. However, the top level attributes returned from a dxagent/read.sh operation actually gives two additional attributes, namely dsaJsonSchema and installationInfo. These two attributes are read-only system level attributes. Hence the dxagent update using a payload contains these two attributes could cause some confusing. As of the first release of this framework, cleanse.sh's are provided for dxagents and dsas. They take in a JSON input and attempt to remove the extra attributes to create a JSON payload more suitable for update and create operations.

    When a JSON representation is manipulated using jq, jq helps maintain its JSON syntactic soundness. However, the semantic correctness of a manipulated JSON representation is not simply not guarateed. A number of high-level operatoions are included in the franework to help inspire the possibilities of using the basic framework. For example, "dxas/ext/addpeers.sh ENVNAME DXA1 DSA1 DXA2 DSA2" can be used to create bidirectional peer knowledges between two DSAs.

    Delete Operations, Dispositions, and Side Effects

    In theory, a delete operation needs to clean up all references to the object to be deleted. For example, when a DSA is deleted, the knowledge of its peers should all be removed as well. For the most part, the Directory Manager RestAPI seems to do well. During the testing of this first release of the framework, we did find, however, when a DSA was removed, it was not being removed from the write-precedence settings references.

    The deletion of a dxagent or Environment does not cause any changes to any of exising DSAs. This is because these two types of objects exist only in the Directory Manager database. They are data existing there to help the management of the real DSAs.

    Environment Reconciliation Suggestions

    As of the first release of this framework, we have not yet explored the Environment Reconciliation.

    For now, we would suggest being careful with the Environment reconciliation operation or even avoid using it. What we know is that when a dxagent is added to an environment, all the existing DSAs will appear and link to the dxagent. As we are allowed to create multiple Environments, each with its own set of dxagents, the DSAs created under a dxagent later added to an Environment will not appear under a dxagent previously created under another Environment. The issue really becomes the purposes of using multiple Environments. Within this framework, we proposed a registrar Enviroment designed to hold all the dxagents under the same Directory Manager. This gives a hassle-free approach to create true operation Environments that consist only the involved dxagents and DSAs. Ideally, other than the registrar, we should avoid having a dxagent exists under multiple environments.

    Next Steps

    We have not yet explored the SCIM endpoints. They will be addressed at a later time.
    The next tutorial will focus on the various templates provided in the first release of this framework.