[[TOC]]

Ligoj CLI makes REST calls to a remote Ligoj instance, with parameters and error handling.

• Python 3.11+
• Connectivity and API keys to target endpoints Ligoj, Nexus, Jenkins, SonarQube
• pip
• Valid credentials

Ligoj credentials are based on user/password or user/API Key.

Populate the configuration files with the API key created here #/api/token ("?" > "Api" > "Token")

You can also:

• use the session login command to get a temporary session
• use the token command to create durable API keys

For standard actions, only LIGOJ_ENDPOINT is required and can be set either in the configuration files, as an environment variable, or as a CLI option.

For bootstrap actions, more endpoints and credentials may be required in the configuration files.

Sample usage:

ligoj \
--api-user="ligoj-admin" \
--api-key="..." \
--endpoint="http://localhost:8080/ligoj" \
--version

Options are sourced in the following order of priority, from highest to lowest:

1. Command line options – Overrides settings in any other location, such as the --output and --profile parameters.
2. Environment variables – You can store values in your system's environment variables.
3. Session file – default section or given profile name. The session file is located at ~/.ligoj/sessions on Linux or macOS and holds:

• Session cookies set with the login command.
• API keys set with the login command.

4. Credentials file – default section or given profile name. The credentials file is located at ~/.ligoj/credentials on Linux or macOS.
5. Configuration file – default section or given profile name. The config file is located at ~/.ligoj/config on Linux or macOS. Alternative file ~/.ligoj/cli-config is supported.

Sections in these .ini files correspond to profile names. The default profile name is default and is used when no --profile option and no LIGOJ_PROFILE are provided.

In the file ~/.ligoj/config, default configurations can be specified. No secrets are sourced from this file.

[default]
output = "json"
log_level = "DEBUG"
endpoint=http://localhost:8080/ligoj
jenkins_endpoint=http://localhost:8086
sonar_endpoint=http://localhost:9000/

[some]
output = "json"

Read-only secrets are stored in the ~/.ligoj/credentials file.

Temporary secrets (stored from the session command) are stored in the ~/.ligoj/sessions file.

While ~/.ligoj/credentials can contain configuration settings, secrets are only sourced from the ~/.ligoj/credentials and ~/.ligoj/sessions files.

Sample credential file:

[default]
api_user = ligoj-user1
api_key = secret
jenkins_api_user = admin
jenkins_api_token = secret
sonar_api_token = secret

Note Leading spaces are ignored, and enclosing ' and " are removed. Empty strings are ignored.

The generic options are available to all actions.

Determines the output mode of the command. Use the --output option. The following modes are available:

• json : JSON format
• text : Text format

This option can also be specified in configuration files as output or in environment variable LIGOJ_OUTPUT

ligoj --output json --version
ligoj --version

{"version": "3.3.1-SNAPSHOT"}

ligoj --output text --version

3.3.1-SNAPSHOT

To configure the verbosity, use the --log-level option. The following levels are available:

• TRACE level displays the in/out data. --verbose and --trace are shortcuts for this level.
• DEBUG level displays the internal API calls --debug is a shortcut for this level.
• INFO level displays the actions
• WARN level displays the unexpected behaviors
• ERROR level displays only fatal errors

This option can also be specified in configuration files as log-level or in environment variable LIGOJ_LOG_LEVEL

ligoj --log-level INFO ....
ligoj --verbose ....
ligoj --trace ....

If you want to pipe JSON result to jq, use --output json and --log-level ERROR options.

To allow insecure server connections when using SSL, use the --insecure option. This option can also be specified in configuration files as insecure or in environment variable LIGOJ_INSECURE

ligoj --insecure ....
ligoj --k ....

Ligoj API user name. Use the --api-user option. This option can also be specified in configuration files as api-user or in environment variable LIGOJ_API_USER. By default is ligoj-admin.

ligoj --api-user ligoj-admin ....

Provide an API key, which can be created here #/api/token ("?" > "Api" > "Token"). Use the --api-key option. This option can also be specified in configuration files as api-key or in environment variable LIGOJ_API_KEY

ligoj --api-key secret ....

Ligoj API user name for impersonation. Use the --api-run-as-user option. This option can also be specified in configuration files as api-run-as-user or in environment variable LIGOJ_API_RUN_AS_USER.

Constraints are:

• After the authentication succeeds with --api-key and --api-user
• The current user must have POST /system.user authorization
• --api-run-as-user must exist
• The actions are executed in the name of --api-run-as-user and without needing the related credentials.

This option can also be specified in configuration files as api-run-as-user or in environment variable LIGOJ_API_RUN_AS_USER.

ligoj --api-run-as-user ligoj-user ....

Restrict the computed roles to the local roles of the authenticated user. No plugin roles are involved. This flag makes the authentication independent of the configured plugins (e.g., availability, misconfiguration, etc.).

Since this flag reduces the set of available roles, there is no restriction on the usage.

This option can also be specified in configuration files as api-local-roles or in environment variable LIGOJ_API_LOCAL_ROLES.

ligoj --api-local-roles session get

Ligoj profile name to read from configuration files, credentials, config, and sessions. Use the --profile option. This option can also be specified with environment variable LIGOJ_PROFILE. The default is default.

ligoj --profile some ....

JSON content to load. Use the --from option. The following forms are available:

• Path to a local JSON file
• Remote HTTP URL
• Inline JSON string

After the content has been retrieved, it is interpolated with Jinja with current project (project) and environment variables (env) as context:

• For example:
  • {{ project.id }} is replaced by the project identifier.
  • {{ env.ENV_VAR }} is replaced by the ENV_VAR environment variable value.
  • $${_not_existing_property_in_context_} is replaced by an empty string.
• null values are considered as empty string
• The context depends on the current action. Usually, all given parameters are added to the context.
• The context is completed with environment variables.
• Surrounding spaces inside {{..}} are ignored

Disable colors in messages. Use the --no-color option. This option can also be specified in configuration files as no-color or in environment variable LIGOJ_NO_COLOR

ligoj --no-color ....

Fail (exit code 1) when any hook returns a failure status (X-Ligoj-Hook-*=FAILED). See hooks for more details. Use the --fail-on-hook-error option. This option can also be specified in configuration files as fail-on-hook-error or in environment variable LIGOJ_FAIL_ON_HOOK_ERROR

ligoj --fail-on-hook-error ....

Fail (exit code 1) when any hook returns a failure status (X-Ligoj-Hook-*=FAILED). See hooks for more details.

Hooks status and message are displayed with DEBUG log level:

[DEBUG] [ligoj] Hook 'audit_role_change' status: SUCCEED
[DEBUG] [ligoj] Hook 'audit_role_change' status: FAILED: Message for user

Session operations with credentials and profile management.

Verify the provided user and password and save the returned session cookie into the ~/.ligoj/sessions file for further API call without providing credentials.

Note Secrets like api-user and password are sourced from the CLI options, sessions and credential files, not from the configuration one.

ligoj --api-user "ligoj-admin" --profile default session login --password secret
ligoj --api-user "ligoj-admin" login session --password secret

Completed ~/.ligoj/sessions file:

[default]
session = session_secret_value.node0
api_user = ligoj-admin

Verify the provided user and API key and save the provided API user and API keys into the ~/.ligoj/sessions file for further API call without providing credentials.

Note Secrets like api-user and password are sourced from the CLI options, sessions and credential files, not from the configuration one.

ligoj --api-user "ligoj-admin" --api-key "__api_key__" session login

Return user session details

ligoj session get

{
  "applicationSettings": {
    "buildNumber": "", "buildTimestamp": "", "buildVersion": "3.3.1-SNAPSHOT", 
    "digestVersion": "rRXmeWPgn+...==",
    "plugins": ["feature:welcome:data-rbac"]
  }, 
  "userSettings": {"restricted-hash--": "#/home/project/1/subscription/1002", "security-agreement": "1"}, 
  "uiAuthorizations": ["^id/container/group.*", "^id/user.*", "^id/delegate.*", "^message.*", "^id$", "^home.*", "^id/container/company.*", "^api.*", "^id/home.*", ".*"], 
  "apiAuthorizations": [{"pattern": ".*", "method": "DELETE"}], "roles": ["ADMIN", "USER"], "userName": "ligoj-admin"
}

Return user identifier

ligoj session whoami

{"id": "ligoj-admin"}

A system user can live without federated identity. After a successful login, a federated user can be managed with system roles and API keys.

Create a new system user with role names or identifiers.

ligoj user upsert --id [email protected] --roles USER ADMIN

Optionally, at this time, an API key is generated but only once and only from administrator users.

ligoj user upsert --id [email protected] --roles USER ADMIN --api_key_name cli

Output the API key only if not existing.

{"id": "__api_key__", "name": "cli"}

Note When role names are provided API calls are executed to retrieve their identifiers.

Delete a system user. The command will not fail if the user is not found.

ligoj user delete --id ligoj-user

ligoj user list
ligoj user list --with-roles

{"recordsTotal": 3, "recordsFiltered": 3, "data": ["ligoj-admin", "[email protected]", "ligoj-user"]}

Note When role names are provided API calls are executed to retrieve their identifiers.

Create a new system user with role names or identifiers.

ligoj user delete --id ligoj-user

A system role holds the permissions (ui and api), and can be assigned to users or groups.

Create or update a system role.

Note Whereas Ligoj supports per HTTP method authorizations, this feature is not yet available from this CLI action.

# Deprecated `--id` option
ligoj role create --id ADMIN --api ".*" --ui ".*"
ligoj role create --name ADMIN --api ".*" --ui ".*"
ligoj role create --name SELF_TOKEN_RENEW --api "/api/token.*" --ui "/sys/token"

Output is the created/existing role identifier.

123

Delete a system role. The command will not fail if the role does not exist.

ligoj role delete --id 1
ligoj role delete --name ADMIN

ligoj role list

ligoj role get --id 1
ligoj role get --name ADMIN

{"id": 1, "createdBy": "_system", "createdDate": 1758279349911, "lastModifiedBy": "_system", "lastModifiedDate": 1758279349911, "name": "ADMIN"}

Return API server status

ligoj info status

{"status": "UP"}

Optionally, a wait for status can be defined. A regular poll to the server status is performed until reaching DOWN or UP status. When different from 0, the final status is returned.

ligoj info status --wait 20

{"status": "DOWN"}

Return API server version

ligoj info version
ligoj --version
ligoj -v

{"version": "3.3.1-SNAPSHOT"}

All Ligoj APIs are accessible with REST verbs.

Currently 3 specification formats are available:

• Swagger : Web UI based on OpenAPI JSON file
• OpenAPI JSON file
• WADL

ligoj info api --output openapi --print content
ligoj info api

{
  "openapi" : "3.0.1",
  "info" : {
    "title" : "Ligoj API application",
    "description" : "REST API services of application. Includes the core services and the features of actually loaded plugins",
    "contact" : {
      "name" : "The Ligoj team",
      "url" : "https://github.com/ligoj"

ligoj info api --output wadl --print url
ligoj info api --output openapi --print url
ligoj info api --output swagger --print url

http://localhost:8080/ligoj/rest?_wadl
http://localhost:8080/ligoj/rest/openapi.json
http://localhost:8080/ligoj/api-docs?url=openapi.json

Manage API keys of current user.

For expiration option:

• Either a full ISO date, which corresponds to the furthest date the generated token can be trusted.
• Either a duration starting from now, in a standard duration format. See pytimeparse

Expired tokens are neither listed nor returned even if they are not yet physically deleted.

ligoj token create --id cli_init
ligoj token create --id today_only --expiration 1d
ligoj token create --id SELF_TOKEN_RENEW --expiration 2029-12-31T23:59:59

Optionally, the created token can be saved into the current profile, replacing any previously existing one:

Output:

{"id": "__api_key__", "name": "cli_init"}

ligoj token list

["cli_init", "test"]

ligoj token get --id cli_init

```json
{"value": "__api_key__"}

ligoj token delete --id cli_init

Return API server version

ligoj info version
ligoj --version
ligoj -v

{"version": "3.3.1-SNAPSHOT"}

Configure global values

ligoj configuration set --id "foo" --value "bar"
ligoj configuration set --id "plugins.repository-manager.nexus.search.url" --value "https://localhost/?g:org.ligoj.plugin"
ligoj configuration set --id "plugins.repository-manager.nexus.search.proxy.host" --value "my-proxy.local"
ligoj configuration set --id "plugins.repository-manager.nexus.search.proxy.port" --value "8080"
ligoj configuration set --id "plugins.repository-manager.nexus.artifact.url" --value "https://nexus.localhost:8443/repository/maven_corporate/org/ligoj/plugin/"
ligoj configuration set --id "cache.id-ldap-data.ttl" --value "3600"

Note When you change a configuration related to plugin management, invalidate the related caches to retrieve the up-to-date plugin versions.

Return the configuration value from its id, which can be a Java property name or a stored value in the S_CONFIGURATION table.

Return a specific value. Encrypted values are returned as decrypted.

ligoj configuration get --id "foo"

{"value": "bar"}

Return all values. Encrypted values are not returned.

ligoj configuration get

[{"name": "COMMAND_MODE", "value": "unix2003", "persisted": false, "secured": false, "overridden": false, "source": "systemEnvironment"},...]

ligoj configuration delete --id "foo"

ligoj cache invalidate --id "node-parameters"
ligoj cache invalidate --id "nodes"
ligoj cache invalidate --id "iam-node-configuration"
ligoj cache invalidate --id "id-ldap-data"
ligoj cache invalidate --id "user-details"
ligoj cache invalidate --id "plugins-last-version-nexus"
ligoj cache invalidate

ligoj cache get --id "user-details"

{
    "id": "user-details", 
    "size": 1, 
    "hitCount": 123, 
    "missCount": 14, 
    "hitPercentage": 89.78102, 
    "missPercentage": 10.218978, 
    "averageGetTime": 16.860365, 
    "node": {"id": "00000000-0000-0000-0000-000000000000", "address": "[127.0.0.1]:5701", "version": "5.3.2", "cluster": {"id": "00000000-0000-0000-0000-000000000001", "state": "ACTIVE", "members": [{"id": "00000000-0000-0000-0000-000000000000", "address": "[127.0.0.1]:5701", "version": "5.3.2"}]}}
}

ligoj cache list

[
    {"id": "terraform-version", "size": 0, "hitCount": 0, "missCount": 0, "hitPercentage": 0.0, "missPercentage": 0.0, "averageGetTime": 0.0, "node": {"id": "00000000-0000-0000-0000-000000000000", "address": "[127.0.0.1]:5701", "version": "5.3.2", "cluster": {"id": "00000000-0000-0000-0000-000000000001", "state": "ACTIVE", "members": [{"id": "00000000-0000-0000-0000-000000000000", "address": "[127.0.0.1]:5701", "version": "5.3.2"}]}}},
    ...
]

A file is a remote file readable and/or writable by the API container.

Related path must be authorized by the configuration value ligoj.file.path. This check is performed at upload and download times.

ligoj configuration set --id "ligoj.file.path" --value "^/home/files/.*,^/home/hooks/.*,^/home/ligoj/META-INF/resources/webjars/.*,^/home/ligoj/statics/themes/.*"

Upload a local file to a remote file.

ligoj file put --from https://path/to/icon.png --path "/home/ligoj/icon.png"
ligoj file put --from docs/ui/logo.png --path "/home/ligoj/META-INF/resources/webjars/home/img/logo.png"
ligoj file put --from docs/ui/bg1.jpg  --path "/home/ligoj/statics/themes/bootstrap-material-design/img/bg1.jpg"
ligoj file put --from docs/ui/logo.png --path "/home/ligoj/statics/favicon.ico"
ligoj file put --from docs/ui/logo.png --path "/home/ligoj/statics/themes/bootstrap-material-design/ico/favicon.ico"

ligoj file delete --path "/home/ligoj/icon.png"

Download a remote file and save it to a local file.

ligoj file get --path "/home/ligoj/icon.png"  --out "./icon2.png"

A hook is a command uploaded by a user, and triggered by a successfully invoked API call of Ligoj.

When this command is executed, it receives a PAYLOAD event as environment variable.

Related command must be authorized by the configuration value ligoj.hook.path. This check is performed at creation and execution time:

ligoj configuration set --id "ligoj.hook.path" --value "^/home/ligoj/hooks/.*"
ligoj configuration set --id "ligoj.file.path" --value "^/home/ligoj/hooks/.*"
ligoj file put --from docs/sample_hook_ligoj_audit.sh  --path "/home/ligoj/hooks/ligoj_audit.sh"  --executable

Payload structure:

{
  "name":"audit_role_change",
  "now":"2023-10-17T19:22:21Z",
  "result":{"some_json":"some_value"},
  "path":"system/security/role",
  "api":"RoleResource#update",
  "params":[{"id":2652, "name":"ADMIN_PROJECT1A"}, {}],
  "method":"PUT",
  "user":"ligoj-admin",
  "timeout":30,
  "inject": {"secret1":"value1","secret2":"value2"}
}'

# Asynchronous hook
ligoj hook upsert --name "audit_role_change" --command "/home/ligoj/hooks/ligoj_audit.sh" --directory /var/log --timeout 10 --match '{"path":"system/security/role.*"}' --inject secret1 secret2

# Synchronous hook
ligoj hook upsert --name "audit_role_change" --command "/home/ligoj/hooks/ligoj_audit.sh" --directory /var/log --timeout 10 --match '{"path":"system/security/role.*", "method":"POST"}' --inject secret1 secret2 --delay 0

Note

• For Docker image runtime, this program is executed by the container ligoj-api, and must be resolvable. Either this program is already packaged in the container, or it is mounted as a Docker volume to the host. Usually the mounted volume is /home/ligoj and points to the host path such as /var/path/to/ligoj. In the above hook sample, the user-level script would be /var/path/to/ligoj/ligoj_audit.sh.
• --name The human readable hook name. Is displayed in logs and HTTP headers of synchronous executions.
• --command The command to execute. Must be allowed by ligoj.hook.path configuration. This condition is checked at creation and execution time.
• --directory The working directory where the hook is executed.
• --inject Can relate to any configuration names supported by the configuration get command and will be provided in the payload variable.
• --match Must be a valid JSON stringified object having :
  • at least the path property relating to a valid regular expression matching to one of the available Ligoj's endpoint.
  • an optional method property corresponding to ["DELETE", "GET", "HEAD", "OPTIONS", "PATCH", "POST", "PUT", "TRACE"].
• --delay The delay in seconds before the hook is executed. Default to 1. Use 0 for synchronous hooks.
• --timeout The timeout in seconds before the hook is executed. Default to 10.

Sample executable hook script /home/ligoj/ligoj_audit.sh:

#!/bin/bash
payload="$(echo "$PAYLOAD" | base64 -d)"
echo "$(echo "$payload"|jq -r '.now') $(echo "$payload"|jq -r '.method') $(echo "$payload"|jq -r '.path') [$(echo "$payload"|jq -r '.user')]" >> ligoj_audit.log

For Docker runtime, to verify this hook would run as expected, try the following command from the host:

docker exec ligoj-api jq --version
# > jq-1.6
docker exec ligoj-api python3 --version
# > Python 3.11.5

For update, id or name can be used. However, if name needs to be updated, provide the id as well.

ligoj hook upsert --id 4 --name "audit_role_change_new" --command "$(pwd)/docs/sample_hook_ligoj_audit.sh" --directory  /var/log --match '{"path":"system/security/role.*"}' --inject "feature:iam:node:primary"  "my-secret"

Deletion can be done by id or name attribute:

ligoj hook delete --id 2
ligoj hook delete --name "audit_role_change"

Optional id or name filters are accepted:

ligoj hook get
ligoj hook get --id 1
ligoj hook get --name "audit_role_change"

[{"id": 1, "name": "audit_role_change", "workingDirectory": "/var/log", "command": "/path/to/ligoj_audit.sh", "match": "{\"path\":\"system/security/role.*\"}", "injects": ["java.class.path"]}]

ligoj plugin list

[
    {
        "id": "feature:ui",
        "name": "Ui",
        "plugin": {
            "id": 4,
            "createdBy": "_system",
            "createdDate": 1758279349900,
            "lastModifiedBy": "_system",
            "lastModifiedDate": 1762277251346,
            "version": "2025-10-31T14:25:16.306432087Z",
            "key": "feature:ui",
            "artifact": "plugin-ui",
            "basePackage": "org.ligoj.app.plugin.ui",
            "type": "FEATURE"
        },
        "location": "/path/to/ligoj-plugins/plugin-ui/target/classes/",
        "deleted": false,
        "nodes": 0,
        "subscriptions": 0
    },
    ...
    {
        "id": "service:id:ldap",
        "name": "Ldap",
        "plugin": {
            "id": 155,
            "createdBy": "_system",
            "createdDate": 1762277251427,
            "lastModifiedBy": "_system",
            "lastModifiedDate": 1762450362232,
            "version": "2025-11-05T22:06:40.787627578Z",
            "key": "service:id:ldap",
            "artifact": "plugin-id-ldap",
            "basePackage": "org.ligoj.app.plugin.id.ldap.resource",
            "type": "TOOL"
        },
        "location": "/path/to/ligoj-plugins/plugin-id-ldap/target/classes/",
        "nodes": 2,
        "node": {
            "id": "service:id:ldap",
            "name": "Identity LDAP",
            "refined": {"id": "service:id","name": "Identity", "mode": "create", "uiClasses": "far fa-id-badge"},
            "mode": "all"
        },
        "subscriptions": 5
    }
]

When an explicit version is not provided, the latest version available from Maven Central is used.

This lookup depends on the plugins.repository-manager.nexus.search configuration, while the download relies on plugins.repository-manager.nexus.artifact configuration.

ligoj plugin install --id "plugin-id" --repository "central" --version "2.2.10" --force
ligoj plugin install --id "plugin-id" --version "LATEST" --repository "nexus"
ligoj plugin install --id "plugin-id-ldap" --version "2.1.1" --repository "nexus" --force
ligoj plugin install --id "plugin-req-squash"
ligoj plugin install --id "plugin-req"

[INFO ] [ligoj] Plugin 'plugin-req' has been installed/updated, a restart is required

Two successful consecutive executions give this output:

[INFO ] [ligoj] Plugin 'plugin-id-ldap:2.0.3' is being installed
[INFO ] [ligoj] Plugin 'plugin-req:1.0.1' is installed but requires a restart to be available

Note After installing plugins, a restart is needed to use them.

ligoj plugin restart

null

Optionally, a wait for status can be defined. A regular poll to the server status is performed until reaching DOWN or UP status. When different from 0, the final status is returned.

ligoj plugin restart --wait 20

{"status": "UP"}

ligoj node list

{
  "recordsTotal": 23, 
  "recordsFiltered": 23, 
  "data": [
    {"id": "service:build", "name": "Build", "mode": "link", "uiClasses": "fa fa-cogs", "enabled": true}, 
    {"id": "service:build:jenkins", "name": "Jenkins", "refined": {"id": "service:build", "name": "Build", "mode": "link", "uiClasses": "fa fa-cogs"}, "mode": "all", "uiClasses": "fab fa-jenkins", "enabled": true}, 
    ...
    ]
}

Optionally, parameters can be returned with provided mode and other filters

ligoj node list --parameters-mode "all"
ligoj node list --parameters-mode "all" --search jenkins
ligoj node list --parameters-output "map" --refined "service:build:jenkins"

{
  "recordsTotal": 23, 
  "recordsFiltered": 23, 
  "data": [
    {"id": "service:build", "name": "Build", "mode": "link", "uiClasses": "fa fa-cogs", "enabled": true, "parameters": []}, 
    {"id": "service:build:jenkins", "name": "Jenkins", "refined": {"id": "service:build", "name": "Build", "mode": "link", "uiClasses": "fa fa-cogs"}, "mode": "all", "uiClasses": "fab fa-jenkins", "enabled": true, "parameters": []}, 
    {"id": "service:build:jenkins:local", "name": "Jenkins Local", "refined": {"id": "service:build:jenkins", "name": "Jenkins", "refined": {"id": "service:build", "name": "Build", "mode": "link", "uiClasses": "fa fa-cogs"}, "mode": "all", "uiClasses": "fab fa-jenkins"}, "mode": "all", "enabled": true, 
      "parameters": [
        {"text": "-secured-", "parameter": "service:build:jenkins:api-token"}, {"text": "http://localhost:9190/", "parameter": "service:build:jenkins:url"}, 
        {"text": "-secured-", "parameter": "service:build:jenkins:user"}
      ]
    },
    ...
  ]
}

If the related node already exists, it is updated.

ligoj node upsert --id "service:id:ldap:remote1" --name "Remote1" --from ligoj-ldap.json
ligoj node upsert --id "service:id:ldap:remote1" --name "Remote1" --from https://path/to/ligoj-ldap.json

{"id": "service:id:ldap:remote1", "name": "Remote1", "mode": "all", "enabled": true}

Input --from JSON:

• See --from for JSON loading options
• JSON can be as list or dict (compact). See sample.
• The parameters marked as sensitive are encrypted in database of Ligoj.

Content of sample ligoj-ldap.json file:

[
  {
      "parameter": "service:id:ldap:base-dn",
      "text": "cn=Test"
  },
  {
      "parameter": "service:id:ldap:uid-attribute",
      "text": "uid"
  }
]

ligoj node get --id "service:id"
ligoj node get --id "service:id:ldap"
ligoj node get --id "service:id:ldap:remote1"

{"id": "service:id:ldap:remote1", "name": "Remote1", "mode": "all", "enabled": true}

Optionally, parameters can be returned with provided mode

ligoj node get --id "service:id" --parameters-mode "all"
ligoj node get --id "service:id:ldap" --parameters-mode "all"
ligoj node get --id "service:id:ldap:remote1" --parameters-mode "all"

{
  "id": "service:id:ldap:remote1", "name": "Remote1", "mode": "all", "enabled": true,
  "parameters": [
    {"text": "cn=Test", "parameter": "service:id:ldap:base-dn"}, {"bool": true, "parameter": "service:id:ldap:clear-password"}, 
    {"text": "organizationalUnit", "parameter": "service:id:ldap:companies-class"},
    {"text": "-secured-", "parameter": "service:id:ldap:user-dn"}]
}

Optionally, parameters can be returned with more details

ligoj node get --id "service:id:ldap:remote1" --parameters-mode "all" --parameters-output "full"

{
  "id": "service:id:ldap:remote1", "name": "Remote1", "mode": "all", "enabled": true,
  "parameters": [{
        "parameter": {
            "id": "service:id:group",
            "type": "text",
            "owner": {
                "id": "service:id",
                "name": "Identity",
                "mode": "create",
                "uiClasses": "far fa-id-badge"
            },
            "mandatory": true,
            "secured": false,
            "depends": []
        }
    },
    {
        "text": "cn=Test",
        "parameter": {
            "id": "service:id:ldap:base-dn",
            "type": "text",
            "owner": {
                "id": "service:id:ldap",
                "name": "Identity LDAP",
                "refined": {
                    "id": "service:id",
                    "name": "Identity",
                    "mode": "create",
                    "uiClasses": "far fa-id-badge"
                },
                "mode": "all"
            },
            "mandatory": false,
            "secured": false,
            "depends": []
        }
    }
  ]
}

Optionally, parameter values can be decrypted. One API call is performed for each secured value.

This mode is only available for users having ADMIN role.

ligoj node get --id "service:id:ldap:remote1" --parameters-mode "all" --parameters-output map --parameters-secured

{
  "id": "service:id:ldap:remote1", "name": "Remote1", "mode": "all", "enabled": true, 
  "parameters": {
    "service:id:ldap:base-dn": "cn=Test",
    "service:id:ldap:clear-password": true,
    "service:id:ldap:url": "ldap:localhost:1389",
    "service:id:ldap:password": "secret",
    "service:id:ldap:companies-class": "organizationalUnit", 
    "service:id:ldap:companies-dn": "ou=people,dc=sample,dc=com"
  }
}

ligoj node status --id "service:id:ldap:remote1"

{"id": "down"}

Node delegates allow users, groups or companies to manage nodes.

Sub nodes inherit the delegate permissions.

ligoj delegate-node list

[
  {"id": 1, "createdBy": "_system", "createdDate": 1758279349979, "lastModifiedBy": "_system", "lastModifiedDate": 1758279349979, "name": "service", "receiver": "ligoj-admin", "receiverType": "user", "canWrite": true, "canAdmin": true, "canSubscribe": true, "referenceID": "service"}
]

Create a delegate with subscribe, administration, and creation rights for a receiver on an optional node and its sub-nodes.

The provided node does not need to exist yet.

ligoj delegate-node create --node service --can-subscribe --can-admin --can-write --receiver jdoe --receiver-type user
ligoj delegate-node create --node service:id --can-subscribe --receiver internal --receiver-type company
ligoj delegate-node create --node service:id:ldap:instance1 --can-admin --can-write --receiver group1 --receiver-type group

Delete a delegate node from its identifier.

ligoj delegate-node delete --id 1

Get a delegate node from its identifier.

ligoj delegate-node get --id 1
ligoj delegate-node get --node 1

List projects with optional search criteria.

ligoj project list
ligoj project list --search project1

{
  "recordsTotal": 1, 
  "recordsFiltered": 1, 
  "data": [
    {
      "id": 153, 
      "createdDate": 1705853880193, "lastModifiedDate": 1705853880193, 
      "createdBy": { "id": "ligoj-admin", ...}, 
      "lastModifiedBy": {"id": "ligoj-admin", ...}, 
      "name": "Project 1",
      "teamLeader": {"id": "ligoj-admin", ...}, 
      "pkey": "project1", 
      "description": "",
      "nbSubscriptions": 2
    },
    ...
  ]
}

ligoj project get --id 153
ligoj project get --id "project1"

{
  "id": 153, 
  "createdDate": 1705853880193, "lastModifiedDate": 1705853880193, 
  "createdBy": { "id": "ligoj-admin", ...}, 
  "lastModifiedBy": {"id": "ligoj-admin", ...}, 
  "name": "Project 1",
  "teamLeader": {"id": "ligoj-admin", ...}, 
  "pkey": "project1", 
  "description": "",
  "manageSubscriptions": true, 
  "subscriptions": [
    {"id": 355, ...},
    {"id": 362, ...}
  ]
}

ligoj project create --name "project4" --team-leader "ligoj-admin" --pkey "sample:project4" --description "Sample project 4" --context='{"some":"value"}'

{
  "id": 352, 
  "creationContext": "{\"some\":\"value\"}", 
  "name": "project4", 
  "teamLeader": {"id": "ligoj-admin",...},
  "pkey": "sample:project4", 
  "description": "Sample project 4",
  ...
}

Delete project with optional search criteria.

ligoj project delete --id 252
ligoj project delete --id "sample:project4"
ligoj project delete --id "sample:project4" --with-data

Combined filters are accepted.

ligoj subscription list --node "service:id:ldap:remote1"
ligoj subscription list --tool "service:id:ldap"
ligoj subscription list --service "service:id"
ligoj subscription list --project "project1"
ligoj subscription list --project 104

[
  {"id": 155, "node": "service:id:ldap:remote1", "project": 104}, 
  {"id": 302, "node": "service:qa:sonarqube:8", "project": 104}
]

ligoj subscription get --id 302

{"service:qa:sonarqube:project": "test", "service:qa:sonarqube:url": "http://127.0.0.1:9000/"}

ligoj subscription get --id 302 --details

{"subscription": 302, "project": {"id": 104, "name": "Project1", "description": "Foo bar"}, "parameters": {"service:qa:sonarqube:project": "test", "service:qa:sonarqube:url": "http://127.0.0.1:9000/"}, "node": {"id": "service:qa:sonarqube:8", "name": "Sonar Local 8", "refined": {"id": "service:qa:sonarqube", "name": "SonarQube", "refined": {"id": "service:qa", "name": "Quality Assurance", "mode": "link", "uiClasses": "fas fa-tachometer-alt"}, "mode": "link"}, "mode": "link", "enabled": true}}

Configuration file can be a JSON file, a remote HTTP URL, or plain JSON. Both forms of parameters are accepted, as list or dict (compact).

Duplicate subscriptions are ignored: same project, node and parameters.

ligoj subscription create --project project1 --node "service:id:ldap:remote1" --from conf.json
ligoj subscription create --project project1 --node "service:id:ldap:remote1" --from "https://path/to/conf.json"
ligoj subscription create --project project1 --node "service:id:ldap:remote1" --from '[{"parameter": "service:id:group", "text": "project1-team"}, {"parameter": "service:id:ou", "text": "project1"}]'
ligoj subscription create --project project1 --node "service:id:ldap:remote1" --from '{"service:id:group": "project1-team", "service:id:ou": "project1"}'
...

362

Input --from JSON:

• See --from for JSON loading options
• JSON can be as list or dict (compact). See sample.
• The parameters marked as sensitive are encrypted in database of Ligoj.

Delete a subscription from its identifier.

ligoj subscription delete --id 302

By default, only the link between Ligoj and the remote tool is removed. Optionally, when Ligoj has created data with the subscription, it can also be deleted with this operation.

For example, LDAP groups or a Jenkins job created at subscription time will be deleted.

ligoj subscription delete --id 302 --with-data

Return the last computed status of all subscriptions of given project.

ligoj subscription status --project 104
ligoj subscription status --project project1

{
  "155": {"specifics": [], "value": "UP", "type": "status", "node": {"id": "service:id:ldap:remote1", "name": "TestAnnuaireCLI", "mode": "all"}, "subscription": 155}, 
  "252": {"specifics": [], "value": "DOWN", "type": "status", "node": {"id": "service:qa:sonarqube:user", "name": "Sonar Local User", "mode": "link"}, "subscription": 252},
  "157": {"specifics": [], "value": "UP", "type": "status", "node": {"id": "service:id:ldap:remote1", "name": "TestAnnuaireCLI", "mode": "all"}, "subscription": 157}
}

Retrieve the up-to-date status of a subscription.

Up subscription:

ligoj subscription refresh --id 155

{"id": 155, "status": "up", "node": "service:id:ldap:remote1", "project": 104, "data": {"members": 0}, "parameters": {...}}

Down subscription:

ligoj subscription refresh --id 252

{"id": 252, "status": "down", "project": 104, "data": {}, "parameters": {"service:qa:sonarqube:project": "test",...}}

Operations related to plugin-id and sub-plugins.

Operations related to container scopes managed by service:id nodes.

Create a container scope

ligoj id:scope create --id "Unassigned" --type "group" --dn "ou=groups,dc=example,dc=com"
ligoj id:scope create --id "Projects" --type "group" --dn "ou=projects,ou=groups,dc=example,dc=com"
ligoj id:scope create --id "Tools" --type "group" --dn "ou=tools,ou=groups,dc=example,dc=com"
ligoj id:scope create --id "Unassigned" --type "company" --dn "ou=people,dc=example,dc=com"
ligoj id:scope create --id "Internal" --type "company" --dn "ou=internal,ou=people,dc=example,dc=com"
ligoj id:scope create --id "Unassigned" --type "tree" --dn "dc=example,dc=com"

Return a container scope

ligoj id:scope get --id "SampleGroup2"

{"id": "samplegroup2", "name": "SampleGroup2", "scope": "Unassigned", "locked": false}

Return a list of container scopes

ligoj id:scope list --type "group"

{
  "recordsTotal": 4, "recordsFiltered": 3, 
  "data": [
    {"id": 5, "name": "Unassigned", "dn": "ou=groups,dc=sample,dc=com", "type": "group", "locked": false}, 
    {"id": 6, "name": "Project", "dn": "ou=projects,ou=groups,dc=sample,dc=com", "type": "group", "locked": false}, 
    {"id": 7, "name": "Technical", "dn": "ou=tools,ou=groups,dc=sample,dc=com", "type": "group", "locked": false}
  ]
}

Operations related to groups managed by service:id nodes

Group name is case insensitive.

Create a group.

ligoj id:group create --name "SampleGroup2" --scope "Unassigned"

Create a group inside a group

ligoj id:group create --name "SampleSubGroup" --scope "Unassigned" --parent "SampleGroup2"
ligoj id:group create --name "SampleSubGroup2" --scope "Unassigned" --parent "SampleSubGroup"

Delete a group. The command will not fail if the group does not exist.

ligoj id:group delete --name "SampleGroup2"

Retrieve a group

ligoj id:group get --name "SampleGroup2"

{"id": "samplegroup2", "name": "SampleGroup2", "scope": "Unassigned", "locked": false}

Delete a group. If the group does not exist, the command will not return an error.

ligoj id:group delete --name "SampleGroup2"

List groups

ligoj id:group list

{
    "recordsTotal": 4,
    "recordsFiltered": 4,
    "data": [
        {
            "id": "sample group",
            "name": "Sample Group",
            "scope": "Unassigned",
            "locked": false,
            "countVisible": 3,
            "count": 3,
            "canWrite": true,
            "canAdmin": true,
            "containerType": "group"
        },
        {
            "id": "samplegroup2",
            "name": "SampleGroup2",
            "scope": "Unassigned",
            "locked": false,
            "countVisible": 0,
            "count": 0,
            "canWrite": true,
            "canAdmin": true,
            "containerType": "group"
        },
        {
            "id": "samplesubgroup",
            "name": "SampleSubGroup",
            "scope": "Unassigned",
            "locked": false,
            "countVisible": 0,
            "count": 0,
            "canWrite": true,
            "canAdmin": true,
            "containerType": "group",
            "parents": [
                "samplegroup2"
            ]
        },
        {
            "id": "samplesubgroup2",
            "name": "SampleSubGroup2",
            "scope": "Unassigned",
            "locked": false,
            "countVisible": 0,
            "count": 0,
            "canWrite": true,
            "canAdmin": true,
            "containerType": "group",
            "parents": [
                "samplesubgroup",
                "samplegroup2"
            ]
        }
    ]
}

Operations related to users managed by service:id nodes

ligoj id:user create --id jdupont --firstname "Jean" --lastname "Dupont" --mail "[email protected]" --company "external" --groups "Sample Group,SampleGroup2"
ligoj id:user create --id jdupont2 --firstname "Jean" --lastname "Dupont" --mail "[email protected]" --company "external" --groups "Sample Group,SampleGroup2"

Delete a user. If the user does not exist, the command will not return an error.

ligoj id:user delete --id jdupont2
ligoj id:user delete --mail [email protected]

ligoj id:user list
ligoj id:user list --company "department1" --group "Sample Group" --criteria "@sample.com" --page-length 2
ligoj id:user list --company "department1" --page-length 2

{
  "recordsTotal": 102, 
  "recordsFiltered": 102,
  "extensions": {"customAttributes": ["uidFonctionnel"]}},
  "data": [
    {"firstName": "John", "lastName": "Doe", "id": "jdoe", "company": "external", "mails": ["[email protected]"], "groups": ["Sample Group", "SampleGroup2"], "name": "jdoe"}, 
    {"firstName": "Cli2", "lastName": "Name", "id": "cli2name", "company": "external", "mails": ["[email protected]","[email protected]"], "groups": ["Sample Group"], "name": "cli2name"}
  ]
}

Return a user. If the user does not exist, the command will return null.

ligoj id:user get --id jdupont
ligoj id:user get --mail [email protected]

{"firstName": "Jean", "lastName": "Dupont", "id": "jdupont", "company": "external", "mails": ["[email protected]"], "groups": ["Sample Group", "SampleGroup2"], "name": "jdupont"}

The user and the group must exist. The command does not fail if the user is already in the group.

ligoj id:user add --id jdupont --groups "SampleGroup2"
ligoj id:user add --mail [email protected] --groups "SampleGroup2"
ligoj id:user add --mail [email protected] --groups "Sample Group"

The user and the group must exist. The command does not fail if the user is not in the group.

ligoj id:user remove --id jdupont --groups "SampleGroup2"
ligoj id:user remove --mail [email protected] --groups "SampleGroup2"

For a specific user (need administrative rights):

The user must exist.

ligoj id:user reset-password --id jdupont
ligoj id:user reset-password --mail [email protected]

For current user:

ligoj id:user reset-password

The following commands can be executed to perform several API commands following a complex workflow.

Most bootstrap arguments like --jenkins-endpoint, corresponding configuration file option such as jenkins_endpoint is accepted, and environment variable JENKINS_ENDPOINT too.

Initialize Ligoj with basic group management, containers, and companies hierarchy.

Sample Docker command:

ligoj bootstrap init --base-dn="dc=sample,dc=com"

Note --base-dn argument can also be defined as ligoj_ldap_base_dn in configuration file and LIGOJ_LDAP_BASE_DN environment variable.

Hierarchy tree sample for base DN dc=sample,dc=com

ligoj bootstrap init --base-dn="dc=sample,dc=com" --users-base-dn "ou=people" --internal-users-base-dn "" --technical-users-base-dn "ou=technical-users" --external-users-base-dn "ou=external" --groups-base-dn "ou=groups" --technical-groups-base-dn "ou=tools" --projects-base-dn "ou=projects" --technical-groups "sonar-administrators" "jenkins-administrators" "nexus-administrators"

## Users and companies

### OU LDAP intermediate
ligoj id:ou create --name "people" --parent-dn "dc=sample,dc=com"
ligoj id:ou create --name "external" --parent-dn "ou=people,dc=sample,dc=com"
ligoj id:ou create --name "technical-users" --parent-dn "ou=people,dc=sample,dc=com"

### Companies
ligoj id:scope create --name "Unassigned" --type "company" --dn "ou=people,dc=sample,dc=com"
ligoj id:scope create --name "External" --type "company" --dn "ou=external,ou=people,dc=sample,dc=com"
ligoj id:scope create --name "Technical" --type "company" --dn "ou=technical-users,ou=people,dc=sample,dc=com"

## Groups

### OU LDAP intermediate
ligoj id:ou create --name "groups" --parent-dn "dc=sample,dc=com"
ligoj id:ou create --name "projects" --parent-dn "ou=groups,dc=sample,dc=com"
ligoj id:ou create --name "tools" --parent-dn "ou=groups,dc=sample,dc=com"

### Scope functionals for groups
ligoj id:scope create --name "Unassigned" --type "group" --dn "ou=groups,dc=sample,dc=com"
ligoj id:scope create --name "Project" --type "group" --dn "ou=projects,ou=groups,dc=sample,dc=com"
ligoj id:scope create --name "Technical" --type "group" --dn "ou=tools,ou=groups,dc=sample,dc=com"

### Technical groups and sub-groups
ligoj id:group create --name "jenkins-administrators" --scope "Technical"
ligoj id:group create --name "nexus-administrators" --scope "Technical"
ligoj id:group create --name "nexus-administrators-paris" --scope "Technical" --parent "nexus-administrators"
ligoj id:group create --name "nexus-administrators-paris-8" --scope "Technical" --parent "nexus-administrators-paris"

Configure a new project and its administrator.

ligoj bootstrap welcome-user --id jdupont --project project1 --name "Project 1" --group-suffix="-team"

Optionally, the project key can be validated with DNS within a defined DNS zone :

ligoj bootstrap welcome-user --id jdupont --project project1 --name "PIProject 1" --verify-project-with-dns "PROJECT_KEY.holder.kloudy.io,PROJECT_KEY.holder2.kloudy.io" --group-suffix="-team"

{
    "admin_user": "jdupont", 
    "script_user": "project1-script", 
    "script_api_key": "...", 
    "reader_user": "project1-reader", 
    "reader_password": "...", 
    "project_key": "project1", 
    "project_id": 6552
}

Optionally, Ligoj nodes such as Jenkins and SonarQube can be created during this step.

ligoj bootstrap welcome-user --id jdupont --project project1 --name "Project 1" --verify-project-with-dns "PROJECT_KEY.holder.kloudy.io,PROJECT_KEY.holder2.kloudy.io" --group-suffix="-team" --jenkins-create-node --jenkins-endpoint http://localhost:8086 --jenkins-api-token="" --sonar-create-node --sonar-endpoint http://localhost:9000  --sonar-api-token="" --reset-reader-password 

Notes

• reader_password result is provided only for new user and cannot be retrieved by Ligoj.
• To generate another password, use the --reset-reader-password flag.
• reader_password (or reset password) is used to create API tokens saved in Ligoj nodes
• --jenkins-api-token and --sonar-api-token can be provided with this command but should be related to the reader_user or --jenkins-api-user value.
• All endpoints and tokens are also sourced from configuration file and environment variables.

Create new groups within a new project related to another one.

Considering this use case :

• Create a new project having project-a as key and Project A as name.
• Team leader (administrator) will be [email protected]. Actual username is resolved automatically from email.
• Initial groups within this project are admin, dev and test.
• The parent project's key (used as context) is project1. This project must be managed by the user: ligoj-user

The corresponding command is:

ligoj bootstrap create-project --project project-a --name "Project A" --groups "admin" "dev" "test" \
--parent-project "project1" \
--parent-admin "ligoj-user" \
--team-leader [email protected] \

Note When parent-admin is provided, this operation exploits the run-as feature of Ligoj to check the administrator of parent-project. In such a case, the session user must be a system administrator.

Delete a project including all groups, not only the references.

ligoj bootstrap delete-project --project project-a --parent-admin "ligoj-user"

Note When parent-admin is provided, this operation exploits the run-as feature of Ligoj to check the administrator of parent-project. In such a case, the session user must be a system administrator.

Create mapped roles in various tools

Supported services are:

• Jenkins
• SonarQube
• Nexus
• Alfresco
• GitLab

Created contents by tools

Group and role configuration JSON file conf.json. See --from for JSON loading options

ligoj bootstrap create-roles --project project-a --from conf.json \
--argocd-token="$ARGOCD_TOKEN" \
--argocd-user="$ARGOCD_USER" \
--alfresco-endpoint="$ALFRESCO_ENDPOINT" \
--alfresco-user="$ALFRESCO_USER" \
--alfresco-password="$ALFRESCO_PASSWORD" \
--nexus-endpoint="$NEXUS_ENDPOINT" \
--nexus-user="$NEXUS_USER" \
--nexus-password="$NEXUS_PASSWORD" \
--gitlab-endpoint="$GITLAB_ENDPOINT" \
--gitlab-token="$GITLAB_TOKEN" \
--jenkins-home="$JENKINS_HOME" \
--jenkins-endpoint="$JENKINS_ENDPOINT" \
--sonar-endpoint="$SONAR_ENDPOINT" \
--sonar-api-token="$SONAR_API_KEY" \
--harbor-endpoint="$HARBOR_ENDPOINT" \
--harbor-user="$HARBOR_USER" \
--harbor-password="$HARBOR_PASSWORD"

ligoj bootstrap create-roles --project project-a --from "https://path/to/conf.json"

ligoj bootstrap create-roles --project project-a --from '[{"text": "organizationalUnit","parameter": "service:id:ldap:companies-class"},...]'

For detailed tool specific options, execute usage command:

ligoj bootstrap create-roles --help

usage: Ligoj CLI bootstrap create-roles [-h] [--project PROJECT] [--group-suffix GROUP_SUFFIX] [--groups [GROUPS ...]] [--from FROM] 
  [--schema SCHEMA] 
  [--alfresco-endpoint ALFRESCO_ENDPOINT] [--alfresco-user ALFRESCO_USER] [--alfresco-password ALFRESCO_PASSWORD]
  [--alfresco-ticket ALFRESCO_TICKET] 
  [--gitlab-endpoint GITLAB_ENDPOINT] [--gitlab-token GITLAB_TOKEN] [--gitlab-base-group GITLAB_BASE_GROUP]
  [--gitlab-project-group-prefix GITLAB_PROJECT_GROUP_PREFIX] [--gitlab-project-subgroup-prefix GITLAB_PROJECT_SUBGROUP_PREFIX]
  [--jenkins-home JENKINS_HOME] [--jenkins-crumb JENKINS_CRUMB] [--jenkins-endpoint JENKINS_ENDPOINT]
  [--jenkins-api-user JENKINS_API_USER] [--jenkins-api-token JENKINS_API_TOKEN]
  ...

options:
  -h, --help            show this help message and exit
  --project PROJECT, -p PROJECT
                        Associated project key
...

Each supported tool can be included or excluded from the bootstrap commands:

• By default, all discovered JSON's content is considered, no exclusion. Implicit --includes "*".
• Special value * means all.
• Multiple includes and excludes values can be provided
• The excludes option has higher priority than includes.
• When the resolved endpoint is empty or null, the tool is ignored.

Checked constraints:

• Referenced groups must be defined at root level. This constraint ensures a correct definition and avoids typos.
• Empty permissions set are not allowed.
• Given JSON must validate the JSON Schema document schema.json.
• JSON Schema can be merged with custom additions: --schema "JSON Schema string, file or URL".

Sample constraint limiting Alfresco sites to 1: --schema='{"properties":{"alfresco":{"properties":{"sites":{"maxItems": 1}}}}}'

Supported resources are:

• Nested folders
• Credentials with or without values
• Roles, group mapping and permissions, at folder or global level

• Recursive folders are supported; however, each folder must be unique. This is not an implementation limit, but it makes folder reorganization possible.
• Folder maximal depth is 4, but it is not a hard limit
• Folder names are encoded, special chars are supported
• Supported folder types are com.cloudbees.hudson.plugins.folder.Folder and jenkins.branch.OrganizationFolder. Folder mode update is not supported. Other folder modes might work, but have not been tested.
• There is no permission limitation; internal identifiers must be used, such as hudson.model.Item.Build, hudson.model.Hudson.Administer, etc.:
  • Overall permissions
  • Run permissions
  • Item permissions
  • SCM permissions
  • Credential permissions
  • The naming convention for permissions is the full class name, followed by the field (Permission) name converted to Camel case, e.g., hudson.model.View.Read

There is no limitation for credentials type, the supported configuration is:

• Any parameter type but file
• Tested types are:
  • com.cloudbees.plugins.credentials.impl.UsernamePasswordCredentialsImpl
  • org.jenkinsci.plugins.plaincredentials.impl.StringCredentialsImpl
  • com.cloudbees.jenkins.plugins.sshcredentials.impl.BasicSSHUserPrivateKey
• Supported scope values are global and system (case insensitive). When not provided, the default behavior of this credential type is applied.
• Attached domain is always All domains: _

Requires the installed, configured and assigned Jenkins plugin Role-based Authorization Strategy. Underlying role management API is executed.

CaC (Configuration as Code) YAML file management is supported:

• CaC file location override support is JENKINS_CASC_FILE variable, then CASC_JENKINS_CONFIG variable, then $JENKINS_HOME/jenkins.yaml as default.
• Only update mode is supported after all API calls, not creation
• Both current and in-memory CaC files YAML structure must contain this path: jenkins.authorizationStrategy.roleBased.roles
• Both current and in-memory CaC files YAML structure must contain this path: jenkins.securityRealm.ldap.configurations
• The script must be able to write the backup file $path_to_cac_file.ligoj, which will be overwritten.
• A unified diff is computed and printed for current and in-memory CaC files
• Backup and update are executed only if there is at least one change detected in the computed unified diff
• By default, the related sub-folder access is granted from the parent folder, and the related pattern is suffixed with the (/.*)? expression. Set recursive to false to block this behavior.
• Roles use the folder identifier, case is insensitive

  securityRealm:
    ldap:
      configurations:
      - displayNameAttributeName: "cn"
        groupMembershipStrategy:
          fromGroupSearch:
            filter: "(| (member={0}) (uniqueMember={0}) (memberUid={1}))"
        groupSearchBase: "ou=groups"
        groupSearchFilter: "(& (cn={0}) (| (objectClass=groupOfNames) (objectClass=groupOfUniqueNames)\
          \ (objectClass=posixGroup)))"
        inhibitInferRootDN: false
        managerDN: "cn=Manager,dc=sample,dc=com"
        managerPasswordSecret: "{...}"
        rootDN: "dc=sample,dc=com"
        server: "ldap://localhost:1389"
        userSearchBase: "ou=people"
      disableMailAddressResolver: false
      disableRolePrefixing: true
      groupIdStrategy: "caseInsensitive"
      userIdStrategy: "caseInsensitive"

Supported resources are:

• Projects
• Template
• Roles, group mapping and permissions, at project or global level

Supported resources are:

• Repository
• Roles, group mapping and permissions, at repository level or global level

Repository configuration must follow the [/#admin/system/api](http://localhost:8681/#admin/system/api) of your Nexus instance of:

• POST /vi/repositories/docker/hosted
• POST /vi/repositories/maven/hosted
• ... By default, repository mode is hosted and can be overridden with mode property.

Supported resources are:

• Projects
• Roles and group mapping, at project level

No resources are supported, only roles. GitLab groups and sub-groups are created according to the given groups and naming guidelines. Real Git repository projects are not managed by this CLI.

Project hierarchy for a project project1:

Sub-groups are created with project_creation_level flag set to noone and with a specific avatar. See GitLab API create-a-subgroup

Supported resources are:

• Projects
• Roles and permissions, at project level only
  • action: [delete, get]
  • permission: [allow,deny], by default allow
  • application:, by default *

Sample JSON part:

{
  "projects": [
    {
      "name": "project1",
      "description": "Project description",
      "roles": {
        "dev": {
          "permissions": [
            {
                "action": "get"
            },
            {
                "action": "delete",
                "application": "app1",
                "permission": "deny"
            }
          ]
        },
        "test": {
          "permissions": [
            {
                "action": "get"
            }
          ]
        }
      }
    }
  ]
}

Supported resources are:

• Sites
• Roles and permissions, at site level only

ligoj bootstrap create-roles --schema='{
    "properties": {
        "groups": {
          "items": {
            "enum": [
                "dev",
                "admin",
                "test",
                "securite"
            ]
          }
        },
        "alfresco": {
            "properties": {
                "sites": {
                    "maxItems": 1
                }
            }
        }
    }
}' --project "project1" --group-suffix="-team" --from="conf/sample.conf.alfresco.json"

Alfresco ticket generation by API:

• either from Swagger API explorer /?urls.primaryName=Authentication%20API#/authentication/createTicket,
• either with cURL command:

curl -X POST  -H "Content-Type: application/json" -d '{"username":"admin","password":"admin"}' "https://alfresco.sample.com/alfresco/s/api/login"

Delete mapped roles from various tools symmetrically as create-roles operation.

See --from for JSON loading options

By default, only roles are deleted; to perform a full cleanup, see the --with-data option

ligoj bootstrap delete-roles --project project-a --from conf.json \
--with-data "jenkins" "sonar" \
--argocd-token="$ARGOCD_TOKEN" \
--argocd-user="$ARGOCD_USER" \
--alfresco-endpoint="$ALFRESCO_ENDPOINT" \
--alfresco-user="$ALFRESCO_USER" \
--alfresco-password="$ALFRESCO_PASSWORD" \
--nexus-endpoint="$NEXUS_ENDPOINT" \
--nexus-user="$NEXUS_USER" \
--nexus-password="$NEXUS_PASSWORD" \
--gitlab-endpoint="$GITLAB_ENDPOINT" \
--gitlab-token="$GITLAB_TOKEN" \
--jenkins-home="$JENKINS_HOME" \
--jenkins-endpoint="$JENKINS_ENDPOINT" \
--sonar-endpoint="$SONAR_ENDPOINT" \
--sonar-api-token="$SONAR_API_KEY" \

Deleted contents by tools

Each supported tool can be included (by default) or excluded, as described in create-roles includes/excludes option documentation. For excluded tools, no role and no data are deleted.

By default, only roles are deleted. To symmetrically delete the created contents, --with-data must be set to * or a specific list of plugins. In this case, all discovered JSON content is considered for deletion, including Jenkins folders, Nexus repositories, etc.

• By default, no data is deleted
• When --with-data is set to *, all discovered JSON's content for included plugins is considered
• When --with-data is set to plugin1 plugin2, only these plugins are considered for data deletion, only if these plugins are included

The purpose of this documentation is only for troubleshooting and understanding the full behavior of bootstrap operations:

• Bootstrap init : initial IDP (LDAP, ...), administrative setup. Only executed once.
• Bootstrap welcome-user: initial administration user. Each administrator can execute their own base configuration.
• Bootstrap create-project: create a new project in Ligoj and the linked IDP
• Bootstrap create-roles: permissions, role mapping and containers creation for an existing project
• Bootstrap delete-roles: permissions, role mapping and containers deletion from a project
• Bootstrap delete-project: delete a project from Ligoj and linked IDP

Commands from zero to zero:

ligoj -V bootstrap init --base-dn="dc=sample,dc=com"
ligoj -V bootstrap welcome-user --id "jdupont" --project "pic-master" --name "PIC Master" --script-custom-attributes '{"uidFonctionnel":"pic-master-script"}' --reader-custom-attributes '{"uidFonctionnel":"pic-master-reader"}' --jenkins-create-node --sonar-create-node --reset-reader-password  
ligoj -V bootstrap create-project --project "project-module1" --name "ProjetNew" --groups "dev" "admin" --parent-project "pic-master" --parent-admin "jdupont" --team-leader jdupont
ligoj -V bootstrap create-roles --project "project-module1" --from "conf/ligoj/sample.conf.json" --excludes gitlab alfresco argocd
ligoj -V bootstrap create-roles --project "project-module1" --from "conf/ligoj/sample.conf.json" --excludes gitlab
ligoj -V bootstrap delete-roles --project "project-module1" --from "conf/ligoj/sample.conf.json" --excludes gitlab
ligoj -V project delete              --id "project-module1" --parent-admin "jdupont" --with-data '*'
ligoj -V project delete              --id "pic-master" --with-data '*'

This section covers the case of running Ligoj with interaction with HTTPS services using self-signed certificates or issued by internal Certificate Authorities.

For each HTTPS website, run the following command. It requires keytool to be available on the host.

python plugins/ssl.py keycloack.sample.com 443 ./ligoj.jks changeit

When successive calls are done, the target TrustStore JKS file contains all aggregated certificates and can be provided to ligoj-ui and/or ligoj-api containers.

# Copy the TrustStore file in the mounted Ligoj home directory
cp ./ligoj.jks /var/lib/instance_datas/ligoj/

# Start the container with the TrustStore reference
docker run -e CUSTOM_OPTS='-Djavax.net.ssl.trustStore=/home/ligoj/ligoj.jks' \

This procedure is only for development where Ligoj CLI package is installed in editable.

echo '
export PYENV_ROOT="$HOME/.pyenv"
command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"' >> ~/.bashrc
source ~/.bashrc
brew install pyenv-virtualenv 3.11 ligoj # See https://github.com/pyenv/pyenv-virtualenv
pyenv install 3.11
pyenv virtualenv 3.11 ligoj
pyenv activate ligoj

# Proxy configuration
export PYTHON_OPTS=' --proxy="10.154.154.154:3128"'
export http_proxy="http://10.154.154.154:3128"
export https_proxy="http://10.154.154.154:3128"
export NO_PROXY="localhost,*.rie.gouv.fr,127.0.0.1,0.0.0.0,ligoj.$TENANT"

pip install --upgrade pip
pip install -U  --root-user-action=ignore pip -e . 

# Build
python -m pip install --upgrade build
python -m build
ruff check . --fix
flake8 .