FIN 5.3.1 中文文档

外观

lib-certAuth 库参考 ​

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

导读： TLS 客户端证书认证模块

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

目录（导读） ​

  • lib
  • meta
  • docs
  • tags
  • views
  • def
  • supertypes
  • Overview
  • Setup
  • Using Certificate Authentication
    • Certificate Auth Settings
    • HTTPS Key Pair
  • Use Cases
  • Using a Reverse Proxy

概述（中译） ​

TLS 客户端证书认证模块

API 正文（英文） ​

docs ​

Overview • Setup • Using Certificate Authentication • Use Cases • Using a Reverse Proxy

tags ​

certificatePemPEM encoding of the User Certificate
userCertificateA user certificate

views ​

certAuthConfigUpload user certificates to configure certificate authentication
certAuthSettingsSettings for the Client Certificate Authentication module

def ​

certificatePem ​

PEM encoding of the User Certificate.

meta ​

defcertificatePem
isstr
liblib:certAuth
tagOnuserCertificate

supertypes ​

valData value type
scalarScalar is an atomic value kind
strUnicode string of characters

lib certAuth ​

Overview ​

The Certificate Authentication (certAuth) AuthMod enables TLS Client Certificate Authentication to SkySpark. This allows users to skip the standard SkySpark username/password login page and use a certificate to authenticate. In order to use Certificate Authentication, SkySpark users must already be connecting to SkySpark over HTTPS (either using the internal HTTPS server or by using a reverse proxy).

The Settings|Certificate Auth view allows configuration of the Certificate Auth settings.

Setup ​

The following steps are required to use Certificate authentication:

  1. Enable the certAuth SysMod from the Host|SysMods view
  2. Configure the required Certificate Auth Settings (see Certificate Auth Settings)
  3. Add a certificate key pair to the SkySpark Trust Store (see HTTPS Key Pair)
  4. Change the userAuth tag for one or more local SkySpark users to AuthMod - certAuth
  5. Upload one or more user public certificates using the User|User Certificate Config view
  6. Assign uploaded certificate to a SkySpark user configured for Certificate Authentication
  7. Users must access a specific path to authenticate (see Using Certificate Authentication)

IMPORTANT: User's must have their certificate loaded on their system so that the web browser allows the user to select their certificate for authentication.

Using Certificate Authentication ​

After completing the Certificate Auth setup instructions, SkySpark will be listening for connections on the configured certAuthPort. Users that access SkySpark through a web browser will still see the standard login page when they navigate to the SkySpark Server Url (unless the certAuth/ path is accessed directly). Users can click the Certificate Login link or access the certAuth/ path directly by typing it in the address bar to login with their certificate. The browser will be redirected to the configured certAuthPort and the user will be prompted to select their certificate. Most browsers will cache the selected certificate so user's may not be prompted to select a certificate on subsequent logins. After the TLS session is established the browser will be automatically redirected back to SkySpark and logged in. Review the user cases section for additional information on using certificate authentication.

IMPORTANT: SkySpark will not automatically create users when a certificate authentication login attempt is made. User records must be created before logging in, the userAuth tag must be set to AuthMod - certAuth and the user's public certificate must be uploaded and assigned to the user record.

Certificate Auth Settings ​

After enabling the certAuth SysMod on the Host|SysMods view, navigate to Settings|Certificate Auth view.

The only required setting is certAuthPort. SkySpark will open another listening port to handle certificate authentication. This port must be configured for HTTPS so it requires a key pair. Ensure the configured port does not conflict with the standard SkySpark HTTP or HTTPS port.

  1. addr - Optional setting. If the SkySpark server has multiple IP addresses assigned, only listen for connections to this IP address.
  2. certAuthPort - Required setting. The local port SkySpark will listen on for Certificate Auth logins.
  3. useReverseProxy - If users connect to SkySpark through a reverse proxy, set this setting to true. Review the Using a Reverse Proxy section.
  4. certAuthProxyPort - Required setting if useReverseProxy set to true. The port the reverse proxy server is listening on for client certificate authentication.
  5. displayCertificateLogin - Add a Certificate Login link to the SkySpark login page. This makes it easier to login with a certificate, but users that don't have their browser configured properly will get an error if they click the link.
  6. supportText - Optional setting. Fandoc formatted text that will display on certAuth/authFailed page that can be used to help users troubleshoot login issues.

HTTPS Key Pair ​

Follow the standard SkySpark instructions to load an HTTPS key pair if SkySpark is not already using HTTPS for its standard login. If desired, a different key pair can be loaded for the certificate authentication port using the alias certauth.

Use Cases ​

The primary use case that drove the design of this feature, was offering a login option that did not depend on passwords. Configuring users with the su userRole to use certificate authentication can mitigate the security problems associated with passwords and will allow organizations that already use certificates for secure logins to other applications to leverage their existing investment in their Public Key Infrastructure (PKI) for SkySpark logins.

A secondary use case was to allow authentication to the SkySpark REST API from client libraries that do not support Haystack Authentication. Now if a client library connects directly to <server>:certAuthPort/token and performs client certificate authentication, the authToken will be returned in the Authentication-Info header that can be reused for API requests sent to the standard SkySpark listening port by setting the Authorization header as shown below:

Authorization: BEARER authToken=web-LYF0...

Using a Reverse Proxy ​

If SkySpark is running behind a reverse proxy, the reverse proxy must support passing through the TLS session to the SkySpark certAuthPort without terminating the TLS session. This may be referred to as a TLS Passthrough Proxy or a straight TCP proxy which will proxy TLS connections as-is without decrypting and re-encrypting.

HAProxy ​

HAProxy can be configured as a straight TCP proxy by using mode tcp. An example configuration is shown below where the IP address and ports need to be updated to match the local configuration:

frontend localhost_Passthrough
  mode  tcp
  bind  *:{certAuthProxyPort}
  default_backend   TLS_Passthrough

backend TLS_Passthrough
  mode      tcp
  server  MyServer  xxx.xxx.xxx.xxx:{certAuthPort}

Nginx ​

Nginx supports a passthrough feature by embedding a server directive in the stream directive. The stream directive cannot exist within an http directive. An example configuration is shown below where the IP address and ports need to be updated to match the local configuration:

stream {
  server {
    listen {certAuthProxyPort};
    listen [::]:{certAuthProxyPort};

    proxy_pass xxx.xxx.xxx.xxx:{certAuthPort};
  }
}

def ​

userCertificate ​

A user certificate. Identifies a public certificate used for user login with the Certificate Authentication SysMod.

meta ​

defuserCertificate
iconuser
isentity
liblib:certAuth
mandatory✓

supertypes ​

markerMarker labels a dict with typing information
entityTop-level dicts with a unique identifier

tags ​

certificatePemPEM encoding of the User Certificate
disDisplay name for an entity
idDefines the unique identifier of an entity in system using a ref value type
userRefReference to user entity

def ​

view:certAuthConfig ​

Upload user certificates to configure certificate authentication

meta ​

appNameusers
defview:certAuthConfig
disUser Certificate Config
iconview
isview
liblib:certAuth
order900
su✓

supertypes ​

featureFeature namespace of definitions formatted as feature:name
viewFresco UI view

src ​

view:    { inherit:"table" }
upload:  { disKey:"ui::upload" action:"certAuthMod::CertUploadAction.onUpload" }
assign:  { disKey:"certAuthMod::certAuth.assignUser" action:"certAuthMod::CertAssignAction.onAssign" select }
delete:  { action:"certAuthDelete" }
data:    { expr:"certAuthReadAll()" }

def ​

view:certAuthSettings ​

Settings for the Client Certificate Authentication module

meta ​

appNamesettings
defview:certAuthSettings
disKeycertAuthMod::certAuthSettings
iconview
isview
liblib:certAuth
su✓

supertypes ​

featureFeature namespace of definitions formatted as feature:name
viewFresco UI view

src ​

view:       {inherit:"form"}
submit:     {action:"hostCommit"}
validate:   {action:"certAuthValidateConfig"}
data:       {expr:"hostSettings(\"certAuth\")"}