SSO

Support for SSO (Single Sign On), also known as identity federation login, based on SAML 2.0. This article introduces how enterprises use their own identity system for SSO with Surfercloud.

Basic Concepts

Identity Provider (IdP): An IAM entity that contains metadata about the external identity provider and provides identity management services.
Enterprise Local IdP: Microsoft Active Directory Federation Service (AD FS), Shibboleth, etc.
Cloud IdP: Surfercloud Application Identity Service, Azure AD, Google Workspace, Okta, OneLogin, etc.
Service Provider (SP): An application that uses IdP’s identity management function to provide specific services to users. The SP uses the user information provided by IdP.
Security Assertion Markup Language (SAML 2.0): A standard protocol for implementing enterprise-level user identity authentication. It is one of the technical implementations for connectivity between SP and IdP. SAML 2.0 is now a de facto standard for implementing enterprise-level SSO.
SAML assertion: The core element in the SAML protocol that describes authentication requests and responses. For example, user specific attributes will be included in the assertion of the authentication response.
Trust: The trusting mechanism established between the SP and IdP, usually implemented by public and private keys. The SP obtains the SAML metadata of IdP in a trusted way, the metadata contains the signature validation public key issued by IdP’s SAML assertion. The SP then uses the public key to verify the integrity of the assertion.
Verification fingerprint: In order to prevent the Issuer URL from being maliciously hijacked or tampered, you need to configure the verification fingerprint generated by the external IdP’s HTTPS CA certificate. Surfercloud will help you calculate this verification fingerprint automatically. But it is suggested that you calculate it once locally (for example, using OpenSSL to calculate the fingerprint) and compare it with the fingerprint calculated by Surfercloud. If a discrepancy is found, it means that the Issuer URL may have been attacked. Please be sure to confirm again and fill in the correct fingerprint.

SAML Configuration of Surfercloud SP

Steps

Open Access Control-SSO management, this function is off by default, at this point Surfercloud users can log in with a password, all SSO settings do not take effect.

If you choose to enable this function, the password login method for sub-users will be closed and unifiedly redirected to the enterprise IdP for identity authentication. If it is closed again, the user password login method will be automatically restored.
Metadata document: Click to upload the file, upload the metadata document provided by the enterprise IdP.
Note: The metadata document is provided by the enterprise IdP, usually in XML format, containing the IdP’s login service address and X.509 public key certificate (used to verify the validity of the SAML assertion issued by the IdP).
Click to open, upload the metadata file.

Note: This function only applies to all IAM sub-users under the account of Surfercloud, and will not affect the login of the Surfercloud master account.

Next Steps

After the SAML configuration is complete, create an IAM user that matches the enterprise IdP, user management - invite sub-user, fill in the username, no need for email, the system will generate a virtual email for this sub-user, and the invitation will be activated.

Note: After enabling, when you close the SSO function again, you need to enable the console access ability for the sub-users created during the period when the SSO function is enabled. So that after closing the SSO function, the sub-account can use account email login and other functions.

Enterprise IdP SAML Configuration

Obtain SAML service provider metadata URL from Surfercloud.

Create a SAML SP in your enterprise IdP and configure Surfercloud as the trusted party in any of the following ways according to the actual situation. Directly configure the Surfercloud metadata URL described in Step 1. If your IdP does not support URL configuration, you can download the metadata file through the URL described in Step 1 and upload it to your IdP. If your IdP does not support the uploading of metadata files, you need to manually configure the following parameters:

Entity ID: The value of the entityID attribute of the md:EntityDescriptor element in the downloaded metadata XML.
ACS URL: The value of the Location attribute of the md:AssertionConsumerService element in the downloaded metadata XML.

User SSO SAML Response

In the SSO process based on SAML 2.0, when the enterprise user logs in to the IdP, the IdP will generate an authentication response containing SAML assertion in accordance with the requirements of SAML 2.0 HTTP-POST binding, and it will be automatically forwarded to Surfercloud by the browser (or program). This SAML assertion will be used to confirm the user login status and parse the subject from it. Therefore, if the assertion does not include the elements required by Surfercloud, the identity of the logged-in user will not be confirmed, resulting in SSO failure.

SAML Response

Please ensure that your IdP sends a SAML response to Surfercloud that meets the following requirements, and each element must exist, otherwise SSO will fail.


<saml2p:Response>
    <saml2:Issuer>...</saml2:Issuer>
    <ds:Signature>
        ...
    </ds:Signature>
    <saml2p:Status>
        ...
    </saml2p:Status>
    <saml2:Assertion>
        <saml2:Issuer>...</saml2:Issuer>
        <saml2:Subject>
            <saml2:NameID>${NameID}</saml2:NameID>
            <saml2:SubjectConfirmation>
                ...
            </saml2:SubjectConfirmation>
        </saml2:Subject>
        <saml2:Conditions>
            <saml2:AudienceRestriction>
                <saml2:Audience>${Audience}</saml2:Audience>
            </saml2:AudienceRestriction>
        </saml2:Conditions>
        <saml2:AuthnStatement>
            ...
        </saml2:AuthnStatement>
    </saml2:Assertion>
</saml2p:Response>

Explanation of Elements in SAML Assertion

Common elements of the SAML 2.0 protocol

Element	Description
Issuer	The value of Issuer must match the EntityID in the metadata file you uploaded in the user SSO settings of Surfercloud.
Signature	Surfercloud requires that SAML assertions must be signed to ensure that they have not been tampered with, Signature and its contained elements must include information such as the signature value and signature algorithm.
Subject	The Subject must contain the following elements: there is only one NameID element, which is the identity identifier of a certain IAM sub-user under the Surfercloud account. For details, please refer to the NameID element and NameID example described below. There is only one SubjectConfirmation element, which contains a SubjectConfirmationData element. The SubjectConfirmationData must have the following two properties: NotOnOrAfter: Specifies the validity period of the SAML assertion. Recipient: Surfercloud checks the value of this element to ensure that Surfercloud is the intended recipient of this assertion, its value must be https://signin.ucloud.cn/saml/SSO .
Conditions	In the Conditions element, there must be an AudienceRestriction element, which can contain one to many Audience elements, but there must be an Audience element with the value of https://signin.ucloud.cn/${CompanyID}/saml/SSO , where ${CompanyID} is the company ID of Surfercloud.

Here is an example of a Subject element:


<Subject>
  <NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">Alice</NameID>        
  <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">   
    <SubjectConfirmationData NotOnOrAfter="2019-01-01T00:01:00.000Z" Recipient="https://signin.ucloud.cn/saml/SSO"/>    
  </SubjectConfirmation>
</Subject>|

Here is an example of a Conditions element:


<Conditions>
  <AudienceRestriction>
    <Audience>https://signin.ucloud.cn/${CompanyID}/saml/SSO</Audience>
  </AudienceRestriction>
</Conditions>

NameID Element

Surfercloud needs to locate an IAM sub-user through CompanyID+ username, so it requires that the SAML assertion generated by the enterprise IdP contains the username of the sub-user. Surfercloud realizes user SSO by parsing the NameID element in the SAML assertion to match the username of the IAM sub-user.

Therefore, when configuring the SAML assertion issued by IdP, you need to map the field corresponding to the IAM sub-user username to the NameID element in the SAML assertion.