FIN 5.3.1 中文文档

外观

lib-samlSso 库参考 ​

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

导读： SAML 单点登录认证系统模块

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

目录（导读） ​

  • lib
  • meta
  • docs
  • tags
  • views
  • Overview
  • Logging in with Local Accounts
  • Using SamlSso Authentication
  • Setup
    • SAML Attributes
    • SAML SSO Settings
    • Manually Import IdP Signing Certificate
    • Login Update Mode
    • User Prototype Mapping
    • Optional User Attributes
    • Example applyTagsFunc
    • SAML IdP Configuration
    • SkySpark Entity Id
    • SkySpark Assertion Consumer Service Uri
  • Encrypted Assertions

概述（中译） ​

SAML 单点登录认证系统模块

API 正文（英文） ​

docs ​

Overview • Logging in with Local Accounts • Using SamlSso Authentication • Setup • Encrypted Assertions

tags ​

samlSsoUserProtoAttrValThe value of this tag is used to help the SAML SSO auth mod determine which user prototypes a SAML SSO user matches

views ​

samlSsoSettingsSettings for the SAML system module

lib samlSso ​

Overview ​

The SAML SSO AuthMod incorporates single sign-on functionality into the login process:

  • Enables single sign-on (SSO) functionality via SAML allowing users to skip the standard SkySpark username/password login page if they are already logged in to their SSO environment.
  • User record tags can be dynamically mapped or updated during SAML login with a user prototype.
  • SkySpark uses the HTTP Redirect Binding for logging in to the Identity Provider (IdP).

The Settings|SAML SSO view allows configuration of the single sign-on properties.

Logging in with Local Accounts ​

After setting up SAML, navigating to the SkySpark Uri will automatically attempt SAML login via single sign-on so the standard SkySpark login page will not be displayed. During initial setup or in the rare instance where the SkySpark host is having communication issues with the SAML server, it may be necessary to login with a local SkySpark user account. To login with local SkySpark accounts, such as the su account created during setup, access {SkySpark URL:port}/user/login directly, which will display the standard SkySpark user login page (bypassing single sign-on).

Using SamlSso Authentication ​

After configuring SamlSso, users will no longer see the standard login page when they navigate to the SkySpark Server Url (unless the Uri described in Local Account Login is accessed directly). The SamlSso AuthMod will verify SAML assertions sent by the IdP to authenticate the user and read configured attributes from the assertion to authorize the user.

SkySpark provides flexibility in how user records are managed when using SAML. User roles and access filters can be managed entirely in the SkySpark User app or users can be synthesized during login by mapping the user to a configured prototype in SkySpark and using the synthesized user to create a local user record. Therefore, users do not need to be setup prior to login, but SkySpark can be configured to require that a local user record exists. Review the details of the Login Update Mode setting for more information.

Setup ​

The following steps are required to configure SAML SSO authentication:

  1. Enable the samlSso SysMod from the Host|SysMods view
  2. Identify required user attributes (see SAML Attributes)
  3. Enter the required SAML Settings (see SAML SSO Settings)
  4. Configure one or more user prototypes for SAML (see User Prototype Mapping)
  5. Configure IdP (see SAML IdP Configuration)
  6. If using the authOnly Login Update Mode, the userAuth tag must be set to AuthMod - samlSso

IMPORTANT: If there are already local user records created in the SkySpark user database that will now use SAML, the userAuth tag must be manually changed to AuthMod - samlSso.

SAML Attributes ​

Two attributes must be included in an Assertion sent by the IdP:

  1. The attribute (samlResponseUsernameAttribute) that identifies the username of the user.
  2. The attribute (userProtoAttr) that identifies what prototype to map the user to in SkySpark. If a default prototype is configured, this attribute is not required.

Record the names of these attributes as they must be configured in SkySpark.

IMPORTANT: When configuring the attributes, make sure the value of Name is used, not FriendlyName.

In the example below from a SAML attribute statement, this attribute has a FriendlyName of uid and a Name of urn:oid:0.9.2342.19200300.100.1.1. In SkySpark, the value that must be configured for the samlResponseUsernameAttribute is urn:oid:0.9.2342.19200300.100.1.1 assuming this is the attribute that will be used to identify the username.

<saml2:Attribute FriendlyName="uid"
                 Name="urn:oid:0.9.2342.19200300.100.1.1"
                 NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
                 >
    <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                          xsi:type="xsd:string"
                          >samlusername</saml2:AttributeValue>
</saml2:Attribute>

SAML SSO Settings ​

After enabling the samlSso SysMod on the Host|SysMods view, navigate to Settings|SAML SSO view.

The easiest way to configure SAML, is by using the SAML IdP Metadata. SkySpark can import the IdP Metadata from a Uri or from text.

Click the Import IdP Metadata (Uri) or Import IdP Metadata (Text) button and enter either the Uri to the IdP's XML metadata location or copy and paste the IdP Metadata into the xml field. Importing from a Uri is preferred, but if the IdP does not host the metadata, then the Text option can be used. SkySpark will read the XML document and automatically configure the host, port, tls, idpLoginPath, and idpEntityId settings. SkySpark will also automatically import the IdP Signing Certificate(s) to verify digitally signed assertions sent by the IdP. SkySpark requires all messages sent from the IdP to be digitally signed.

After the import, the samlResponseUsernameAttribute and userProtoAttr must be manually configured with the names identified in the SAML Attributes section. The userProtoPriority setting must also be manually configured. See the prototype example for guidance on how to configure the userProtoPriority setting.

IMPORTANT: All these settings may be manually configured if the IdP XML Metadata is not accessible from SkySpark. In that case, be sure to Manually Import the IdP Signing Certificate.

  1. autoUpdateIdPMetadataUri - Read Only setting configured via Import IdP Metadata Action. This setting is used to identify the Uri that will be used to check for and automatically update IdP Signing Certs. The IdP Metadata must be digitally signed to support the auto update workflow. If the IdP Metadata is not digitally signed or the IdP Metadata was imported via Text, no Uri will be displayed and auto updates will not occur.
  2. host - Enter the hostname or IP address of the SAML server.
    • Example: saml.acme.com
  3. port - Enter the port of the SAML server
  4. tls - Use TLS to connect to the SAML server
  5. idpLoginPath - Path to the login HTTP REDIRECT binding on the IdP.
  6. idpEntityId - Entity ID of the IdP, which will be verified by SkySpark in each message.
  7. loginUpdateMode - See Login Update Mode for details.
  8. samlResponseUsernameAttribute - Required The attribute in the SAML assertion to use for the synthesized user's username.
  9. userProtoAttr - When using updateOnLogin loginUpdateMode, this setting is Required unless userProtoDefault is configured. This setting defines the attribute in the user's SAML assertion that is used to determine the user's prototype. See User Prototype Mapping for details.
  10. userProtoPriority - When using updateOnLogin loginUpdateMode, this setting is Required unless userProtoDefault is configured. 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.
  11. userProtoDefault - Optional setting. If a user cannot be mapped to a prototype via the userProtoAttr, then use the prototype with this name as the default.
  12. applyTagsFunc - Optional setting. Axon callback function used to set/change tags on a user before a session is created. The function should take two parameters (user, attrs) where user is the current User tags (with prototype already applied) and attrs is the SAML assertion attributes Dict for that user. Return the updated User Dict. See Example applyTagsFunc.
  13. supportText - Optional setting. Fandoc formatted text that will display on samlSso/authFailed page that can be used to help users troubleshoot login issues.

Manually Import IdP Signing Certificate ​

SkySpark requires all SAML Assertions to be digitally signed. SkySpark must trust the certificate used by the IdP to digitally sign SAML Assertions. Refer to Trusted Certificates for steps to manually import the IdP Signing Certificate.

Login Update Mode ​

The SAML mod can be configured to interact with users in the user database in several, flexible ways. Choose the option that meets the project requirements:

  • authOnly: ( default ) SAML 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 using SamlSso, the user is not prompted for a username or password so the SAML assertion is used to lookup a SkySpark User in the local user database. If a local user record cannot be found and Login Update Mode is configured to updateOnLogin then to construct a valid user, an authenticated user must be mapped to a User Prototype.

  1. Create the user prototypes required for the host.
  2. Configure the samlSsoUserProtoAttrVal for each prototype that will be used for SamlSso:
    1. When the SamlSso SysMod is enabled, a new tag is available to add to a user prototype called samlSsoUserProtoAttrVal
    2. The value of this tag is used to help the SamlSsoMod determine which user prototypes a SamlSso user maps to. The SamlSsoMod will check the values of the userProtoAttr (as configured in the Saml SSO settings)
    3. After a user is authenticated using SamlSso, the SamlSsoMod looks up the user's attribute in the SAML assertion
    4. When reading the user's attributes SAML assertion, if one of them matches this tag's value, then this prototype is a potential match for the user attempting to log in.
  3. Configure one or more user prototypes as a comma separated list (enter userProtoName of each userProto record) for the userProtoPriority setting.
  4. Optionally configure a default user prototype (enter userProtoName of userProto record) so users can still login when they cannot be mapped to an existing prototype. As a best practice, this prototype should have an operator role and limited access.

Example ​

SAML SSO Settings:

userProtoAttr: "SkySparkUserPrototype"
userProtoPriority:"engineering, si, default"

User Prototypes

id: @engineering
userProto
userProtoName: "engineering"
dis:"Engineering"
userRole:"admin"
samlSsoUserProtoAttrVal: "Engineering"

id: @si
userProto
userProtoName: "si"
dis:"System Integrator"
userRole:"op"
samlSsoUserProtoAttrVal: "SI"
appAccess: "energy"

SAML assertion for user bob (represented as a Dict for clarity).

username: "bob"
email: "bob@company.com"
SkySparkUserPrototype: "SI"
... other attributes ...
  1. User bob authenticates via SamlSso.
  2. The SamlSsoMod will determine the username from the SAML assertion is bob.
  3. The SamlSsoMod 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. The samlSsoUserProtoAttrVal for this prototype is Engineering. This value is not in the SkySparkUserPrototype list specified in Bob's SAML assertion.
    2. The next prototype in the list is si. The samlSsoUserProtoAttrVal for this prototype is SI. This value is in the SkySparkUserPrototype list for Bob.
  4. 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).

NOTE: It is an error for a user to exist in the local user database with a username that matches the username of a user logging in via SamlSso. If this condition is detected, the user will not be allowed to log in. An error to this effect will be logged to the console.

Optional User Attributes ​

The following optional SAML attributes will be set while synthesizing the user if they exist:

  1. Display Name (dis) - Assertion Attribute: displayName
  2. Email Address (email) - Assertion Attribute: email

NOTE: The dis tag is set to the username if a displayName attribute does not exist.

Example applyTagsFunc ​

A simple example use case for the applyTagsFunc is to add the email address to the synthesized user. In this example, the user's email address is provided in the Assertion with the attribute name skysparkEmailAddress.

NOTE: Every key in the attrs Dict is a List of values (a single value will be a List with one item). Additionally, each attribute returned from the identity provider is converted to a valid tag name using toTagName() so accessing the name of the attribute may differ from what is shown in the encoded SAML authentication response message. During initial configuration, echo(attrs) can be helpful to verify attribute names.

(user, attrs) => do
  emailList: attrs["skysparkEmailAddress"]
  if (emailList != null and emailList.size == 1)
    user = user.set("email", emailList.first)
  return user
end

SAML IdP Configuration ​

On the Settings|SAML SSO view, click the Show SkySpark SP Metadata button to display the SkySpark SAML Metadata. Some IdPs will support configuring the SkySpark Service Provider by copying and pasting this XML into the IdP SP configuration page. By default, the siteUri setting is used in the two locations specified below as {siteUri}.

The entityId does not include the port. The SkySpark siteUri is configured on the Settings|HTTP view. When configuring the IdP it is important to use the address that users will connect to SkySpark with as the IdP will likely reject a request for an unknown Entity ID. Additionally, SkySpark will check that the Audience lists the SkySpark Entity ID in the response.

<?xml version='1.0' encoding='UTF-8'?>
<md:EntityDescriptor xmlns:md='urn:oasis:names:tc:SAML:2.0:metadata' entityID='{siteUri without port}'>
 <md:SPSSODescriptor WantAssertionsSigned='true' protocolSupportEnumeration='urn:oasis:names:tc:SAML:2.0:protocol'>
  <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</md:NameIDFormat>
  <md:AssertionConsumerService Binding='urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST' Location='{siteUri}/samlSso/assertionConsumerService' index='0' isDefault='true'/>
 </md:SPSSODescriptor>
</md:EntityDescriptor>

For convenience when displaying the SkySpark SP Metadata, the SkySpark Entity ID and Assertion Consumer binding are called out below the XML. When copying the SkySpark Metadata to an IdP, do not include the lines shown below:

SkySpark Entity ID: {siteUri without port}

SkySpark Assertion Consumer HTTP-POST Binding: {siteUri}/samlSso/assertionConsumerService

SkySpark Entity Id ​

By default, the siteUri of the SkySpark server is used for the SkySpark Entity Id, excluding the port. This can be overridden by adding a tag to the samlSso entry in var/host/folio.trio called skysparkEntityId and specify a Str value.

Restart SkySpark after making the change.

SkySpark Assertion Consumer Service Uri ​

By default, the siteUri of the SkySpark server is used to build the Assertion Consumer Service Uri using this format: {siteUri}/samlSso/assertionConsumerService

Most of the time, it is recommended to use the siteUri, but when working across numerous dev and test environments it can simplify testing to use something other than the siteUri. To do that, add a tag to the samlSso entry in var/host/folio.trio called skysparkBaseUri and specify a Uri value. Remember to include the port if necessary. When adding this tag, the default Entity Id will also change. See SkySpark Entity Id section to change the SkySpark Entity Id.

Restart SkySpark after making the change.

Encrypted Assertions ​

Support for encrypted assertions is not enabled by default. Additional support pods are required.

def ​

samlSsoUserProtoAttrVal ​

The value of this tag is used to help the SAML SSO auth mod determine which user prototypes a SAML SSO user matches. The SAML SSO mod checks the values of the userProtoAttr (as configured in the SAML SSO settings) when reading assertion from the configured SAML server, and if one of them matches this tag's value, then this prototype is a potential match for the user attempting to log in.

meta ​

defsamlSsoUserProtoAttrVal
isstr
liblib:samlSso
tagOnuserProto

supertypes ​

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

def ​

view:samlSsoSettings ​

Settings for the SAML system module

meta ​

appNamesettings
defview:samlSsoSettings
disKeysamlSsoMod::samlSsoSettings
iconview
isview
liblib:samlSso
su✓

supertypes ​

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

src ​

view:       {inherit:"form"}
submit:     {action:"hostCommit"}
import:     {action:"samlImportIdPMetadataUri" templateName:"importIdPMetadataUriTemplate"}
importText: {action:"samlImportIdPMetadataText" templateName:"importIdPMetadataTextTemplate"}
print:      {action:"samlShowSkySparkMetadata"}
validate:   {action:"samlValidateConfig"}
data:       {expr:"hostSettings(\"samlSso\")"}