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:

voPersonID: TEAMCO100005


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.

 

For example, suppose the passport server is passed the following (CILogon OP) OIDC sub value

http://cilogon.org/serverT/users/999999999

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:
https://spaces.at.internet2.edu/display/COmanage/COmanage+Registry+Technical+Manual

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.

https://github.com/umccr/gen3-doc


GA4GH Passports

aka: Researcher Passports - may require integration with a REMS system to extend functionality.

TBD


Beacon Service

TBD


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.

 

OIDC Administration

(Draft)

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/"


Future Roadmap

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.