COmanage Registry includes an Organizational Source plugin for ORCID. Since Registry version 4.4.0, this plugin may be used with either the member or public ORCID API, enabling COmanage Registry enrollment flows to request user access permissions to interact with their ORCID Record via the ORCID API.

This recipe describes how to integrate COmanage Registry with ORCID to collect ORCID iDs and API tokens for reading and writing to ORCID Records.

Recipe Ingredients

  • This recipe requires COmanage Registry version 4.4.0 or later.
  • Assumes the presence of an ORCID API client (member or public).
Recipe Steps
  1. Install Plugins
    Install the ORCID Source Org Identity Source Plugin

  2. Configure Source and Server
    1. Establish an ORCID API Client
    2. Configure an ORCID OAuth 2.0 Server
    3. Configure the ORCID Source

  3. Enable user feature
    Enable users to connect their ORCID iD (and provide read/write permissions) via an enrollment flow

  4.  Obtain ORCID Tokens via Registry API
    Get stored ORCID Access and Refresh Tokens via the Registry API

  5.  REF: Use the ORCID access tokens


Recipe Steps


1. Install Plugins

COmanage Registry supports several types of plugins in order to easily customize and extend Registry functionality. Plugins may be one of three types, each of which has a different process for being installed and enabled: Supported Core Plugins, Supported Non-core Plugins, and External Plugins.

Step overview

For this recipe, you will need to install and enable the following plugins. Since these plugins are Core plugins, they are likely already available for your use.


Plugins needed for this recipe

NAMETYPEPLUGIN CLASSDESCRIPTION
ORCID SourceCOREOrganizational Identity SourcePlugin designed to integrate with the ORCID API to create organizational identities and securely link an ORCID ID to an existing CO person record.
RESOURCES for step 1. Install Plugins

See the following resources for details to complete this recipe step:

USE GUIDES / OVERVIEWS

TECHNICAL GUIDES


2. Configure Org Identity Source and Server

All plugins have basic settings related to their Class. In addition, some plugins have plugin-specific settings to configure the specifics of the plugin.

Some connections also require a configuration of a Server to connect to an external system.

2.a Establish an ORCID API Client

The COmanage Registry configuration interacts with an API Client Application that you have established at ORCID. In Registry versions before v4.4.0, only Public ORCID API credentials in its Production environment are supported. In Registry versions v4.4.0 and beyond, both Public and Member API clients are supported in both ORCID's Production and Sandbox environments.

Using the resources on the left, register COmanage Registry as an ORCID API Client Application. You will add two Redirect URIs that will be defined by Registry during the course of this configuration, one from the ORCID Server configuration, and one from the ORCID Server configuration.

A note about ORCID API Credentials

A common question is if one should register COmanage Registry as a NEW ORCID Client Application, or if the Registry redirect URIs should be added to an existing Client Application. These decision very much depends on the policies that your organization establishes for sharing information and permissions between applications and the expectations of your users.

User permissions are granted to a single API Client: OAuth 2.0 interactions between ORCID iD Holders and your registered ORCID API Client Application. When using the ORCID Member API, these interactions may result in permissions to read limited-access information from and write to the iD Holder's ORCID Record. As with all Oauth 2.0 permissions, these are granted to a specific API Client.

If you are using an API Client across multiple systems, it will be important to inform the user of all of the systems that they are granting permissions to. (You describe this in the description provided for your API Client, which is displayed to the user.) If these systems shouldn't be sharing the user's permissions to access their data, it is a sign that separate API Clients should be used.

2.b Configure an ORCID OAuth 2.0 Server

ORCID uses OAuth 2.0 to authenticate users and obtain permissions for Application Clients to interact with their ORCID Records. COmanage Registry establishes this connection through the configuration of an OAuth2 Server.


Server Basic Settings

FIELDDESCRIPTION
DescriptionUse a descriptive name that users will see when interacting with the Server. It may be helpful to include details about whether the public or member API is used and whether it is connected to the Production or Sandbox ORCID environment.
StatusSelect [ Active ]
TypeSelect [ OAuth2 ]

Server-specific Settings: [ Outh2 ]

FIELDDESCRIPTION
Redirect URIThe Redirect URI is defined by COmanage Registry. You will need to include this redirect URI in your configuration of your ORCID API Client.
Server URL *
Proxy

(v4.4.0 and later) Your proxy configuration in the form of [host:port], if needed

Client ID *The Client ID provided by ORCID
Client Secret *The Client Secret provided by ORCID
Access Token Grant Type *
  • If your credentials are registered with ORCID's Public API, select [ Client Credentials ]
  • (v4.4.0 and later) If your credentials are registered with ORCID's Member API, select [ Authorization Code ]
Scope
  • If your credentials are registered with ORCID's Public API, type '/read-public'
  • (v4.4.0 and later) If your credentials are registered with ORCID's Member API, type a list of your desired scope (each separated by a space) that represent the permissions that you want to obtain from users.

You may test your configuration by clicking the 'Obtain New Token' button, and authenticate at ORCID if necessary.



2.c Configure the ORCID Source

The ORCID Source plugin only uses basic settings. Sources are set at the CO level. NOTE: More than one ORCID Source may be defined per ORCID Server, if desired.

Organization Identity Source Basic Settings

FIELDDESCRIPTION
Description *Use a descriptive name that users will see when interacting with the Source. It may be helpful to include details about whether the public or member API is used and whether it is connected to the Production or Sandbox ORCID environment.
Plugin *Select [ ORCIDSource ]
Status * Select [ Active ]
Sync Mode * Select [ Manual ]
Sync on LoginCheck this checkbox

Plugin-specific Settings: [ ORCIDSource ]

Note: Some of these fields may be available only in Registry v4.4.0 and later.

FIELDDESCRIPTION
Additional ORCID Redirect URIAn additional Redirect URI is defined by COmanage Registry. You ALSO will need to include this redirect URI in your configuration of your ORCID API Client.
Server * Select the server that you defined in the previous step
API type * Select the type of API Client that you are using for ORCID: Public or Member ('Member" is available in v4.4.0 and later)
API tier * Select the ORCID environment that you are using: Production or Sandbox ('Sandbox" is available in v4.4.0 and later)
Inherit ScopeCheck this checkbox if you want to use the scopes that you defined in the ORCID Server. You may use different scopes for this configuration by unchecking this box and defining the desired scope in the next field.
Scope

(v4.4.0 and later) If your credentials are registered with ORCID's Member API, type a list of your desired scope (each separated by a space) that represent the permissions that you want to obtain from users.

RESOURCES for step 2. Configure Source and Server

See the following resources for details to complete this recipe step:

USE GUIDES / OVERVIEWS

TECHNICAL GUIDES


ORCID API Resources

The following resources may be helpful as you interact with the ORCID API, including the set up of API Clients:

  • ORCID Membership - Information about the benefits and fees for becoming an ORCID Member
  • Hands on with the ORCID API - Tutorial for using the ORCID API. Tutorial includes information about using their test Sandbox environment, including how to obtain test membership credentials. 
  • ORCID API Technical Documentation - Full technical documentation for using the ORCID API including how to request Member and Public Credentials

3. Enable user feature

By adding an ORCID Source, you have enabled the possibility of linking ORCID iDs (and access permissions) for any CO Person record. You may enable users to link their ORCID iD to their CO Person record in Registry via an enrollment flow.

Step overview

For this recipe, you will create an Account Linking Enrollment Flow to collect authenticated ORCID iDs (and access permissions if configured with the ORCID Member API).

  1. Create an Account Linking Enrollment Flow
    In the Enrollment Flows Configuration area of Registry, duplicate the Account Linking (template); click the "Add/Restore Default Templates, if needed.

  2. Configure the Duplicated Flow
    Edit duplicated Account linking, updating the following fields:

    FieldDescription
    NameUpdate the name to something more descriptive to its use, for example, "Link ORCID Account"
    StatusChange the status from "Template" to "Active"
    Enable My Identity ShortcutIf applicable, check this checkbox to allow signed-in users to initiate this Flow by clicking on the menu displayed in Registry when the user clicks on their name in the upper right corner when signed in.
    Email Confirmation ModeNone is needed, as the person is already signed in. Change this value to "None"
  3. Remove Enrollment Attributes
    In this account linking scenario, an individual is already signed into COmanage. No information needs to be collected from the user to start the enrollment petition. Click the [ Edit Enrollment Attributes ] link in the Enrollment Flow Edit form, and remove any present attributes so that none are collected.

  4. Attach the configured ORCID Source Organizational Identity Source
    Attach the ORCID Source that you configured in the previous step to the Enrollment Flow.  

    Click the [ Attach Org Identity Sources ] link in the Enrollment Flow Edit form, and add your configured Source by clicking the [ Add Enrollment Source ] link above the table on the right. 

    FieldDescription
    Organizational Identity Source *Select the Organizational Identity Source that you configured for ORCID in the previous step. (Note, if you do not se the source, check to make sure that your configured source has a status of "Active")
    Org Identity Mode *Select [ Authenticate ] to have the user authenticate to ORCID using the ORCID Source configuration.
    Order[not needed]
  5. Test the enrollment flow
    Ensure that an ORCID iD is added to a CO Person record.
RESOURCES for step 3. Enable user feature

See the following resources for details to complete this recipe step:

USE GUIDES / OVERVIEWS

TECHNICAL GUIDES


4. Obtain stored tokens using the Registry API

(v4.4.0 and later) COmanage Registry stores collected ORCID access tokens that are obtained during the OAuth 2.0 flow. These tokens can be retrieved via the Registry REST API.

Step overview

In Registry v4.4.0, a new API endpoint was added to the Registry REST API that enables one to access access and refresh tokens that are collected and stored in the use of an ORCID Source configuration with the Member API.

  1. Create an API User
    If needed, create an API User that will access the REST API v1. API Users can be established in your CO Configurations.

  2. Request the User Token
    Using the COmanage REST API v1, use the ORCID Token API endpoint to obtain the token  information stored in the COmanage database. You will include the CO Identifier for the CO where the enrollment flow was configured and the ORCID iD associated with the CO Person of interest.

    curl -k -u user:password -X GET "https://comanage.example.com/registry/orcid_source/orcid_tokens/token.json?orcid=<ORCID identifier>&coid=<id>"
  3. Review the response
    The response from the API call will return the following information. See the ORCID Token Schema page for a description of the API response.
    • ORCID - the ORCID iD used in the API call
    • Access Token - the access token received during ORCID OAuth flow
    • Refresh Token - a token received during the ORCID permission flow that can be exchanged for a new access token. Also see the ORCID documentation.
    • Scopes - the ORCID API scopes associated with the access token (permissions granted by the user during the ORCID OAuth flow)
    • id_token - a JSON web token (JWT) that is returned during an (ORCID permission flow). Also see the ORCID documentation.
RESOURCES for step 4. Obtain stored tokens

See the following resources for details to complete this recipe step:

USE GUIDES / OVERVIEWS

  • Use Guide: Using the Registry API

TECHNICAL GUIDES


5. Use the ORCID access tokens (REFERENCE ONLY)

FOR REFERENCE ONLY

These instructions in this section are NOT intended to provide instruction or guidance on the use of the ORCID API.

At all times, you should consult your security guidelines and seek the advice of experts when using the ORCID API and information obtained through its use, particularly when using the ORCID Production environment. The resources in this section are designed ONLY to provide links to what might be helpful references.

Test your configuration by checking that the information stored for the ORCID Token behaves as expected.

  1. Check Scopes
    For each of the scopes that you established in your ORCID Server and Source, try an ORCID API call to ensure that the stored access tokens work as expected. See the ORCID API Tutorials for more information about reading from and writing to ORCID Records.

  2. Check Refresh Token
    Refresh tokens enable you to get an updated access token. Try to refresh the access token to ensure that this is possible with what is stored. See the ORCID Refresh tokens tutorial for more information about exchanging refresh tokens for a new access token.

    Pro Tip

    Since the Access Token stored in the COmanage database will not be updated when you use the Refresh Token, the stored access token may be unreliable for use. You may address this by using the refresh token to get and use a fresh access token each time that you want to make an API call to read or write information in an ORCID Record.

RESOURCES for step 5. Use the ORCID access tokens

ORCID API Resources

The following resources may be helpful as you interact with the ORCID API, including the set up of API Clients:

  • ORCID Membership - Information about the benefits and fees for becoming an ORCID Member
  • Hands on with the ORCID API - Tutorial for using the ORCID API. Tutorial includes information about using their test Sandbox environment, including how to obtain test membership credentials. 
  • ORCID API Technical Documentation - Full technical documentation for using the ORCID API including how to request Member and Public Credentials
  • Refresh tokens - Tutorial on exchanging refresh tokens for a new access token.
  • ORCID API Tutorials - tutorials for using the ORCID API.
  • ORCID API Calls - list of possible ORCID API calls and the scopes required for each


Recipe Variations and Complements

Managing Access Tokens

Use ORCID Refresh Tokens

Since the Access Token stored in the COmanage database will not be updated when you use the Refresh Token, the stored access token may be unreliable for use. You may address this by using the refresh token to get and use a fresh access token each time that you want to make an API call to read or write information in an ORCID Record.

About Revoked Access Tokens

ORCID users may revoke access tokens (and related permissions) at any time through the ORCID platform. This action will affect your ability to use an Access Token stored in the COmanage database. (Using a revoked access token will generate an error. See the ORCID API Errors resource for more information.) Note that the token information stored in the COmanage database will not be updated if a user revokes permissions.

Known Limitations

An enrollment flow for linking an ORCID ID and permissions will only work once for each user to collect ORCID API tokens and permissions. Although the ORCID API allows for one to request multiple access tokens for a user (which can contain different permissions), the COmanage Registry ORCID plugin will only allow the first request to go through. 

Similarly,  COmanage Registry will not know if a user revokes a token, so the enrollment flow currently may not be used to re-establish permissions that have been revoked by the user because the previous token is stored in the COmanage Registry database.