Differences

This shows you the differences between two versions of the page.

--- developers:advanced-integration:principles [2019/08/01 09:42]
tjotov removed
+++ — (current)
@@ Line 1: / Line 1: @@
-====== Principles of ADUCID integration ======
-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.
-{{:developers:advanced-integration:integration-components.png?nolink&565x502}}
-=== ADUCID components ===
-  * **Application**  - A component that integrates ADUCID technology. The application communicates with AlM during authentication.
-  * **AIM (ADUCID Identity Machine) **- A self-authenticating component. Delivers the interface for working with the identity and the authentication protocol interface.
-  * **PEIG-Proxy **- A client-side component that is used for communication between AIM, PEIG and the web browser (other client).
-  * **PEIG **- A component that maintains identities and performs authentication. It communicates with AIM through the PEIG-Proxy.
-  * **Client **- Usually an Internet browser.
-===== Authentication "user story" =====
-This chapter defines the typical authentication workflow from integrating application’s perspective:
-  - The application initiates an authentication session in AIM.
-  - The integrator forces the initiation of the authentication process on PEIG (it uses either the AIM-Proxy component or its own resources).
-  - Authentication is performed between PEIG and AIM, and the credentials are sent back to the integrating application.
-  - If the verification is successful, the application fetches user profile data from AIM.
-The following text describes two ways to implement this scenario which demonstrate the basic integration principles:
-  * Use of the AIM-Proxy server adapter (simpler use)
-  * Direct control of the client part (transmission of requests to PEIG needs to be programmed)
-===== Use of the AIM-Proxy server adapter =====
-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.
-{{:developers:advanced-integration:integration-aim-proxy.png?nolink&588x569}}
-=== Integration using AIM-Proxy ===
-The following sequence diagram illustrates individual authentication steps.
-{{:developers:advanced-integration:integration-aim-proxy-sequence-events.png?nolink&766x626}}
-=== Sequence of events when using AIM-Proxy ===
-  - The user moves to the secure page of the given application.
-  - The application creates a new authentication session in AIM (it uses either ADUCID Java SDK or direct access to AIM via the R4 interface). This generates an **authId**  and the optional **bindingId**  and/or **bindingKey**  identifiers for the authentication session. These parameters are then transmitted to the AIM-Proxy component via HTTP. \\ //Note: **authId**, **bindingId**  and **bindingKey**  must be converted to Base64. All parameters must be escaped prior to calling HTTP redirect URL.//
-  - The AIM-Proxy component generates an AJAX page, which performs the following actions:
-      - It initiates the client-side authentication process, it is done through the following steps:
-        - Checks, if the ADUCID schema is supported, if it is, it calls this schema— **this****causes the start of mobile phone PEIG**- If step i/ was not successful, it tries to push totheHTTP redirect adapter— **this****causes the authentication session to start over PC PEIG, if it is running**- Without dependency on the success of steps i/ or ii/ **the****QR**** code is prepared and shown to the user**, if it is supported by current binding mode, The QR code is an alternative way to start an authentication session- It periodically checks the progress status of authentication against AIM: - On a mobile phone platform,PEIG-Proxychecks the authentication status - On a PC platform, AJAX page checks the authentication status - If the AJAX script or a mobile phonePEIG-Proxydetects a successful authentication, a query is sent from the HTTP Redirect adapter or a mobile phonePEIG-Proxycomponent to obtain theauthKey. - HTTP Redirect adapter or a mobile phonePEIG-Proxyredirects back to the application (returnUrl), where adding theauthIdandauthKeyto the URL to verify and complete the authentication process.
-  - On a PC platform, AJAX page checks the authentication status
-==== AIM-Proxy Interface (IAIM-Proxy) ====
-The interface of the AIM-Proxy component is based on HTTP protocol and defines the following commands (the interface address is [[http://<aim_host|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:
-<code>
-http://<aim_host>/AIM-proxy/process?authId=%2fVRUFhn8ISY%3d&bindingId=1AB5HQxtZJ0%3d&bindingKey=zrlnWxxhCFg%3d
-</code>
-\\
-===== Direct control of the client part =====
-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:
-{{:developers:advanced-integration:integration-direct-control.png?nolink&558x450}}
-=== Integration with direct control of the client part ===
-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.
-==== HTTP Redirect interface of the PEIG-Proxy component— PC platform ====
-| \\  **Endpoint**   | \\  **Description**   |
-| \\ The endpoint used to run the authentication process ([[http://localhost:44240/ADUCID/PEIG/auth|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|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:
-<code>
-http://localhost:44240/ADUCID/PEIG/auth?id=%2fVRUFhn8ISY%3d&bindingId=1AB5HQxtZJ0%3d&bindingKey=zrlnWxxhCFg%3d&url=http%3a%2f%2flocalhost%3a8080%2fAIM%2fservices%2fR3
-</code>
-Example of completing the authentication process on the client side:
-<code>
-http://localhost:44240/ADUCID/PEIG/auth?authId=%2fVRUFhn8ISY%3d
-</code>
-\\
-==== PEIG-Proxy — mobile phone platform ====
-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:
-<code>
-aducid://callback?authId=%2fVRUFhn8ISY%3d&bindingId=1AB5HQxtZJ0%3d&bindingKey= zrlnWxxhCFg%3d&r3Url=http%3a%2f%2flocalhost%3a8080%2fAIM%2fservices%2fR3
-</code>
-After successful authentication and fetching **authKey**, the mobile phone PEIG returns control back to the browser that started the authentication process.
-===== AIM (R4) Interface =====
-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:
-<code>
-http://<aim_host>/AIM/services/R4
-</code>
-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.
-\\

ADUCID 4.x

User Tools

Site Tools

Differences

Page Tools