High level description
From a high level perspective, FIFA Connect ID service is divided into four main components:
- Hashing - provides REST API for computing hashes of person's first and last name
- ID Directory - provides REST API for registration/management/search of persons, organizations and facilities
- Connect Service Bus - provides REST API for asynchronous, encrypted queue-based communication between all management systems
- Admin Console - web application for reporting and auditing including notifications; no personal data is available here or in Connect ID service.
The service is hosted in Azure cloud environment. To generate all REST API documentation Swagger is used.
Primary use case, when Connect ID service handles registration of a person is described below:
- Member association platform sends a request to Connect ID service to register a person
- Connect ID service either returns the unique FIFA ID or the list of potential duplicates with details downloaded from other member associations' platforms
It is important to note the Connect ID service performs a number of operations in the background in order to check for duplicates and extract detailed data from other platforms over Connect Service Bus. All this complexity, however, is hidden from the developer using FIFA Connect ID SDK.
Some of those operations which happen behind the scenes are listed below:
- Member association platform sends a request to Hashing service to get different hashes of the name
- Hashing service returns computed hashes to member association platform
- Member association platform sends a request to ID Directory service passing hashes returned from Hashing service, date of birth and person registrations
- ID Directory service looks for duplicates
- If no duplicates are found then ID Directory assigns a new FIFA ID and member association platform saves the value in its local database
- In case of duplicates, Connect ID service tries to download details of potential duplicates from other member association platforms via Connect Service Bus. Then it is up to member association platform to decide whether it is a real duplicate or not. This scenario is described in details in the further part of this document.
The most important scenario is that of a first-time registration. Please see in the PDF file attached to this article a flow chart describing which Connect ID SDK methods are used in the scenario of a first-time registration with potential duplicates found by the Connect ID Service.
Software development kit for developers
The best way to integrate with FIFA Connect ID service is to use one of delivered SDK. Full documentation for each supported technology can be found as part of specified package: FIFA Connect ID SDK. This package also includes Connect Service Bus libraries providing infrastructure for exchanging encrypted messages with other member associations' platforms. FIFA Connect ID SDK provides a unified way to perform resolving duplicates during registrations and other scenarios which don't require exchanging data between member associations.
Additionally there is a FIFA Connect Service Bus SDK package offered. It should very rarely be used - only by platforms which don't deal with registration scenarios and their only goal is to use Connect Service Bus infrastructure to send/receive encrypted messages.
Although it is recommended to use one of provided SDK, it is still possible to integrate with FIFA Connect ID service using another technologies. More details can be found here.
How to take advantage of FIFA Connect ID SDK
Download SDK package, read the documentation, import libraries in your project and start using it. As simple as that! Current version of SDK supports two ways of integration with FIFA Connect ID service:
- Using RegistrationFacade object to register/update/find and search for duplicates at the same time. This requires communication with other member associations via Connect Service Bus. Complexity of sending and receiving messages between member associations is hidden and implemented. Although RegistrationFacade must be properly configured in order to be able to receive and response to incoming messages. Please refer to section 3.1 Using Registration Facade documentation of FIFA Connect ID SDK for more details.
FifaConnectIdClientfor other scenarios. No duplicates checks are performed and no communication between registration platforms is involved. Please refer to section 3.2 Using FIFA Connect ID Client documentation of FIFA Connect ID SDK for more details.
In both ways following aspects of integration are implemented and hidden:
- Calling REST API - there is no need to explicitly send requests to any REST API. All that logic is hidden behind RegistrationFacade or
- Authentication and authorization - access control to REST API is implemented using Azure Active Directory. Each system that is using FIFA Connect ID or Connect Service Bus service has a separate service account. You only need to provide clientId and secretKey when creating an instance of client in code. The whole process of authentication and checking permissions works out of the box.
- Encryption and decryption of messages - Connect Service Bus SDK provides end to end encryption which is enabled by default. Messages are being encrypted in SDK of sending member association and decrypted in SDK of receiving member association. It is done by using public-key encryption. Public key is available to anyone but a private key is known only to a recipient of a message. Every registration platform of member association is responsible for storing private certificate in a secure way.
- Hashing of persons' names before registering them - due to personal data protection regulations, Hashing and ID Directory services are separated, so that ID Directory does not know anything about the real name of a person being registered. As a developer, you don't need to care about this distinction (or hashing in general). SDK communicates with Hashing and ID Directory automatically whenever is needed.
How to get an access/credentials to FIFA Connect ID service?
In order to have an access to any of modules of FIFA Connect ID service, you need to contact Connect ID Support team by opening a ticket in this support portal or writing an e-mail to firstname.lastname@example.org (which will open a ticket automatically).
How to generate certificates
A detailed description how to generate certificates for later use in Connect Service Bus can be found in a SDK packages both for FIFA Connect ID and FIFA Connect Service Bus.
The package also contains all tools needed to generate both public and private certificates. Right now, those tools are prepared to work only under Microsoft operating systems.
After downloading the package to your computer, please refer to fifa-connectservicebus-certificates-generation.html.
Exchanging data between member associations
Connect Service Bus is a central point for exchanging personal data between member associations. This is crucial when it comes to resolving conflicts during registration process.
Let's consider following example so it is easier to understand this behavior. The whole communication between member associations is encrypted by default. This setting can be changed in code.
- The Canadian Soccer Association (CAN) already went live, registration platform is configured to integrate with FIFA Connect ID service.
- Norges Fotballforbund (NOR) went live, registration platform is configured to integrate with FIFA Connect ID service.
- Both mentioned registration platforms are able to receive and response for incoming request to get person details.
- NOR is trying to register a person (Jon Doe) using RegistrationFacade from FIFA Connect ID SDK and a possible duplicate has been returned.
- SDK sends an HTTP request to Hashing REST API and waits for response
- SDK sends an HTTP request to ID Directory REST API and waits for response
- ID Directory returns found duplicate from Canadian Soccer Association - let's say it's FIFA ID is 105C408
- SDK sends request for person details to CAN via Connect Service Bus
- Registration platform in CAN handles this message. As a response to that, CAN sends a message via Connect Service Bus to NOR with person details
- NOR receives message with person details (id:105C408, name: John Doe) and information that possible duplicate has been registered in CAN
- It's up to Norges Fotballforbound to decide if it's a duplicate or not.
A Powerpoint presentation, which explains the whole process of finding international duplicates and exchanging data between member associations can be found in the attachment at the end of this article.
When opening the Admin Console for the first time you might be surprised by the lack of persons' basic information, like name. In the Connect ID service we do not store any personal details due to data protection reasons. Information related to a person is limited to:
- FIFA ID
- Hashed (anonymized) names
- Date of birth
- Role(s) in football
...which is information required for our football participation statistics. The detailed information is kept in the domestic registration systems. In case there is a potential duplicate in another Member Association or a transfer takes place, we offer the Connect Service Bus which enables direct exchange of detailed person information, using the FIFA Connect Data Standard, between the two concerned member associations.
FIFA Connect ID environments
There are different environments that registration platform connects to when using FIFA Connect ID SDK.
- Beta - environment used for testing purposes. Intended to be used during development process. After a notice, data may be erased from Beta.
- Preproduction - once you completed development process on Beta and cleaned up your data from local duplicates you are ready to work with it. Then you use real data to register all players and see how many international duplicates are found before going to Production. The purpose of this environment is to have a place to test the system with real data.
- Production - live environment. Once you completed tests on Preproduction you can start registration process on Production.
All mentioned environments are shared and might be used by other registration platforms within different member associations.
Note, that because every Member Association loads the real data to Preproduction as part of the roll-out process, the environment contains data that is very similar to production data. As a result, a duplicate check can give a good approximation of how many international duplicates would be found when loading data to Production.