View on GitHub

easitrace

« Back to ScotMoves

Movement Services | ScotMoves (Scotland Cattle) - Authentication

ScotMoves is the Movement Service for Cattle in Scotland. It uses the ScotEID shared authentication infrastructure, which means authentication is handled through the ScotEID platform.

Overview

ScotMoves authentication follows a credential-based model where your application must provide both service provider credentials (identifying your software provider) and user credentials (property owner login). Unlike some services that use token-based authentication, ScotMoves uses direct credential submission to the ScotEID web service with HTTP Basic Authentication.

Key Features

Sections

Flow

┌─────────────────────────────────────────────────────────────────┐
│ ScotMoves Authentication Flow                                   │
└─────────────────────────────────────────────────────────────────┘

1. CLIENT REGISTRATION
   ├─ Register as Software Provider with ScotEID
   │  └─ Provide: Company name, contact details, application details
   ├─ Receive: ProgramName (e.g., "easitrace-production")
   └─ Receive: ProgramVersion (e.g., "1.2.0")

2. PROPERTY SETUP
   ├─ Each property must have ScotEID user credentials
   │  └─ Provided by property owner from ScotEID system
   ├─ Username: ScotEID login (usually email or numeric ID)
   └─ Password: ScotEID password

3. TRANSACTION SUBMISSION
   ├─ Client calls EasiTrace API with transaction
   │  ├─ ServiceProviderAuth (ProgramName, ProgramVersion, Password)
   │  └─ PropertyAuth (Username, Password)
   ├─ EasiTrace validates credentials with ScotEID
   │  └─ Performs test API call to verify access
   └─ If valid: Transaction is packaged and sent to ScotEID

4. SCOTEID PROCESSING
   ├─ ScotEID receives SOAP request with HTTP Basic Auth
   ├─ Validates credentials against ScotEID user database
   ├─ Processes transaction
   └─ Returns response (success/error)

5. RESPONSE
   ├─ EasiTrace receives response from ScotEID
   └─ Returns to client with transaction result

┌─────────────────────────────────────────────────────────────────┐
│ Note: No token exchange or redirect needed                      │
│ Credentials are validated on first use via API call             │
└─────────────────────────────────────────────────────────────────┘

Prerequisites

To use ScotMoves through EasiTrace, you will need:

1. Software Provider Registration with ScotEID

2. Service Provider Credentials (from ScotEID)

3. Property Owner Credentials (from ScotEID)

4. Property Information

Setup

Once you have obtained your credentials from ScotEID, integrate them into your application.

Step 1: Store Provider Credentials

Store your service provider credentials securely (e.g., in environment variables or secure configuration):

{
  "scotmoves": {
    "programName": "easitrace-production",
    "programVersion": "1.0",
    "serviceProviderPassword": "your-service-provider-password"
  }
}

Security Best Practices:

Step 2: Obtain Property Credentials

For each property you want to manage:

  1. Property owner logs into ScotEID system
  2. Property owner creates or provides user credentials with movement permissions
  3. Property owner shares credentials securely with your organization
  4. Store property credentials securely (environment variables, encrypted database, etc.)

Example structure:

{
  "properties": [
    {
      "cph": "84/567/0037",
      "scoteid_username": "john.smith@example.com",
      "scoteid_password": "property-owner-password"
    },
    {
      "cph": "89/677/0009",
      "scoteid_username": "farm_manager",
      "scoteid_password": "another-password"
    }
  ]
}

Step 3: Submit Transactions with Credentials

When submitting a transaction to EasiTrace, include all authentication information:

JSON Transaction Example (Movement On)

{
  "reference": "MOV-2024-001",
  "transactionDate": "2024-01-15T10:30:00.000Z",
  "type": "MOV-ON",
  "speciesCode": "C",
  "servicetag": "SCOT-MOVES",
  "propertyIdentifier": "84/567/0037",
  
  "serviceProviderAuth": {
    "programName": "easitrace-production",
    "programVersion": "1.0",
    "password": "your-service-provider-password",
    "schemaVersion": "1.0"
  },
  
  "propertyAuth": {
    "username": "john.smith@example.com",
    "password": "property-owner-password",
    "propertyType": "F"
  },
  
  "fields": {
    "ScotMoves.Movement.DepartureMainCPH": "89/677/0009",
    "ScotMoves.Movement.DestinationMainCPH": "84/567/0037",
    "ScotMoves.Movement.DestinationLocation": "84/567/0044"
  },
  
  "animals": [
    {
      "visual": "GB123456789012"
    },
    {
      "visual": "GB123456789013"
    }
  ]
}

JSON Transaction Example (Animal Registration)

{
  "reference": "REG-2024-001",
  "transactionDate": "2024-01-15T10:30:00.000Z",
  "type": "REG",
  "speciesCode": "C",
  "servicetag": "SCOT-MOVES",
  "propertyIdentifier": "84/567/0037",
  
  "serviceProviderAuth": {
    "programName": "easitrace-production",
    "programVersion": "1.0",
    "password": "your-service-provider-password",
    "schemaVersion": "1.0"
  },
  
  "propertyAuth": {
    "username": "john.smith@example.com",
    "password": "property-owner-password",
    "propertyType": "F"
  },
  
  "animals": [
    {
      "visual": "GB123456789014",
      "birthDate": "2024-01-10T00:00:00.000Z",
      "breedCode": "BA",
      "sexCode": "F",
      "damOfficialId": "GB123456789001",
      "sireOfficialId": "GB123456789002",
      "fields": {
        "ScotMoves.Register.UserReference": "USER-REF-001"
      }
    }
  ]
}

C# Code Example

using MPaaS.Api.Core.Models;
using System;

// Build service provider authentication
var serviceProviderAuth = new ServiceProviderAuthentication
{
    ProgramName = "easitrace-production",
    ProgramVersion = "1.0",
    Password = "your-service-provider-password",
    SchemaVersion = "1.0"
};

// Build property authentication
var propertyAuth = new PropertyAuthentication
{
    Username = "john.smith@example.com",
    Password = "property-owner-password",
    PropertyType = "F" // Farm
};

// Build authentication object
var authentication = new Authentication
{
    ServiceProviderAuth = serviceProviderAuth,
    PropertyAuth = propertyAuth
};

// Build transaction
var transaction = new Transaction
{
    Reference = "MOV-2024-001",
    TransactionDate = DateTime.UtcNow,
    Type = "MOV-ON",
    SpeciesCode = "C", // Cattle
    ServiceTag = "SCOT-MOVES",
    PropertyIdentifier = "84/567/0037", // CPH format
    Fields = new Dictionary<string, object>
    {
        { "ScotMoves.Movement.DepartureMainCPH", "89/677/0009" },
        { "ScotMoves.Movement.DestinationMainCPH", "84/567/0037" },
        { "ScotMoves.Movement.DestinationLocation", "84/567/0044" }
    },
    Animals = new List<TransactionAnimal>
    {
        new TransactionAnimal { Visual = "GB123456789012" },
        new TransactionAnimal { Visual = "GB123456789013" }
    }
};

// Submit to EasiTrace
var result = await easitraceClient.SubmitTransactionAsync(transaction, authentication);

Step 4: Handle Validation Responses

EasiTrace validates credentials before processing:

{
  "isValid": true,
  "errors": [],
  "warnings": [],
  "message": "Transaction accepted for processing"
}

If credentials are invalid, you’ll receive:

{
  "isValid": false,
  "errors": [
    {
      "code": "AUTHENTICATION.SERVICE_CREDENTIALS_INVALID",
      "message": "No program name provided"
    },
    {
      "code": "AUTHENTICATION.SERVICE_CREDENTIALS_INVALID",
      "message": "Invalid service provider password"
    }
  ],
  "warnings": []
}

Authentication Structure

Service Provider Authentication

ScotMoves requires complete service provider authentication:

Field Type Required Description
ProgramName String ✓ Yes Your registered application name
ProgramVersion String ✓ Yes Your application version
Password String ✓ Yes Service provider password from ScotEID
SchemaVersion String ✓ Yes API schema version (typically “1.0”)

Property Authentication

Property-level credentials for accessing ScotEID:

Field Type Required Description
Username String ✓ Yes ScotEID user login (email or user ID)
Password String ✓ Yes ScotEID user password
PropertyType String ✓ Yes Always “F” (Farm) for ScotMoves

HTTP Basic Authentication (SOAP Level)

When EasiTrace sends requests to ScotEID, it uses HTTP Basic Authentication in the SOAP headers:

Authorization: Basic base64(username:password)

Example (decoded):

Username: john.smith@example.com
Password: property-owner-password
Header: Authorization: Basic am9obi5zbWl0aEBleGFtcGxlLmNvbTpwcm9wZXJ0eS1vd25lci1wYXNzd29yZA==

This is handled automatically by EasiTrace - you don’t need to manage this directly.

ScotEID Infrastructure Relationship

Shared Platform Architecture

ScotMoves is implemented as part of the broader ScotEID platform infrastructure. This relationship means:

1. Authentication Infrastructure

2. Unified Registration

3. Common Data Model

4. Account Management

How ScotMoves Uses ScotEID

┌──────────────────────────────────────┐
│      ScotEID Web Service             │
│   (Shared Infrastructure)            │
│  ├─ Sheep/Goats/Pigs (ScotEID)      │
│  ├─ Cattle (ScotMoves)              │
│  └─ User Authentication              │
└──────────────────────────────────────┘
         ▲              ▲
         │              │
    HTTP Basic Auth  SOAP Headers
    (user:password)  (provider creds)
         │              │
    ┌────┴──────────────┴────┐
    │   EasiTrace Services   │
    │   - Validation         │
    │   - Translation        │
    │   - Error Handling     │
    └────┬──────────────────┬┘
         │                  │
    ┌────▼──┐          ┌────▼──┐
    │Client │          │Client │
    │(Cattle)         │(Sheep)│
    └───────┘          └───────┘

Credential Validation

How Validation Works

When you submit a transaction with credentials, EasiTrace validates them by:

  1. Creating a test transaction using the GET-ADDTNL-HOLDINGS capability
  2. Attempting to send this test transaction to ScotEID with the provided credentials
  3. Checking the response to verify credentials are valid
  4. Reporting validation results before processing the actual transaction

Validation Code

// From UserCredentialValidator.cs
public bool Validate(string username, ref string password, ServiceProviderAuthentication serviceProviderAuth)
{
    var transaction = new Transaction()
    {
        SpeciesCode = Core.Species.Cattle.Value,
        Type = ServiceCapability.GetAdditionalHoldings.Code,
        TransactionDate = DateTime.Now
    };

    var authentication = new Authentication()
    {
        ServiceProviderAuth = serviceProviderAuth,
        PropertyAuth = new PropertyAuthentication()
        {
            Username = username,
            Password = password,
            PropertyType = "F"
        }
    };

    var packed = _container.Packer.Pack(transaction, authentication);

    try
    {
        _container.Sender.Send(ServiceCapability.GetAdditionalHoldings, packed, authentication);
        return true;
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Authentication Error with ScotMoves");
        return false;
    }
}

Validation Checks

ScotMoves performs the following validations:

Validation Error Code Impact
ProgramName missing AUTHENTICATION.SERVICE_CREDENTIALS_INVALID Transaction rejected
ProgramVersion missing AUTHENTICATION.SERVICE_CREDENTIALS_INVALID Transaction rejected
Service password missing AUTHENTICATION.SERVICE_CREDENTIALS_INVALID Transaction rejected
SchemaVersion missing AUTHENTICATION.SERVICE_CREDENTIALS_INVALID Transaction rejected
Username missing Validation error Transaction rejected
Password missing Validation error Transaction rejected
Invalid credentials (ScotEID rejects) Exception logged Credential validation fails
Property lacks movement permissions Exception logged Credential validation fails

Invalid Credentials Response Example

{
  "transactionId": "12345",
  "status": "FAILED",
  "errors": [
    {
      "code": "AUTHENTICATION.CREDENTIALS_INVALID",
      "severity": "ERROR",
      "message": "Invalid username or password provided. Please verify ScotEID credentials with property owner.",
      "field": "propertyAuth"
    }
  ],
  "validationResults": {
    "isValid": false,
    "credentialValidationFailed": true,
    "failureReason": "HTTP 401 Unauthorized from ScotEID service"
  }
}

Test Environment

Test Credentials

For development and testing, ScotEID provides test accounts:

{
  "provider": {
    "programName": "easitrace-test",
    "programVersion": "1.0",
    "password": "test-service-password"
  },
  "testProperties": [
    {
      "cph": "84/567/0037",
      "username": "testuser1@scoteid-test.com",
      "password": "TestPassword123!",
      "description": "Test property - cattle enabled"
    },
    {
      "cph": "89/677/0009",
      "username": "testuser2@scoteid-test.com",
      "password": "TestPassword456!",
      "description": "Test property - full capabilities"
    }
  ]
}

Note: Contact ScotEID support to obtain test credentials for your registered application.

Test Environment Endpoints

Production ScotEID Web Service:
https://www.scoteid.com/Services/webservice

Test/Staging ScotEID Web Service:
https://test.scoteid.com/Services/webservice
(Request access from ScotEID)

Testing Checklist

When testing ScotMoves authentication:

Sample Test Transaction

curl -X POST https://api.easitrace.local/v1/transactions \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "TEST-MOV-001",
    "transactionDate": "2024-01-15T10:30:00Z",
    "type": "MOV-ON",
    "speciesCode": "C",
    "servicetag": "SCOT-MOVES",
    "propertyIdentifier": "84/567/0037",
    "serviceProviderAuth": {
      "programName": "easitrace-test",
      "programVersion": "1.0",
      "password": "test-service-password",
      "schemaVersion": "1.0"
    },
    "propertyAuth": {
      "username": "testuser1@scoteid-test.com",
      "password": "TestPassword123!",
      "propertyType": "F"
    },
    "fields": {
      "ScotMoves.Movement.DepartureMainCPH": "89/677/0009",
      "ScotMoves.Movement.DestinationMainCPH": "84/567/0037",
      "ScotMoves.Movement.DestinationLocation": "84/567/0044"
    },
    "animals": [
      {
        "visual": "GB123456789012"
      }
    ]
  }'

Security Considerations

Credential Management

  1. Never log credentials - EasiTrace automatically redacts credentials in logs
  2. Use environment variables - Store credentials in env vars, not config files
  3. Rotate regularly - Change service provider password quarterly or as per policy
  4. Limit distribution - Only share credentials with authorized personnel
  5. Use HTTPS only - All communications must be encrypted
  6. Audit access - Log and monitor credential usage for anomalies

HTTP Basic Auth Security

Credential Rotation

When you need to change service provider password:

  1. Contact ScotEID support
  2. Request password rotation
  3. Obtain new password from ScotEID
  4. Update credentials in your secure storage
  5. Update all running instances of your application
  6. Coordinate to avoid service disruption

Troubleshooting

Common Authentication Errors

Error Cause Solution
Invalid service provider password Password doesn’t match ScotEID records Verify password with ScotEID support
No program name provided ProgramName field is empty/null Check that ProgramName is included in request
Authentication Error with ScotMoves ScotEID rejected credentials Verify property credentials in ScotEID portal
HTTP 401 Unauthorized Invalid username/password for property Confirm property owner credentials are correct
Property lacks permissions User account doesn’t have movement access Contact property owner to enable permissions in ScotEID

Debugging Tips

  1. Enable debug logging - Set log level to DEBUG to see credential validation details
  2. Test in ScotEID portal - Log in directly to verify credentials work
  3. Check account status - Ensure ScotEID account is not suspended/locked
  4. Verify permissions - Confirm user has “Cattle Movement” permissions enabled
  5. Review audit logs - Check ScotEID audit logs for failed login attempts

For further assistance, contact:

Last Updated: January 2024 Documentation Version: 1.0 ScotMoves API Version: 1.0