adrienaury/owl repository overview

⁠Owl CLI

Owl is a platform agnostic set of tools to manage realms of units, users and groups. Thanks to the modular conception, any backend can theorically be used to store and access data (LDAP, MySQL, MongoDB, ...). For now, only LDAP is supported, please open an issue if another one is needed.

The project is composed of 3 tools :

• Owl CLI : manage your realms with a powerfull devops CLI
• Owl REST API Server : equivalent to the CLI but with exposed REST Endpoints
• Owl Web Administration GUI : graphical user interface in front of the REST API Server

This repo is for Owl CLI.

⁠Concepts

Owl is opiniated on how to manage user accounts, but it is also highly customizable.

There is only 4 types of object manipulated.

Each object has a unique identifier and a set of prefefined properties that can be multivalued. Additional properties can be configured.

⁠Realms

Realms are associated with servers, instance, etc... where the data is persisted. Each realm is in isolation from other realms.

⁠Units

Units are logical grouping of users and groups, used to mimic real-world organization (like OU in LDAP).

⁠Users

⁠Groups

⁠Tools

⁠Owl CLI

First principle : Owl CLI respect the UNIX philosophy.

How ?

• it's simple, no complicated fanciness (like in LDAP for example)
• read inputs as json on the standard input by default
• write outputs as json on the standard output by default
• write logs on the standard error by default

Second principle : Owl is a devops tool.

Why ?

• it can be used by a human operator or automated by scripting
• local configuration is stored "as code" in the current directory
• every object can be serialized as JSON or YAML, if you need to store them in a code repository (like Git)

⁠Examples

⁠Manage realms

Create or modify realms with owl realm set command.

$ owl realm set dev ldap://dev.my-company.com/dc=example,dc=com cn=admin,dc=example,dc=com
Set realm 'dev' to 'ldap://dev.my-company.com/dc=example,dc=com'.

List created realms with owl realm list command.

$ owl realm list -o table
ID    Username                    URL
dev   cn=admin,dc=example,dc=com  ldap://dev.my-company.com/dc=example,dc=com
prod  cn=admin,dc=example,dc=com  ldap://prod.my-company.com/dc=example,dc=com

Login into a realm with owl realm login command. It is also possible to use the --realm flag on a specific command.

$ owl realm login dev
Password :
Connected to realm 'dev' as user 'admin'.

⁠Manage organizational units

Create a new unit with owl unit create command.

$ owl unit create my-unit Test unit
Created unit 'my-unit' in realm 'dev'.

Every create command also read JSON on stdin, so these are other ways of doing :

$ owl unit create <<< '{"ID": "my-unit", "Description": "Test unit"}'
Created unit 'my-unit' in realm 'dev'.

$ echo '{"ID": "my-unit", "Description": "Test unit"}' | owl unit create
Created unit 'my-unit' in realm 'dev'.

List existing units with owl unit list command.

$ owl unit list
ID       Description
my-unit  Test unit

To create users and groups, you first need to select a unit with owl unit use command. It is also possible to use the --unit flag on a specific command.

$ owl unit use my-unit
Using unit 'my-unit' for next commands.

⁠Manage users

To create a user, use owl user create command.

$ owl user create batman firstname=Bruce lastname=Wayne
Created user 'batman' in unit 'my-unit' of realm 'dev'.

$ owl user create <<< '{"ID": "batman", "FirstNames": ["Bruce"], "LastNames": ["Wayne"]}'
Created user 'batman' in unit 'my-unit' of realm 'dev'.

You can also create or replace an existing user with owl user apply command.

$ owl user apply firstname=Bruce lastname=Wayne [email protected]
Modified user 'batman' in unit 'my-unit' of realm 'dev'.

$ owl user apply joker firstname=Arthur lastname=Flake [email protected]
Created user 'joker' in unit 'my-unit' of realm 'dev'.

To only add a single attribute, use owl user append command.

$ owl user append joker firstname="Jack"
Modifier user 'joker' in unit 'my-unit' of realm 'dev'.

List user with owl user list command.

$ owl user list
ID      First Names   Last Names  E-mails
batman  Bruce         Wayne       [email protected]
joker   Arthur, Jack  Flake       [email protected]

Give user a random password with owl user new-password command.

$ owl user new-password joker
Assigned new random password to user 'joker' in unit 'my-unit' of realm 'dev'.

⁠Manage groups

You guessed it, use owl group create command to create a group.

$ owl group create bad-guys member=joker member=batman
Created group 'bad-guys' in unit 'my-unit' of realm 'dev'.

Member list can be modified with owl group member sub-commands.

$ owl group member remove bad-guys batman
Modified group 'bad-guys' in unit 'my-unit' of realm 'dev'.

$ owl group member add good-guys batman
Modified group 'good-guys' in unit 'my-unit' of realm 'dev'.

⁠Advanded commands

All commands can output results in JSON or YAML format, thanks to the --output (short -o) flag.

$ owl user list -o json
{"Users": [{"ID": "batman", "FirstNames": ["Bruce"], "LastNames": ["Wayne"], "Emails": ["[email protected]"]}, {"ID": "joker", "FirstNames": ["Arthur", "Jack"], "LastNames": ["Flake"], "Emails": ["[email protected]"]}]}

This universal interface enable the use of other programs, for example jq.

$ owl user list -o json | jq
{
    "Users": [
        {
            "ID": "batman",
            "FirstNames": [
                "Bruce"
            ],
            "LastNames": [
                "Wayne"
            ],
            "Emails": [
                "[email protected]"
            ]
        },
        {
            "ID": "joker",
            "FirstNames": [
                "Arthur",
                "Jack"
            ],
            "LastNames": [
                "Flake"
            ],
            "Emails": [
                "[email protected]"
            ]
        }
    ]
}

$ owl user ls -o json | jq ".Users | [.[].ID]"
[
  "batman",
  "joker"
]

Owl also understand JSON if passed throught stdin, this enables chaining of owl commands.

$ owl user list -o json | owl import --realm=prod --unit=organization
Imported 2 users in unit 'organization' of realm 'prod'.