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 https://<Application Server>/Flexicapture12/Server/Saml. The name of the field containing the SAML data should be SAMLResponse.
public static async Task sendSamlToServer( string samlData )
{
string serviceUrl = "https://<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.UTF8.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. https://<ApplicationServer>/Flexicapture12/Server/Saml?Tenant=MyTenantName
In order for authentication to work, a user with a login matching the identifier in the SAML data must be registered on the Application Server. The value of the /samlp:Response/saml:Assertion/saml:Subject/saml:NameID field will be used as the login.
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 https://<ApplicationServer>/flexicapture12/Server/FCAuth/ or https://<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 for compatibility with older 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 will 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
12.04.2024 18:16:01