SAML2

1. Create configuration file

The default data directory is /data/hap/script/volume/sso/sso.json, with the following contents:

Note: If 404 still appears after mounting, you can copy the content to json.cn to verify whether the json format is legal

{
  "mode": "common-saml2",
  "name": "saml2",
  "saml2": {
    "entityId": "{server}/orgsso/metadata.xml",
    "assertUrl": "{server}/orgsso/assert",
    "params": {
      "UserId": "PrimarySid",
      "Name": "Name",
      "Email": "EmailAddress"
    },
    "autoRegister": true,
    "projectId": ""
  }
}

Some parameters and explanations

Parameters	Type	Required	Meaning
saml2.entityId	String	Yes	The unique identifier of the SP, usually set to the SP metadata address, `{server}/orgsso/metadata.xml`; such as http://192.168.10.20:8880/orgsso/metadata.xml
saml2.assertUrl	String	Yes	SP assertion address, receives SAMLResponse; fixed setting is `{server}/orgsso/assert`, needs to be configured in IDP; such as http://192.168.10.20:8880/orgsso/assert
saml2.params	Object	Yes	Returns user information field mapping rules, key is a fixed field and value is configured according to actual user information; Parameter configuration method
saml2.params.UserId	String	Yes	User unique identifier
saml2.params.Name	String	Yes	Name, if the user already exists, it will be updated and overwritten
saml2.params.Email	String	No	Email; this field must be set when searching or registering through email; Either email or mobile phone number must be set; if a third-party relationship has been bound, Users can be found through relationships, and the email or mobile phone does not need to be set
saml2.params.Mobile	String	No	Mobile phone number; this field must be set to search or register by mobile phone number;
saml2.params.Positions	Array	No	Position; automatically updates the user's position, there is no automatic creation
saml2.params.Departments	Array	No	Department; automatically update the user's department, there is no automatic creation
autoRegister	Boolean	No	Whether to automatically create an account when the account does not exist; the default is `true`
projectId	String	Yes	HAP organization number; Organization Management (upper right corner) > Organization Information (page) > Organization Number ID; (Multi-organization single sign-on does not require configuring this parameter,See step 3); such as 1x-2x-3x-4x-5x

Create the IDP metadata file idp.xml. The default path is /data/hap/script/volume/sso/metadata/idp.xml. The reference content is as follows:

<EntityDescriptor entityID="https://saml2.domain.com" ID="pfxea2a0d2f-c296-4b4d-a108-53711984eee"
  xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
  <IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <KeyDescriptor use="signing">
      <KeyInfo
        xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <X509Data>
          <X509Certificate>MIIDHjCCAgagAw....</X509Certificate>
        </X509Data>
      </KeyInfo>
    </KeyDescriptor>
    <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://saml2.domain.com/65681be085c07db1c8136eee/logout"/>
    <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://saml2.domain.com/65681be085c07db1c8136eee"/>
    <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://saml2.domain.com/65681be085c07db1c8136eee"/>
  </IDPSSODescriptor>
</EntityDescriptor>

This configuration is generally automatically generated by the IDP service

Interaction diagram

SP obtains the SAMLResponse submitted by IDP

// The request body from IDP POST is roughly as follows
{
  SAMLResponse: 'PHNhbWxwOlJlc3BvbnNlIElEPSJwZngyNzQxM2ZiYi1mYTdmLTRjZWItYjkxY...'
  ...
}

Use Base64 Decode + Inflate to return user, timestamp, signature and other information. If the user information part corresponds to the following, then params Configuration:

...
<AttributeStatement>
    <Attribute Name="Name">
        <AttributeValue>Zhangsan</AttributeValue>
    </Attribute>
    <Attribute Name="PrimarySid">
        <AttributeValue>12345</AttributeValue>
    </Attribute>
    <Attribute Name="EmailAddress">
        <AttributeValue>test@domain.com</AttributeValue>
    </Attribute>
  	...
</AttributeStatement>
...    

According to the above 👆 return, the params configuration:

"params": {
  "UserId": "PrimarySid",
  "Name": "Name",
  "Email": "EmailAddress"
}

Note: Microsoft ADFS Identity Authentication Source, the following attribute declarations will be automatically converted to mapped values

{
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress": "email",
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname": "given_name",
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name": "name",
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn": "upn",
    "http://schemas.xmlsoap.org/claims/CommonName": "common_name",
    "http://schemas.xmlsoap.org/claims/Group": "group",
    "http://schemas.microsoft.com/ws/2008/06/identity/claims/role": "role",
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname": "surname",
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier": "ppid",
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier": "name_id",
    "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod": "authentication_method",
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/denyonlysid": "deny_only_group_sid",
    "http://schemas.microsoft.com/ws/2008/06/identity/claims/denyonlyprimarysid": "deny_only_primary_sid",
    "http://schemas.microsoft.com/ws/2008/06/identity/claims/denyonlyprimarygroupsid": "deny_only_primary_group_sid",
    "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid": "group_sid",
    "http://schemas.microsoft.com/ws/2008/06/identity/claims/primarygroupsid": "primary_group_sid",
    "http://schemas.microsoft.com/ws/2008/06/identity/claims/primarysid": "primary_sid",
    "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname": "windows_account_name"
}

params can be configured as

"params": {
  "UserId": "name_id",
  "Name": "name",  // Equivalent configuration "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
  "Email": "email" // Equivalent configuration "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
}

2. Mount configuration file

Modify the docker-compose.yaml corresponding to the microservice application, the default path is /data/hap/script/docker-compose.yaml, add file mounting in volumes and restart the microservice application.

- ./volume/sso/sso.json:/usr/local/MDPrivateDeployment/sso/OptionFile/sso.json
- ./volume/sso/metadata/idp.xml:/usr/local/MDPrivateDeployment/sso/OptionFile/metadata/idp.xml

SP's metadata.xml [Download address: {server}/orgsso/metadata.xml] The default is a self-signed certificate. If you need to customize the SP signing certificate, you need to mount the replacement private key and certificate files.

- ./volume/sso/ssl/key.pem:/usr/local/MDPrivateDeployment/sso/OptionFile/ssl/key.pem # Replace the private key
- ./volume/sso/ssl/cert.crt:/usr/local/MDPrivateDeployment/sso/OptionFile/ssl/cert.crt # Replace the certificate

Accessible via {server}/orgsso/metadata.xml

Enable relationship search

If you need to bind a third-party association ID, you need to create the file extend.json. The default path is /data/hap/script/volume/sso/extend.json and the content is as follows

{
  "relation": true
}

Add mounting files

- ./volume/sso/extend.json:/usr/local/MDPrivateDeployment/sso/extend.json

tip

After the mounting configuration is completed, the microservice application needs to be restarted. After the restart is successful, you can access the {server}/orgsso/checkssoconfig interface through GET to check whether the configuration file is successfully mounted.

3. Single sign-on

Single Organization Browser access: {server}/orgsso/sso?returnUrl={returnUrl}

Multiple Organizations Browser access: {server}/orgsso/sso?returnUrl={returnUrl}&appKey={appKey}&sign={sign}&timestamp={timestamp}&projectId={projectId}

For multi-organization projectId needs to be passed through parameters, and enterprise authorization authentication parameters are also required;

For enterprise authentication and authorization signature algorithm, please refer to: https://www.showdoc.com.cn/mingdao/15539798

note

{server} is the HAP system address, for example, it can be replaced with: http://192.168.10.20:8880

{returnUrl} is the jump address after successful login, does not need to be filled in; for example, if you need to jump to the application page, it can be replaced with: http://192.168.10.20:8880/app/cf595091-e3ac-4669 -a320-068e55533c33/64477b37df36209b5f36f1cf/64477b4f61655012a90ed994?from=insite

If an SSO Error prompt appears during the access process, you can log in to the HAP system through the administrator account, click the avatar in the upper right corner: System Configuration > Log; search for the service name as sso, and check the specific cause of the error.

SAML2

1. Create configuration file​

2. Mount configuration file​

Enable relationship search​

3. Single sign-on​

1. Create configuration file

2. Mount configuration file

Enable relationship search

3. Single sign-on