Command line tools for OA4MP

These are a set of programs that are accessible from a CLI (command line interface) allow an administrator to do CRUD (Create, Read, Update and Delete) operations on client records and approvals. There is also the option to copy a store completely from one store to another.

Getting the tools

OAuth 1.0a
The latest version of the Oauth 1.0a command line tool is available at oa4mp-cli.jar You should also get the script that runs this too, oa4mp-cli
Oauth 2.0
The latest version of the Oauth 2.0 command line tool is available at oa2-cli.jar You should also get the script that runs this too, oa2-cli

Configuration

The tool uses a standard configuration file exactly like the server. Indeed, you can just point the tool at the server configuration file. You will need to supply the name of the configuration in the file you want to use. Aliases can be quite handy here. Given the abilities of the CLI to do quick copies of the store, it pays to have a backup (file) store configured and occasionally simple copy the active store to that. There are many possible uses. It is assumed that the tools are installed in a location called $OA4MP_HOME. Normally the default for this is

OAuth 1.0a: OA4MP_HOME=/opt/oa4mp

OAuth 2.0: OA4MP_HOME=opt/oa2 Note that we will be discussing the OA4MP tools rather than the OA2 tools in what follows. Everything here works the same if you replace oa4mp-* by oa2-*

The assumption of the script is that files are in the following directory structure

  • $OA4MP_HOME/etc/admin-cfg.xml - the configuration file
  • $OA4MP_HOME/lib/oa4mp-cli.jar - the jar containing the CLI
  • $OA4MP_HOME/bin/oa4mp-cli - the script for running this. Be sure it is set to be executable.
The default name of the configuration is assumed to be "default" (no quotes). If you invoke the script with no arguments it will use this and the above configuration file.

Running the CLI

Invocation from the command line is usually done with the supplied shell script, oa4mp-cli. The invocation syntax is
oa4mp-cli [configName configFile]
You should run this as root and might need to set the script to be executable if it is not. If you give neither arguments then defaults are used. Invoke with the argument "--help" for more information. If you give one argument it is assumed to be the configuration name in the default configuration file.

Command line options for the jar.

You should run this from the script, but if you want or need to specify invoke the jar directly, the invocation options they are listed here.
Argument Value required? Required? Description
-cfg Y Y The full path to the configuration file.
-name F F The name of the configuration within the file. If there is a single configuration in the file, then no name is needed. If there are multiple configurations you must specify which one to use.
-log F F The full path log file. If this is not specified then a file named "log.xml" is dumped into the invocation directory.
-use F F Specify the component to use. Rather than loading the whole CLI then use-ing a components (such as clients) you may simply specify that here.
-v F F No argument. Turns on verbose logging so that much more information is dumped onto the console. This is useful for debugging or just if you want to see what it is up to.
    java -jar oa4mp-cli.jar -cfg /path/to/cfg.xml -name myConfig -log /path/to/mylog.xml -use approvals
This would load the configuration named "myConfig" from the given file, write the log to a file called "mylog.xml" and bring up the approvals component.

Running the tool

The CLI consists of utilities for each component that can be used. Once invoked you will see the startup banner and prompt:
[mybox bin]# ./oa4mp-cli
**********************************************************
* OA4MP CLI (Command Line Interpreter)                   *
* Version 4.0.1                                          *
* By Jeff Gaynor  NCSA                                   *
*  (National Center for Supercomputing Applications)     *
*                                                        *
* type 'help' for a list of commands                     *
*      'exit' or 'quit' to end this session.             *
**********************************************************
oa4mp >
If you type "help" You will get
oa4mp >help

Here are the commands available:
use
load
To get more information on a command type

command --help
Basic supported commands are
  • use - specify a component to use.
  • load configName [configFile] - load the given named configuration from the current config file. Specify the config file if you need a different one.
To see the help for, say, the use command you would issue
 oa4mp> use --help

 Choose the component you wish to use.
 you specify the component as use + name. Supported components are
 clients - edit client records
 approvals - edit client approval records
 copy - copy an entire store.

 e.g.

 use clients

 will call up the client management component.
 Type 'exit' when you wish to exit the component and return to the main menu
Each of these components; clients, approvals and copy is described in detail below. But first, a few preliminary notions.

Index vs. Unique ID

Since most objects have unique identifiers, you can specify these are arguments at any time it makes sense to do so by prefixing the id with a forward slash, "/". If there is a list of objects, you can also specify the index on the list as the target of the operation. Most components have a command to list everything in the active component (the ls command).

After you issue an ls (no arguments) you will see a complete list of items in the store. These are numbered on the right hand side. This is the item's index. You may then specify the index directly. E.g. to print out a long version of the item with index 4 issue

ls 4

Typically you will know the unique identifier for an item and you can enter this if you escape it with a forward slash (/). To give the long listing of an object with unique identifier myproxy:oa4mp,2012:/client/a4b78549990 you would issue

ls /myproxy:oa4mp,2012:/client/a4b78549990

Note that since there is no canonical ordering of objects in a store, you should always issue an ls before using the index. It is generally always safer to use the unique identifier.

Options supported in each storage tool.

Each of these in turn will be discussed in detail.

Common commands for all storage components.

Getting The Number Of Objects In a Component.

This will print the number of elements in the current storage component.
Example. For showing the number of clients in a store you would have something like the following
oa4mp >use clients
  clients >size
    Current store has 22 entries
  clients >exit
exiting ...
oa4mp >

Listing Object or Details of an Object.

This lists every element in the current component. The default is to sort by the given identifier. Clients are sorted by creation date. At this point, sorting behavior cannot be changed. Each record is recorded on a single line. No argument prints out everything in the store. Giving the optional index or unique identifier will print a detailed listing of the object.
Example. Listing a specific object by unique identifier
oa4mp >use approvals
  approvals >ls
  0. ClientApproval[approved=true, approver=null, id=myproxy:oa4mp,2012:/client/468afcd5f598227e1a0b79e6e94b3506, on Mon Apr 01 11:37:58 CDT 2013]
  1. ClientApproval[approved=true, approver=auto-approver, id=myproxy:oa4mp,2012:/client/1e4310262889ebdf72b8a7b148acdf2a, on Mon Jul 09 16:21:47 CDT 2012]
  approvals >
and now print out the details on number 1:
  approvals >ls 1

Approver:auto-approver
  Identifier:myproxy:oa4mp,2012:/client/1e4310262889ebdf72b8a7b148acdf2a
  Approved at:Mon Jul 09 16:21:47 CDT 2012
  Is approved? true
  approvals >
We could have done the exact same thing by simply using the unique identifier:
    approvals>ls /myproxy:oa4mp,2012:/client/1e4310262889ebdf72b8a7b148acdf2a

Approver:auto-approver
  Identifier:myproxy:oa4mp,2012:/client/1e4310262889ebdf72b8a7b148acdf2a
  Approved at:Mon Jul 09 16:21:47 CDT 2012
  Is approved? true
  approvals >

Another option is the flag -la which will print all the details of every item it applies to. For instance, to get a dump of every approval record in detail issue

        approvals>ls -la
    

The output is extremely lengthy however it is an easy way to get a text dump of a store. This flag has no effect if it is given for a specific id. All that will happen is that details of that id will be printed in full.

Updating (aka Editing) Objects.

This will let you update or edit an existing object. The general function is shown below. Current object values are shown in [ ]'s and simply hitting return will preserve the current value.
Example. Edit a client record. In this case we want to make this client use limited proxies.
    oa4mp >use clients
      clients >update /myproxy:oa4mp,2012:/client/6eb6ef83dbb89e7212cde073c7e682a4
      Update the values. A return accepts the existing or default value in []'s
        enter the identifier[myproxy:oa4mp,2012:/client/6eb6ef83dbb89e7212cde073c7e682a4]:
        enter the name[Another Ashigaru Gateway]:
        enter email[jgaynor@ncsa.illinois.edu]:
        enter error uri[http://ashigaru.ncsa.uiuc.edu:44444/client]:
        enter home uri[http://ashigaru.ncsa.uiuc.edu:44444/client]:
Up to this point we have changed nothing and have hit return each time. Now we change the value:
        does this client require limited proxies?[n]:y
        enter full path and file name of public key[-----BEGIN PUBLIC KEY----...]:
         public key entry skipped.
That finishes the entry for the client. Had we wanted to change the public key, we would have supplied a a file with complete path containing it. The system then prints out the entire new object and prompts us to save it:
        here is the complete client:
    Client name=Another Ashigaru Gateway
        identifier=myproxy:oa4mp,2012:/client/6eb6ef83dbb89e7212cde073c7e682a4
        email=jgaynor@ncsa.illinois.edu
        home uri=http://ashigaru.ncsa.uiuc.edu:44444/client
        error uri=http://ashigaru.ncsa.uiuc.edu:44444/client
        limited proxies? true
        creation timestamp=Thu Jun 28 13:46:31 CDT 2012
        approved by auto-approver
        public key:
      -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAruhBa7EAnm8zDeBhNmuhYLUcij5pSr5r
    Z6481lhzvs0k+EtCsuDpr4RlcxUlX90uxF7ZsCjMSnk8pPr4e5HPu9lqr3wUb1TJbPbg3hdj/06O
    sJrOUYddVG5SmkafsCMmn+i5SrYq9vuWRsYVXZM36p/BzBzn4s4r6JqFzRWX71U9YybVCR72AIGi
    LClW2utUP3Q6axpDgkEXl6CuloGDshr1cMpct2/cpDqj6kpv5oV3WFUDiXf33kwqmBWjmXwCMTSu
    wAVhUmJNZ48YdnTQcotMURo9j5a1DBk1t2hKj/W7HqwT+TxnLgDu/cVxX5ZJDNTlgMaTbZKOFUhA
    MMnssQIDAQAB
    -----END PUBLIC KEY-----

        save [y/n]?y
        client updated.

Creating a new object

To create a new object, you must supply a unique identifier. This does not need to be escaped with a /. Once created, you will be given the option of editing it. You may enter any valid identifier as long as it is a valid URI
Example. Crreating a new client. This will create a new client with a specified identifier. If no identifier were supplied a random one would have been created.
    clients >create my:new:client
    Created object with id "my:new:client"
The object already exists in the store by this point. We will be given the option to edit it (equivalent to issuing the update command against its unique id):
      edit [y/n]?y
    Update the values. A return accepts the existing or default value in []'s
      enter the identifier[my:new:client]:
      enter the name[(null)]:My new client
      enter email[(null)]:foo@bar.baz
      enter error uri[(null)]:http://localhost/error
      enter home uri[(null)]:https:/localhost/home
      does this client require limited proxies?[n]:n
      enter full path and file name of public key[(null)]:
      No file entered. Public key entry skipped
Now the completed, new client is displayed and we are prompted if we want to keep the changes.
      here is the complete client:
    Client name=My new client
      identifier=my:new:client
      email=foo@bar.baz
      home uri=https:/localhost/home
      error uri=http://localhost/error
      limited proxies? false
      creation timestamp=Wed Nov 20 11:54:55 CST 2013
      no approval record exists.
      public key:
      none
      save [y/n]?y
      client updated.

Removing Objects From the Store.

Removing an object. This will remove the object completely from the store. In the case of clients you do not need to remove the corresponding approval -- it will be done automatically. However, if you remove the approval record then the client is in effect unapproved until you re-approve it. To remove the client we create with id my:new:client would look like the next
Example. Removing an object by id
    clients >rm /my:new:client
      Removing approval record
      Done. Client approval with id = my:new:client has been removed from the store
      removing client record
    Done. object with id = my:new:client has been removed from the store
Note The remove command will happily remove objects by index, but remember that the indices of all other objects change, so best practice is to only remove by identifier.

Storing objects on disk

    serialize [-file path] index

A common enough task is to want to do a considerable amount of editing which the direct CLI is not so well suited for, e.g. twiddling extensive lists of callbacks. This is always component specific, so you must use a comnponent for this to be available. You may serialize any object to disk in XML format, edit it with any standard text editor and then simply read it back in with the deserialize command. The basic syntax is

In this case, the index is as per any other component. The file is optional in the sense that if it is omitted, the result will be dumped at the command line. The file will be overwritten, so make sure you have it right.
Example. Serializing a client.
    cli> use clients
      clients> serialize -file /path/to/my/client.xml /client:sdfsdf:erg98540j034/456eythw456
    done!
Firing up a text editor shows the file which starts to look like this:
    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
    <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
    <properties>
    <entry key="name">Updated Test client 42</entry>
    <entry key="sign_tokens">true</entry>
    <entry key="creation_ts">2018-06-28T13:06:28.000Z</entry>
    <entry key="public_key">j75OY1FoPf1AzW5v9KDqTkxrslD1VQhQ5wdVfqUu7pO7SRoMtEwRXqBdFFtNfwmX0Z4l4vbiVRYpq9zGtoMKYw</entry>
    <entry key="rt_lifetime">456767875477</entry>
    <entry key="public_client">false</entry>
    <entry key="client_id">testScheme:oa4md,2018:/client_id/756a9e899981a4cf93f97f40a9da345a</entry>
    <entry key="home_url">https://baz.foo.edu/H2w3GevCrOU/home</entry>
    <entry key="cfg">{
      "config": "updated by converter from old LDAP entry",
      "claims": {
        "sourceConfig": [
          {
     ... lots more
Note that the format is very simple. A key is given (you cannot change these) and then the value is given as the contents of the element.

Reading objects from disk

    deserialize [-new] -file path

This will read an object from a file. This is always component specific, so you must use a comnponent for this to be available. You may specify it as being new, which will also tell the system to create a new identifier for it or it will reject the object if an existing identifier exists. NOTE: This will replace the object, not just update a few attributes. This means that if you just want change the value of an attribute, you have to do it manually.

Example Deserializing a file
    clients> deserialize -file /path/to/my/file
    done!

This will take the given file and replace the contents. A not uncommon use is to serialize a file, edit it and issue deserialization commands against it repeatedly as you debug it.

Invoking the components.

Clients

Invoke as
oa4mp> use clients
Operations allowed in addition to the standard ones are
  • approve [index | /uniqueID]
  • create_hash [string | -file path]
The first will prompt you for the information needed to make a new approval for the client with the given id. The second is used to create a hash for a secret that you supply. This is needed for OAuth2/OIDC clients since we store a hash and not the secret. You may either specify a file containing the secret or type in manually at the command line.

Approvals

Invoke as
oa4mp> use approvals
There are no extra options beyond the standard ones, however, the create command takes the unique id of the client record you are going to approve. Once created, you may enter the approval information directly.

Copy

Invoke as
oa4mp>use copy
Supported operation is
  • cp source target [-verify] - copy source to target optionally verifying
This works over the entire store. It has a single command that will allow you to make a copy of one store (the source) that completely replaces another (the target). This is destructive, meaning that the every object in the target is deleted, so no merge takes place. If the -verify option is used then the two stores are compared once the copy has been completed. Note that this can be very time consuming for a large store! However, if there is any question it is at times very useful.

Last modified 10/25/18.
©2000-2013 Board of Trustees of the University of Illinois.