In this section, you will find information about handling queries that are sent to the API Server.
Authentication
When a query 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).
NOTE: This test is not done if the API method used by the query is marked as AllowUnauthenticated.
The imx-session-<API project name> cookie is evaluated to allocate the current session.
If a cookie is passed that cannot be associated with an active session in the current process, the security token in the cookie is used to set up a new session (see Session status and security tokens).
If there is no primary login, the API Server tries to establish a database connection through one of the enabled single sign-on authentication modules.
If login cannot be carried out, the process is canceled and the HTTP error code 500 is passed to the client (see Response codes).
Authorizing method access
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).
Validating the query
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).
Processing queries (for entity methods)
- GET (loads an entity)
-
Determines the WHERE clause with internal and external filters
-
Loads data from the database
-
Augments an entity with calculated columns
-
An entity in delayed-logic mode can be changed with a POST query or deleted with a DELETE query. An entity in this mode is stateless and does not take up any resources on the server after it has been processed.
Supported HTTP methods:
-
An interactive entity must be created once with a PUT query and after that they obtain their own ID. Use the ID in subsequent queries (POST or DELETE).
Supported HTTP methods:
-
GET (loads an entity)
-
PUT (creates an interactive entity)
-
POST (changes an interactive entity)
-
DELETE (deletes an interactive entity)
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:
-
Required primary authentication: Default authentication through an authentication module
-
Optional secondary authentication: Multi-factor authentication (using OneLogin)
For more information about configuring authentication, see the One Identity Manager Web Application Configuration Guide.
Detailed information about this topic
Related topics
You can specify how users authenticate themselves on your API. You configure authentication in the API project.
To configure authentication
-
Edit your API project.
-
Create the SessionAuthDbConfig class and populate the following properties:
-
Product: Specify the application with the authentication module that you want to use (for example the WebDesigner or the Manager),
-
SsoAuthentifiers: Specify the single sign-on authentication modules to use.
-
ExcludedAuthentifiers: Specify the authentication modules not to use.
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 query containing the following:
{ "Module": "RoleBasedPerson", "User": "<user name>", "Password": "<password>" }
TIP: See the SDK for examples.
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 containing the CSRF protection token issued by the server (XsrfProtectionCookieName) and Path for the CSRF protection cookie (XsrfProtectionCookiePath) configuration keys.
You can also disable CSRF protection in the administration portal (Globally disable CSRF protection tokens (XsrfProtectionDisabled) configuration key). One Identity does not recommend doing this.
For more information about editing configuration keys, see the One Identity Manager Web Application Configuration Guide.
