Active directory auth service

Contents

• Active directory auth service

  • Setup

  • EAPI methods

    • auth.user

    • cache.delete

    • cache.purge

    • user.get_profile_field

  • Preparing related services

  • Active Directory configuration

  • Usage

    • Authentication

    • ACL prefixes

Requires EVA ICS Enterprise.

Active directory user authentication service, see Authentication, authorization and accounting for more details.

Setup

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

# Active directory authentication service
command: svc/eva-aaa-msad
bus:
  path: var/bus.ipc
config:
  ## ACL service
  acl_svc: eva.aaa.acl
  ## OTP service
  #otp_svc: eva.aaa.otp
  ## domain=ad_host, e.g. mydomain.com: ad.mydomain.com (or IP)
  #hosts:
  #  mydomain.com: ad.mydomain.com
  #  mydomain2.com: 1.2.3.4
  ## optional default domain, if no domain specified in user name
  #default_domain: mydomain.com
  ## optional default domain controller host/ip
  #default_host: ad.mydomain.com
  ## organization unit (default is EVA)
  #ou: EVA
  ## optional ACL prefix
  #acl_prefix: "msad_"
  #tls: true
  ## alternative CA file (.der for DER, any other extension for PEM)
  #tls_ca: path/to/crt
  ## alternative CA file, per domain (has higher priority then the default one)
  #domains_tls_ca:
  # mydomain.com: path/to/crt
  # mydomain2.com: path/to/crt2
  #no_tls_verify: false
  ## cache entries and use the cache if ad is unavailable
  #cache_time: 86400
  ## if cached entry exists - use it before ad authentication
  #cache_first: false
  ## required to get user profile fields (e.g. email addresses)
  #service_account_login: someuser
  #service_account_password: secret
  # when email profile field is requested, return login in case of username@domain format
  #login_as_email: ignore # possible values: prefer, fallback
user: eva

Create the service using eva-shell:

eva svc create eva.aaa.msad /opt/eva4/share/svc-tpl/svc-tpl-aaa-msad.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.user

Description	Authenticates a client using Active Directory 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

cache.delete

Description	Delete cache entry for a user
Parameters	required
Returns	nothing

Parameters

Name	Type	Description	Required
i	String	Account login	yes

cache.purge

Description	Purge cache
Parameters	none
Returns	nothing

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": true,
    "value": "admin@localhost"
}

Preparing related services

Edit the HMI service (e.g. “eva.hmi.default”) and add the additional authentication service provider into “auth_svcs” section:

eva svc edit eva.hmi.default

auth_svcs:
    - eva.aaa.localauth
    - eva.aaa.msad

The above configuration will try to authenticate users against local accounts and switch to Active Directory if no local account exits. To authenticate against Active Directory accounts first, change the order of the authentication services.

Note

The service can be deployed multiple times with different configs to support e.g. non-standard Active Directory federation setups.

Active Directory configuration

Log into the Active Directory domain controller, open Active Directory Users and Computers and create an organizational unit (default - EVA)

or with Powershell:

New-ADOrganizationalUnit -Name "EVA"

Create security groups inside the organizational unit. Group names must match IDs of EVA ICS ACLs:

or with Powershell:

New-ADGroup -Name "operator" -Path "OU=EVA,DC=your,DC=domain,DC=com"

Assign a security group to a domain user. If multiple security groups are assigned, a combined ACL is created.

or with Powershell:

Add-ADGroupMember -Identity "user" -Members "operator"

Usage

Authentication

After OU security group is assigned to Active Directory user, its credentials can be immediately used for authentication in EVA ICS. It is not necessary to create a local user in local authentication services.

Users can authenticate themselves either with “login” or with “login@domain”.

If “default_domain” option is specified in the configuration, users can omit domains in their logins and the default domain is used for authentication.

Note

For cached credentials, “user” and “user@domain” are two different users. If such behavior leads to a logical confusion for 3rd party software or UI apps, disable “default_domain” option in the configuration.

If “default_domain” option is not specified, users MUST always specify a domain in their logins.

ACL prefixes

If acl_prefix is specified in the service configuration, it will look for ACL with id {acl_prefix}{AD security group}, e.g.

• acl_prefix = msad_

• user has assigned security group EVA/operator

• EVA ICS ACL must have id msad_operator