Getting started with the basics

If you have access to an identity service URL and are familiar with common developer tools as described in Introduction to Centrify identity services API, you are ready to learn the basics of making a call using the identity services API.

The first step is knowing the importance of the URL you use to access identity service. The URL is used in every call to the API and required to authentication users when they log on.

Working in your customer-specific namespace

Your customer-specific namespace is the URL you use to access identity service. It is sometimes also referred to as a tenant or tenant ID. The URL you use is important because it is the logical unit that separates subscriber organizations from each other in Centrify identity services. When users and administrators log on, they log on to a customer-specific instance, and every operation they perform applies only to that instance.

When an organization registers for identity services, Centrify assigns a unique customer-specific identifier, or tenant ID, to their instance and automatically generates a URL by prefixing the customer-specific identifier to the string 'my.centrify.net'. For example, if the customer-specific identifier is ABCD1234, Centrify automatically creates the following URL: ABC1234.my.centrify.net

Custom and preferred URLs

The customer-specific URL that Centrify generates is considered the system URL. You can also create your own custom URLs by prefixing a string, such as company name, or some other identifier to 'my.centrify.net'; for example, acme.my.centrify.net. Every identity service instance has one system URL and zero or more custom URLs. As an administrator, you can designate one of the custom URLs as the default, or preferred URL.

If a user logs in with a system URL, the identity service redirects the browser to the preferred URL. If a user logs in with a custom or preferred tenant URL, the identity service maintains that URL.

The customer-specific URL not only identifies the identity service instance for users logging on. The URL is also required to identify the origin for each API call. For example, here are examples that use a system URL and a custom URL for a call to Security/StartAuthentication:

https://abc1234.my.centrify.net/Security/StartAuthentication //system URL
https://acme.my.centrify.net/Security/StartAuthentication //custom URL

As a developer, you must be able to support redirection of the custom URL by the identity service. The identity service automatically performs the following tasks for URLs:

• Maintains the custom URL if one or more custom URLs are defined.
• Maintains the preferred custom URL if a preferred URL is specified.
• Redirects the system URL to the preferred URL if a preferred URL is specified.

From the API standpoint, redirection applies only to authentication. If you start authentication by specifying the customer-specific system URL, you must be prepared for redirection to the preferred custom URL. See Handling redirects in Authenticate Users for details.

Making a call

You call the API by making an HTTPS request to a function in the identity service. The call includes the unique customer-specific URL and identifies each function using the following format:

//<tenantURL>/<module>/<function>

Where:

• tenantURL is the customer-specific URL that identifies the identity service instance. Customers can also create custom URLs by prefixing the URL with a company name or other identifier.
• module is a named category. All of the API functions are organized into named categories with a similar purpose. For example, the module for creating and assigning roles is /SaasManage. Similarly, there are modules for device management (/Mobile), authentication (/Security), and so on. The API Reference documentation is organized by modules.
• function is the specific function that you can call. The API Reference documentation lists request payloads or parameters, and responses for all functions.

The following example illustrates a system-generated URL (with a customer-specific identifier ABC1234) and a call to the /SaasManage/GetRole function. The call to this fuction requires you to pass the name parameter using the GUID of the role:

https://ABC1234.my.centrify.net/SaaSManage/GetRole
{name:'bff73836_148c_47ca_85d6_655e328472ab}

The following example ilustrates a custom URL (with a prefix of acme) and a call to the /CDirectoryService/GetUser function to retrieve detailed information about a Centrify directory service user. The call to this function requires you to pass the ID parameter to identify the user:

https://acme.my.centrify.net/CDirectoryService/GetUser
{ID: '07bf119e-0c31-4510-949d-81976d5a4d73'}

You access functions through the standard HTTP methods GET and POST. However, the majority of calls use the POST method. See the API Reference documentation for additional details about any function.

Most of the examples in this guide show the URL, module, and function (or just the module and function) and the JSON input and output, without regard to any specific language or tool you use to make the call. For example:

https://acme.my.centrify.net/CDirectoryService/GetUser
{ID: '07bf119e-0c31-4510-949d-81976d5a4d73'}

or

/CDirectoryService/GetUser
{ID: '07bf119e-0c31-4510-949d-81976d5a4d73'}

Exceptions include the examples that illustrate how to set HTTP headers and how to pass authentication cookies.

Setting HTTP headers

All calls to the API require setting two HTTP headers:

X-CENTRIFY-NATIVE-CLIENT: True // Prevents cross-site scripting.
Content-type: application/json // Sets the application type to JSON -- use it for all calls unless the reference document says otherwise.

Optionally, you can send a (preferably unique) value in the X-CFY-TX-CH header, which is echoed unchanged in the response to your REST call. Including this header does not affect the operation of the API call. You can use this header to identify specific transactions on your end, and the header can be any combination of letters, digits, and ‘+’, ‘/’, and ‘=’ characters up to 1024 characters in length.

This example shows how to execute calls to the API by using cURL , a command line tool and library for transferring data between a client and server. cURL supports numerous protocols, including HTTPS, the required protocol for all calls to the API.

In cURL, you set the HTTP headers for the API call by using the -H (--header) parameter.

Here’s an example:

// The -d ( --data) parameter sends the specified data in a POST request to the HTTP server.
.\curl
-H "X-CENTRIFY-NATIVE-CLIENT:True
-H "Content-type: application/json"
-d "{Name:'[email protected]',Password:'@0B1c9#2'}
-b headers https://acme.my.centrify.net/CDirectoryService/CreateUser

The cURL program is open-source software, complete with documentation , that you can download, if necessary, at curl.haxx.se.

Response body

The response body follows a standard JSON format for all calls.

A call that HTTPS delivers successfully (that is, without an HTTP error) returns a standard JSON payload. The success field indicates whether the call returned the expected result. The other fields are null, or contain error messages, depending on the value of success.

If success = true, Result contains the expected value and all other fields are null. For example, the response for a successful call to create a user returns the GUID of the new user:

https://acme.my.centrify.net/CDirectoryService/CreateUser
"{Name:'[email protected]',Password:'@0B1c9#2'}
{
"success": true,
"Result": "fae7378d-a322-4f88-8ddb-f1c7a2899a64",
"Message": null, "MessageID": null, "Exception": null, "ErrorID": >null
}

If success = false, Result is set to null and the other fields display information about the error. For example, here is an unsuccessful call to retrieve an application by its app key:

https://acme.my.centrify.net/SaasManage/GetAppByKey
"{appkey:'71c4f290-a74c-4629-898c-d9433e7a7760'}"
{
"success": false
"Result": null,
"Message": "You do not have access to this application or the application has been removed.",
"MessageID": "_I18N_ApplicationNotFound",
"Exception": "No additional diagnostic information is available.",
"ErrorID": "112135f5-b070-4369-bbdd-18da74200743:0510e13b7afd45389dc19782ec39ee57",
"ErrorCode": >null,
}

You can enable the console to include diagnostic information (server-side stack trace and exception details) in error logging for API calls. A call to the API returns diagnostic information in the Exception field, which is set to null if diagnostic logging is not enabled.

To enable diagnostic logging

1. Open a browser and log in to Cloud Manager.
2. Click the arrow by your account name and select Support.
3. Select the option, Include diagnostic information in user errors, and click Save.

Security

The Centrify API requires the use of TLS 1.2 or greater. Ensure that your client application and/or framework has been configured to support this requirement.

HTTP Errors

You need to check responses from the API for both HTTP errors and application errors. The following table shows a list of the standard HTTP errors that you might see:

Sample use cases

The REST API exposes all Centrify Identity Services features, including the ability to programmatically execute all functions available from the user interface. The most common reasons you would use the REST APIs to perform administrative tasks programmatically include the following:

You want to integrate web-based functionality with identity service features

A simple integration scenario might involve calling the REST API to add specific identity service features such as multi-factor authentication to your organization's website or to your web applications. For example, you could call the API functions to add a user's application icons and access rights to a company intranet, rather than requiring the user to go to a separate site (Centrify User portal) to access applications. You could design your own portal with its own branding, or combine application access with other features in a single front end.

When integrating identity-services functionality with a web-based client application or site, you can write code that calls the API directly from a client (browser) or that calls the API from a web server, which in turn communicates with the browser. The approach you take depends on a number of factors, including the structure of your application and the languages in which you prefer to codeThe API supports either approach.

For an example of this use case, see Add Applications to a Website, which explains how to retrieve and place the application icons for a user in a web page by calling the REST API with back-end code for a web server.

You want to automate identity service tasks

Many identity service tasks lend themselves to automation through the use of API functions. For example, you can automate one-time tasks, such as creating a set of users from an existing database. To automate this task you could export user data to a .CSV file and execute a set of API functions to create the users in the identity service. You can also use the API to automate on-going tasks. For example, you might use API functions to automate sending reports to an email aliass, checking for status changes, or provisioning users on a scheduled basis.

Depending on your platform, and the nature of the tasks, there are a couple of different approaches you can take. For example:

• Call Linux shell scripts or PowerShell scripts to execute API functions.
• Create a custom binary, such as a Windows service, or a UNIX or Mac binary file, to execute API functions.

You want to customize identity services to suit your organization

You can call the API to customize your identity service instances and portal interfaces, or privilege service. For example, you could customize the login screen, or add functionality to any of the UI pages.

Trying out API calls

There are several developer tools available for download that you can use to try out individual API calls. The most common options for exercising the code and testing API calls include the following:

• Use the Postman site or app to make API calls. Be certain that you execute an authentication call before making other calls. See Using Postman for more information.
• Log on to one of the Centrify identity service and use a debugger such as Fiddler or Chrome Developer Tools to see which API functions are executed when you execute different menu functions. All of the features available in identity services are implemented through identity service REST API calls. See Using Trace Tools for more information.