Open Apereo Cifer APIs

CIFER APIs:Filling The Gaps In The Exchange of Identty Data

Keith HazeltonBenjamin Oshrin

1 June 2015 • Open Apereo

CIFER APIs: Filling The Gaps In The Exchange of Identty DataOpen Apereo 2015

2

ACAMP 2010Raleigh, NC, US

OSSIDM4HEOSSIDM4HE FIFERFIFER

FIFER APIFIFER API


3

Jasig+ACAMP 2011Westminster, CO, US


4

Another Naming Process

OSSIDM4HEOSIdM4HEOSIdM4HE

FIFERCIFERCIFER

FIFER APICIFER APICIFER API


5

And Even a Logo!


6

Change Happens


7

Change Happens


8

Change Happens


9

CIFER API and TIER

OSSIDM4HEOSIdM4HE

FIFERCIFER



10

CIFER API and TIER

TIERTIER


Trust andIdentty inEducaton andResearch


11

CIFER APIs In Context


12

CIFER API: Objectves

Facilitate fexible, loosely coupled (modular) IAMdeployments to help insttutons avoid product lock-inand to improve maintainability as identtyrequirements evolve.


13

CIFER API: Objectves

Directories: LDAP

Authentcaton: SAML, OAuth, etc

Provisioning: SCIM, SPML(!), etc

SOR/Registry

ID Match

Account Management


14

Sample Deployment (Phase 1)


15



16



17

Why Not Just Use SCIM?

● How to represent ID Match?● Not just “search based on atributes”● Fuzzy match indicaton, resoluton● Pending matches for administrator review

– Synchronous vs asynchronous resoluton● Varying modes of operaton

– Coordinated (SORs in agreement)– Independent (SORs in isolaton)

● Lots of details to consider...


18

Why Not Just Use SCIM?

● Atributes● Addresses is top level, not per role● Need additonal sub-atributes

– Language encoding– Additonal types– Verifed status for email– Etc

● Some conficts more resolvable than others


19

Why Not Not Just Use SCIM?

● No need to re-invent the wheel● Paginaton● Search Filters● Query Parameters and Response Codes● Versioning

● Details at htps://spaces.internet2.edu/x/VonYAg

https://spaces.internet2.edu/x/VonYAg


20

ACAMP 2014Indianapolis, IN, US

WHEREAS reinventng the wheel is undesirable,

WHEREAS SCIM and CIFER have similar but notcompletely overlapping objectves,

RESOLVED, the CIFER APIs shall be derived from SCIMconventons, phrasing the API structure as difs fromSCIM API,

RESOLVED, the CIFER Core Schema shall stand on itsown and not just extend the SCIM Core Schema.


21

Core Schema

● Provide common atributes and types for APIs● Based on a comparison of HE&R-oriented registries

and protocols● OpenRegistry, CPR, COmanage, KIM● eduPerson, IMS Global, OpenSocial, SCIM, etc

● Extensions for locally defned atributes


22

Core Schema Person Atributes● address

● citzenship

● dateOfBirth

● emailAddress

● ethnicity

● gender

● identfer

● identtyProof

● name

● photo

● telephoneNumber

● url

● visa


23

Core Schema Person Role Atributes● address

● afliaton

● campus

● department

● displayTitle

● emailAddress

● identfer

● leaveBegins / leaveEnds

● organizaton

● percentTime

● roleBegins / roleEnds

● sponsor

● status

● telephoneNumber

● terminatonReason

● ttle

● url

● validFrom / validThrough


24

Core Schema Example"identifiers": [{

"identifier": "ps1",

"type": "network"

},{

"identifier": "N787900",

"type": "enterprise"

}],

"names": [{

"family": "Smith",

"formatted": "Patricia Smith",

"language": "en",

"type": "official"

},{

"family": "Smith",

"formatted": "Pat Smith",

"language": "en",

"type": "preferred"

}],

"primaryAffiliation": "faculty",

"roles": [{

"meta": {

"id": 518674,

"sor": "hris"

},

"affiliation": "employee",

"addresses": [{

"country": "US",

"locality": "New Haven",

"region": "CT",

"street": ”1 Elm St",

"type": "official"

}],

"title": "Professor"

},

...]


25

SOR to Registry API

● Provides a mechanism for transferring SOR Roledata to an Identty Registry● An SOR can only be authoritatve for its roles (eg:

student, faculty, alumni, staf, etc) and not for a person● The Identty Registry maintains the canonical view of a

person


26

SOR to Registry API:SOR Person Role Added● Request Using Separate Person-Level and Role-

Level AtributesPOST /sor_people/hrms/X12345

{

"givenName":"Pat",

"sn":"Lee",

"dateofBirth":"1983-03-18"

}

POST /sor_people/hrms/X12345/R98765

{

"title":"Professor of Phrenology",

"percentAllocation":"50%"

}


{

"title":"Administrative Assistant",


}


27

SOR to Registry API:SOR Person Role Added● Request using person-level atributes expressed as

role-level atributesPOST /sor_people/hrms/X12345/R98765

{

"givenName":"Pat",

"sn":"Lee",


"title":"Professor of Phrenology",

"percentAllocation":"50%"}


{

"givenName":"Pat",

"sn":"Lee",


"title":"Administrative Assistant",


}


28

SOR to Registry API:SOR Person Role Updated / Deleted

PUT /sor_people/hrms/X12345/R98765

{

"givenName":"Patricia"

}

DELETE /sor_people/hrms/X12345/R98765


29

ID Match API

● Status: POC implementaton● Designed to work from within the IdMS or as a

standalone service called directly via SORs● As with SOR-Registry, SOR can only assert

knowledge of its own populaton● Goal is to obtain a Reference Identfer

● Could be a campus specifc identfer or internal just tothe match engine


30

ID Match Flow


31

ID Match Reference Identfer RequestPUT /v1/people/sis/971194843

{"sorAttributes":{"name":

{"type":"official",

"given":"Pat",

"family":"Lee"},

"dateOfBirth":"1983-03-18",

"identifiers":[

{"type":"national",

"identifier":"3B902AE12DF55196"}],

“telephoneNumbers”:[

{“type”:”mobile”,

“number”:”8185551234”}]}}


32

ID Match Responses200 OK

{

“referenceId”:”M225127891”

}

201 Created

{

“referenceId”:”M225127891”

}

202 Accepted

{

“matchRequest”:”1005”

}

300 Multiple Choices

{

"matchRequest”:”1009”,

“candidates”:[

{

(various candidates & attributes)

}

]

}


33

Additonal ID Match API Operatons

● Get Pending Matches● Forced Reconciliaton Request

● Follow up to a 300 Multple Choices response

● Get / Update Match Atributes● If an atribute (eg: name) changes afer a match, the

SOR or IdMS should update the Match Engine so futurematches resolve against the new value


34

Registry Extracton API

● Status: Early design● Read or Pull model to obtain data from the Registry

on demand● Notfcaton or Push model for (near) real tme

updates


35

Registry Extracton API


36

Current Status

● Various strawmen (strawmans?, strawpeople?)documents exist

● Some implementable, with caveats● Reference documentaton in progress

● Drafs targeted for October 2015


37

Design Maturity

ID Match

Core Schema

SOR-Registry

Authorizaton

Registry Extracton

Account Management

MoreMature


38

Resources

● htps://spaces.internet2.edu/display/cifer/API ● htps://github.com/ciferproject/cifer ● [email protected]● Periodic conference calls

● Biweekly Tuesday @ 1pm ET / 17:00 UTC (for now)● Especially interested in increased internatonal

partcipaton

https://spaces.internet2.edu/display/cifer/API

https://github.com/ciferproject/cifer

mailto:[email protected]


39

Acknowledgments

Many partcipants have contributed to the CIFER APIwork, but in partcular the following have been corecontributors:

● Keith Hazelton, University of Wisconsin-Madison● Chris Hyzer, University of Pennsylvania● Jim Fox, University of Washington● Benn Oshrin, Spherical Cow Group

Education

Open Apereo Cifer APIs