Enable Sub-Tenancy

You can enable or disable access for multiple users to the resources based on an origin using REST APIs (contact_origins). As an MSP administrator, you can globally modify the user-origin association of existing or new users by mapping them to specific origins for a Tenant. By default, when you add a user to an account, they do not have access to any resources, such as Performance Reports, Alarm Viewer, UMP Dashboards, until you enable the pre-provisioned white list of the origins for them. You can enable multiple origins for multiple UIM contact users and LDAP users. This feature is supported when you enable contact_origins_enabled flag on the wasp probe raw configuration on the primary hub and the UMP (if the UMP is deployed on a separate server).
uim902-9-0-2
You can enable or disable access for multiple users to the resources based on an origin using REST APIs (
contact_origins
). As an MSP administrator, you can globally modify the user-origin association of existing or new users by mapping them to specific origins for a Tenant. By default, when you add a user to an account, they do not have access to any resources, such as Performance Reports, Alarm Viewer, UMP Dashboards, until you enable the pre-provisioned white list of the origins for them. You can enable multiple origins for multiple UIM contact users and LDAP users. This feature is supported when you enable 
contact_origins_enabled
 flag on the wasp probe raw configuration on the primary hub and the UMP (if the UMP is deployed on a separate server).
Imagine you are an MSP selling software to various customers. As an MSP, you provide ensure for the software and also support your customers with setting up the software and performing various optimizations. You (the MSP) become a CA UIM customer and your customers become Subtenants. Based on the nature of the customer's business, you (MSP) offer various services like online support, predictive maintenance, and remote performance optimization. You are able to view the collected data for the software while they are residing at the customers environment. You can offer various resources to the customers (Subtenants) like Performance Reports, Alarm Viewing, and Dashboards among others to optimize their business.
 
Contents:
 
 
 
Prerequisites
The following requirements exist:
  • CA UIM 9.0.2 (or later)
  • Deploy the uimapi-9.0.2 package on the primary hub robot in your CA UIM 9.0.2 environment. For more information, see Deploy the uimapi Package.
     Do not deploy the package on the CABI robots.
  • Ensure that the Account Administration privileges are available to the user to update origins to users.
  • Create or identify the users that you want to map to specific origins. For more information, see Add or Modify Users with Account Admin.
  • Ensure that the LDAP setup is available if you are mapping the LDAP users to an origin. For more information, see Add or Modify Users with Account Admin.
Enable Sub-Tenancy
 If you enable sub-tenancy without mapping the users to one or more origins, 
all
 the users fail to log in to the UMP server unless either the users are mapped to the origins or you disable the feature. To allow the users to log in to the UMP server, you 
must
 complete all the steps in the following procedure. To disable sub-tenancy, follow the procedure Disable Sub-Tenancy.
Step 1: Create or Edit Users
Create or edit users, associate the origins to the accounts, and define the ACLs.
 The character limit for login_name is 64 characters and for origin is 255 characters.
 
Follow these steps:
 
  1. As the MSP administrator, log into UMP and navigate to 
    Configuration
    Accounts
    .
  2. Create or edit the existing user, as required. For more information, see Add or Modify Users with Account Admin.
     Add or Modify Users with Account Admin 
    Edit account details, if necessary.
     Edit Account Details  
    As there is no user-origin mapping, the login to the UMP server fails.
Step 2: Map Users to Origins
Map each user or users to one or more required origins by using the REST client.
 
Follow these steps:
 
  1. Open the REST client using the following URL:
    http://<<hostname>>:<<port>>/uimapi/docs/index.html#/contact_origins
  2. For each user or users, using the POST (addorigins) API, define the number of origins that they are entitled to.
    For example, you want to add contact users acme_user1, 
    acme_user2,
     to the origins 
    win2k12-m-sh03
     and 
    win2k12-m-ph_hub
    , define the following parameters:
    1. In 
      body
      , define the user in 
      login_name
       parameter and the list of accounts in 
      origin
      .
      [ { "login_name": "acme_user1", "origin": [ "win2k12-m-sh03","win2k12-m-ph_hub" ] }, { "login_name": "acme_user2", "origin": [ "win2k12-m-sh03", "win2k12-m-ph_hub" ] } ]
    2. In 
      Parameter content type
      , select 
      application/json.
       
    3. Select 
      Try it out
       to execute the query.
    4. In 
      Response Body
      , verify that the origins are returned in the response.
      The following response indicates that for the user acme_user1 and acme_user2, the association with win2k12-m-ph_hub and win2k12-m-sh03 origins is available.
      [
      {
      "login_name": "acme_user1",
      "origin": [
      "win2k12-m-ph_hub", "win2k12-m-sh03"
      ]
      },
      {
      "login_name": "acme_user2",
      "origin": [
      "win2k12-m-ph_hub", "win2k12-m-sh03",
      ]
      }
      ]
  3. Using the GET API, verify that the users and origins are associated.
    1. In 
      loginname
      , define the userID. For example, define 
      acme_user1.
      get_api.png 
    2. In 
      Response content type
      , select 
      application/json.
       
    3. Select 
      Try it out
       to execute the query.
    4. In 
      Response Body
      , verify that the origins are returned in the response.
      {
      "login_name": "
      acme_user1
      ",
      "origin": [
      "win2k12-m-ph_hub", "win2k12-m-sh03"
      ]
      }
  4. Using the POST API getcontactorigins, verify that the users and origins are associated.
    1. In 
      body
      , define the login names. For example, define 
      ["acme_user1","acme_user2"].
      multiple origins.png 
    2. In 
      Response content type
      , select 
      application/json.
       
    3. Select 
      Try it out
       to execute the query.
    4. In 
      Response Body
      , verify that the origins are returned in the response.
      [
      {
      "login_name": "acme_user1",
      "origin": [
      "win2k12-m-ph_hub", "win2k12-m-sh03"
      ]
      },
      {
      "login_name": "acme_user2",
      "origin": [
      "win2k12-m-ph_hub", "win2k12-m-sh03",
      ]
      }
      ]
Step 3: Enable the Sub-tenancy Feature
 The UMP server and the primary Hub can be on the same server. If the UMP and primary Hub are deployed on different servers, then perform this procedure on both the servers.
 
Follow these steps:
 
  1. On the UMP server, navigate to 
    Hub
    Robot
    Probes
    , and open the 
    Raw Configure
     page for the 
     
    wasp
     
     probe.
  2. Select 
    setup
     to view the configuration sections.
    Raw Configure setup Sections 
  3. Select the option 
    Edit value
     for the 
    contact_origins_enabled
     parameter.
    Edit Value 
  4. Define the value of the parameter as 
    true
     to enable the sub-tenancy option and select 
    UPDATE
    .
    Define Parameter Value  
  5. Select 
    UPDATE
     on the 
    Raw Configure
     page to save the changes to the server.
  6. Set the 
    contact_origins_enabled
     parameter to 
    true
     on the remaining UMP servers and wherever the adminconsoleapp package is deployed.
  7. Restart 
    wasp
     on all the servers running UMP and Administration Console.
  8. Access the REST client and verify that the API endpoints appear in the list.
    For example, use the following URL:
    http://<<hostname>>:<<port>>/uimapi/docs/index.html#/contact_origins
Step 4: Verify the Configuration
 
Follow these steps:
 
  1. Log in with this user (acme_user1) in UMP, navigate to 
    Inventory
     to verify that the user (acme_user1) has access to only those origins that they are mapped to in the preceding procedure.
    Associated Origins in the Origin Column 
  2. In UMP, navigate to the Alarms view and verify that the user (acme_user1) has access to the origins that they are mapped to in the steps above.
 Origin Columns where associated Origins are visible 
 If the Origin column is not visible by default, navigate to 
Actions
Edit Columns
, and then select 
Origin
.
Supported API Functions
API Name
Description
POST /contact_origins/addorigins 
Adds the list of origins for multiple contact login names. 
DELETE /contact_origins/deletecontactorigins
Removes list of origins for multiple contact login names.
POST /contact_origins/getcontactorigins
Returns list of origins for multiple contact login names.
POST /contact_origins/removeorigins
Removes list of origins for the contact login name.
POST /contact_origins/setorigins
Sets list of origins for the contact login name.
DELETE /contact_origins/{loginname}
Removes the list of origins for the contact login name.
GET /contact_origins/{loginname}
Returns the contact origins that are configured for the provided contact login name.
API Name
Request URL
Parameter
Response
POST /contact_origins/addorigins
http://<uim_server>/uimapi/contact_origins/addorigins
login name (specify the username)
origins (specify the list of origins to associate with the user)
 { 
   "login_name": "acme_user1", 
   "origin": [ 
         "win2k12-m-ph_hub", "win2k12-m-sh03" 
  ] 
 }, 
  "login_name": "acme_user2", 
  "origin": [ 
       "win2k12-m-ph_hub", "win2k12-m-sh03",
  ] 
 } 
]
DELETE /contact_origins/deletecontactorigins
http://<uim_server>/uimapi/contact_origins/deletecontactorigins
login name (specify the usernames for which you want to delete the corresponding origins)
No content
POST /contact_origins/getcontactorigins
http://<uim_server>/uimapi/contact_origins/getcontactorigins
login name (specify the usernames for which you want to retrieve the corresponding origins)
 { 
   "login_name": "acme_user1", 
   "origin": [ 
         "win2k12-m-ph_hub", "win2k12-m-sh03" 
  ] 
 }, 
  "login_name": "acme_user2", 
  "origin": [ 
       "win2k12-m-ph_hub", "win2k12-m-sh03",
  ] 
 } 
]
POST /contact_origins/removeorigins 
http://<uim_server>/uimapi/contact_origins/removeorigins
login name (specify the username for which you want to remove the origins)
origins (specify the list of origins that you want to remove for the user)
{
"Message": "Success", "ContactOrigins":  [ ]
}
{
"Message": "Partial success, Login name does not exist in DB for these contacts",
"ContactOrigins": 
[ { "login_name": "acme_user1", "origin": [] },
{ "login_name": "acme_user2", "origin": []
]
}
POST /contact_origins/setorigins
http://<uim_server>/uimapi/contact_origins/setorigins
login name (specify the username)
origins (specify the list of origins that you want to set for the user; this replaces any previously set origins)
 { 
   "login_name": "acme_user1", 
   "origin": [ 
         "win2k12-m-ph_hub", "win2k12-m-sh03" 
  ] 
 }, 
  "login_name": "acme_user2", 
  "origin": [ 
       "win2k12-m-ph_hub",
  ] 
 } 
]
DELETE /contact_origins/{loginname}
http://<uim_server>/uimapi/contact_origins/User1
login name (specify the username for which you want to delete the corresponding origins)
 No content
GET /contact_origins/{loginname}
http://<uim_server>/uimapi/contact_origins/User1
login name (specify the username for which you want to retrieve the corresponding origins)
{
"login_name": "acme_user1", "origin": [ "win2k12-m-ph_hub", "win2k12-m-sh03" 
]
}
Disable Sub-Tenancy
You can disable the 
contact_origins_enabled
 option and can revert to the initial state where the users can view all the devices and other resources that are associated with the account. When you disable, all the previously configured contact origins are cleared from the system. The data on UMP for the user is not honored based on corresponding origin association.
 
Follow the steps:
 
  1. As an administrator, log into the Administration Console.
  2. Disable the sub-tenancy feature:
    1. On the UMP server, navigate to 
      Hub
      Robot
      Probes
      , and open the 
      Raw Configure
       page for the 
      wasp
       probe.
    2. Select 
      setup
       to view the configuration sections.
      Raw Configure setup Sections 
    3. Select the option 
      Edit value
       for the 
      contact_origins_enabled
       parameter.
      Edit Value 
    4. Define the value of the parameter as 
      false
       to disable the sub-tenancy option and select 
      UPDATE
      .
      Define Parameter Value  
    5. Select 
      UPDATE
       on the 
      Raw Configure
       page to save the changes to the server.
    6. Set the 
      contact_origins_enabled
       parameter to 
      false
       on the primary Hub and the remaining UMP servers and wherever the adminconsoleapp package is deployed.
  3. Restart 
    wasp
     on all the UMP servers and Administration Console.