`lib-ldap` 库参考

原文: https://finproducts.atlassian.net/wiki/spaces/JIDD3/pages/34793521466/FIN+5.3.1+lib-ldap 中文整理基于 FIN 5.3.1

导读： LDAP认证系统模块

以下为 API 参考，保留英文以便对照源码；目录已列出（英文标题便于检索）；概述已尽量中译。

目录（导读）

lib
meta
docs
tags
views
Overview
Setup
- Enable LDAP SysMod
- Configure LDAP Settings
- Test LDAP Configuration
- Login Update Mode
- User Prototype Mapping
- Mapping LDAP Attributes to Tags
Using LDAP Authentication
- def
- supertypes
- src

概述（中译）

LDAP认证系统模块

API 正文（英文）

docs

Overview • Setup • Using LDAP Authentication


ldapUserProtoAttrVal	The value of this tag is used to help the LDAP mod determine which user prototypes an LDAP user maps to

views


ldapSettings	Settings for the LDAP system module

lib ldap

Overview

The LDAP SysMod enables users to authenticate to SkySpark by verifying their credentials against a remote LDAP server.

User passwords are not stored in the SkySpark User database
A user cannot reset their LDAP password through SkySpark
User tags are configured by mapping an LDAP user to a SkySpark user prototype.

The Settings | LDAP view allows configuration and testing of the LDAP server properties.

LDAP login has been tested against Microsoft Active Directory and ApacheDS.

Setup

The following steps are required to configure LDAP authentication

Enable the LDAP SysMod
Enter the LDAP Settings for your local environment
Test the LDAP Configuration
Configure user prototypes for LDAP

NOTE: The user's credentials must be passed in the clear from the browser to SkySpark in order to authenticate agaisnt the remote LDAP server. Therefore, it is highly recommended that you only enable LDAP authentication on SkySpark servers in a trusted environment, or which are running HTTPS.

Enable LDAP SysMod

Starting in SkySpark 3.0.23, there is a new view where you can enable SysMods located at Settings | SysMods. The ldap SysMod must be enabled to use LDAP authentication.

Configure LDAP Settings

Login with a local super user, ensure the LDAP SysMod is enabled and navigate to Host | Settings | LDAP. Configure the following settings for your local environment and use the Submit action to save the changes:

host - Enter the hostname or IP address of the LDAP server.
- Example: ldap.acme.com
port - Enter the port of the LDAP server
tls - Use TLS to connect to the LDAP server
- The LDAP server must be configured to support secure LDAP connections.
- TLS is Strongly Recommended - Refer to Trusted Certificates in docs for trusting the public certificate chain of your LDAP server.
connectionTimeout - LDAP connect timeout
readTimeout - LDAP read timeout
userBaseDN - The base distinguished name to search for Users. Users must exist under this base DN.
- Example: CN=SkySparkUsers,OU=Groups,DC=acme,DC=com
loginAttr - The name of the LDAP attribute used to look up the user in the LDAP server.
- Example: sAMAccountName or uid
- The value of the attribute chosen MUST match the username of the user attempting to login.
- NOTE: The LDAP mod also support login by email address. If the loginAttr doesn't match the supplied username, then the LDAP mod will automatically try to lookup the user by matching against the mail attribute.
loginUpdateMode - See Login Update Mode for details.
userAttrs - Additional attributes to retrieve for a user. By default, we always get the logintAttr and userProtoAttr.
userProtoAttr - The attribute to check on a user's LDAP entry for mapping to a user prototype in SkySpark. See User Prototype Mapping for details.
userProtoDefault - (optional) - If a user cannot be mapped to a prototype via the userProtoAttr, then use the prototype with this name as the default.
userProtoPriority - If a user maps to multiple user prototypes, this list specifies the priority of which one should be chosen. See User Prototype Mapping for details.
applyTagsFunc - See LDAP attribute mapping for details.
serviceAccountDN - The distinguished name of the Service Account used to bind to the LDAP server.
- Example: CN=SkySpark Service,OU=Service Accounts,DC=acme,DC=com
password - The password for the Service Account.

Test LDAP Configuration

The Settings | LDAP view allows you to verify that LDAP authentication is working. After submitting the settings, select the Verify Service Account Login button and the SkySpark server will attempt a LDAP login using the Service Account credentials.

If you see SUCCESS!! LDAP authentication should work for your users.

If you have the Use TLS setting configured to true, then make sure SkySpark trusts the connection. You can use the Host | Crypto | Trust Uri action to add the LDAP server certificate chain to the SkySpark trust store, but you MUST restart SkySpark for the connection to be trusted.

The LDAP mod can be configured to interact with users in the user database in several, flexible ways. Choose the option that suits your use cases:

authOnly: ( default ) LDAP will only be used for authenticating the user. The user must exist in the user database in order to log in.
updateOnLogin: Creates or updates the user database rec every time the user logs in by applying the configured prototype and invoking the applyTagsFunc (if configured). The user rec is only updated if the prototype assignment changes, or tags are modified by the the applyTagsFunc.

User Prototype Mapping

When a user successfully authenticates against the remote LDAP server, a SkySpark User must be synthesized in-memory to repersent the user for the session. In order to construct a valid user, an authenticated user must be mapped to a User Prototype.

Create the user prototypesyou need for your users.
Configure the ldapUserProtoAttrVal for each prototype you want to enable for use with the LDAP:
1. When the LDAP SysMod is enabled, you will see a new tag available for edit on a user prototype called ldapUserProtoAttrVal
2. The value of this tag is used to help the LDAP mod determine which user prototypes an LDAP user maps to. The LDAP mod will check the values of the userProtoAttr (as configured in the LDAP settings) when reading the user entry from LDAP, and if one of them matches this tag's value, then this prototype is a potential match for the user attempting to log in.
If you would like to ensure users can log in, even if they don't map to a user prototype, configure the userProtoDefault value in the LDAP settings.

Example

LDAP Settings:

userBaseDN: "OU=Dev,DC=skyfoundry,DC=local"
loginAttr: "sAMAccountName"
userProtoAttr: "memberOf"
userProtoPriority:"engineering, si, default"

User Prototypes

id: @engineering
userProto
userProtoName: "engineering"
dis:"Engineering"
userRole:"admin"
ldapUserProtoAttrVal: "CN=Engineering,OU=Dev,DC=skyfoundry,DC=local"

id: @si
userProto
userProtoName: "si"
dis:"System Integrator"
userRole:"op"
ldapUserProtoAttrVal: "CN=SI,OU=Dev,DC=skyfoundry,DC=local"
appAccess: "energy"

LDAP Entry for user bob in the remote LDAP server (represented as a Dict for clarity).

sAMAccountName: "bob"
memberOf: ["CN=SI,OU=Dev,DC=skyfoundry,DC=local"]
... other attributes ...

User bob attempts to login from the SkySpark login screen
The LDAP mod will search the userBaseDN OU=Dev,DC=skyfoundry,DC=local for an LDAP entry where the sAMAccountName equals bob. The entry exists so the LDAP mod will attempt to authenticate bob's credentials. Let's assume he entered the correct password
The LDAP mod now checks prototype priorities specified by the userProtoPriority setting in order to try and find the best prototype match for bob:
1. The first prototype in this list is engineering.
2. We look at the engineering user prototype. The ldapUserProtoAttrVal for this prototype is CN=Engineering,OU=Dev,DC=skyfoundry,DC=local. This value is not in the memberOf list specified on bob's LDAP entry. So we check the next prototype in the priority list.
3. The next prototype in the list is si.
4. We look at the si user prototype. The ldapUserProtoAttrVal for this prototype is CN=SI,OU=Dev,DC=skyfoundry,DC=local. This value is in the memberOf list for bob. So we choose this prototype to apply for bob.
The si prototype is used to create a synthetic user for Bob's session and Bob is successfully logged in. (Bob will be an operator with access only to the energy app).

Mapping LDAP Attributes to Tags

Sometimes it is necessary or desirable to set tags on a user based on the user's attributes as defined in the LDAP server. The LDAP settings page contains a setting called applyTagsFunc which allows you to define an Axon function that will be invoked prior to to creating the session for a user who successfully authenticates with LDAP. This callback can be used to set/modify tags on the user who is logging in.

The function accepts two parameters (user, attrs) where the user is a Dict with the current state of the user tags (after the prototype is applied). The attrs parameter is a Dict containing the LDAP attributes for the user as defined in the LDAP server. The function should return an updated user Dict.

NOTE: Sometimes LDAP attributes have names that are not valid Haystack tag names. In that case the name of the attribute in the attrs Dict will be the result of calling toTagName() on the LDAP attribute name.

NOTE: If the Axon function fails to parse or throws an error, then only superusers will still be able to log in.

Example

(user, attrs) => do
  // set projAccessFilter based on employeeType
  etype: attrs["employeeType"]
  if (etype == "tenant") user = user.set("projAccessFilter", "demo, tenantProj")
  return user
end

Using LDAP Authentication

After configuring LDAP, users will login the same way as local SkySpark users. Users can enter their username or email address (if an email address is set up for the user) and the username for the user account is passed to the LDAP server to search with the configured login attribute. If a user account is found in the LDAP server, the LDAP server will verify the user's password is correct. SkySpark does not store the user's password in the local SkySpark user database.

def

ldapUserProtoAttrVal

The value of this tag is used to help the LDAP mod determine which user prototypes an LDAP user maps to. The LDAP mod will check the values of the userProtoAttr (as configured on the LDAP mod settings) when reading the user entry from LDAP, and if one of them matches this tag's value, then this prototype is a potential match for the user attempting to log in.


def	ldapUserProtoAttrVal
is	str
lib	lib:ldap
tagOn	userProto

supertypes


val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

def

view:ldapSettings

Settings for the LDAP system module


appName	settings
def	view:ldapSettings
disKey	ui::ldap
icon	view
is	view
lib	lib:ldap
su	✓

supertypes


feature	Feature namespace of definitions formatted as `feature:name`
view	Fresco UI view

src

view:   {inherit:"form"}
submit: {action:"hostCommit"}
test:   {action:"ldapVerifySettings"}
data:   {expr:"hostSettings(\"ldap\", {password})"}

FIN Framework

Axon Language

Other

Fantom Language

Haxall & SkySpark

Project Haystack

FIN Libraries

System Libraries

`lib-ldap` 库参考

目录（导读）

概述（中译）

API 正文（英文）

docs

tags

views

lib ldap

Overview

Setup

Enable LDAP SysMod

Configure LDAP Settings

Test LDAP Configuration

User Prototype Mapping

Example

Mapping LDAP Attributes to Tags

Example

Using LDAP Authentication

def

ldapUserProtoAttrVal

meta

supertypes

def

view:ldapSettings

meta

supertypes

src

lib-ldap 库参考 ​

目录（导读） ​

概述（中译） ​

API 正文（英文） ​

docs ​

tags ​

views ​

lib ldap ​

Overview ​

Setup ​

Enable LDAP SysMod ​

Configure LDAP Settings ​

Test LDAP Configuration ​

Login Update Mode ​

User Prototype Mapping ​

Example ​

Mapping LDAP Attributes to Tags ​

Example ​

Using LDAP Authentication ​

def ​

ldapUserProtoAttrVal ​

meta ​

supertypes ​

def ​

view:ldapSettings ​

meta ​

supertypes ​

src ​

`lib-ldap` 库参考

目录（导读）

概述（中译）

API 正文（英文）

docs

tags

views

lib ldap

Overview

Setup

Enable LDAP SysMod

Configure LDAP Settings

Test LDAP Configuration

Login Update Mode

User Prototype Mapping

Example

Mapping LDAP Attributes to Tags

Example

Using LDAP Authentication

def

ldapUserProtoAttrVal

meta

supertypes

def

view:ldapSettings

meta

supertypes

src