SAML 2.0 Best Practices And Technical Setup_allowed saml authentication request's nameidpolicy-CSDN博客

SAML (Security Assertion Markup Language) is an XML and HTTP based secure, industry-standard way to perform Single-Sign On (SSO) between online applications. MindTouch supports SAML out of the box, and it is the preferred way to integrate SSO for your users.

Customer Effort

SAML SSO scenarios are not trivial integrations to setup, test, and deploy. Your organization will likely require an IT Administrator with knowledge of SAML SSO in order to successfully deploy this SSO solution. MindTouch-supported SAML SSO vendors, such as OneLogin and Salesforce, simplify the configuration required by your organization to deploy SAML SSO.

Certified Identity Providers (IdP)

MindTouch's coverage of SAML SSO features allows integration with any authentication provider that supports SAML. There are IdP's that MindTouch tests regularly and supports with high confidence. MindTouch does not support the integration with any IdP's other than the following listed:

Salesforce.com

(Force.com, Service Cloud)

Microsoft Active Directory Federated Services (ADFS) 2.0+

OneLogin

PingOne

(by PingIdentity)

How Do I Configure SAML SSO?

You will need the following information about your SAML SSO Identity Provider:

Entity ID (required): The unique identifier for your IdP. MindTouch will only accept SAML assertions from this ID.
Single Sign On Service (required): The SSO endpoint that MindTouch will send authentication requests to.
Single Logout Service (recommended): The SLO endpoint that MindTouch will send logout requests to.
Public X.509 Certificate (required): MindTouch will use this to establish trust with your IdP. MindTouch will validate incoming SAML assertions from the IdP with this certificate.

In addition, SAML SSO sessions can occur behind existing VPN or IP-restrictions if it is enabled for your MindTouch site. See the Security section below for more information about additional security measures that can be configured for the SAML SSO scenario.

Once you have all required information, you can head to the MindTouch Control Panel and open the Authentication > Single Sign-On > SAML section, to configure SAML SSO.

SAML SSO Setup and IdP Configuration

Enable Single Sign-On with SAML (optional): Require all sign in requests to redirect to your SAML SSO Login URL.
Enable Debug & Error Reporting (optional): Show verbose SAML SSO request and response data in page informational messages. This feature is not meant for production use, as it may contain sensitive information.
Federation Metadata Document (Available after a valid SAML SSO configuration has been saved): Links to the SAML SSO Service Provider Metadata XML document.
Upload Identity Provider Metadata (optional): This file upload button allows you to upload your IdP Metadata XML and pre-populate some or all of the IdP configuration fields on this page. Changes do not take affect until the configuration is saved, by clicking the "Save" button at the bottom of the page.
Identity Provider Entity ID (required): he unique identifier for your IdP. MindTouch will only accept SAML assertions from this ID.
Login URL (required): The SSO endpoint that MindTouch will send authentication requests to.
Logout URL (recommended): The SLO endpoint that MindTouch will send logout requests to.
Identity Provider x.509 Signing Certificate (required): MindTouch will use this to establish trust with your IdP. MindTouch will validate incoming SAML assertions from the IdP with this certificate.

SAML SSO Service Provider Configuration

Service Provider Private Key (recommended): Used to sign requests to the IdP, and decrypt responses from the IdP.
Service Provider x.509 Certificate (recommended): Used to sign requests to the IdP, and decrypt responses from the IdP.
NameID Format (optional): The allowed NameID formats are:
- urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
  - Preferred in nearly every scenario. Persistent usernames ensure that the identity between MindTouch and the IdP never changes.
- urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
  - Compatibility requirement for Ping Identity's PingOne service to authenticate with a username/password combination.

Service Provider Private Key and x.509 Certificate

This is an optional service provider certificate / key pair that allows SAML requests to be signed and/or encrypted (if the IdP supports decryption). If you do not have a private key and public certificate to use for SAML SSO, you can generate your own pair with a UNIX-like system and OpenSSL.

Note: Since a certificate / key pair can be generated on any UNIX system, MindTouch does not provide a Service Provider certificate/key pair. Customers who wish to utilize this option for their configuration will need to provide their own certificate / key pair. This allows the customer to determine the strength of their encryption key for their organization's needs.

A self-signed certificate will work for this option; please use the steps below to generate a self-signed certificate in a UNIX environment:

To begin with, you need to generate the root CA key (this is what signs all issued certs):

`1`	`openssl genrsa -out rootCA.key 2048`

Generate the self-signed (with the key previously generated) root CA certificate:

`1`	`openssl req -x509 -new -nodes -key rootCA.key -days 365 -out rootCA.crt`

SAML SSO User and Group Configuration

Custom Display Name Pattern (optional): A find-and-replace pattern to build a display name from any attributes in the IdP sign-on response XML. See the User Information and Group sections below for more information about configuring user display names.
Group List Attribute (optional): The name of the SAML assertion attribute to look up for a list of groups to synchronize with the user's current group membership list. See the Group section below for more information about configuring MindTouch group membership synchronization with your IdP.
Group List Attribute Delimiter (optional): The delimiter to split up the attribute value into multiple values. See the Group section below for more information about configuring MindTouch group membership synchronization with your IdP.

SAML SSO Terminology

SAML SSO has two high-level concepts used to identify the systems in a SAML SSO scenario:

Service Provider (SP): The application the user needs to access, in this case the MindTouch site.
Identity Provider (IdP): The sign on system that will authenticate the user via username and password, or another verification method.

All SAML SSO scenarios share common terminology to describe requests and responses between the SP and IdP:

Authentication Request (AuthnRequest): A request from the SP to the IdP, made on behalf of the user after they initiate sign on. MindTouch initiates sign on when a user clicks the sign on link, or attempts to visit a protected resource such as a page or file attachment.
Assertion: An XML document, either part of an IdP's response to an authentication request or an IdP's unsolicited request to sign a user into a SP, that contains the metadata required to sign on or create a user on the SP.

Supported SSO/SLO Scenarios

There are two primary SAML SSO scenarios supported by MindTouch. MindTouch supports SAML 2.0 SSO with HTTP Redirect-POST binding. Authentication requests from the SP are sent to the IdP as an HTTP redirect. Responses or requests from the IdP to the SP are expected to be sent as HTTP Post.

SP-Initiated SSO

SP-Initiated SSO is a scenario in which the user starts the sign-on flow from MindTouch either actively or passively.

Active SSO

The user signs into MindTouch by clicking the Sign In link.

Passive SSO

The user visits a private page or file attachment which they cannot access without authentication.

Authenticating with IdP

Both Active and Passive SSO will send the user to the IdP for authentication.

IdP-Initiated SSO

A user is using an internal application such as Salesforce, and has already authenticated with the IdP. They click on a link to the MindTouch site, which begins a SSO session. If needed, a new user is created on MindTouch (or the existing user is found), and the user is logged in.

Single Logout

In addition to SSO, MindTouch supports SAML 2.0 Single Logout (SLO) with HTTP Redirect-Redirect binding. SLO allows a MindTouch user to click the Sign Out button on a MindTouch site, which signs the user out of both MindTouch and the IdP.

While SLO is optional, its highly recommended for private MindTouch sites. Without SLO, signing out of a MindTouch site redirects the user to the SAML SSO authentication provider, which maintains the SSO session, sending the user back to MindTouch signed in. In effect, it creates a scenario where the user cannot sign out, without signing out of the SAML SSO authentication provider first, creating a confusing experience.

User Clicks Sign Out

The user actively clicks the sign-out link in MindTouch.

IdP Sends Unsolicited Logout Request

If the IdP and all SP's in the federated SSO session are configured correctly and the user signs out of any other application in the federated SSO session, MindTouch will receive a sign out request from the IdP and sign the user out of MindTouch.

User Information

MindTouch will attempt to extract the following information from IdP sign-on responses:

Username (required): The username to create or lookup on the MindTouch site.
- MindTouch will look for this value in the response XML Response/Assertion/Subject/NameID node.
- The allowed NameID formats are:
  - urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
    - Preferred in nearly every scenario. Persistent usernames ensure that the identity between MindTouch and the IdP never changes.
  - urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
    - Compatibility requirement for Ping Identity's PingOne service to authenticate with a username/password combination.
Display Name (optional): This information sets the user's display name in MindTouch, which is shown in place of their username. This is often a friendlier version of a username, such as "Bob Jones" instead of "rjones."
- MindTouch will attempt to build a display name from the IdP sign-on response in the following ways, in order, using IdP sign-on response attributes. Attributes are found in the IdP sign-on response XML nodes matching Response/Assertion/AttributeStatement/Attribute/AttributeValue.
  1. Use a find-and-replace pattern to build a display name from any attributes in the IdP sign-on response XML. You can configure a pattern for your MindTouch site to use when parsing the IdP response XML for attributes you would like included in the display name.
    - Example: Supplying the pattern "[CustomFirstName] [Surname]" would look for the attributes CustomFirstName and Surname and concatenate them to build a display name.
  2. Use the display name attribute value from one of the following response XML nodes:
    1. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
    2. DisplayName
  3. Concatenate the first and last name attribute values from the following response XML nodes:
    - First name
      1. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
      2. FirstName
    - Last name
      1. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
      2. LastName
  4. Do not set a display name.
Email Address (optional): This sets the user email associated with the user account. In general this should be provided, which makes it easy for users to subscribe to notifications. MindTouch will attempt to find the email address in one of the following IdP sign-on response XML nodes matching Response/Assertion/AttributeStatement/Attribute/AttributeValue:
1. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
2. EmailAddress
Other Metadata: Other attributes (located in nodes matching Response/Assertion/AttributeStatement/Attribute/AttributeValue) may be included in the IdP sign-on response, which are stored as properties on the MindTouch user. These properties are stored as a JSON string and can be accessed programmatically using DekiScript.

Groups

MindTouch will attempt to determine which MindTouch Group memberships an authenticated user should be added to or removed from. In order to execute this action, You will need to set up MindTouch-SAML SSO Group Synchronization. This feature is optional, but gives IdP administrators and MindTouch site administrators tight control over what content can be viewed on the MindTouch site. In order to set up this feature, you will require the following:

The name of the SAML assertion attribute to look up for a list of groups to synchronize with the user's current group membership list. SAML assertion attributes are IdP response XML nodes that match Response/Assertion/AttributeStatement/Attribute/AttributeValue.
- Example: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/group
The delimiter to split up the attribute value into multiple values. If a delimiter is not set, it is assumed that the attribute value contains multiple XML nodes, each one a different group name.
- Example: The attribute value is "group1,group2,group3". The delimiter should be "," (the comma character) as it will split that text into three parts, each part being a group membership to synchronize.
- Example: The delimiter is empty, and the SAML assertion attribute node is
```
<Attribute Name="Group">
    <AttributeValue>group1</AttributeValue>
    <AttributeValue>group2</AttributeValue>
    <AttributeValue>group3</AttributeValue>
</Attribute>
```

Group synchronization will not create groups in MindTouch, nor set up permissions. The groups must exist in MindTouch, prior to synchronization. All permissions granted to groups are made in the MindTouch page access controls, as explained in this article.

Security

SAML is a secure protocol which supports encryption and message signing. Here are a few details:

HTTP communication security is ensured by SSL between the IdP and SP.
Messages can be signed and encrypted to ensure message-level security.
- MindTouch requires that all assertions from the IdP are signed. Signing the assertion allows MindTouch to verify that the assertion originated at the trusted IdP by validating the assertion's signature against the trusted IdP's public X509 certificate.
- Optionally supplying MindTouch with a public X509 certificate and private key allows MindTouch, as the SP, to sign outgoing requests to the IdP, as well as decrypt assertions from the IdP.
  - To take advantage of these security features, the IdP must be configured to validate signatures and encrypt assertions using the same private key and public X509 certificate that MindTouch uses to sign outgoing requests to the IdP.
- MindTouch signs outgoing messages to the IdP with the SHA1 hashing algorithm. MindTouch supports incoming messages from the IdP signed with the SHA1 or SHA256 hashing algorithms.
- MindTouch can decrypt assertions from IdP, encrypted with AES-128, AES-256, or Triple DES encryption algorithms.
User passwords are never transmitted as part of a SAML authentication request or response. A signed authentication request indicates a new user should be created. This request only contains the username and any additional metadata (name, email address, etc.) that was configured by the IdP administrator.

SSL Requirement

SAML SSO requires HTTPS authentication while using a custom domain. If you're currently not using an SSL for your MindTouch site's custom domain, please contact your Account Manager for further details. If you would like to implement an SSL for your custom domain after your SAML SSO integration has been configured, please plan for 4-6 hours to coordinate an update to your MindTouch SAML SSO integration.

VPN/IP Restrictions

SAML SSO sessions can occur behind existing VPN or IP-restrictions if enabled for your MindTouch site.

Frequently Asked Questions

Can MindTouch help me set up my custom IdP?

No, MindTouch will only support IdP's that we have certified to work with MindTouch.

Where can I access a MindTouch site's SP metadata?

MindTouch sites that are SAML SSO enabled publish their metadata at this location: https://example.com/@app/saml/metadata. Depending on your IdP configuration needs, you can either download it as an XML document or poll this endpoint regularly to ensure your IdP has the latest information about the MindTouch SP.

My IdP complains that MindTouch's SP metadata is invalid, how can I fix this?

Many IdP's require that SP's sign outgoing authentication requests, and MindTouch highly recommends this practice as well. By default MindTouch's SP metadata does not include a public X.509 certificate. See the How Do I Configure SAML SSO? section above to learn how to provide a signing public X.509 certificate.

Where can I access a MindTouch site's SP X.509 public certificate?

MindTouch sites that are SAML SSO enabled with a configured public X.509 certificate provide the certificate for download at this location: https://example.com/@app/saml/certificate.

Can I use SAML SSO with MindTouch Custom SSO API's?

No. SAML SSO is the only supported method for single sign-in between MindTouch and your authentication provider. Legacy MindTouch Custom SSO API's are not guaranteed or designed to work alongside SAML SSO scenarios.

Can I use SAML with local accounts?
Yes. Enabling SAML SSO still allows local accounts to sign in by visiting the local sign-in page directly (https://example.com/Special:UserLogin). This allows accounts that should be local-only to access the site. The Sign-in button on the MindTouch site will always initiate a SAML SSO session, therefore users requiring a local sign-in should bookmark a direct link to the sign in page. Administrative users can always sign in and access the Control Panel by visiting https://example.com/deki/cp.

Can I automatically create groups from a SAML assertion?
No. SAML SSO can sync existing groups, but does not create new local groups. Groups must be created within MindTouch and added to the synchronization whitelist.

Can I automatically seat users as pro members?

Users cannot be seated by a SAML assertion. A user must be explicitly seated by an administrator using the control panel. If automatic seating is required, this can be accomplished via our API.

My IdP's public X509 certificate is going to expire one day, how can I prepare for that?

If your IdP's public X509 certificate is nearing expiration (within 30 days), MindTouch site administrators are notified by a large banner at the top of the MindTouch site (only viewable by site administrators). In addition, expect MindTouch Support to contact you before the certificate to assist expires.

Additional Information

If you are interested in setting up SSO with your SAML 2.0 authentication provider, fill out our contact form and an account representative will reach out to you.

https://success.mindtouch.com/Documentation/Integration/Single_Sign_On/SAML_2.0