User Tools

Site Tools


developers:advanced-integration:principles

This is an old revision of the document!


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.

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:

  1. The application initiates an authentication session in AIM.
  2. The integrator forces the initiation of the authentication process on PEIG (it uses either the AIM-Proxy component or its own resources).
  3. Authentication is performed between PEIG and AIM, and the credentials are sent back to the integrating application.
  4. 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.

Integration using AIM-Proxy

The following sequence diagram illustrates individual authentication steps.

Sequence of events when using AIM-Proxy

  1. The user moves to the secure page of the given application.
  2. 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.
  3. The AIM-Proxy component generates an AJAX page, which performs the following actions:
    1. It initiates the client-side authentication process, it is done through the following steps:
      1. Checks, if the ADUCID schema is supported, if it is, it calls this schema— thiscauses the start of mobile phone PEIG- If step i/ was not successful, it tries to push totheHTTP redirect adapter— thiscauses the authentication session to start over PC PEIG, if it is running- Without dependency on the success of steps i/ or ii/ theQR 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.
  4. 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>/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


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:

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)

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


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:

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.

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:

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.


developers/advanced-integration/principles.1477468112.txt.gz · Last modified: 2016/10/26 07:48 by 127.0.0.1