Synchronizing Third-Party Authentication Protocol Users to Huawei Cloud Astro Zero

Creating a Custom Authorizer

1. Log in to the Huawei Cloud Astro Zero console and click Access Homepage. The application development page is displayed.
2. In the upper left corner of the page, click and choose Environments > Environment Configuration.
3. In the navigation pane, choose Integrated Connection > Identity Authentication, and click Custom > Create.
4. In the basic configuration area, enter the label and name, and click the next button.
5. In the authentication source configuration area, set authentication source information and click the next button.
   Figure 1 Oauth2 authentication configuration
   

   Table 1 Parameters for configuring Oauth2 authentication

   Parameter	Description
   Authentication Protocol	Set this parameter based on the authentication protocol provided by the peer authentication server. In this example, set this parameter to Oauth2.
   Authentication Address	Set the authentication login address, which is obtained from the third party.
   For obtaining an access token	Request address for obtaining the access_token. Obtain it from the third party.
   For obtaining user information	Request address for obtaining user information. Obtain the value from the third party.
   access_token parameter location	Location of the access_token parameter transferred during user information obtaining.
   Method	Request method for calling the API for obtaining user information.
   Logout Address	After a user logs out of Huawei Cloud Astro Zero, the user is redirected to the logout address of the server. You are advised to configure the logout address. The variable {redirect} can be added to the logout address. During logout, the variable is replaced with the currently configured page address. Example: https://host/api/v1/logout?redirect_url={redirect}
   Auto-Create User on Login	Indicates whether to automatically create a user when the user logs in to the system for the first time and the user does not exist in the system.
   Profile	When you log in to the system as a third-party user, if the user does not exist and automatic user creation is enabled, this permission is used as the default permission for the created user.
   Verify state	Indicates whether to verify the state parameter. You are advised to enable state verification to prevent CSRF attacks. After responding to a request, Huawei Cloud Astro Zero redirects the request to a third-party server. The third-party server determines whether to verify the consistency of the state parameter (that is, the state in the cookie or session) based on the configuration. If the state is inconsistent after the verification is enabled, Huawei Cloud Astro Zero rejects the request and does not send a request for obtaining the access_token. If they are the same, the process runs properly.
   Attribute Mapping	Configure the attribute mapping between Huawei Cloud Astro Zero and the third-party system. That is, map the fields with the same user attributes returned by Huawei Cloud Astro Zero and the third-party login API. Obtain the user information from the peer third-party system. The returned user information is as follows: { "id": "20201029190841785-CB37-8BD36B...", // user ID "name": "test", // Name "userName": "test", // User login name "mobile": "1XXXX456789", // Phone number "email": "123@example.com" // Mailbox "local": "en_US" // User language } After obtaining the preceding information, configure the attribute mapping between third-party fields and Huawei Cloud Astro Zero fields by referring to Figure 1.

   Figure 2 CAS authentication configuration
   

   Table 2 Parameters for configuring CAS authentication

   Parameter	Description
   Authentication Protocol	Set this parameter based on the authentication protocol provided by the peer authentication server. In this example, set this parameter to CAS.
   Authentication Address	Authentication login address, which is obtained from the third party.
   URL used to validate tickets	Address for verifying the ticket and obtaining user attribute information. Obtain the address from the third party. This parameter is mandatory only when the authentication protocol is set to CAS.
   Logout Address	After a user logs out of Huawei Cloud Astro Zero, the user is redirected to the logout address of the server. You are advised to configure the logout address. The variable {redirect} can be added to the logout address. During logout, the variable is replaced with the currently configured page address. Example: https://host/api/v1/logout?redirect_url={redirect}
   Auto-Create User on Login	Indicates whether to automatically create a user when the user logs in to the system for the first time and the user does not exist in the system. Yes: The system automatically creates a user and logs in to the system. No: The login fails.
   Profile	When you log in to the system as a third-party user, if the user does not exist and automatic user creation is enabled, this permission is used as the default permission for the created user.
   Attribute Mapping	Configure the attribute mapping between Huawei Cloud Astro Zero and the third-party system. That is, map the fields with the same user attributes returned by Huawei Cloud Astro Zero and the third-party login API. Obtain the user information from the peer third-party system. The returned user information is as follows: <cas:serviceResponse xmlns:cas="http://www.yale.edu/tp/cas"> <cas:authenticationSuccess> <cas:user>Lily</cas:user> // User login name <cas:attributes> <cas:authenticationDate>2020-02-11T09:28:14.987Z</cas:authenticationDate> <cas:longTermAuthenticationRequestTokenUsed>false</cas:longTermAuthenticationRequestTokenUsed> <cas:isFromNewLogin>true</cas:isFromNewLogin> <cas:date>2020-02-03T16:00:00.000Z</cas:date> <cas:birthday>2020-02-04T16:00:00.000Z</cas:birthday> <cas:createAt>2020-01-10T09:01:04.000Z</cas:createAt> <cas:disabledAt>null</cas:disabledAt> <cas:disabed>false</cas:disabed> <cas:email>email@example.com</cas:email> // Email address <cas:local>en_US</cas:local> // User language <cas:token>XXXXXXXXXXXXXXXXX</cas:token> // Third-party system user token </cas:attributes> </cas:authenticationSuccess> </cas:serviceResponse> After obtaining the preceding information, configure the attribute mapping between third-party fields and Huawei Cloud Astro Zero fields by referring to Figure 2. The email and phone properties can be left empty. If the peer end does not return the name and extIdentityID fields, the email and phone properties can be set to the value of the userName field. The field corresponding to the attribute is mandatory.

   Figure 3 SAML2 authentication configuration
   

   Table 3 Parameters for configuring SAML2 authentication

   Parameter	Description
   Authentication Protocol	Set this parameter based on the authentication protocol provided by the peer authentication server. In this example, set this parameter to SAML2.
   Logout Address	After a user logs out of Huawei Cloud Astro Zero, the user is redirected to the logout address of the server. You are advised to configure the logout address. The variable {redirect} can be added to the logout address. During logout, the variable is replaced with the currently configured page address. Example: https://host/api/v1/logout?redirect_url={redirect}
   Auto-Create User on Login	Indicates whether to automatically create a user when the user logs in to the system for the first time and the user does not exist in the system. Yes: The system automatically creates a user and logs in to the system. No: The login fails.
   Profile	When you log in to the system as a third-party user, if the user does not exist and automatic user creation is enabled, this permission is used as the default permission for the created user.
   Verify state	You are advised to enable state verification to prevent CSRF attacks. After responding to a request, Huawei Cloud Astro Zero redirects the request to a third-party server. The third-party server determines whether to verify the consistency of the state parameter (that is, the state in the cookie or session) based on the configuration. If the state is inconsistent after the verification is enabled, Huawei Cloud Astro Zero rejects the request and does not send a request for obtaining the access_token. If they are the same, the process runs properly.
   Client Certificate	Public key of the SAML client signature certificate. To obtain the public key of a self-signed certificate, for example, saml.crt, perform the following steps. The certificate created using this method applies only to test scenarios. Run the following command on the Linux server to generate the key file saml.key: openssl genrsa -out saml.key 2048 After the command is executed, a private key file saml.key is generated in the current directory. The key generated must be in the following format: -----BEGIN PRIVATE KEY----- ..................................................... -----END PRIVATE KEY----- Use the key file obtained in the previous step to generate the saml.csr file. openssl req -new -key saml.key -out saml.csr Enter the country, region, organization, email address, and common name as prompted, and press Enter. (If HTTPS is used, the value of this parameter must be the same as the domain name. Otherwise, an alarm will be generated on the browser.) Issue the certificate file saml.crt using the generated file. openssl x509 -req -days 365 -in saml.csr -signkey saml.key -out saml.crt The generated certificate must be in the following format: -----BEGIN CERTIFICATE----- ..................................................................... -----END CERTIFICATE-----
   Client Certificate Private Key	Private key of the SAML signature certificate. The self-signed certificate private key is the saml.key file generated during the creation of the client certificate. Certificates created this way apply only for testing scenarios.
   Idp Metadata File	Metadata file of the SAML server, which needs to be obtained from the SAML identity provider.
   Attribute Mapping	Configure the attribute mapping between Huawei Cloud Astro Zero and the third-party system. That is, map the fields with the same user attributes returned by Huawei Cloud Astro Zero and the third-party login API. The email and phone properties can be left empty. If the peer end does not return the name and extIdentityID fields, the email and phone properties can be set to the value of the userName field. The field corresponding to the attribute is mandatory.

6. In the identity source configuration area, configure the peer authentication ID, peer authentication key, and synchronization script, and click Save.
   If Authentication Protocol is set to CAS, you only need to configure the synchronization script.

   Figure 4 Configuring identity source
   
   The synchronization script is used to synchronize third-party organizations and users to Huawei Cloud Astro Zero. The following is an example script:

   // Here's your code./*
   
   
   import * as http from 'http';
   import * as db from 'db';
   import * as iconv from 'iconv';
   import { Encoding } from 'buffer';
   
   export class Output {
       @action.param({ type: "Any" })
       result: any;
   }
   
   export class StructRole {
       @action.param({ type: "String", description: "Organization name, which can correspond to a third-party organization code", isCollection: false })
       name: string;
       @action.param({ type: "String", description: "Organization name, which can correspond to a third-party organization name", isCollection: false })
       label: string;
       @action.param({ type: "String", description: "Upper-level organization, which corresponds to the ID of Huawei Cloud Astro Zero organization.", isCollection: false })
       reportTo: string;
   }
   
   export class StructUser {
       @action.param({ type: "String", description: " user name", isCollection: false})
       name: string;
       @action.param({ type: "String", description: "User account, which is unique in an account", isCollection: false })
       usrName: string;
       @action.param({ type: "String", description: "Third-party system user ID, which is unique in the third-party system", isCollection: false })
       extIdentityID: string
       @action.param({ type: "String", description: "Organization, which corresponds to the ID of Huawei Cloud Astro Zero organization.", isCollection: false })
       roleId: string
       @action.param({ type: "String", description: "Created portal user permission, profileId", isCollection: false })
       profile: string
       @action.param({ type: "String", description: "Type of the portal user created. The value is fixed to custom.", isCollection: false })
       userType: string
   }
   @useObject(['PortalUser'])
   export class SyncContact {
   
       @action.method({ input: "Input", output: "Output", description: "Run this method during development and test." })
       run(): Output {
           //return this.SyncUser();
           return this.SyncRole(); // Debug the synchronization organization and uncomment this line.
       }
   
       // SyncUser is the method for synchronizing users. The method name cannot be changed.
       SyncUser(): Output {
           let output = new Output();
           let token = this.getToken();
           if (!token) {
               output.result = "Failed to synchronize users.";
               return output;
           }
           let users = this.queryUsers(token);
           for (let u of users) {
               let portaluser: StructUser = {
                   name: u.user_name,
                   usrName: u.user_name,
                   extIdentityID: u.user_id,
                   profile: "000T0000000000000003", // Set to the ID of the Portal User Profile.
                   roleId: "",
                   userType: "custom"
               }
               let role = this.queryRoleByName("oneaccess" + u.org_id);
               if (role) {
                   portaluser.roleId = role.id;
               }
               this.addUser(portaluser);
           }
           output.result = "User synchronization succeeded.";
           return output;
       }
   
       // SyncRole is the method for synchronizing organizations. The method name cannot be modified.
       SyncRole(): Output {
           let output = new Output();
           let token = this.getToken();
           if (!token) {
               output.result = "Failed to synchronize the organization.";
               return output;
           }
           let orgs = this.queryOrgs(token, "");
           for (let org of orgs) {
               this.syncOrg(org, token);
           }
           output.result = "Organization synchronized successfully.";
           return output;
       }
   
       private addUser(portaluser: StructUser): String {
           // Check whether the record already exists.
           let option = {};
           let condition = {
               "conjunction": "AND",
               "conditions": [{
                   "field": "name",
                   "operator": "eq",
                   "value": portaluser.usrName
               }]
           };
           let record = db.object('PortalUser').queryByCondition(condition, option);
           if (record && record.length > 0) {
               console.log("This record already exists and will not be created.");
               return record[0].id;
           }
           // Insert data.
           let roleId = portaluser.roleId;
           delete portaluser.roleId; //This is a non-portaluser field and is deleted after being saved.
           let portaluserId = db.object('PortalUser').insert(portaluser);
           if (!roleId) {
               return portaluserId;
           }
           db.setup('roleportaluser').insert({
               "portaluser": portaluserId,
               "role": roleId
           });
           return portaluserId;
       }
       // The service side develops the query logic to query the users of the third-party system and add the users to the portaluser table of the platform. For details, see the example of connecting to the OneAccess in the help document.
       private queryUsers(token: string): Array<any> {
           // Write the logic for invoking the third-party API to obtain the user list.
           let req: http.Request = {
               headers: {
                   "content-type": "application/json",
                   "Authorization": "Bearer " + token
               },
               params: {
                   "limit": 100, // If the value is greater than 100, all pages need to be queried.
                   "offset": 0,
               }
           };
           let result = this.sendRequest("https://test.example.com/api/v2/tenant/users", "GET", req);
           if (result.error_code) {
               throw new Error(result.error_msg);
           }
           return result && result.users || [];
       }
   
       private queryRoleByName(name: string): any {
           let option = {};
           let condition = {
               "conjunction": "AND",
               "conditions": [{
                   "field": "name",
                   "operator": "eq",
                   "value": name
               }]
           };
           let records = db.setup('role').queryByCondition(condition, option);
           if (records && records.length > 0) {
               console.log("This record already exists and will not be created.");
               return records[0];
           }
           return null;
       }
   
       private addRole(role: StructRole): string {
           // Check whether the record already exists.
           let record = this.queryRoleByName(role.name);
           if (record) {
               console.log("This record already exists and will not be created.");
               return record.id;
           }
           // Insert data.
           return db.setup('role').insert(role);
       }
   
       // The service side develops the query logic to query the OU logic of the third-party system and adds the logic to the role table of the platform. For details about how to query the OU for the first time, see the example of connecting to the OneAccess in the help document.
       private queryOrgs(token: string, org_id?: string): Array<any> {
           // Write the logic for invoking the third-party API to obtain the organization structure.
           let level0Orgs = this.getOrgList(100, 0, org_id, token);
           if (level0Orgs && level0Orgs.organizations) {
               return level0Orgs.organizations;
           }
           return [];
   
       }
   
       // Synchronize an organization that has suborganizations.
       private syncOrg(org: any, token: string, reportTo?: string) {
           console.log(org)
           let role = new StructRole();
           role.name = "oneaccess" + org.org_id;
           role.label = org.name;
           console.log(reportTo)
           if (reportTo) {
               role.reportTo = reportTo;
           }
           let parentRoleId = this.addRole(role)
           let childOrgs = this.queryOrgs(token, org.org_id);
           console.log(childOrgs);
           for (let childOrg of childOrgs) {
               if (childOrg.parent_id === org.org_id) {
                   this.syncOrg(childOrg, token, parentRoleId)
               }
           }
       }
   
   
       // OneAccess method for querying organizations. This method needs to be rewritten when other third-party systems are connected.
       private getOrgList(limit: number, offset: number, org_id: string, token: string): any {
           // Write the logic for invoking the third-party API to obtain the organization structure.
           let req: http.Request = {
               headers: {
                   "content-type": "application/json",
                   "Authorization": "Bearer " + token
               },
               params: {
                   "limit": limit,
                   "offset": offset,
                   "org_id": org_id,
                   "all_child": false
               }
           };
           let result = this.sendRequest("https://test.example.com/api/v2/tenant/organizations", "GET", req);
           if (result.error_code) {
               throw new Error(result.error_msg);
           }
           return result;
       }
   
       private sendRequest(url: string, method: string, callOptions?: http.Request): any {
           let client = http.newClient();
           let resp;
           if (method === "GET") {
               resp = client.get(url, callOptions);
           } else {
               resp = client.post(url, callOptions);
           }
           let result = iconv.decode(resp.data, Encoding.Utf8);
           return JSON.parse(result);
       }
   
       // Obtain the API calling credential of the third-party system. The service side needs to perform adaptation development based on the third-party API.
       private getToken(): string {
           let req = {
               headers: {
   
                   'Content-Type': "application/x-www-form-urlencoded"
               },
               params: {
                   "client_id": "o8XvdwMF7******KLxVzoxarXr",
                   "client_secret": "uf8vBFR1RMAf******Uq31NThCzT1OOAlepsM00",
                   "grant_type": "client_credentials",
               }
           };
           let result = this.sendRequest('https://test.example.com/api/v2/tenant/token', "POST", req);
           if (result.error) {
               throw new Error(result.error);
           }
           return result.access_token;
       }
   }

7. Click the synchronization button to synchronize organization and user information. You can synchronize organization and user information immediately or set a scheduled synchronization task.
   Figure 5 Synchronizing organization and user information
   
   • Synchronizing departments or users immediately
     1. Click Sync now under Department Synchronization. In the dialog box that is displayed, select Also clear departments that are not included to clear the deleted third-party departments from Huawei Cloud Astro Zero. Click the confirm button.
     2. Click Sync now under User Synchronization. In the dialog box that is displayed, select Also clear users that are not included to clear the deleted third-party users from Huawei Cloud Astro Zero. Click the confirm button.
   • Setting a scheduled task to implement automatic synchronization
     1. In the Department Synchronization area, enable Turn on Auto Sync. Click Turn on Auto Sync of Department Synchronization, set the first synchronization time and execution period, select Also clear departments that are not included to clear the deleted third-party departments from Huawei Cloud Astro Zero. Click the confirm button.
     2. In the User Synchronization area, enable Turn on Auto Sync. Click Turn on Auto Sync of User Synchronization, set the first synchronization time and execution period, select Also clear users that are not included to clear the deleted third-party users from Huawei Cloud Astro Zero. Click the confirm button.

   The system synchronizes the third-party organization information to the Organizations & Users > Organizations page of the Huawei Cloud Astro Zero service configuration center, and synchronizes the third-party user information to the Organizations & Users > Users page of the Huawei Cloud Astro Zero service configuration center.

8. (Optional) In the authentication configuration menu, download the SP metadata file.
   

   • You need to configure the file to the identity provider later.
   • Perform this step only when the authentication protocol in 5 is set to SAML2.