About ID Match
ID Match refers to the task of determining if a person presented by a system of record is already known to the Identity Management System.
There are several characteristics of an ID Match implementation.
Coordinated vs Independent Attributes
In a coordinated implementation, all systems of record agree to a single set of "golden" attributes, and the ID Match component is authoritative for these attributes. When an SoR presents attributes for matching, the ID Match component matches against the single, golden set of attributes.
In an independent implementation, each system of record is authoritative for all of its own attributes. When an SoR presents attributes for matching, the ID Match component may match against a canonical representation of these attributes as managed by the IdMS, but it may also match against each SoR's representation of these attributes.
Synchronous vs Asynchronous Match Resolution
When a partial/potential match occurs, the client may be able to resolve the match synchronously by presenting information to the data entry personnel and submitting a forced resolution request.
If the client is not able to do so, then the match is resolved asynchronously, usually by a notification going to a match administrator, who can then view the potential match and resolve it.
When matching is performed via batch operations, it must be asynchronous.
Implementation at Registry vs Standalone
ID Match can be performed at the Person Registry or as a standalone service.
Match Before Registry vs Match At Registry
ID Match can be performed before a record is added to the Person Registry, or at the Person Registry. In either case, the ID Match might be performed by the Person Registry, or by a standalone service.
Algorithm
The matching algorithm is generally out of scope for the ID Match API.
About the ID Match API
This API is used to obtain a unique reference to a Person known to the IdMS based on data known to an SOR. The Person may or may not be known to the IdMS at the time of the query, but generally the Person will be new to the SOR.
This API is exposed by the ID Match component. The Registry component may also expose this API, either because it implements ID Match natively or because it brokers requests to the ID Match component.
This draft is based on the ID Match Strawman. All services are mandatory unless otherwise stated.
Identifiers used by the Match API may be returned in either string or number notation. This includes the match reference identifier, the match request identifier, and any local identifiers.
People
The ID Match API operates with the primary resource being People. The goal of a client is to obtain a reference identifier for a person.
Reference Identifier Request
Obtain a unique reference identifier from the ID Match component in order to canonically identify the person presented by the SOR.
The following sorAttributes are defined for matching purposes, with an intent to align with SOR-Registry Core Schema Strawman definitions:
This list is likely to change
- sorId (provided in the URL)
- address (home, official; broken out into st, l, etc)
- affiliation
- dateOfBirth
- gender
- nationalId (may be hashed)
- institutionId (eg: University ID)
- mail (ie: personal email)
- mobile
- name:official, name:preferred
- given
- middle
- family
- netId
- telephoneNumber:home, telephoneNumber:official
The specific sorAttributes that are required may vary by instance.
Note: The reference identifier returned to an SOR may match an identifier previously known to the SOR. For example, if an employee returns after an absence of several years, the IdMS may have the original reference identifier whereas the HRMS may have purged its copy.
Request
In this example, sis is the SOR label and 971194843 is the SOR ID for the candidate.
If the SOR ID is sensitive (such as being an SSN), placing it in the URL may not be ideal. In such a case, use of a salted-hashed identifier is recommended.
PUT /v1/people/sis/971194843
{
"sorAttributes":
{
"name":
{
"type":"official",
"given":"Pat",
"family":"Lee"
},
"dateOfBirth":"1983-03-18",
"nationalId":"3B902AE12DF55196",
"mobile":"8185551234"
}
}
Response: Unique Match Found
An existing identity was found matching the specified attributes.
responseType and version here (and in other places) should be replaced with a reference to a schema.
200 OK
{
"responseType":"referenceId",
"version":"1.0",
"referenceId":"M225127891"
}
Response: New Identifier Assigned
A new identity was created, since no existing identity matched the specified attributes. New Identifier Assigned and Unique Match Found are effectively equivalent from the perspective of the client.
201 Created
{
"responseType":"referenceId",
"version":"1.0",
"referenceId":"M225127891"
}
Response: With Additional Identifiers
Implementations may return additional identifiers in a successful (200 or 201) response.
The identifier attribute names are not specified, and may vary by local implementation.
200 OK
{
"responseType":"referenceId",
"version":"1.0",
"referenceId":"M225127891",
"identifiers":
{
"netid":"pl388",
"universityid":"905003148"
}
}
Response: Potential Match Found
This response allows an SOR to interactively select from potential matches. (See also Forced Reconciliation Request, below.) This response may include as few as one candidate. Implementation of this response is optional if the Externally Handled response is implemented.
confidence is an integer from 0 through 100, where 100 indicates maximum confidence.
Attributes may be returned to facilitate the selection of a candidate. The attributes may include any attribute specified in the SOR-Registry Core Schema Strawman, even attributes that the matching engine does not use to perform matching. The specific set of attributes returned may vary by local implementation.
To indicate a new person, the Identity Match engine may create a provisional record returned in the 300 Multiple Choices response, with a suitable referenceId assigned. Alternately, the referenceId may be set to new. Either way, the original data submitted is provided as a candidate with confidence omitted.
The Identity Match engine may elect to assign a match request ID to the transaction that generated the 300 Multiple Choices response. The match request ID is optional. If assigned, it is the same identifier as used to retrieve Pending Matches, and may be used in that context. If assigned, the match request ID must be provided when making a Forced Reconciliation Request to resolve the 300 Multiple Choices response.
300 Multiple Choices
{
"responseType":"candidates",
"version":"1.0",
"matchRequest":"1009",
"candidates":
[
{
"confidence":"85",
"referenceId":"M219488003",
"attributes":
[
{
"sor":"HRMS",
"sorId":"089010023",
"netId":"pl292",
"name":
{
"type":"official",
"given":"Patricia",
"family":"Lee"
},
"ou":"Biomedical Informatics"
},
{
"sor":"Alumni",
"sorId":"A330-200",
"netId":"pl292",
"name":
{
"type":"official",
"given":"Patricia",
"family":"Lee"
},
"ou":"Class of 1997"
}
],
"identifiers":
{
"netid":"pl292",
"universityid":"905008772"
} },
{
"confidence":"71",
"referenceId":"M523441767",
"attributes":
[
{
"sor":"guest",
"sorId":"pl388",
"netId":"pl388",
"name":
{
"type":"official",
"given":"Patricia",
"family":"Lee"
},
"mobile":"8185551234"
}
],
"identifiers":
{
"netid":"pl388",
"universityid":"905003148"
}
},
{
"referenceId":"new",
"attributes":
[
{
"sor":"SIS",
"sorId":"971194843",
"name":
{
"type":"official",
"given":"Pat",
"family":"Lee"
},
"mobile":"8185551234"
}
]
}
]
}
Response: Potential Match Found (Externally Handled)
Some configurations may not support an interactive transaction over the API to resolve a conflict. In this sort of scenario, the ID Match engine will submit a reconciliation request to a Reconciliation Manager (probably via email with a URL for resolution). The engine is responsible for maintaining enough state to be able to handle a manual reconciliation at a later (but not too much later) time.
See also Console Support Operations, below.
202 Accepted
Response: Error With Request
Errors could include failing to submit required attributes, submitting invalid values for attributes, etc.
400 Bad Request
An optional human readable error message may be included in the response body.
400 Bad Request
{
"error":"Required field not provided"
}
Forced Reconciliation Request
After a 300 Multiple Choices response, the client must submit a modified request with an ID Match Reference Identifier to link to an existing record, or an indication that a new person should be created. This will generally result in 200 OK. Only candidates listed in the 300 response may be included in the forced reconciliation.
PUT /v1/people/sis/971194843
{
"sorAttributes":
{
"name":
{
"type":"official",
"given":"Pat",
"family":"Lee"
},
"dateOfBirth":"1983-03-18",
"nationalId":"3B902AE12DF55196",
"mobile":"8185551234"
},
"referenceId":"M523441767"
}
Update Match Attributes
The Identity Match engine must be kept up to date if attributes used for matching are updated. (For example, if a person's name changes, the SOR must update the name attributes in case the person subsequently shows up via a different SOR.) This can also be handled out of band, eg by sync'ing the match database with a registry database, or by the two databases being the same. As such, implementation of the following three requests is optional (though if any one is implemented, all three must be implemented).
A complete set of attributes are provided to replace the existing set.
Request
PUT /v1/people/sis/971194843
{
"sorAttributes":
{
"name":
{
"type":"official",
"given":"Patricia",
"family":"Lee"
},
"dateOfBirth":"1983-03-18",
"nationalId":"3B902AE12DF55196",
"mobile":"8185551234"
}
}
}
Request Current Values
The current values of match attributes as known to the match engine may be retrieved by the SOR. Note that if a match has previously been made, the referenceId will be included in the response.
GET /v1/people/sis/971194843
{
"sorAttributes":
{
"name":
{
"type":"official",
"given":"Patricia",
"family":"Lee"
},
"dateOfBirth":"1983-03-18",
"nationalId":"3B902AE12DF55196",
"mobile":"8185551234"
}
},
"referenceId":"M523441767"
}
This operation may also return 403 Unauthorized or 404 Not Found.
Delete Current Values
The match attributes for the SOR can be deleted. Typically, this should only be done when a record was added erroneously, as the match engine will perform better if it has access to historical records.
DELETE /v1/people/sis/971194843 200 OK
This operation may also return 403 Unauthorized or 404 Not Found.
Pending Matches
In order to support an Identity Console, certain additional resources are needed. These operations are mandatory, in order to support decoupling of services (in this case the Identity Match engine from the Identity Console).
Note that resolving a pending reconciliation request is handled via the Forced Reconciliation Request, described above.
Request Pending Matches
GET /v1/pendingMatches
200 OK
{
"responseType":"pendingMatches",
"version":"1.0",
"matchRequests":
{
"1009":
[
{
"confidence":"85",
"referenceId":"M219488003",
"attributes":
[
{
"sor":"HRMS",
"sorId":"089010023",
"netId":"pl292",
"name":
{
"type":"official",
"given":"Patricia",
"family":"Lee"
},
"ou":"Biomedical Informatics"
}
]
},
{
"confidence":"71",
"referenceId":"M523441767",
"attributes":
[
{
"sor":"guest",
"sorId":"pl388",
"netId":"pl388",
"name":
{
"type":"official",
"given":"Patricia",
"family":"Lee"
},
"mobile":"8185551234"
}
]
}
],
"1014":
[
{
"confidence":"78",
"referenceId":"M660187457",
"attributes":
[
{
"sor":"HRMS",
"sorId":"914890374",
"netId":"p5478",
"name":
{
"type":"official",
"given":"Richard",
"family":"Hertz"
},
"ou":"Biology"
}
]
},
{
"confidence":"64",
"referenceId":"M287898924",
"attributes":
[
{
"sor":"HRMS",
"sorId":"881095626",
"netId":"p8314",
"name":
{
"type":"official",
"given":"Ricardo",
"family":"Hertzfeld"
},
"ou":"Neuroscience"
}
]
}
]
]
}
Request Pending Match
It may be desirable for the response to include all known SOR data, if the match engine has access to it. This would facilitate the reconciliation administrator in determining how to resolve a pending match. Such functionality is optional, and could also be provided by having the Identity Console query the Identity Registry.
GET /v1/pendingMatches/1009
300 Multiple Choices
{
"responseType":"candidates",
"version":"1.0",
"candidates":
[
{
"confidence":"85",
"referenceId":"M219488003",
"attributes":
[
{
"sor":"HRMS",
"sorId":"089010023",
"netId":"pl292",
"name":
{
"type":"official",
"given":"Patricia",
"family":"Lee"
},
"ou":"Biomedical Informatics"
}
]
},
{
"confidence":"71",
"referenceId":"M523441767",
"attributes":
[
{
"sor":"guest",
"sorId":"pl388",
"netId":"pl388",
"name":
{
"type":"official",
"given":"Patrick",
"family":"Lee"
},
"mobile":"8185551234"
}
]
}
]
}