Local user/key authentication service

Contents

Local user/API key authentication service, see Authentication, authorization and accounting for more details.

Setup

Use the template EVA_DIR/share/svc-tpl/svc-tpl-aaa-localauth.yml:

# Local users and API keys service
command: svc/eva-aaa-localauth
bus:
  path: var/bus.ipc
config:
  # the password policy is applied on user.set_password EAPI method only if
  # check_policy parameter is set to true.
  #
  # In practice, the policy is applied only if the password is changed by a
  # user itself via HMI HTTP API.
  #
  # Node administrator can set a password to any value using eva-shell
  password_policy:
    min_length: 8 # minimal password length
    required_letter: true # at least one letter is required
    #required_mixed_case: true # at least one uppercase and one lowercase letter is required
    required_number: true # at least one number is required
  # ACL service
  acl_svc: eva.aaa.acl
  # OTP service
  #otp_svc: eva.aaa.otp
  # allow one-time users
  one_time:
    # one-time user account expiration (sec)
    expires: 10
user: nobody

Create the service using eva-shell:

eva svc create eva.aaa.localauth /opt/eva4/share/svc-tpl/svc-tpl-aaa-localauth.yml

or using the bus CLI client:

cd /opt/eva4
cat DEPLOY.yml | ./bin/yml2mp | \
    ./sbin/bus ./var/bus.ipc rpc call eva.core svc.deploy -

(see eva.core::svc.deploy for more info)

EAPI methods

See EAPI commons for the common information about the bus, types, errors and RPC calls.

auth.key

Description	Authenticates a client using API key
Parameters	required
Returns	The method returns errors if auth is not successful

Parameters
Name	Type	Description	Required
key	String	API key value	yes
timeout	f64	Max operation timeout	no

auth.user

Description	Authenticates a client using a local user account
Parameters	required
Returns	The method returns errors if auth is not successful

Parameters
Name	Type	Description	Required
login	String	Account login	yes
password	String	Account password (plain text)	yes
timeout	f64	Max operation timeout	no

key.deploy

Description	Deploys API keys
Parameters	required
Returns	nothing

Parameters
Name	Type	Description	Required
keys	Vec<struct>	API keys (same as got in key.export)	yes

key.destroy

Description	Destroy a single API key
Parameters	required
Returns	nothing

Parameters
Name	Type	Description	Required
i	String	API key ID	yes

key.export

Description	Export API keys as a deployment
Parameters	required
Returns	API key deployment struct

Parameters
Name	Type	Description	Required
i	String	API key ID (can be mask)	yes

Return payload example:

{
    "keys": [
        {
            "acls": [
                "default"
            ],
            "id": "default",
            "key": "defaultXXX"
        }
    ]
}

key.get

Description	Get a single API key value
Parameters	required
Returns	API key ID/key value

Parameters
Name	Type	Description	Required
i	String	API key ID	yes

Return payload example:

{
    "id": "default",
    "key": "defaultXXX"
}

key.get_config

Description	Get configuration of a single API key
Parameters	required
Returns	API key configuration

Parameters
Name	Type	Description	Required
i	String	API key ID	yes

Return payload example:

{
    "acls": [
        "default"
    ],
    "id": "default",
    "key": "defaultXXX"
}

key.list

Description	List API keys
Parameters	none
Returns	List of defined API keys, they values and assigned ACLs

Return payload example:

[
    {
        "acls": [
            "admin"
        ],
        "id": "admin",
        "key": "mykey"
    },
    {
        "acls": [
            "default"
        ],
        "id": "default",
        "key": "defaultXXX"
    },
    {
        "acls": [],
        "id": "default-v3",
        "key": "default123"
    },
    {
        "acls": [
            "ui_all",
            "ui_default"
        ],
        "id": "ui",
        "key": "ij31i3j21345"
    },
    {
        "acls": [
            "ui_default"
        ],
        "id": "uid",
        "key": "YHiT172ani2KGoTUPSurSA1Rx6n7TVnL"
    }
]

key.regenerate

Description	Re-generates key value of API key
Parameters	required
Returns	API key configuration with a new key value

Parameters
Name	Type	Description	Required
i	String	API key ID	yes

Return payload example:

{
    "acls": [
        "default"
    ],
    "id": "default",
    "key": "uULa5QSORbEJX1QM3RYeC2kVwcVlg2zC"
}

key.undeploy

Description	Undeploy API keys
Parameters	required
Returns	nothing

Parameters
Name	Type	Description	Required
keys	Vec<struct/String>	API keys or a list of API key IDs	yes

password.hash

Description	Hashes the password with the requested algorithm
Parameters	required
Returns	password hash

Parameters
Name	Type	Description	Required
password	String	Plain password string string to hash	yes
algo	String	sha256, sha512 or pbkdf2	yes

Return payload example:

{
    "hash": "$1$CaqoIL8WXkDnqnwMXLeW5g==$qXQVPbRibRSomjtzKuyOePv59lx3eAQUR3yqAUS4YoE="
}

user.create_one_time

Description	Creates an one-time temporary user account, which is auto-deleted after the first login
Parameters	required
Returns	One-time account credentials

Parameters
Name	Type	Description	Required
acls	String	ACL IDs	yes
login	String	included into one-time login as OT.$login.$RANDOM	no

Return payload example:

{
    "login": "OT.test.eHlrGMgPlpqKmzTr",
    "password": "QZoz0jYRaL2BSdKc"
}

user.deploy

Description	Deploys local user accounts
Parameters	required
Returns	nothing

Parameters
Name	Type	Description	Required
users	Vec<struct>	Users (same as got in user.export, note: passwords must be sha256-hashed)	yes

user.destroy

Description	Destroy a single local user account
Parameters	required
Returns	nothing

Parameters
Name	Type	Description	Required
i	String	User login	yes

user.export

Description	Exports local user accounts as a deployment
Parameters	required
Returns	User accounts deployment struct

Parameters
Name	Type	Description	Required
i	String	Login (can be mask)	yes

Return payload example:

{
    "users": [
        {
            "acls": [
                "ui_default",
                "ui_all"
            ],
            "login": "operator",
            "password": "cd2eb0837c9b4c962c22d2ff8b5441b7b45805887f051d39bf133b583baf6860"
        }
    ]
}

user.get_config

Description	Get configuration of a single user account
Parameters	required
Returns	User account configuration

Parameters
Name	Type	Description	Required
i	String	User login	yes

Return payload example:

{
    "acls": [
        "ui_default",
        "ui_all"
    ],
    "login": "operator",
    "password": "cd2eb0837c9b4c962c22d2ff8b5441b7b45805887f051d39bf133b583baf6860"
}

user.get_profile_field

Description	Get user profile field
Parameters	required
Returns	Profile field

Parameters
Name	Type	Description	Required
i	String	User login	yes
field	String	Field name (email/phone)	yes

Return payload example:

{
    "readonly": false,
    "value": "admin@localhost"
}

user.list

Description	List local user accounts
Parameters	required
Returns	List of defined local user accounts, the ACLs and password hashes

Parameters
Name	Type	Description	Required
with_password	bool	Include user password hashses into the result	no

Return payload example:

[
    {
        "acls": [
            "admin"
        ],
        "login": "admin"
    },
   {
        "acls": [
            "ui_default",
            "ui_all"
        ],
        "login": "operator"
    }
]

user.set_password

Description	Changes user’s password. Does not require the current one, so consider calling auth.user* before*
Parameters	required
Returns	nothing

Parameters
Name	Type	Description	Required
i	String	User login	yes
password	String	New password (plain text)	yes
check_policy	bool	Check password policy	no

user.set_profile_field

Description	Set user profile field
Parameters	required
Returns	nothing

Parameters
Name	Type	Description	Required
i	String	User login	yes
field	String	Field name (email/phone)	yes
value	Any	Field value	yes

user.undeploy

Description	Undeploy local users
Parameters	required
Returns	nothing

Parameters
Name	Type	Description	Required
users	Vec<struct/String>	User structs or a list of user logins	yes