One Identity Manager API Guide 10.0
One Identity Manager API Guide 10.0
WARNING: A WARNING icon highlights a potential risk of bodily injury or property damage,
for which industry-standard safety precautions are advised. This icon is often associated with
electrical hazards related to hardware.
Developing APIs 5
About us 44
Contacting us 44
Technical support resources 44
Index 45
This guide explains the API Server's functionality, how you program API calls, and add your
own API methods to One Identity Manager.
Available documentation
The online version of One Identity Manager documentation is available in the Support
portal under Technical Documentation. You will find videos with additional information at
[Link]/OneIdentity.
Web applications use the API Client to communicate with the One Identity Manager API.
The API Client controls all network access on the API Server.
The most important components for developing your own APIs are:
l API projects: An API project represents the actual application and provides API
methods. Various API projects are supplied with One Identity Manager, for example
the Web Portal (portal).
l API plugins: An API plugin serves as a container for custom extensions. With an API
plugin, you can deploy your own API projects and/or add more API methods to
existing API projects.
l API Provider: An API provider is a single class in a DLL file that declares API methods.
Encryption
The API Server stores data securely encrypted on the client.
The certificate is configured when the API server is installed on the IIS.
For more information, see Installing and updating an API Server.
For more information, see Changing encryption.
Authentication
When a request is sent to the API Server, there is a test to ascertain the success of the
primary and, possibly, secondary login in the session for the current project (see
Authentication on page 19).
NOTE: This test is not done if the API method used by the request is marked as
AllowUnauthenticated.
The API Server checks whether the currently logged in user is authorized to run the
method. If the user does not have the required permissions, the process is canceled and
the HTTP error code 500 is passed to the client (see Response codes on page 18).
The API Server calls the validators stored with the API method one by one. If one fails, the
process is canceled and the HTTP error code 400 is passed to the client (see Response
codes on page 18).
API methods
You can define the following types of API methods.
NOTE: To restrict access to the API, you can assign permissions groups to API
methods.
For more information, see Authorization and authentication.
Entity methods
Entity methods work with small parts of the object model in order to read data from the
database or write data to the database. When you create an entity method, you only need
to enter the table and column name and, if required, a filter condition (WHERE clause).
Internal processing is handled by the API Server. The data schema for the input and output
also has a specific format.
For examples for the definition of entity methods, see the SDK under Sdk01_Basics\01-
[Link].
Advice
l Do not declare path parameters in the URL of entity methods that support operations
of type Update or Create.
l Hash values from columns that are declared as passwords cannot be queried via the
API and are always treated as "not visible" for security reasons.
Limiting results
The following query parameters help you to limit the amount of data that is returned by
obtaining multiple data sets from sequential responses:
StartIndex 0 Specifies as from which data sets the results are returned in
the response.
This parameter is null-based (the first element is addressed
with the value 0).
Example
The following request returns 50 identities and starts with the 101st identity:
[Link] name>/ApiServer/portal/person/all?PageSize=50&StartIndex=100
Sort order
Use the OrderBy query parameter to sort the results returned in an response. This
parameter allows you to sort the column names of the underlying database table.
Examples
The following request returns identities sorted by first name in ascending order:
[Link] name>/ApiServer/portal/person/all?OrderBy=FirstName
The following request returns identities sorted by first name in descending order
:[Link] name>/ApiServer/portal/person/all?OrderBy=FirstName%20DESC
Filtering
Use the filter query parameter to filter the results returned in an response. A filter like this
consists of a JSON formatted string that must contain the following:
l ColumnName: Name of the column used to filter
l CompareOp: The operator for comparing the contents of the selected column with
the expected value
The following comparison operators are permitted:
l Equal: The results only include data sets with column data that matches the
comparison value.
l NotEqual: The results only include data sets with column data that does NOT
match the comparison value.
Example
The following request returns all identities with the last name "User1":
[Link] name>/ApiServer/portal/person/all?filter=[{"ColumnName":
"LastName", "CompareOp": 0, "Value1": "Smith"}]
Grouping
You can use the group path parameter to group the results returned in a response. You can
use the by query parameter to specify which attribute to use for grouping. Furthermore,
you can use the withcount query parameter to specify (values: true or false) whether to
calculate the number of objects for each group. This may increase the runtime.
NOTE: The API method must support grouping (by using the EnableGrouping
parameter).
The result of the query contains a filter condition that you can pass to the URL
parameter as filter.
Example
{
"TotalCount": 8,
"Groups": [
{
"Display": [
{
"Display": "(No value: Identity type)"
}
],
"Filters": [
{
"ColumnName": "IdentityType",
"Type": 0,
"CompareOp": 0
}
],
"Count": 0
},
{
"Display": [
{
"Display": "Machine identity"
}
],
"Filters": [
{
"ColumnName": "IdentityType",
"Type": 0,
"CompareOp": 0,
"Value1": "Machine"
}
],
"Count": 0
},
{
"Display": [
{
"Display": "Organizational identity"
}
],
"Filters": [
{
"ColumnName": "IdentityType",
"Type": 0,
"CompareOp": 0,
"Value1": "Organizational"
}
Example
The following request determines the service categories directly under the given
service category:
[Link] name>/ApiServer/portal/servicecategories?ParentKey=QER-
f33d9f6ec3e744a3ab69a474c10f6ff4
NOTE: To enable table columns for these queries, set the Show in wizards option in
the column properties of the relevant columns in the Designer.
TIP: You can delimit the names of multiple columns with commas.
Example
The following request determines the number of all identities and also returns their
preferred name and title:
[Link]
name>/ApiServer/portal/person/all?withProperties=PreferredName,Title
Response:
{
"TotalCount": 105950,
"TableName": "Person",
"Entities": [
{
"Display": "100, User (USER1)",
"LongDisplay": "100, User (USER1)",
"Keys": [
"bbf3f8e6-b719-4ec7-be35-cbd6383ef370"
],
"Columns": {
"DefaultEmailAddress": {
"Value": "USER1@[Link]",
"IsReadOnly": true
},
"IdentityType": {
"Value": "Primary",
Type-safe classes
Type-safe classes allow you to use the database model in a type-safe way. This gives you
the following advantages:
l Compiling scripts checks whether the classes used are correct. This allows you to
detect spelling mistakes in table and column names early on.
l The development environment can offer auto-completion.
l The column's data type is detected, which prevents type conversion errors.
1. Edit the corresponding API plugin (see Editing API plugins on page 27) and proceed
as follows:
l Add a reference to the type-safe class library of the corresponding database
module ([Link] for example).
This makes the classes for this module available in the <module
name>.TypedWrappers namespace ([Link] for example).
User-defined methods
User-defined methods are methods for which you fully define the processing, input, and
output data in code. This type therefore offers the greatest flexibility.
For examples for the user-defined methods, see the SDK under Sdk01_Basics\03-
[Link].
WebSocket methods
Use WebSocket methods in situations where bidirectional, event controlled
communications is required. You define the processing as well as input and output data
within the WebSocket method.
NOTE: When the session ends or the server, all open WebSocket connections are
also closed.
Response codes
Responses that are sent from the REST API use the following codes. If requests fail, an
explanatory error message is displayed.
Response Description
codes
403 Login failed. For example, this response is sent if an incorrect user name or
password is entered.
405 The HTTP method used is not allowed for this request.
500 A server error occurred. The error message is sent with the response. On
the ground of security, a detailed error message is not included in the
response. For more information, see the application log file on the server.
Response formats
Most API methods return results in JSON format (application/json). Furthermore, there is
support for results in CSV and PDF format as long as the result of the respective API
method is declared as exportable (with the AllowExport flag). Basically, an API method
can return results in any format compatible with HTTP.
NOTE: To obtain results in PDF format, the RPS module must be installed on
your system.
Related topics
l Response codes on page 18
Authentication
User authentication is carried out on the API Server for each API project.
Running an API method requires prior authentication on an API project. If the API method
is marked as AllowUnauthenticated, authentication is not required (you can find an
example in the SDK)
Authentication has two steps:
Related topics
l Handling API Server requests on page 8
To configure authentication
Authentication (primary)
You can use the imx/login/<API project name> API method for primary authentication
on the API project.
To do this, use the POST HTTP method to send a request containing the following:
{ "Module": "RoleBasedPerson", "User": "<user name>", "Password": "<password>" }
Security mechanisms
The API Server uses a security mechanism to prevent cross-site request forgery (XSRF)
attacks. This randomly generates a token (XSRF-TOKEN) and sends it to the client in a
cookie at login. The client must then transmit the value of this token in an HTTP header (X-
XSRF-TOKEN) in each request sent to the server. If this header is missing, the request is
terminated with error code 400.
NOTE: If an API request breaks off with an error and indicates an incorrect CSRF
protection cookie, check if your browser accepts the cookies sent by the browser.
TIP: You can change the name and path of the cookie and the name of the HTTP
header in the Administration Portal. To do this, use the Name of the cookie contain-
ing the CSRF protection token issued by the server (XsrfPro-
tectionCookieName) and Path for the CSRF protection cookie
(XsrfProtectionCookiePath) configuration keys.
Logging out
You can use the imx/logout/<API project name> API method to log out of the
API project.
To do this, use the POST HTTP method to send a request without content.
Example
[Link]("person")
.FromTable("Person")
.EnableRead()
.With(m => [Link] = [Link]("This
identity could not be found."))
Date formats
Date values in requests to change or add objects must be specified in ISO 8601 format in
the client's local time zone.
Example
2016-03-19T13:09:08.123Z
Related topics
l Parameter formats on page 22
HTTP methods
HTTP requests can apply the following HTTP methods:
l GET: This method requests data from the application server.
l PUT: This method changes data on the application server.
l POST: This method creates data on the application server.
l DELETE: This method deletes data on the application server.
Parameter formats
HTTP requests use the following types of parameters:
l Path parameters
l Query parameters
Related topics
l Date formats on page 21
Path parameters
Path parameters extend the URL path. A forward slash is used as the delimiter.
If a request uses path parameters, they are given in URI format.
Query parameters
Query parameter are appended to the URL with a question mark (?) or an ampersand (&).
The first query parameter must be prefixed by a question mark. In this case, you must use
the following format:
?parameter name=parameter value (for example, ?orderBy=LastName)
Subsequent query parameters must be prefixed by an ampersand. In this case, you must
use the following format:
¶meter name=parameter value (for example, ?sortOrder=ascending)
NOTE: Unknown query parameters are rejected by the server with error code 400.
This also affects query parameters with incorrect upper and lower case spelling.
Example
[Link] name>/AppServer/portal/person?orderBy=LastName
NOTE: If the API Server's current user restarts the browser, the cookie and its session
information are reset.
Language
In web applications, every session has two language-specific properties: display language
and formatting language.
Display language
The display language specifies the language in which web application texts are shown.
Formatting language
The formatting language specifies the format of numerical data (e.g. numbers and dates).
To determine the display language, the following priority list is worked through for each API
request until the first step that returns a usable language is found:
Remark
In the API Server, the CulturePlugIn is responsible for assigning the correct languages for
each request. The languages are set in the LanguageManager class and apply both to the
current thread and to asynchronously called tasks.
The data evaluation of the logged in identity is implemented by the
[Link] plugin.
To make it easier for you to start developing your API, One Identity provides a Software
Development Kit (SDK) with lots of commented code examples.
You will find the SDK in the GitHub Repository.
[assembly: [Link]("CCC")]
Example
imxclient start-update
Example
TIP: (Optional) If you want to use another name for the imx-api-ccc packet,
extend the [Link] by adding a line for the packet in the list.
Related topics
l compile-api on page 33
1. Create or edit an API plugin (see Creating API plugins on page 26 or Editing API
plugins on page 27) and proceed as follows:
a. Create a new class in the API plugin project. This class represents the so-called
API provider.
b. Declare the class with the interface that belongs to the API project you want to
add your API to.
The following One Identity API projects can be added:
Example
1. Edit the API plugin (see Editing API plugins on page 27) associated with the API
project and proceed as follows:
l In the API plugin project, create a new class that implements the
IApiProviderFor<name of your API project> interface. This class
represents the so-called API provider.
You can use the ImxClient command line tool to run different functions for managing the
API Server and files on the command line.
check-translations
Searches for captions (multilingual text) with missing translations in a particular folder and
its subfolders.
Parameters
Login parameter:
Required parameters:
l /path <path to folder>: Specifies the path to the folder you want to check.
Optional parameter:
l /conndialog <option>: Specifies whether a login window is displayed for the
database connection. The following options are possible:
l off: The login window is not shown. If the database is not connected, an
attempt is made to establish a connection.
l show: The login window is shown (even is a database is already connected) and
the new connection replaces the old one.
l fallback (default): The current database connection is used. If the database is
not connected, an attempt is made to establish a connection.
l /factory <target system>: Specifies the target system for the connection. Enter this
parameter if you want to establish a connection to the application server.
Example: [Link], [Link]
compile-api
Compiles the API. This performs the following steps:
l Verifies the API definition
l Compiles a TypeScript API client library
l Creates a DialogAEDS EP object in the database for each API endpoint
Parameters
Login parameter:
l /conn <database connection>: Specifies the database you want to connect to.
l /dialog <authentication module>: Specifies the authentication module.
Optional parameter:
l /factory <target system>: Specifies the target system for the connection. Enter this
parameter if you want to establish a connection to the application server.
Example: [Link], [Link]
l N: Prevents saving to the database.
l /modules <module1, module2>: Specifies which modules are included. If you do not
enter anything here, all modules are included. Enter the modules' names,
delimited by commas.
compile-app
Runs HTML5 package compilation.
This command performs the following steps:
Parameters
Login parameter:
l /conn <database connection>: Specifies the database you want to connect to.
l /dialog <authentication module>: Specifies the authentication module.
Optional parameter:
l /conndialog <option>: Specifies whether a login window is displayed for the
database connection. The following options are possible:
l off: The login window is not shown. If the database is not connected, an
attempt is made to establish a connection.
l show: The login window is shown (even is a database is already connected) and
the new connection replaces the old one.
l fallback (default): The current database connection is used. If the database is
not connected, an attempt is made to establish a connection.
l /factory <target system>: Specifies the target system for the connection. Enter this
parameter if you want to establish a connection to the application server.
Example: [Link], [Link]
connect
Establishes a database connection.
If a connection to a database has already been established, this is closed and a new
connection is then established.
Parameters
Login parameter:
l /conn <database connection>: Specifies the database you want to connect to.
l /dialog <authentication module>: Specifies the authentication module.
Optional parameter:
l /conndialog <option>: Specifies whether a login window is displayed for the
database connection. The following options are possible:
l off: The login window is not shown. If the database is not connected, an
attempt is made to establish a connection.
l show: The login window is shown (even is a database is already connected) and
the new connection replaces the old one.
l fallback (default): The current database connection is used. If the database is
not connected, an attempt is made to establish a connection.
l /factory <target system>: Specifies the target system for the connection. Enter this
parameter if you want to establish a connection to the application server.
Example: [Link], [Link]
Parameter
Login parameter:
l /conn <database connection>: Specifies the database you want to connect to.
l /dialog <authentication module>: Specifies the authentication module.
Required parameters:
l /path <path to folder>: Specifies which configuration file to load (for example, the
[Link] file of a web application). The BaseURL setting of this configuration file is
used to determine the application to create the trusted source key for.
Optional parameter:
l /conndialog <option>: Specifies whether a login window is displayed for the
database connection. The following options are possible:
l off: The login window is not shown. If the database is not connected, an
attempt is made to establish a connection.
l show: The login window is shown (even is a database is already connected) and
the new connection replaces the old one.
l fallback (default): The current database connection is used. If the database is
not connected, an attempt is made to establish a connection.
l -T: Configures a random generated trusted source key for the application.
l /trustedsourcekey <trusted source key>: Configures the given trusted source key
for the application.
fetch-files
Loads a specific machine role from the database and saves it in a local folder.
Parameters
Login parameter:
l /conn <database connection>: Specifies the database you want to connect to.
l /dialog <authentication module>: Specifies the authentication module.
Required parameters:
l /targets <target1;target2;...>: Specifies which are your preferred machine roles.
Optional parameter:
get-filestate
Compares the local file structure with the file structure in the database.
Using the QBM | ImxClient | get-filestate | NewFilesExcludePatterns configuration
parameter, you can define which files are excluded from the synchronization. This prevents
excessive load during synchronization. The node_modules and imx-modules folders are
excluded from the synchronization by default.
You can adjust the configuration parameters in the Designer. Use the following formats
when defining the rules:
[Link]
Use the | character to delimit multiple entries.
NOTE: This configuration parameter is generally only used to exclude new files from
the synchronization. Files that already exist in the database are not taken into account.
Parameters
Login parameter:
l /conn <database connection>: Specifies the database you want to connect to.
l /dialog <authentication module>: Specifies the authentication module.
Required parameters:
l /targets <target1;target2;...>: Specifies which are your preferred machine roles.
Optional parameter:
l /conndialog <option>: Specifies whether a login window is displayed for the
database connection. The following options are possible:
help
Displays a list of available commands.
Parameters
inject-package
Installs packages from a tgz file into the node_modules directory of the working directory.
This is intended to be used only with local, dependency-free packages that do not require a
full NPM installation.
Parameter
Required parameters:
l /inject <package1>,<package2>,...: Specifies which packages to install. Enter the
packages' names, separated by commas.
Optional parameter:
l /workspace <working directory path>: Specifies the working directory where the
packages will be installed in the node_modules subdirectory. If you do not enter
anything here, the current directory is used.
Parameters
Login parameter:
l /conn <database connection>: Specifies the database you want to connect to.
l /dialog <authentication module>: Specifies the authentication module.
Required parameters:
l /app <application name>: Specifies which name is used for the application (for
example, in the browser's title bar).
l /sessioncert <certificate thumbprint>: Specifies which (installed) certificate is
used for creating and verifying session tokens.
TIP: For example, to obtain a certificate thumbprint, you can use the Manage
computer certificates Windows function and find the thumbprint through the
certificate's detailed information.
Optional parameter:
l /conndialog <option>: Specifies whether a login window is displayed for the
database connection. The following options are possible:
l off: The login window is not shown. If the database is not connected, an
attempt is made to establish a connection.
l show: The login window is shown (even is a database is already connected) and
the new connection replaces the old one.
l fallback (default): The current database connection is used. If the database is
not connected, an attempt is made to establish a connection.
l -u: Allows insecure HTTP connections to the API Server website. By default, the
API Server website can only be opened over an encrypted connection.
l /site <site name>: Specifies the website on the IIS under which the web application
will be installed. If you do not enter anything, the website is found automatically
(normally Default website).
l /searchservice <URL>: Specifies the application server's URL that the search service
you want to use is hosted on.
NOTE: If you would like to use the full-text search, then you must specify an
application server. You can enter the application server in the configuration file at
a later date.
l /roles <role name1|role name2|...>: Specifies which machine roles to install. Enter
the names of the machine roles separated by pipes (|). If you do not enter anything
push-files
Saves files that you have changed locally back to the database.
Parameters
Login parameter:
l /conn <database connection>: Specifies the database you want to connect to.
l /dialog <authentication module>: Specifies the authentication module.
Required parameters:
l /targets <target1;target2;...>: Specifies which are your preferred machine roles.
Optional parameter:
l /conndialog <option>: Specifies whether a login window is displayed for the
database connection. The following options are possible:
l off: The login window is not shown. If the database is not connected, an
attempt is made to establish a connection.
l show: The login window is shown (even is a database is already connected) and
the new connection replaces the old one.
l fallback (default): The current database connection is used. If the database is
not connected, an attempt is made to establish a connection.
repl
Starts the ImxClient command line tool in REPL mode.
In this mode, the following actions are performed in an infinite loop:
l Read commands from stdin
l Forward commands to the relevant plugin
l Output the results of processing to stdout
run-apiserver
Starts or stops a local self-hosted API Server.
This command requires a database connection.
Parameters
Login parameter:
l /conn <database connection>: Specifies the database you want to connect to.
l /dialog <authentication module>: Specifies the authentication module.
Optional parameter:
l /conndialog <option>: Specifies whether a login window is displayed for the
database connection. The following options are possible:
Example
/baseaddress [Link]
Example
/baseaddress [Link]
l /plugin <file name 1, file name 2>: Loads additional plugins from the given files.
l /htmldir <directory>: Specifies the directory to use to load additional web
application files and plugin. This setting is intended for development scenarios.
Example
/htmldir C:example\imxweb\cpl
The cpl plugin is loaded from the C:example\imxweb\cpl folder instead of the
default source.
Parameter
Login parameter:
l /conn <database connection>: Specifies the database you want to connect to.
Optional parameter:
l /target <update directory path>: Specifies the installation directory of the software
to update. If you do not enter anything here, the current directory is used.
l -C: Only checks if software updates are available. The software update does
not start.
l -G: Hides the software update user interface.
workspace-info
Queries the state of the Angular working directory (existing applications and last API
client update).
Parameters
Optional parameter:
l /workspace: Specifies which working directory to query. If you do not enter anything
here, the current directory is used.
About us
One Identity solutions eliminate the complexities and time-consuming processes often
required to govern identities, manage privileged accounts and control access. Our solutions
enhance business agility while addressing your IAM challenges with on-premises, cloud and
hybrid environments.
Contacting us
For sales and other inquiries, such as licensing, support, and renewals, visit
[Link]
A E
API development entity methods
basics 6 general 10
API files 9 examples 25
async 22
authentication 19
F
primary 19-20
filtering 10
secondary 19
format
await 22
date 21
parameter 22
B response 19
basics 6
G
C grouping 10
CLI 32
code 18
H
command line 32
help 25
commandos 32
HTTP method 22
ConfigureAwait 22
conventions 8
CSV 19 I
custom methods 17 ImxClient 32
commandos 32
D check-translations 32
compile api 33
data structure
compile app 34
hierarchical 10
connect 35
date format 21
edit-config 36
deadlock 22
fetch-files 36
P StartIndex 10
PageSize 10
parameter format 22 T
query parameter 23 token 23
URL parameter 22
PDF 19 U
policies 8
URL parameter 22
Q
W
query
WebSocket methods 18
authentication 8
authorization 8
processing 8