Last updated 23 August 2022.
Integrate a Service as an OIDC Relying Party with CILogon
For example a GA4GH Passport Server or a REMS system.
Updates to the OIDC Plugin
4 July 2022
This new feature for the OIDC Plugin is currently only available on the BioCommons instance. It will become available on other instances in the coming weeks (tbd).
A number of new features/details are available for configuring the OIDC Plugin:
- A contact email address is now required for the client, with a reasonable default algorithm
- Public clients (OpenID scope only) are now available
- Finer grained control over how claims are populated from LDAP
Additionally, there is now the concept of a Named Configuration, which is essentially a template that can be applied to an OIDC client. When selecting a Named Configuration, only a call back URI(s) is necessary. The COs can have as many Named Configurations as necessary. When creating a new OIDC client, hovering over the name of the template will reveal a full description to aid in selecting the right template for a service.
Only certain privileged users (essentially platform admins) can define a Named Configuration. When creating workflows, consult with the CILogon team so we understand the requirements. The CILogon team will create the Named Configuration and make it available as a choice when managing OIDC clients.
If there are no Named Configurations for a CO, the option is not visible when adding/editing an OIDC client.
Common CILogon integration patterns
The CILogon developers suggest the following integration patterns: https://docs.google.com/document/d/1IkXMdILtmDk_btwFrAPF8NtMDofDTkMsEDw3ioZifVs
When integrating with the CILogon TEST environment, select the most appropriate endpoint from the following for the method chosen: https://test.cilogon.org/ https://test.cilogon.org/oauth2/userinfo https://test.cilogon.org/.well-known/openid-configuration
Approach One - Using OIDC Claims
For example where GA4GH Passport service is integrated, the passport server (or another service) is an OIDC client (RP) to the CILogon OP. Users go through a standard OIDC flow and the OIDC client receives claims from the CILogon OP. The claims can include group membership (relatively soon those "claims" will involve a GA4GH passport/visa - that work is in progress).
The OIDC client can only be created and managed by admins/operators of a Collaborative Organisation (CO) or a group delegated the capability. The AAF will manage the group of operators for a CO and will request activation of the OA4MP admin functionality for creating and managing OIDC clients (within CILogon service) on the operators behalf when requested.
OIDC clients can be configured to assert group membership as a claim. For example: create a new OIDC client and configured it to assert these attributes (in addition to standard claims):
is_member_of: a list of group memberships
uid: unique, opaque, never-changing user ID
During the flow the values for claims are retrieved from the CILogon LDAP directory. An example typical LDAP record would have the following attributes:
dn: voPersonID=TEAMCO100005,ou=people,o=Team,o=CO,dc=Community,dc=org,dc=au sn: Smith cn: John objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson objectClass: eduMember objectClass: voPerson givenName: John Smith mail: John.Smith@example.org uid: http://cilogon.org/serverT/users/999999999 isMemberOf: CO:members:all isMemberOf: CO:members:active isMemberOf: Test Data Set Authorization voPersonApplicationUID;app-gen3: john.smith3 voPersonID: TEAMCO100005
As configured in this example, the uid and is_member_of claim would include these values:
http://cilogon.org/serverT/users/999999999 CO:members:all CO:members:active TEST Data Set Authorization
The above LDAP record is a reflection of the information managed by COmanage, the collaboration/group management platform with which CILogon is integrated. The group membership "TEST Data Set Authorization" exists in COmanage and the LDAP service. If John was made a group owner, he can manage that group’s membership (note: only a group owner or CO admin can manage a group's memberships).
The uid (attribute) claim for John could have value 'http://cilogon.org/serverT/users/999999999'. The relationship between groups and claims is configurable in terms of which values are placed into which claims.
The voPerson LDAP schema is relatively new, but is community developed and supported. Read more about voPerson at https://voperson.org/..
The COmanage Registry is using version "draft-2.0.0", so when looking up the details in GitHub be sure to switch to the "draft-2.0.0" branch.
For a OIDC client configuration, add a LDAP to Claim Mapping that maps:
voPersonID TO sub
and the CILogon OP will assert the sub claim (using the above example) with the following value:
Approach Two - Querying The CILogon LDAP Service
Another integration possibility is that the passport server obtains a unique identifier (say some other service authenticates the user against CILogon and passes an identifier to the passport server (or application).
Then the passport server (or application) can query the LDAP directory directly.
The passport server could perform the following LDAP search
ldapsearch \ -LLL \ -H ldaps://ldap-test.cilogon.org \ -D 'uid=readonly_user,ou=system,o=Team,o=CO,dc=Community,dc=org,dc=au' \ -x \ -w 'XXXXXXXX' \ -b 'ou=people,o=Team,o=CO,dc=Community,dc=org,dc=au' \ '(uid=http://cilogon.org/serverT/users/999999999'
to find the record and obtain all the group memberships in the isMemberOf attribute (as well as any other information in the LDAP record returned).
The passport server (or application) could search on another attribute like voPersonID or even mail attribute, however it is NOT recommended to use email as an identifier since (as is well known) email addresses make lousy long-lived and stable identifiers. The AAF will help organisations only use email for display purposes and the actual sending of email. However, sometimes organisations decide they just have to use email as a primary identifier and must live with the consequences of an unstable primary identifier.
Approach Three - Calling The Rest API
Registry v4.0.0 introduces the Core API, a collection of higher level APIs that provide transaction-oriented operations, rather than the lower level, model-oriented REST API v1. The Core API is implemented as a standard Plugin that is enabled by default. https://spaces.at.internet2.edu/display/COmanage/Core+API
The COmanage REST API (https://spaces.at.internet2.edu/display/COmanage/REST+API+v1) is quite fine-grained and most developers find LDAP searches easier. If you want to use the REST API, an example of the curl command line calls to demonstrate how to start with an identifier and wind up with group memberships can be made available.
The documentation itself is pretty good, but unless the COmanage data model is well understood, interacting with the API can be daunting to use at first. If you want to go down this path, make a request and you will be sent those example curl commands.
COmanage also supports a number of "out of the box" Provisioning plugins, the list is available here:
Search for "Provisioning From Registry" on that page and you will see 14 or so existing plugins.
The CO Group API is documented here: https://spaces.at.internet2.edu/display/COmanage/CoGroup+API
The CO Group Member API is documented here: https://spaces.at.internet2.edu/display/COmanage/CoGroupMember+API
Gen3 integration with CILogon
UMCCR outlines their integration with the GEN3 platform.
aka: Researcher Passports - may require integration with a REMS system to extend functionality.
Organisations have a lot of flexibility with how a CO could leverage CILogon/COmanage/LDAP. If you have ideas or questions just let us know.
Platform > Oa4mp Admin Clients > Add a New Oa4mp Admin Client
The trust model is that each vetted CO receives its own admin client. The CO administrators (default) for the CO (or other delegated CoGroup in a CO) can then create and manage OIDC clients using the admin client (this happens transparently for the CO admins or other delegated group).
In all situations, it is important to vet any user given admin permissions at the CMP or CO level, to ensure they represent valid Research and Scholarship (R&S) organisations, since those administrators will be able to create OIDC clients and use CILogon authentication flows (and hence eduGAIN IdPs) without any further approval.
In granting CO administrator privileges, think carefully about the lifecycle for that privilege and set a group membership Valid Through date or use another appropriate control so that the user is only able to create and manage OIDC clients for the appropriate amount of time.
Once you are ready to proceed, you can request the OA4MP admin client from the AAF (or read this AAF Support article - draft)
Example of an OIDC Client Configuration
OIDC callback URLs typically end with "/user/login/cilogon/login/"
Updates to the COmanage Registry plugin that manages OIDC clients and allows for more sophisticated configurations are planned, currently (late 2022). Any editing of the OIDC client configuration by hand renders it no longer possible to use COmanage to edit the configuration item.
At the moment, changes to these items require submission of a request to the CILogon support team with the clientID and the required change.