Authentication using JSON Web Tokens

Overview of the authentication process

JSON Web Token (JWT) is a data transfer format that is used to transfer data securely between the ABBYY FlexiCapture 12 Application Server and third-party services. When authenticating through JWT, no identification data is sent to the Application Server. Authentication is carried out on a third-party service, following which the Application Server is informed that the user has been authenticated by a trusted service.

 

Implementation

Getting JSON data

JSON data sample:

{"alg":"RS256","kid":"-JLCtyyTyF69AZrtjpk-xGs-nUE","x5t":"-JLCtyyTyF69AZrtjpk-xGs-nUE","typ":"JWT"}. 
          {"nameid":"user","nbf":1572267172,"exp":1572267772,"iss":"ABBYY","aud":"test JWT app"}
        

JSON data containing user certificates is encrypted in Base64 in order to create a JSON web token (JWT).

The following sample request creates a JWT token:

 

Sending a JWT to the Application Server

A JWT needs to be sent to the Application Server using the following URL: http://<ApplicationServer>/Flexicapture12/Server/jwt. This is done using a POST request.

Note: If you are using a tenant, add the tenant's identifier to the Application Server URL: http://<ApplicationServer>/Flexicapture12/Server/jwt?Tenant=MyTenantName

static async Task<string> AuthenticateByJwtAsync( string jwtToken ) 
                  { 
                      var fields = new Dictionary<string, string> 
                      { 
                          { "JwtToken", jwtToken } 
                      }; 
                      FormUrlEncodedContent content = new FormUrlEncodedContent( fields ); 
          
                     using ( var client = new HttpClient() ) 
                      { 
                          HttpResponseMessage response = await client.PostAsync( jwtServiceUrl, content ); 
                          if ( response.StatusCode == HttpStatusCode.OK ) 
                          { 
                              return response.Headers.GetValues( "AuthTicket" )?.First() ?? throw new Exception( "AuthTicket header not found" ); 
                          } 
                          else 
                          { 
                              throw new Exception( await response.Content.ReadAsStringAsync() ); 
                          } 
                      } 
                  }
       

In order for authentication to work, a user with a login matching the identifier in the JWT (enclosed in the nameid node value) must be registered on the Application Server

 

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

The value in the ticket field is the authenticated ABBYY FlexiCapture 12 ticket. You can use this ticket to make calls to all Application Server interfaces that require authentication. Services should be accessed using ABBYY FlexiCapture authentication, i.e. addresses starting with http://<ApplicationServer>/flexicapture12/Server/FCAuth/ or http://<ApplicationServer>/flexicapture12/Server/MobileApp/.

 

Using an authenticated ABBYY FlexiCapture 12 ticket

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

Example:

We recommend using an Authorization: Bearer header (cookies are only supported for downward compatibility).

 

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.

To download the project and accompanying materials, use this link: JWT_Example.zip

11/10/2020 12:08:03 PM


Please leave your feedback about this article