API Authentication

Overview

Access to the Livestock Information Service (LIS) application is controlled by the Azure B2C authentication service that requires users to provide user credentials in order to record and query livestock movements.

This service uses a standards-based user authentication solution, using secure and well proven technology (OpenID Connect), with a large body of reference implementations. All major software development toolsets, languages and frameworks are supported, with wide availability of sample code and supporting documentation.

Below is an overview of the procedures that third party developers and the client application they develop will follow in order to consume LIS API:

• Register an application and Subscribe to use the LIS service under the my Apps & Data page and make a note of all credentials
• Obtain a test user account and test data to use the LIS Sandbox service (LI will contact you with this)
• Develop application flows to:
  1. Capture account credentials from the user
  2. Obtain an authentication token and access token
  3. Use the access token to access LIS API

Client application types

Your application can be one of two client types: ‘public’ and ‘confidential’. The two client types are distinguished by their ability to authenticate securely with the authorization server and maintain the confidentiality of their client credentials. The type of client governs which kinds of authorisation flows are permitted.

Confidential client applications

These are applications that run on servers (web apps, web API apps, or even service/daemon apps). They're considered capable of keeping configuration data and application information secret because it is difficult for casual users to gain access either due to physical location, or build-in software defence mechanisms. A web app is the most common type of confidential client.

Each instance of the client has a distinct configuration (which includes the client ID and client secret). The client ID is exposed through the web browser, but the secret is passed only in the back channel and never directly exposed.

The authorisation flow for this type of application is shown in the diagram below

Public client applications

This is an application that is installed in an untrusted location, or where the security and safety of the confidential or secret data cannot be assured.

Typical examples of a public client applications include those that run on a desktop computer, laptop or mobile phone, often used by a single user. It might also be a Single Page Application with no back-end where application data, including user credentials are stored on the host machine. They're not trusted to safely keep application secrets, so they only access web APIs on behalf of the user.

The authorisation flow for this type of application is shown in the diagram below

Comparing the application types

As a developer, there are some differences in the authentication pattern you will use, depending of what type of client application you are developing. Below are some similarities and differences between the operation of public client and confidential client applications:

• Both kinds of app maintain a user token cache and can acquire a token silently (when the token is already in the token cache). Confidential client apps also have an app token cache for tokens that are for the app itself
• Both types of app manage user accounts and can get an account from the user token cache, get an account from its identifier, or remove an account
• Public client apps have four ways to acquire a token (four authentication flows). Confidential client apps have three ways to acquire a token (and one way to compute the URL of the identity provider authorize endpoint). For more information, see Acquiring tokens

You will need to let us know which application type you are developing when you register your application, so that we can provide you the correct information to allow your application to connect to our service.

Authentication process flows

Both application types follow similar high-level patterns when authenticating:

• The application directs the user to the authentication service to capture user credentials
• The user provides credentials
• The application receives an authorisation code from the authentication service
• The application passes the authorisation code (and client secret where applicable) to the /token endpoint and where it is exchanged for an access token
• The application uses the access token and the LIS API subscription key to access protected information or a protected resource hosted by the LIS service
• The LIS service validates the access token and subscription key to verify that access can be granted
• The application periodically refreshes the access token

The diagram below summarises this flow:

Note that at step 1. it is the authentication service that is prompting the user for credentials, not the client application.

The client application is simply redirecting the user to the authentication service screen flow and awaiting the result. Information capture, retry handling and user assistance (e.g. lost password reminders) are all managed by the authentication service. An example of the user credentials input is shown below.

Once the client application has received an access token from the authentication service, it uses this together with the subscription key to access the secure services exposed by the Livestock Information Service.

The technical detail of the implementation is beyond the scope of this document. Implementation patterns and specific details will vary according to which programming languages, code libraries and applications frameworks are used to develop the client application.

Microsoft B2C Documentation

Full documentation detailing the application flows, together with code samples for a variety of development technologies and frameworks is available on the Microsoft Azure B2C Documentation web site. This location also provides information about how the specific implementation details required depending on whether you are developing a public or a confidential client application.

Sample Code on Livestock Github Channel

Sample code illustrating authentication with Livestock Identity platform in a WPF desktop application is available via our github repository.

Sample code illustrating authentication with Livestock Identity platform in a web application is available via our github repository.