[reported on behalf of Jon Dunn at Indiana University]
COmanage enrollment flows provide a straightforward way for individuals to use a self-service Enrollment flow to connect an authenticated ORCID iD as an Identifier on the CO Person object that represents them in COmanage. This identifier can then be shared with other systems as configured within COmanage.
Given the ease of establishing this connection with the end-user, this enhancement request requests that an option be added so that the ORCID member API could be used as an alternative to the public API. With this enhancement, administrators would be able to configure the API scope permissions requested from the user (for example, permission to read privileged info from or write to the ORCID Record). These actions would allow for the exchange of information that would enable the use of these ORCID API permissions by downstream systems, or potentially by COmanage itself (though a plug-in).
Key features would include the following (likely through a plugin):
- The ability to add ORCID Member API credentials to COmanage
- The ability to configure COmanage to make calls to the ORCID API for scopes beyond the "Authenticate" scope that is currently operational, for example, scopes enabling read of and write to the end user's ORCID Record.
- The ability to store and make available for use encrypted copies of authentication tokens received by the ORCID API for the purpose of making subsequent ORCID API calls to use these tokens (most likely by downstream systems)
Today there is a Source plugin available for ORCID, the ORCID Source.
Code | Documentation
This plugin uses the public API to get an authenticated ORCID iD from the user and store it as an identifier (with type ORCID iD) in an Org Identity Source. From there you can attach it to a CO Person record (the conical representation of a person) by configuring a COmanage Pipeline. This process can be kicked off by an enrollment flow.
Details for configuring this setup can be found on this wiki page about the ORCID Source.
Configuration in COmanage
COmanage OAuth2 Server Configuration
|Setting||Current Config (uses read public config)||Future Config (uses explicit permissions)|
|Client ID||The Client ID provided by ORCID||The MEMBER Client ID provided by ORCID|
|Client Secret||The Client Secret provided by ORCID||The MEMBER Client Secret provided by ORCID|
|Access Token Grant Type||Client Credentials||Authorization Code|
|Scope||/read-public||Selected from the list of available scopes. It is HIGHLY recommended that the opened scope be included in this list so that an id_token is included (see below) and can be shared with other apps.|
This change would mean that the plugin would need to exchange the authorization code for the access token. Alternatively, the implicit fow could be used.
Storing information in COmanage
The ORCID iD would be stored as an ORCID iD identifier as it is today, but the id_token should also be stored so that it is available to downstream systems (though could only be used by applications that have access to the ORCID API client credentials. While the token technically can not be usedwithout these credentials, it may be advisable to store them securely, for example through encryption.
ORCID API calls
It is recommended that this feature be established using ORCID's Token Delegation Process. In this process, an ORCID end-user grants permission to the original client following the standard 3 step OAuth process with the openid scope, as well as any other scopes the client wants. When the authorization code is exchanged, in addition to the access token an id_token is returned This id_token is then securely passed to the second client. The second client exchanges the id_token for a new access token that they can use to read and update the record. The implicit flow can be used instead of OAuth if desired.
Downstream (provisioned) systems can use this id_token and their stored information for the API client ID and secret to exchange the id_token for an access token that has the permissions granted by the end-user in the original exchange. Access tokens generated via token delegation expire after one hour, however, id_tokens do not expire unless revoked and can be used to generate new access tokens. (if implicit flow is used, COmanage would only receive the /read-public scope, but tokens gerated by the second client from the id_token will have all scopes that the user has granted permission for.)