Presenting OAuth

In order to provide the best experience for users, we strongly recommend that members follow the guidelines below for presenting ORCID within their systems.

  1. Use a button or link to connect users to ORCID via OAuth
  2. Include text describing ORCID and a link to the ORCID website
  3. Present the OAuth sign-in screen as a popup or modal window
  4. Provide an appropriate redirect page and close the OAuth window
  5. When OAuth is skipped

To see these guidelines in action, visit Try it Out! at the bottom of this page.

You may also want to customize the information presented on the OAuth screen, such as the displayed language, or pre-filling in user information. For more on this, see Customize the OAuth Sign-in Screen.


Use a button or link to connect users to ORCID via OAuth

  • Please do not prompt users to type in their ORCID identifier!
  • Prompt users to sign into ORCID via OAuth - this ensures that you receive the correct ORCID iD from the user and prevents entry errors
  • Link directly to the OAuth form either within the same window or in a new window -- iframes and embedded forms are not supported
  • Include ORCID branding in your button/link

Examples

Create or connect your ORCID iD

Get the code for these examples!

Where should the button/link direct to?

The URL included in your button/link should contain a call that prompts users to sign into their ORCID account via OAuth in order to grant your application permission to access their ORCID record. The link should go to the same window or a new window/tab. (Note: There is a frame buster, so iframes are not supported.)

For information on constructing this URL, see tokens using three-legged OAuth. Your URL will vary, but will look similar to:

https://orcid.org/oauth/authorize?client_id=APP-NPXKK6HFN6TJ4YYI&response_type=code&scope=/read-limited&redirect_uri=https%3A%2F%2Fdevelopers.google.com%2Foauthplayground

This URL can also be adapted to pre-fill the sign in/registration form with user information, to specify a language setting, or to show the sign in form (instead of the registration form). See Customize the OAuth Sign-in Screen for more information.

For more examples showing URLs for specific actions, see:

For information about OAuth, see:


Include text describing ORCID and a link to the ORCID website

Inform your users about what ORCID is and provide them with a source for more information. Please use the text below when describing ORCID.

Examples

ORCID provides a persistent digital identifier that distinguishes you from other researchers. Learn more at orcid.org

 

ORCID is an independent non-profit effort to provide an open registry of unique researcher identifiers and open services to link research activities and organizations to these identifiers. Learn more at orcid.org .

 


  • Ensure that the popup is triggered by user action to avoid popup blocker issues (ex: use the JavaScript onclick() event to trigger the window.open() method)
  • Ideal dimensions for the popup window are 500px wide by 600px high
  • Show the page URL in the address bar of the popup window
  • Include scroll bars for the popup window

 

 

 

 

 

 


Provide an appropriate redirect page and close the OAuth window

  • Your redirect URI call will be displayed inside the popup window - make sure that your content and formatting are appropriate for this window
  • After the user completes the process, close the OAuth window automatically or provide a button to close it

Example


Note: The image above is for demonstration purposes only - ORCID does not provide a redirect page. You will need to create your own redirect page in order to send users back to your site.


Try it out!

Click the button below to run the code (this is just a demo - no information from your ORCID record will be transferred).

Get the code for this button example!

 

If an active access token already exists with the same scopes for and the user is signed into their ORCID record, they will not be prompted to grant authorization again. Instead they will be taken directly to the redirect URI. If an authorization code is exchanged for a new access token when an access token with the same scopes already exists, a new access token will be issued. Both the new and old access tokens will continue to work until they expire.

In practice this workflow goes as follows: The researcher clicks the ‘link to ORCID’ button on your site for the first time, they are taken the ORCID website where they sign in and grant you access to their record. They are then returned to the redirect URI and you exchange the authorization code for an access token.  If the researcher then clicks the 'link to ORCID' button again. Instead of seeing the authorize page they are immediately taken to the redirect URI. A new authorization code is issued, if you exchange this authorization code you will be sent a new access token. If you want to require a user to grant authorization every time they connect, use the force logout process..