Movement Services | NIFAIS - Authentication

NIFAIS (Northern Ireland Farm Animal Information System) is the Movement Service for Cattle in Northern Ireland. This document provides comprehensive details on authenticating with NIFAIS.

Overview
Flow
Prerequisites
Setup
Credential Validation
Test Environment

Overview

NIFAIS uses a token-based authentication model where credentials are managed by the caller, not by EasiTrace. Starting from the transition to the GovGateway authentication system, users must obtain a JWT (JSON Web Token) directly from the NIFAIS authentication service and provide it with each transaction request.

Key Points:

Authentication uses Bearer tokens (JWT format)
Tokens are passed via the serviceAuthToken field in transaction requests
EasiTrace does NOT store or manage NIFAIS credentials
Token validation occurs at the NIFAIS API endpoint during each request
Token expiration is handled by the NIFAIS service (status code 419)

Supported Regions: Northern Ireland
Cattle Species: Cattle only (Species Code: C)

Flow

The NIFAIS authentication flow differs from traditional credential-based systems:

┌─────────────────────────────────────────────────────────────────────────┐
│                    NIFAIS Authentication Flow                            │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                           │
│  1. USER OBTAINS TOKEN                                                   │
│     └─> User authenticates with GovGateway/NIFAIS auth service           │
│     └─> Receives JWT token                                              │
│     └─> Typically stored in session/cache with expiration metadata       │
│                                                                           │
│  2. USER SUBMITS TRANSACTION TO EASITRACE                                │
│     └─> Includes serviceAuthToken in request body                       │
│     └─> EasiTrace validates field requirements                          │
│     └─> Transaction is queued for processing                            │
│                                                                           │
│  3. EASITRACE FORWARDS REQUEST TO NIFAIS API                             │
│     └─> Creates HttpClient with "Bearer {token}" header                 │
│     └─> Sends HTTP request to NIFAIS WebServiceUrl                      │
│     └─> Includes Content-Type: application/json header                  │
│                                                                           │
│  4. NIFAIS VALIDATES TOKEN                                               │
│     └─> If token valid (2xx response): Process transaction              │
│     └─> If token expired (419): Return auth error                       │
│     └─> If token invalid (401/403): Return auth error                   │
│                                                                           │
│  5. RESPONSE RETURNED TO EASITRACE                                       │
│     └─> Success: Transaction processed, ID returned                     │
│     └─> Auth Error: Token expired/invalid message returned              │
│     └─> Other Error: Standard error response                            │
│                                                                           │
│  6. EASITRACE RETURNS RESULT TO USER                                     │
│     └─> User checks response status                                     │
│     └─> If auth error: User must refresh token and retry                │
│     └─> If success: Transaction recorded in NIFAIS                      │
│                                                                           │
└─────────────────────────────────────────────────────────────────────────┘

Authentication Decision Point: The burden of obtaining and maintaining valid tokens rests with the caller of EasiTrace. EasiTrace passes the provided token to NIFAIS without modification. Token lifecycle management (refresh, expiration handling) must be implemented by the calling system.

Prerequisites

To use NIFAIS through EasiTrace, you must have:

GovGateway Account - Access credentials for the NIFAIS GovGateway login portal
Herd Number - Valid Northern Ireland NIFAIS herd number (used as propertyIdentifier)
Valid JWT Token - Obtained through GovGateway authentication
Valid Animal Data - For cattle movements:
- Visual identifier in format: UK N NNNNNN NNNN N
- Example: UK 9 555555 0305 6
Destination/Source Information - Depending on transaction type:
- For MOV-OFF/MOV-INTENT: Destination herd number
- For MOV-ON: Departure herd number and movement ID

IMPORTANT: You do NOT need to register with EasiTrace for NIFAIS credentials. Token management is the responsibility of the transaction initiator.

Setup

Obtaining and Managing Tokens

1. GovGateway Authentication

First, you must authenticate with the NIFAIS GovGateway portal to obtain your JWT token:

// Example: Redirect user to GovGateway login
private const string GovGatewayAuthUrl = "https://reference.dardni.gov.uk/AuthWeb/auth/login";
private const string ProgramName = "your-program-name"; // e.g., "easitrace-test"

public IActionResult RedirectToNifaisLogin()
{
    var loginUrl = $"{GovGatewayAuthUrl}/{ProgramName}/2/";
    return Redirect(loginUrl);
}

2. Token Callback Handler

After successful authentication, GovGateway will POST the token to your callback URL. The token is included in the form body with the key token:

[HttpPost]
public IActionResult HandleNifaisTokenCallback(IFormCollection formCollection)
{
    var tokenString = formCollection["token"];
    
    if (string.IsNullOrWhiteSpace(tokenString))
    {
        return BadRequest("Token not received from GovGateway");
    }
    
    // Store token securely (session, cache, database, etc.)
    // Include expiration metadata if available
    HttpContext.Session.SetString("NifaisToken", tokenString);
    HttpContext.Session.SetString("NifaisTokenTime", DateTime.UtcNow.ToString("O"));
    
    // Redirect back to your application
    return RedirectToAction(nameof(Dashboard));
}

3. Token Storage Best Practices

Secure Storage: Store tokens in encrypted session/cache, NOT in logs or plain text
Expiration Handling: Track token age and implement refresh mechanism
Error Handling: Catch 419 (Token Expired) responses and prompt user to re-authenticate
HTTPS Only: Always use HTTPS when transmitting tokens

Submitting Transactions with Token

Once you have obtained a valid token, include it in every transaction request to EasiTrace using the serviceAuthToken field.

Example (MOV-OFF)

{
  "reference": "MOV-OFF-001",
  "transactionDate": "2024-01-15T10:30:00Z",
  "type": "MOV-OFF",
  "speciesCode": "C",
  "propertyIdentifier": "555555",
  "serviceAuthToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkZhcm1lciIsImlhdCI6MTUxNjIzOTAyMn0.c_Z5aIsQ93Yz7CdGJyKt7lWKGpq0dL_Qdl0_dBCFGl0",
  "fields": {
    "Destination.HerdNumber": "613394",
    "Movement.MoveDate": "2024-01-15",
    "Fci.Signature": "John Smith",
    "Fci.SignatureDate": "2024-01-15",
    "Fci.ToSlaughter": "false",
    "Fci.DescribeDiseases": "None",
    "Fci.DescribeSamples": "No samples taken",
    "Haulier.Signature": "Transport Co.",
    "Haulier.SignatureDate": "2024-01-15",
    "Haulier.DepartureDate": "2024-01-15",
    "Haulier.DriverName": "James Driver",
    "Haulier.JourneyDistanceOver65K": "false",
    "Haulier.TransportName": "ABC Transport",
    "Haulier.MeansOfTransport": "Cattle Lorry"
  },
  "animals": [
    {
      "visual": "UK 9 555555 0305 6",
      "hasFciDetails": true
    },
    {
      "visual": "UK 9 555555 0306 7",
      "hasFciDetails": true
    }
  ]
}

Special Authentication Requirements

Token Format

NIFAIS tokens are JWT (JSON Web Tokens) issued by GovGateway. They follow this structure:

Header.Payload.Signature

Example:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.
c_Z5aIsQ93Yz7CdGJyKt7lWKGpq0dL_Qdl0_dBCFGl0

Bearer Token Authorization

EasiTrace converts the token to an HTTP Authorization header using the Bearer scheme:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Empty Token Handling

If no token is provided in serviceAuthToken, EasiTrace will still attempt the request without authorization. However, NIFAIS will reject it with a 401 Unauthorized response. Always provide a valid token.

Credential Validation

Error Status Codes

When EasiTrace receives a response from NIFAIS, it interprets status codes as follows:

Status Code	Meaning	Action
200-299	Success	Transaction processed
401	Unauthorized	Invalid token (may be malformed)
403	Forbidden	Token lacks required permissions
419	Token Expired	User must obtain new token from GovGateway
400	Bad Request	Invalid transaction data/format
422	Unprocessable Entity	Transaction validation failed
5xx	Server Error	NIFAIS service unavailable

Token Expiration (419):

{
  "success": false,
  "errors": [
    {
      "code": "AUTHENTICATION.AUTHORISATION_ERROR",
      "message": "Token has expired."
    }
  ]
}

Token Validation Checklist

Before submitting each transaction, verify:

Token obtained from GovGateway in current session
Token not manually edited or corrupted
Token included in serviceAuthToken field
Token provided as string (not JSON object)
Herd number (propertyIdentifier) is valid and active
User/token has permissions for transaction type
Transaction date is valid (not in future by >7 days)

Troubleshooting Authentication Issues

Issue: Transaction rejected with “Token has expired”

Solution: Obtain new token from GovGateway, implement token refresh mechanism

Issue: Transaction rejected with “Unauthorized”

Solution: Verify token format, ensure it’s not corrupted, check token not empty

Issue: Consistent 403 Forbidden responses

Solution: Verify user account has NIFAIS transaction permissions in GovGateway

Issue: Cannot verify token validity locally

Solution: Use endpoint availability check or submit test transaction to validate