Differences
This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
tutorial:adm:api_requirements [2018/12/27 13:55] kotisovam [Example of DB Table] |
tutorial:adm:api_requirements [2021/02/25 14:19] kotynekv [Source of identities] fix link |
||
---|---|---|---|
Line 1: | Line 1: | ||
+ | ====== API - Requirements for a system to be connected ====== | ||
+ | This tutorial is intended as a guide for an administrator/ | ||
+ | CzechIdM supports [[devel: | ||
+ | |||
+ | ===== A source system or managed system? ===== | ||
+ | |||
+ | The requirements naturally differ for source systems (synchronization to CzechIdM) and managed systems (data provisioning from CzechIdM). These are the operations that a system' | ||
+ | |||
+ | ==== a) Source systems - Synchronization ==== | ||
+ | {{ : | ||
+ | Clearly, for fetching data into CzechIdM, the connected system must be able to provide it. As a minimum, it must provide the list of all items and one item by its ID: | ||
+ | |||
+ | ^ Operation | ||
+ | | List All | Operation should provide list of all objects in your system, at least their IDs | | List of all objects, e.g. Identities| | ||
+ | | Get Object | When CzechIdM want to load one specific user | id - identifier of user needed | One specific object | ||
+ | |||
+ | The following operation is not a must, but it's useful when synchronizing the Czech IdM data with outside data, but only the data that has changed since the last synchronization run. It is typically based on the value of some special attribute like LastUpdateTime. It is especially useful in cases when there are many objects to be synchronized (over thousands) and/or the connected system is somewhat slow. | ||
+ | |||
+ | ^ Operation | ||
+ | | Search objects | ||
+ | |||
+ | ==== b) Managed systems - Provisioning ==== | ||
+ | {{ : | ||
+ | |||
+ | To be able to provide data to a connected system, its API must support the CRUD operations: | ||
+ | |||
+ | ^ Operation ^ Description ^ Operation parameters ^ Output | ||
+ | | Get Object | ||
+ | | Delete Object | Delete object in a system | ||
+ | | Update Object | After changing some attribute of an identity in CzechIdM, we want to provide the change into the managed system. If you also want to update the user's permissions in the managed system (e.g. user's AD Groups), the operation should support it too or provide an operation that does the job on its own | id of the user we want to update | id - identifier of the updated object | | | ||
+ | | Create Object | Having created a new identity in CzechIdM, we want it in the managed system, too. This operation should work both with one input parameter (id) and without it | id of the object | id - if no input parameter has been given | | ||
+ | |||
+ | If still in doubt, look at the example below. It might give you a better clue of what it should look like. | ||
+ | |||
+ | ===== Example of REST ===== | ||
+ | |||
+ | If you want to connect your system via REST, just prepare the endpoint as described and we can use our REST connector. It supports both provisioning and synchronization. | ||
+ | |||
+ | ^ Endpoint ^ Operation type ^ Corresponding operation | ||
+ | | / | ||
+ | | / | ||
+ | | /users/{id} | Get | Get Object | ||
+ | | /users/{id} | Put | Create/ | ||
+ | | / | ||
+ | |||
+ | As you can see, the operations in this example fully correspond to the generic API description presented in the previous chapters. | ||
+ | |||
+ | ===== Example of DB Table ===== | ||
+ | |||
+ | If you want to connect one DB table to CzechIdM, your DBMS must support CRUD operations (which it does, naturally :-)). So your main concern is to set the appropriate rights for the user that CzechIdM will use for the connection to DB. | ||
+ | |||
+ | ^ SQL operation ^ Corresponding operation | ||
+ | | SELECT * FROM < | ||
+ | | DELETE FROM < | ||
+ | | SELECT * FROM < | ||
+ | | INSERT INTO < | ||
+ | | UPDATE < | ||
+ | |||
+ | < | ||
+ | <ID> - the name of the column with the unique identifier - e.g. primary key | ||
+ | |||
+ | As you can see, the operations in this example fully correspond to the generic API description presented in the previous chapters. | ||
+ | |||
+ | ===== A source system' | ||
+ | |||
+ | Each source system must contain some information based on the type of the connected system no matter the way in which the system is connected (REST, DB, CSV...). There three basic types of connected source systems: source of identities, source of contracts, and source of organizations. | ||
+ | |||
+ | ==== Source of identities ==== | ||
+ | |||
+ | [[current: | ||
+ | |||
+ | Must contain: | ||
+ | * ID - a unique identifier of the identity | ||
+ | * User name - a user name (or login) used to log in to CzechIdM | ||
+ | |||
+ | Can contain (often contains): | ||
+ | * Personal number | ||
+ | * First name | ||
+ | * Surname | ||
+ | * Phone | ||
+ | |||
+ | * Title before name | ||
+ | * Title after name | ||
+ | |||
+ | Cannot contain: | ||
+ | * Information about the user's position (belongs to contracts) | ||
+ | * Information about the user's superiors (belongs to contracts) | ||
+ | |||
+ | ==== Source of contracts ==== | ||
+ | |||
+ | [[9.7: | ||
+ | |||
+ | Must contain: | ||
+ | * Contract ID - a unique identifier of the contract | ||
+ | * Identity ID - an identifier of the identity to which to contract belongs | ||
+ | |||
+ | Can contain (often contains): | ||
+ | * Valid from - the start of the validity of the contract | ||
+ | * Valid till - the end of the validity of the contract | ||
+ | * Name of the position | ||
+ | * Department ID - the position within the organization, | ||
+ | * Department name | ||
+ | * Superior - either by Identity ID or Login | ||
+ | |||
+ | ==== Source of organizations ==== | ||
+ | |||
+ | IdM can use [[9.7: | ||
+ | |||
+ | Must contain: | ||
+ | * Code - a unique identifier of the tree node | ||
+ | |||
+ | Can contain: | ||
+ | * Name of the tree node | ||
+ | * Superior element - can be null in which case it is considered to be the root element by default |