mxids/docs/stores/exec.md

Exec Identity Store

• Features
• Overview
• Configuration
  • Global
    • Tokens
  • Executable
    • Input
    • Output
  • Examples
  • Per-Feature
• Authentication
  • Tokens
  • Input
  • Output
• Directory
  • Tokens
  • Input
  • Output
• Identity
  • Single Lookup
    • Tokens
    • Input
    • Output
  • Bulk Lookup
    • Tokens
    • Input
    • Output
• Profile
  • Tokens
  • Input
  • Output

---

Features

Name	Supported
Authentication	Yes
Directory	Yes
Identity	Yes
Profile	Yes

This Identity Store lets you run arbitrary commands to handle the various requests in each support feature.
It is the most versatile Identity store of ma1sd, allowing you to connect any kind of logic with any executable/script.

Overview

Each request can be mapping to a fully customizable command configuration.
The various parameters can be provided via any combination of:

• Standard Input
• Command-line arguments
• Environment variables

Each of those supports a set of customizable token which will be replaced prior to running the command, allowing to provide the input values in any number of ways.

Success and data will be provided via any combination of:

• Exit status
• Standard Output

Each of those supports a set of configuration item to decide how to process the value and/or in which format.

All values, inputs and outputs are UTF-8 encoded.

Configuration

Each feature comes with a set of possible lookup/action which is mapped to a generic configuration item block.
We will use the term Executable for each lookup/action and Processor for each configuration block.

Global

exec:
  enabled: <boolean>

Enable/disable the Identity store at a global/default level. Each feature can still be individually enabled/disabled.

Tokens

The following options allow to globally set tokens for value replacement across all features and processors config.
Not all features use all tokens, and each feature might also have its own specific tokens. See each feature documentation.

They can be set within the following scope:

exec:
  token:
    <token>: '<value>'

---

The following tokens and default values are available:

localpart: '{localpart}'

Localpart of Matrix User IDs

domain: '{domain}'

Domain of Matrix User IDs

mxid: '{mxid}'

Full representation of Matrix User IDs

medium: '{medium}'

Medium of 3PIDs

address: '{address}'

Address of 3PIDs

type: '{type}'

Type of query

query: '{query}'

Query value

Executable

Executables have the following options:

command: '/path/to/executableOrScript'

Set the executable (relative or absolute) path to be executed. If no command is given, the action will return a "neutral" result if possible or be skipped altogether.

---

Command line arguments can be given via a list via both YAML formats:

args:
 - '-t'
 - '{token}'
 - '-v'
 - 'value'

or

args: ['-t', '{token}', '-v', 'value]

Each argument will be processed for token replacement.

---

Environment variables can be given as key/value pairs:

env:
  ENV_VAR_1: 'value'
  ENV_VAR_2: '{token}'

Each variable value will be processed for token replacement.

Input

Standard input can be configured in the namespaces input with:

• type: The format to use
• template: The full or partial template with tokens to be used when generating the input

Not all features and Executables allow for a template to be provided.
Templates for listed-based input are not supported at this time.
Default templates may be provided per Executable.

The following types are available:

• json: Use JSON format, shared with the REST Identity Store
• plain: Use a custom multi-lines, optionally tab-separated input

Output

Standard output can be configured in the namespaces output with:

• type: The format to use
• template: The full or partial template with tokens to be used when processing the output

Not all features and Executables allow for a template to be provided.
Templates for listed-based output are not supported at this time.
Default templates may be provided per Executable.

The following types are available:

• json: Use JSON format, shared with the REST Identity Store
• plain: Use a custom multi-lines, optionally tab-separated output

Examples

Basic

exec:
  auth:
    enabled: true
    command: '/opt/ma1sd-exec/auth.sh'
    args: ['{localpart}']
    input:
      type: 'plain'
      template: '{password}'
  env:
    DOMAIN: '{domain}'

With Authentication enabled, run /opt/ma1sd-exec/auth.sh when validating credentials, providing:

• A single command-line argument to provide the localpart as username
• A plain text string with the password token for standard input, which will be replaced by the password to check
• A single environment variable DOMAIN containing Matrix ID domain, if given

The command will use the default values for:

• Success exit status of 0
• Failure exit status of 1
• Any other exit status considered as error
• Standard output will not be processed

Advanced

Given the fictional placeholder feature:

exec:
  enabled: true
  token:
    mxid: '{matrixId}'
  auth:
    token:
      localpart: '{username}'
    command: '/path/to/executable'
    args:
      - '-u'
      - '{username}'
    env:
      MATRIX_DOMAIN: '{domain}'
      MATRIX_USER_ID: '{matrixId}'
    output:
      type: 'json'
    exit:
      success:
        - 0
        - 128
      failure:
        - 1
        - 129

With:

• The Identity store enabled for all features
• A global specific token {matrixId} for Matrix User IDs, replacing the default {mxid}

Running /path/to/executable providing:

• A custom token for localpart, {username}, used as a 2nd command-line argument
• An extracted Matrix User ID localpart provided as the second command line argument, the first one being -u
• A password, the extracted Matrix domain and the full User ID as arbitrary environment variables, respectively PASSWORD, MATRIX_DOMAIN and MATRIX_USER_ID

After execution:

• Process stdout as JSON
• Consider exit status 0 and 128 as success and try to process the stdout for data
• Consider exit status 1 and 129 as failure and try to process the stdout for error code and message

Per Feature

See each dedicated Feature section.

Authentication

The Authentication feature can be enabled/disabled using:

exec:
  auth:
    enabled: <true/false>

---

This feature provides a single Executable under the namespace:

exec:
  auth:
  ...

Tokens

The following tokens/default values are specific to this feature:

password: '{password}'

The provided password

Input

Supported input types and default templates:

JSON (json)

Same as the REST Identity Store;

Plain (plain)

Default template:

{localpart}
{domain}
{mxid}
{password}

Output

Supported output types and default templates:

JSON (json)

Same as the REST Identity Store;

Plain (plain)

NOTE: This has limited support. Use the JSON type for full support.

Default template:

[success status, true or 1 are interpreted as success]
[display name of the user]

Directory

The Directory feature can be enabled/disabled using:

exec:
  directory:
    enabled: <true/false>

---

Two search types configuration namespace are available, using the same input/output formats and templates:

By name:

exec:
  directory:
    search:
      byName:
        ...

By 3PID:

exec:
  directory:
    search:
      byThreepid:
        ...

Tokens

No specific tokens are available.

Input

Supported input types and default templates:

JSON (json)

Same as the REST Identity Store;

Plain (plain)

Default template:

[type of search, following the REST Identity store format]
[query string]

Output

Supported output types and default templates:

JSON (json)

Same as the REST Identity Store;

Plain (plain)

Not supported at this time. Use the JSON type.

Identity

The Identity feature can be enabled/disabled using:

exec.identity.enabled: <true/false>

Single lookup

Configuration namespace:

exec.identity.lookup.single:
  ...

Tokens

No specific tokens are available.

Input

Supported input types and default templates:

JSON (json)

Same as the REST Identity Store;

Plain (plain)

Default template:

{medium}
{address}

Output

Supported output types and default templates:

JSON (json)

Same as the REST Identity Store;

Plain (plain)

Default template:

[User ID type, as documented in the REST Identity Store]
[User ID value]

The User ID type will default to localpart if:

• Only one line is returned
• The first line is empty

Bulk lookup

Configuration namespace:

exec:
  identity:
    lookup:
      bulk:
        ...

Tokens

No specific tokens are available.

Input

Supported input types and default templates:

JSON (json)

NOTE: Custom Templates are not supported.

Same as the REST Identity Store.

Plain (plain)

Not supported at this time. Use the JSON type.

Output

Supported output types and default templates:

JSON (json)

NOTE: Custom Templates are not supported.

Same as the REST Identity Store.

Plain (plain)

Not supported at this time. Use the JSON type.

Profile

The Profile feature can be enabled/disabled using:

exec:
  profile:
    enabled: <true/false>

---

The following Executables namespace are available, share the same input/output formats and templates:

Get Display name:

exec:
  profile:
    displayName:
      ...

Get 3PIDs:

exec:
  profile:
    threePid:
      ...

Get Roles:

exec:
  profile:
    role:
      ...

Tokens

No specific tokens are available.

Input

Supported input types and default templates:

JSON (json)

Same as the REST Identity Store;

Plain (plain)

Default template:

{localpart}
{domain}
{mxid}

Output

Supported output types and default templates:

JSON (json)

Same as the REST Identity Store;

Plain (plain)

Not supported at this time. Use the JSON type.