GuidesAPI ReferenceGitHub
Guides
Community ForumsTwitter

Manage Access to Applications

A key feature of Centrify Identity Platform is the ability to provide users with single sign-on (SSO) access to browser-based apps, native mobile apps, and custom apps. Centrify maintains a catalog of application templates that facilitate the process of enabling SSO. The catalog contains two broad types of application templates:

  • Templates for specific applications. This includes a large, and constantly expanding, list of commonly-used applications, such as Box, Ebay, Amazon, DocuSign, etc. Importing one of these templates to Centrify Identity Platform creates an instance of the application that you can deploy to users for SSO without further configuration. The current topic shows how to use the API to deploy one of these common applications to a set of users.
  • Custom templates for different kinds of applications (for which there is no application-specific template), including User-password applications, SAML applications, and Bookmark applications, among others. Deploying a custom-application is not discussed in the current topic.

The process to deploy an application involves the following:

Create the application: The first step to deploying an application to users is to import the application from the Centrify App Catalog:

Assign the application to a set of users: You deploy applications to users by assigning them to a role:

  • Call /Redrock/query to find available applications.
  • Call /Redrock/query to find available roles.
  • Call /SaasManage/PublishApplication to add an application to a role.

Update the application: You can modify the following attributes of an application that you have created: name, description, icon, and handler. To update an application:

Retrieve the application for a user: Call /UPRest/GetUPData to retrieve a user's application-specific data.

Delete the application: Call /SaasManage/DeleteApplication if you want to delete an application that you have created.

Provide application information for users: Call one of the UPRest functions to get information about and manage the applications that are deployed to users; for example:

This information is not in the current topic — See Manage Applications for Users.

Create an application

This section shows how to import an application template to create an application instance for the Ebay web application.

Call SaasManage/GetTemplatesAndCategories to get a list of applications in the Centrify App Catalog. The call does not require parameters or a payload.

The call returns a list with information for all apps in the catalog. Retain the ID for eBay to pass to /SaasManage/ImportAppFromTemplate to create the app.

The following snippet shows truncated information for the Ebay application:

/GetTemplatesAndCategories sample response: 

{
    "Entities": [
    {
     "Type": "SysApps",
     "Key": "iStockphoto",
     "IsForeignKey": false
    }],
    "Row": 
    {
     "Featured": null,
     "ProvSettingPreview": null,
     "Name": "Ebay",
     "Category": "Other",
     "MobileAppType": null,
     "DisplayName": "Ebay",
     "AppTypeDisplayName": "Web - User Password",
     "OnPrem": null,
     "ID": "Ebay",
     "ShadowAppLink": null,
 
"Description": "Buy and sell electronics, cars, fashion apparel, collectibles, sporting goods, digital cameras, baby items, coupons, and everything else on eBay, the world's online marketplace",
...
    }
}

Call /SaasManage/ImportAppFromTemplate and pass the app-template ID (Ebay) to create the app:

/SaasManage/ImportAppFromTemplate
{
    'ID': 'Ebay'
}

The call returns ID (the ID of the template) and _RowKey, which uniquely identifies the application instance that the call creates. Retain _RowKey to pass to subsequent calls to modify or delete the application.

/SaasManage/ImportAppFromTemplate sample response: 

{
"success":true,
 "Result":  [ 
  { 
    "success": true,
    "ID": "Ebay",
    "_RowKey": "487e4925-ba49-4a40-a5de-fe07cb4cee2a" }
],  
"Message":null,"MessageID":null,"Exception":null,"ErrorID":null,"ErrorCode":null,"InnerExceptions":null
}

📘

If you don't retain the ID of apps that you create, you can query the Application table to return a list of all applications that you have created.

Assign an application to a set of users

To add applications to a role, make the following calls:

Call /Redrock/query on the Role Table to get a list of roles.
Use /SaasManage/UpdateApplicationDE to assign roles for access to applications.

Call /Redrock/query on the Role table with a query similar to the following to get a list of available roles:

/Redrock/query
{
"Script":"Select Name, ID, Description from Role ORDER BY Name COLLATE NOCASE","Args":{"PageNumber":1,"PageSize":100,"Limit":10000,"SortBy":"","direction":"False","Caching":-1}
}

The query returns a list of all roles. The following snippet shows the columns returned for a sample role called 'Report writer'.

/SaasManage/ImportAppFromTemplate sample response: 

...
{
  "FullCount": 16,
    "Results": [
      {
        "Entities": [
          {
            "Type": "Role",
            "Key": "Everybody",
            "IsForeignKey": false
          }
        ],
        "Row": 
        {
          "Name": null,
          "ID": "Everybody",
          "Description": "All authenticated users"
        }
      },
      {
        "Entities": [
          {
            "Type": "Role",
            "Key": "367dd8eb_42df_441b_94c7_4ea9a0d4aded",
            "IsForeignKey": false
          }
        ],
        "Row": 
        {
          "Name": "AFW_Role",
          "ID": "367dd8eb_42df_441b_94c7_4ea9a0d4aded",
          "Description": null
        }
      }, 
...
       "Entities": [
          {
            "Type": "Role",
            "Key": "447acf32_5bb8_45d5_8649_4f31dd5d888e",
            "IsForeignKey": false
          }
        ],
        "Row": 
        {
          "Name": "Report writer"
          "ID": "447acf32_5bb8_45d5_8649_4f31dd5d888e"
          "Description": "Create and run reports",
        }
 },
...

Call /SaasManage/UpdateApplicationDE and do the following:
In AppRoles:

  • Pass the following to Publish to identify the role and application: Name, ID, RoleType, Automatic, Application, and Role.
  • Pass a blank array for UnPublish.
  • Pass IconURI, and _RowKey to identify the application.
/SaasManage/UpdateApplicationDE
{
    "AppRoles":
     {
         "Publish":
         [
          {"Name":"Report Writer","ID":"447acf32_5bb8_45d5_8649_4f31dd5d888e","RoleType":"PrincipalList",
            "Automatic":true,"Application":"28f403a1-2b9d-400b-94a8-fe6dcd37eeb9",
            "Role":"447acf32_5bb8_45d5_8649_4f31dd5d888e"}   
         ],
         "UnPublish":[]
     },
     "IconUri":" https://abc0123.my-pod/vfslow/lib/application/icons/ebay",
     "_RowKey":"28f403a1-2b9d-400b-94a8-fe6dcd37eeb9"
}

On success, the call returns the state of the application.

Update an application

After creating an application, you can update it at any time by changing any of the following attributes:

  • Name
  • Description
  • Icon
  • Handler

The sample calls in the current topic show how to update the name and description for the Ebay web application.

Call /Redrock/query on the Application table with a query similar to the following to get a list of available applications. Save the ID for the Ebay application to pass to the calls to return and update the application.

/Redrock/query
{"Script":"Select ID, Name from Application ORDER BY Name COLLATE NOCASE","Args":{"PageNumber":1,"PageSize":100,"Limit":10000,"SortBy":"","direction":"False","Caching":-1}}

The call returns the name and ID for each application in the Application table.

Truncated Application table response: 

"Results":
...
"Row": {
          "Name": "Ebay",
          "ID": "28f403a1-2b9d-400b-94a8-fe6dcd37eeb9",
...       
        }

Call /SaasManage/GetApplication to return information for the Ebay web application. In _Rowkey, pass the ID from the query to specify the Ebay application:

/SaasManage/GetApplication
{
  '_Rowkey': '28f403a1-2b9d-400b-94a8-fe6dcd37eeb9'
}

The call returns detailed information for the Ebay web application.

/GetApplication response for Ebay: 

{
  "success":true,
  "Result":
  {
  "Description": "Buy and sell electronics, cars, fashion apparel, collectibles, sporting goods, digital cameras, baby items, coupons,
   and everything else on eBay, the world's online marketplace",
  "UsernameField": "input#userid",
    ...
  "TemplateName": "Ebay",
  "_TableName": "application",
  "AppTypeDisplayName": "Web - User Password",
   ...
  "_RowKey": "28f403a1-2b9d-400b-94a8-fe6dcd37eeb9",
   ...
   "Icon": "/vfslow/lib/application/icons/ebay",
 
   "Name": "Ebay"
  }
  "Message":null,"MessageID":null,"Exception":null,"ErrorID":null,"ErrorCode":null,"InnerExceptions":null
  }

Call /SaasManage/UpdateApplicationDE to update the name, description, and icon for the Ebay web application. In _Rowkey, pass the ID from the query to specify the Ebay application:

/SasaManage/UpdateApplicationDE
{
    '_Rowkey': '28f403a1-2b9d-400b-94a8-fe6dcd37eeb9'
    'Name': Ebay2',
    'Description': 'Customized version of the online marketplace app.'
    'Iconuri': https://abc0123.my-pod/vfslow/lib/application/icons/ebay2 
}

📘

You can call /SaasManage/GetApplication again if you want to return information for the updated Ebay web application.

The following is another example showing how to update a field for a SAML application. In this example, a script was manually copied from the SAML Response tab for a SAML app in the Admin Portal and then embedded into the payload of the `/SaasManage/UpdateApplicationDE' endpoint to perform the update programmatically:

POST  https://mytenant.centrify.com/saasManage/UpdateApplicationDE

{
   "SamlAttributes":null,
   "Script":"setIssuer(Issuer);\nsetSubjectName(UserIdentifier);\nsetAudience('box.net');\nsetRecipient('https://sso.services.box.net/sp/ACS.saml2');\nsetSignatureType('Response');\nsetServiceUrl('https://sso.services.box.net/sp/ACS.saml2');\nsetHttpDestination('https://sso.services.box.net/sp/ACS.saml2');\nsetAttribute('Email Address', UserIdentifier); ",
   "IconUri":"/vfslow/lib/application/icons/box",
   "_RowKey":"8c0ac1.."
}

The success field in the response indicates if the update was successful.

{
   "success":true,
   "Result":{
      "State":0
   },
   "Message":null,
   "MessageID":null,
   "Exception":null,
   "ErrorID":null,
   "ErrorCode":null,
   "InnerExceptions":null
}

Delete an application

To delete one or more applications that you have created, call /RedRock/Query to retrieve the IDs for the applications, and /SaasManage/DeleteApplication to delete them.

For example, to delete two applications, EchoSign and Egnyte, call /RedRock/Query on the Application table to retrieve the ID for the applications to delete. Specify the names of the applications in a Where clause:

/Redrock/query
{
    "Script":"Select ID, Name from Application where name = 'EchoSign' or name = Egnyte'
    ORDER BY Name COLLATE NOCASE","Args"
{
    "PageNumber":1,"PageSize":100,"Limit":10000,"SortBy":"","direction":"False","Caching":-1
}
}

The call returns the name and ID for each of the specified applications. Retain the IDs to pass to the call to delete the applications.

Application table sample query response: 

"Results":
 
...
 
 "Row": {
   "Name": "EchoSign (Adobe)",
   "ID": "56df08a2-c959-4b06-a43d-a4c9efa5dd30"
 }
 
 "Row": {
   "Name": "Egnyte",
   "ID": "1897e403-416f-4689-8448-04e7e8eeed3a"
 }

Call /SaasManage/DeleteApplication and pass the IDs for EchoSign and Egnyte as _Rowkeys in the payload:

/SaasManage/DeleteApplication
{
     "_RowKey":
     ["56df08a2-c959-4b06-a43d-a4c9efa5dd30",
     "1897e403-416f-4689-8448-04e7e8eeed3a"]
 }

The call returns the _RowKey for each deleted application.

/SaasManage/DeleteApplication sample response: 

{"success":true,
"Result":
    [
        {"success":true,"_RowKey":"56df08a2-c959-4b06-a43d-a4c9efa5dd30"},
        {"success":true,"_RowKey":"1897e403-416f-4689-8448-04e7e8eeed3a"}
    ],
"Message":null,"MessageID":null,"Exception":null,"ErrorID":null,"ErrorCode":null,"InnerExceptions":null
}

See Also

Updated about 5 years ago