Authentication using JSON Web Tokens

Overview of the authentication process

JSON Web Token (JWT) is a format for transferring 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

Get JSON data

The JSON data looks like this.

{"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 encoded in Base64 to create a JSON web token (JWT). The following sample creates a JWT token:

using System.IdentityModel.Tokens.Jwt;
using System.Security.Cryptography.X509Certificates;
…

static string createEncryptedJwtToken(
    X509Certificate2 encryptCert,
    string issuer,
    string audience,
    string nameid,
    TimeSpan expirationTimespan )
{
    X509SigningCredentials signingCredentials = new X509SigningCredentials( encryptCert );
    JwtHeader jwtHeader = new JwtHeader( signingCredentials );
    var claims = new Claim[]
    {
        new Claim( "nameid", nameid )
    };
    var now = DateTime.UtcNow;
    JwtSecurityToken newToken = new JwtSecurityToken(
        issuer,
        audience,
        claims,
        now,
        now.Add( expirationTimespan ),
        signingCredentials
    );
    var token = new JwtSecurityTokenHandler().WriteToken(newToken);
    return token;
}

Send a JWT to the Application Server

Send the JWT to the Application Server in a POST request to https://<ApplicationServer>/Flexicapture12/Server/jwt. For a tenant, add the tenant identifier to the URL, for example https://<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() );
        }
    }
}

Authentication needs a matching user registered on the Application Server. Its login must match the identifier in the JWT, held in the nameid node value. The Application Server returns a response like this:

<?xml version="1.0" encoding="utf-8" ?>
<authTicket>
    <userName>user</userName>
    <ticket>79BB391216E9BBA3DA13E5F29669FF1EB48C387C8FDE41D473AA5698A2E16A8B6E91470F05F3C2FBF685630FD7683DC2FA42A900A007CFAD1AD310FEE1ADADFC</ticket>
</authTicket>

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, that is, addresses starting with https://<ApplicationServer>/flexicapture12/Server/FCAuth/ or https://<ApplicationServer>/flexicapture12/Server/MobileApp/.

Use an authenticated ABBYY FlexiCapture 12 ticket

Pass an authenticated ABBYY FlexiCapture 12 ticket to the server with an Authorization: Bearer header. A cookie file named FlexiCaptureTmpPrn also works, but is supported only for downward compatibility. For example:

Authorization: Bearer 82BD00C6601EB7F8EF4265450F934D4103C5CA2F010DE1C5FAB4CC830A82300C743D09E5477279733F283D0B6E1C93ACC30FE353D4D9396649965432AAA7994078C3CC63567A95A35E03DA6FDE020F57

Set up a trusted certificate on the Application Server

The Application Server will check the data received from the identity provider. For the Application Server to trust this data, sign it with a custom certificate. The issuing authority must appear in the Application Server database of trusted authorities. Import the certificate to the ABBYY FlexiCapture database. The Application Server then checks data against that certificate. For more information, see Set up Single Sign-On. If the check fails, the Application Server refers to the AllowMixedModeCertificateValidation parameter under <appSettings> in the Web.config file. When that parameter is true, the check uses the certificate in the Trusted Root Certification Authorities folder. That folder sits in the Local Computer certificate store on the computer running the Application Server. If the database holds no certificates, the check falls back to the certificate in the Trusted Root Certification Authorities folder. The AllowMixedModeCertificateValidation parameter is then ignored. A sample project and its accompanying materials are available as JWT_Example.zip.

​Overview of the authentication process

​Implementation

​Get JSON data

​Send a JWT to the Application Server

​Use an authenticated ABBYY FlexiCapture 12 ticket

​Set up a trusted certificate on the Application Server