This is an old revision of the document!
Fundamental components and the way they communicate with each other, including basic principles of integration, are described in the document named “ADUCID Architecture”. For easy orientation, the components are summarized below from the integrator’s point of view.
This chapter defines the typical authentication workflow from integrating application’s perspective:
The following text describes two ways to implement this scenario which demonstrate the basic integration principles:
AIM-Proxy is supplied to simplify the authentication process through HTTP redirect — on PC platform over an HTTP redirect adapter or on a mobile platform over a direct PEIG-Proxy call. The application can delegate the authentication process to these components. AIM-Proxy for integrators delivers the IAIM-Proxy interface.
The figure on the next page illustrates how AIM-Proxy is used during the ADUCID authentication process.
The following sequence diagram illustrates individual authentication steps.
The interface of the AIM-Proxy component is based on HTTP protocol and defines the following commands (the interface address is http://<aim_host>/AIM-proxy/{operation_name}):
Command Name | Description |
/process | This command returns the AJAX script, which facilitates authentication. In most cases, this command is called by the HTTP redirect with the following parameters: authId — Mandatory, URLEncoded and Base64Encoded identifier of the authentication session (acquired via ADUCID Java SDK or direct access to the R4 interface). bindingId — Mandatory, if provided during the session start, the URLEncoded and Base64Encoded identifiers are required for client binding (acquired via the ADUCID Java SDK or direct access to the R4 interface). bindingKey — Mandatory, if provided during the session start, the URLEncoded and Base64Encoded keys are required for client binding (acquired via the ADUCID Java SDK or direct access to the R4 interface). |
/checkStatus | A command for fetching the ongoing status of authentication. URL parameters: authId — Mandatory, URLEncoded and Base64Encoded identifier of the authentication session The command returns the authentication status as defined in chapter 4 |
/processReturnUrl | A command for fetching the returnUrl — URL, where to return to after a successful authentication. This URL is an input to the authentication session start operation, see the ADUCID Java SDK for more information. URL parameters: authId — Mandatory, URLEncoded and the Base64Encoded identifier of the authentication session |
/version | Fetches the AIM-Proxy version. The command returns the version number in plain text format. |
/qrCode | This command generates an image representing the QR code as an authentication start alternative. This image can then be shown via a web interface. When this image is taken by a mobile phone, the authentication session automatically starts. URL parameters: authId — Mandatory, URLEncoded and the Base64Encoded identifier of the authentication session (acquired via the ADUCID Java SDK or by direct access to the R4 interface). bindingId — Mandatory, if provided during the session start, The URLEncoded and the Base64Encoded identifiers are required for client binding (acquired via the ADUCID Java SDK or by direct access to the R4 interface). bindingKey — Mandatory, if provided during session start, The URLEncoded and the Base64Encoded keys are required for client binding (acquired via the ADUCID Java SDK or by direct access to the R4 interface). |
Example of using the interface:
http://<aim_host>/AIM-proxy/process?authId=%2fVRUFhn8ISY%3d&bindingId=1AB5HQxtZJ0%3d&bindingKey=zrlnWxxhCFg%3d
This scenario represents the situation where the integrating application starts the authentication process in its own manner. Typically, this means inserting an AJAX script, which the AIM-Proxy component produces, into the application, so that the HTTP requests do not leave the context of the application, thus increasing the application’s security.
The integration is schematically illustrated in the following figure:
If the integrators want to develop their own way of interacting with PEIG, they can use the HTTP Redirect interface of the PEIG-Proxy component on a PC platform or by using the PEIG-Proxy on a mobile phone platform, which are defined as below.
Endpoint | Description |
The endpoint used to run the authentication process (http://localhost:44240/ADUCID/PEIG/auth) | This command returns a true/false value in plain text format. In case of fatal error in the endpoint, the HTTP 500 status is returned. URL parameters: id - base64 URL of the encoded authId bindingId—base64 URL of the encoded bindingId bindingKey—base64 URL of the encoded bindingKey url - AIM URL, against which the authentication is performed (URL of the R3 interface) |
Endpoint used to complete the authentication on the client and fetching the authKey (http://localhost:44240/ADUCID/PEIG/auth) | This command can be called if authentication has finished (by checking against the AIM server, e.g. via the checkStatus command) The command results in an HTTP redirect to URL in the application where the credentials will be verified. The redirect address includes the authId and authKey parameters. URL parameters: authId - base64 URL of the encoded authId |
Example of running the authentication process:
http://localhost:44240/ADUCID/PEIG/auth?id=%2fVRUFhn8ISY%3d&bindingId=1AB5HQxtZJ0%3d&bindingKey=zrlnWxxhCFg%3d&url=http%3a%2f%2flocalhost%3a8080%2fAIM%2fservices%2fR3
Example of completing the authentication process on the client side:
http://localhost:44240/ADUCID/PEIG/auth?authId=%2fVRUFhn8ISY%3d
All mobile phone platform applications are called over schema. This endpoint is defined to call a mobile phone PEIG:
Endpoint | Description |
The endpoint used to run the authentication process (aducid:/callback?) | This command calls a mobile phone platform PEIG, if one is installed URL parameters: authId—base64 URL of the encoded authId bindingId—base64 URL of the encoded bindingId bindingKey—base64 URL of the encoded bindingKey r3url—AIM URL, against which the authentication is performed (URL of the R3 interface) |
The following is an example of starting the authentication process on the mobile phone client side:
aducid://callback?authId=%2fVRUFhn8ISY%3d&bindingId=1AB5HQxtZJ0%3d&bindingKey= zrlnWxxhCFg%3d&r3Url=http%3a%2f%2flocalhost%3a8080%2fAIM%2fservices%2fR3
After successful authentication and fetching authKey, the mobile phone PEIG returns control back to the browser that started the authentication process.
The AIM server provides the integrator with an R4 interface, which is accessible only to applications on the server side.
The communication interface is based on SOAP/HTTP and consists of a single R4 service available at:
http://<aim_host>/AIM/services/R4
This interface is designed to facilitate direct communication of server applications with the authentication server and offers 4 basic commands:
Name of operation | Description |
AIMrequestOperation | Command for work with electronic identity and pocket personal objects (PPO). |
AIMgetPSLAttributes | Command for fetching the results of operations performed with electronic identity. |
AIMexecutePersonalObject | Command for work with directory personal objects (DPO). |
AIMcloseSession | Command for program termination of an authentication session. |
A WSDL describing the R4 interface is included on the supplied DVD in the following directory: integration/wsdl-xsd.
For easier work with the R4 interface, a Java SDK library has been created, which is described in a separate document, aducid-sdk-java.docx. To simplify the use of the R4 interface, we recommend using the supplied SDK, or reading the provided document.
The ADUCID Java SDK source codes distributed under Apache Server Licence 2.0 provide information on how to specify individual attributes of the web service.