Authentication using SAML 2.0 identity providers in ABBYY FlexiCapture 12

Overview of the authentication process

SAML authentication lets ABBYY FlexiCapture 12 users avoid sending identity data (such as a user name and a password) to the Application Server component of FlexiCapture by authenticating on a third-party identity provider (e.g. Google or Facebook) and then passing data about successful authentication by a trusted third party to the Application Server.

The SAML authentication process on a user application consists of the following steps:

  •  Authenticate on the third-party identity provider
  •  Get the user’s SAML authentication data from the third-party identity provider
  •  Send the SAML authentication data to the Application Server
  •  Receive an authenticated ticket from the Application Server

This ticket can then be used in requests to the Application Server.

Note: The user account must exist in the FlexiCapture database and must have all of the required permissions.

Implementation

Getting SAML data

SAML data from the third-party identity provider is formatted as follows (this example is from OneLogin):

For details on how to get authentication data from a third-party identity provider, see the identity provider’s documentation. For instance, OneLogin offers ready-to-use toolkits for enabling SAML authentication in several programming languages.

Sending SAML data to FlexiCapture 12 Application Server

Encode the SAML data in Base64 and send it to the Application Server by making a POST request to http://<Application Server>/Flexicapture12/Server/Saml. Name the field containing the SAML data SAMLResponse.

   public static async Task sendSamlToServer( string samlData )
   {    
       string serviceUrl = "http://<ApplicationServer>/Flexicapture12/Server/SAML";
       HttpWebRequest request = (HttpWebRequest)WebRequest.Create( serviceUrl );
       request.Method = "POST";

       var fields = new Dictionary<string, string>();
       fields.Add( "SAMLResponse", Convert.ToBase64String( Encoding.Default.GetBytes( samlData ) ) );
           HttpClient client = new HttpClient();
       FormUrlEncodedContent content = new FormUrlEncodedContent( fields );
       HttpResponseMessage response = await client.PostAsync( serviceUrl, content );
       if( response.StatusCode == HttpStatusCode.OK ) {
           processServerResponse( response.Content.ToString() );
       } else {
           processServerError( response.StatusCode, response.Content.ToString() );
       }
   }

If you are using a tenant, add the tenant’s identifier to the server URL, e.g. http://<ApplicationServer>/Flexicapture12/Server/Saml?Tenant=MyTenantName

In order for authentication to work, a user with a login matching the identifier in the SAML data (enclosed in the <saml:NameID> tag) must be registered on the Application Server.

The Application Server will return a response like the one below:

The value in the <ticket> tag is the authenticated FlexiCapture 12 ticket. You can use this ticket to make calls to all Application Server interfaces that require authentication. Requests to FlexiCapture web services must be made using FlexiCapture authentication (addresses starting with http://<ApplicationServer>/flexicapture12/Server/FCAuth/ or http://<ApplicationServer>/flexicapture12/Server/MobileApp/.

Using the authenticated FC 12 ticket

You can pass the ticket to the server using a cookie file (the file must be named FlexiCaptureTmpPrn) or an Authorization: Bearer header. Example:

Authorization: Bearer 82BD00C6601EB7F8EF4265450F934D4103C5CA2F010DE1C5FAB4CC830A82300C743D09E5477279733F283D0B6E1C93ACC30FE353D4D9396649965432AAA7994078C3CC63567A95A35E03DA6FDE020F57
    

We recommend using the header. Cookies are supported in order to maintain compatibility with old solutions.

If authentication succeeds, the server’s response will contain an updated ticket value both in a cookie file with the same login (FlexiCaptureTmpPrn) and in the AuthTicket header. The next request must be made using the updated ticket (tickets expire after a certain amount of time).

Setting up a trusted certificate on the Application Server

The Application Server will check the data received from the identity provider. In order for the Application Server to trust this data, it should be signed with a custom certificate issued by an authority from the Application Server database of trusted authorities.

Import the certificate to the ABBYY FlexiCapture database. Now data will be checked using this certificate. For more information, see Setting up Single Sign-On.

If the check fails, the Application Server will refer to the AllowMixedModeCertificateValidation parameter in the <appSettings> settings in the Web.config file. If this parameter is set to true, the check will be carried out using the certificate added into the Trusted Root Certification Authorities folder in the Local Computer certificate store on the computer that is running the Application Server.

If no certificates are added to the database, the check will be carried out using the certificate located in the Trusted Root Certification Authorities folder, and the AllowMixedModeCertificateValidation parameter will be ignored.

Download the project and the accompanying materials: SAML_Example.zip

10.11.2020 12:08:04


Please leave your feedback about this article