Integration point: Sign in using ORCID credentials

Enabling users to register or sign into your system using their ORCID credentials can save them time and effort; they don’t have to keep track of multiple usernames and passwords, and you immediately obtain an authenticated ORCID iD. At the same time, you can request permission to read or update their ORCID record.

ORCID sign-in is similar to social sign-in, for example sign-in using Google or Facebook, as offered on ORCID and other websites. ORCID sign-in is controlled only with a username and password, or with linked alternate sign-in credentials.  ORCID sign-in may not be appropriate if you require specific information such as an email address, affiliation, or role.

Some adopters of ORCID sign-in include eLife (during the submission and production process), the Lens, and Sciencematters.

ORCID sign-in consists of five steps:

  1. System requirements
  2. Incorporating an ORCID sign-in/registration button
  3. Get the user’s authenticated ORCID iD
  4. Linking ORCID and local accounts
  5. Displaying the linked ORCID iD in your system
  6. Recognizing an ORCID sign-in as a valid authentication for your system

System setup

Please be sure to check that your system meets the requirements below.

  • Your system must be able to accept and store ORCID iDs together with the user’s information.
  • If you are reading from or writing to ORCID records, your system must also be able to accept and store persistent access tokens together with the user’s account data. Even if you only intend to display iDs, we strongly suggest accepting and storing access tokens to indicate that the iD has been authenticated. We also strongly recommend that you store all of the token response, including refresh tokens, scopes, and token expiry, as these can be useful if access tokens are lost, if you want users to expire their access token from within your system, or if you upgrade your system to support new scopes.
  • Customized interaction messages:
    • Connection-success message: After the user successfully authorizes the connection with your system and signs in, a thank you message should be displayed along with their ORCID iD.
    • Connection-failure message: If the user denies the connection with your system and is returned to your site, you should give them the opportunity to sign in again; we highly recommend that you take this chance to explain more fully the reasons why you offer ORCID as a sign in option.
  • Log interactions: Your system should record both calls made to the ORCID API and responses received. This is necessary so our team can help if a problem develops later.
  • The first thing that users should see is a screen inviting them to sign into your system. Since you will be enabling users to sign into your system using alternate credentials, possibly in addition to those already used by your system, the sign-in options could be displayed as illustrated below.

Use an ORCID sign-in button

Provide a hyperlinked ORCID-branded button for signing in and authenticating ORCID iDs: Using the ORCID iD icon consistently helps ensure that users associate it with being asked to securely provide their iD, which in turn builds trust in ORCID as a reliable identifier.

Example button graphics and code

Configure the button’s link to request permissions to access the user’s ORCID record via the API: If you are only planning to collect and display ORCID iDs within your system then you need only /authenticate access to an ORCID record.

You can force users already signed into ORCID to be signed out to ensure that users are in control of that iD, as well as specify a display language and include a state parameter to identify the user in your system. Find out more at Customize OAuth.

If you are planning to add data to user’s ORCID records (member API only), then you should request /read-limited and /activities/update (research actities) and/or /person/update (biographical information).

The below example requests permission to authenticate the user’s ORCID iD using the three-legged OAuth process. Use your client’s ID and registered landing page -- you can also paste it directly in your browser for testing purposes.
   client_id=[Your client ID]&
   redirect_uri=[Your landing page]

Once the user has signed into their ORCID account and authorized (or denied) the connection to your system, they will be automatically redirected to your specified landing page. Note that if the user is already signed into ORCID and has already granted your system access, they will be automatically directed to your specified landing page.

Appended to the end of that link will be a six-digit authorization code and any state parameter you specified:

Authorization Code

At this point, your system’s user interface should display the user’s ORCID iD along with a helpful message—see Display below.

If the user denies your system access: ORCID returns the user to the specified landing page and appends an error message:

   https://[Your landing page]?error=access_denied&error_description=User%20denied%20access

Your system should read this and automatically display the connection-denied message. We strongly recommend that you explain more fully to the user why you are collecting ORCID iDs and requesting permission to access their record, and prompt them again to sign in and authorize the connection to your system.

Get the user’s authenticated ORCID iD

Your system will now need to exchange the code for an access token -- the second part of the three-legged OAuth authentication.

When the user is returned to your specified landing page, the six-digit authorization code will be appended to the end of the URL. In the system backend, immediately exchange the authorization code; the authorization code expires upon use.
  HEADER: accept:application/json
    client_id=[Your client ID]
    client_secret=[Your client secret]
    code=[Code from previous step]
    redirect_uri=[Your landing page]

ORCID will then return the researcher’s verified ORCID iD and an access token, along with the refresh token, scope(s), name on the ORCID record, and token expiry. A example response:

   "scope":"/authorize","name":"Sofia Garcia","orcid":"0000-0001-2345-6789"}

Store the ORCID iD and access token in your system in a safe and secure manner. Both items will be required to perform any action to their ORCID record: read, write, update. If you are only requesting /authorize access, access tokens can be stored to indicate that the iD has been authenticated, as well as to read public access data.

Use the ORCID iD and access token to read the user’s record and populate their profile in your system: Save users time by allowing them to quickly and easily transfer data from their ORCID records to your system. All you need to is to make a quick call to their record:

  Method: GET
  Content-type: application/vnd.orcid+xml or application/vnd.orcid+json
  Authorization type: Bearer
  Access token: [Stored access token]
  End point:[Stored ORCID iD]/record
  Example record XML: GitHub

You can also query the endpoints of the main sections of the record, /person and /activities, to obtain a summary of those sections of the ORCID record. For more on reading the ORCID record, see: Reading ORCID record XML (2.0).

Linking ORCID and local accounts

Now that you have the authenticated ORCID iD and access token, you can link the user’s ORCID account with their local account in your system.

Once the user returns to your site, check whether the returned iD already exists in your system. If so, then proceed to Recognize an ORCID sign-in. It not, prompt the user to do one of the following:

Tip: If you have read the user’s email address on their ORCID record, search for that email address and prompt the user to sign in if it is already in your system.

  • Link to an existing local account
  • Register a new local account

Linking to an existing local account: Request that the user sign into your system using their account credentials for your system. Upon successful sign-in, associate the two accounts by storing the ORCID iD and access token together with the linked local account.

Registering a new local account: Provide the user with your usual registration form and display the ORCID iD on the form to indicate that it has been successfully authenticated. You can save the user time by filling in data that you have read from their ORCID record.

Take it a step further:

  • You can also prompt the user to connect their ORCID iD from their profile or accounts setting page in your system! When the user later signs into your system using their ORCID iD, the accounts will already be linked. 

Display the linked ORCID iD in your system

Once the user has successfully signed into your system using ORCID sign-in, and linked their accounts, clearly display their iD within your system. Format the iD as a hyperlinked HTTPS URI and include the green iD icon, per our iD Display Guidelines.

ORCID iD icon

Provide an unlink option: We strongly recommend that you provide an option for users to unlink their ORCID iDs from their local accounts in your system and remove all data associated with their ORCID iD.

Recognize an ORCID sign-in

Once accounts are linked, your system will need to recognize whether a user with a linked account has signed in using ORCID Registry credentials.

To recognize whether an ORCID sign-in is a valid authentication:

  1. Obtain the ORCID iD using the authentication flow described above. If the iD matches one in your system, consider the associated account to be signed in.
  2. Check whether the user is signed into ORCID, where appropriate. Reinitiate a sign in request if required by your system’s security protocol.