Enable Sub-Tenancy

uim203
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 Alarm Viewer, OC 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 OC(if the OC 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-20.3 package on the primary hub robot in your CA UIM 20.3.0 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 OC server unless either the users are mapped to the origins or you disable the feature. To allow the users to log in to the OC server, you
must
complete all the steps in the following procedure. To disable sub-tenancy, follow the procedure Disable Sub-Tenancy.
Step 1: Enable the Sub-tenancy Feature
The OC server and the primary Hub can be on the same server. If the OC and primary Hub are deployed on different servers, then perform this procedure on both the servers.
Follow these steps:
  1. On the OC 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 OC servers and wherever the adminconsoleapp package is deployed.
  7. Restart
    wasp
    on all the servers running OC 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 2: Create or Edit Users
Create or edit users, associate the origins to the accounts, and define the ACLs.
The character limit for loginName is 64 characters and for origin is 255 characters.
Follow these steps:
  1. As the MSP administrator, log into OC and navigate to
    Settings
    ->
    Account Admin
    .
  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 OC server fails.
Step 3: 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
      loginName
      parameter and the list of accounts in
      origin
      .
      [ { "loginName": "acme_user1", "origin": [ "win2k12-m-sh03","win2k12-m-ph_hub" ] }, { "loginName": "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.
      [ { "loginName": "acme_user1", "origin": [ "win2k12-m-ph_hub", "win2k12-m-sh03" ] }, { "loginName": "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.
      { "loginName": "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.
      [ { "loginName": "acme_user1", "origin": [ "win2k12-m-ph_hub", "win2k12-m-sh03" ] }, { "loginName": "acme_user2", "origin": [ "win2k12-m-ph_hub", "win2k12-m-sh03", ] } ]
Step 4: Verify the Configuration
Follow these steps:
  1. In OC, 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)
[
{
   "loginName": "acme_user1",
   "origin": [
         "win2k12-m-ph_hub", "win2k12-m-sh03"
  ]
},
{
  "loginName": "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)
[
{
   "loginName": "acme_user1",
   "origin": [
         "win2k12-m-ph_hub", "win2k12-m-sh03"
  ]
},
{
  "loginName": "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":
[ { "loginName": "acme_user1", "origin": [] },
{ "loginName": "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)
[
{
   "loginName": "acme_user1",
   "origin": [
         "win2k12-m-ph_hub", "win2k12-m-sh03"
  ]
},
{
  "loginName": "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)
{
"loginName": "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 OC 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 OC 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 OC servers and wherever the adminconsoleapp package is deployed.
  3. Restart
    wasp
    on all the OC servers and Admin Console.