Customize the OAuth sign-in screen

You can save your researchers time and effort by filling in information that your system already has stored about them, setting their display language, and signing them out of any active sessions to ensure that they have signed into the correct ORCID account. 

The ORCID APIs offers several options for customizing the user experience:

For information on how to present the OAuth screen see Presenting OAuth.

Pre-fill the registration/sign-in form

ORCID offers the option for members to pre-fill the OAuth registration/sign-in form as part of an API interaction using the following parameters on the https://orcid.org/oauth/authorize URL.

Any or all of the parameters can be used. When the email parameter is used, if the email address is already associated with a record in the ORCID Registry it fills the sign-in email or iD field, if the email address is not already in the ORCID Registry it fills the email field in the registration form. The user will always have the option to switch between the sign-in and registration forms regardless of what you have pre-filled.

Parameter Field Notes
given_names First name

The first name field will be filled in on the registration form if a specified email address or ORCID iD does not match that of an active ORCID record. 

family_names Last name

The last name field will be filled in on the registration form if the specified email address or ORCID iD does not match that of an active ORCID record. 

email Email

The email/ORCID iD field will be filled in on the sign-in form if the specified email address is found in our system and no valid ORCID iD is specified.

The email field will be filled in on the registration form if the specified email address is found in our system and no valid ORCID iD is specified.

The email address should be URL encoded, including changing "@" to "%40".

If you know the user's ORCID iD and email address, we suggest only providing the ORCID iD in the orcid parameter.

orcid ORCID iD

The email/ORCID iD field will be filled in on the sign-in form if the specified ORCID iD is found in our system.

The registration form will otherwise be displayed if the specified ORCID iD is not found in our system.

The ORCID iD must be in the 16-digit format of the iD URI.

An example URL with these parameters is

https://sandbox.orcid.org/oauth/authorize?client_id=APP-NPXKK6HFN6TJ4YYI
&response_type=code
&scope=/authenticate
&redirect_uri=https%3A%2F%2Fdevelopers.google.com%2Foauthplayground
&family_names=Finn&given_names=Huckleberry&email=huckle%40mailinator.com

Set the display language

ORCID offers the option to specify the display language of the OAuth registration/sign-in form as part of an API interaction using the lang parameter on the https://orcid.org/oauth/authorize URL. This will also set the user's language display preference. (They can change this on their own at any point.)

The following language settings are available:

Language Code
čeština (Czeck) cs
English  en
Español (Spanish) es
Français (French) fr
Italiano (Italian) it
日本語 (Japanese) ja
한국어 (Korean) ko
Português (Portuguese) pt
Русский (Russian) ru
简体中文 (simpified Chinese) zh_CN
繁體中文 (traditional Chinese) zh_TW

An example with the language setting parameter is:

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

The language setting can be combined with the form pre-fill parameters listed above, as in this example:

https://sandbox.orcid.org/oauth/authorize?client_id=APP-NPXKK6HFN6TJ4YYI
&response_type=code
&scope=/authenticate
&redirect_uri=https%3A%2F%2Fdevelopers.google.com%2Foauthplayground
&family_names=Finn&given_names=Huckleberry&email=huck%40mailinator.com
&lang=es 

 

Display the sign-in or registration form 

Currently the ORCID OAuth screen presents the registration form by default and provides a link to switch to the sign-form. In the near future this behavior will be updated so the sign-in form is presented by default and the user can choose to switch to the registration form. Regardless of the default behavior, the form displayed can be set by adding the parameter "&show_login=true" to display the sign-in form or "&show_login=false" to display the registration form. Note that if an email address or ORCID iD are supplied in the URL, the form shown will be determined by those parameters and the &show_login parameter will be ignored.

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

 

Identify the researcher by a custom parameter

A state parameter can be included with the authorize URL in order to identify the user, such as a unique sequence of numbers that translates to the user's internal identifier within your system. The parameter does not affect the user’s experience, but it will be returned with the authorization code and can be used to identify the user or session. The state parameter is also returned if the user denies access.

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

 

Force sign-out

If you are concerned with multiple users being on the same machine and not logging out between sessions, you can force a sign out before starting the OAuth process. To force a signout, send the user to https://orcid.org/userStatus.json?logUserOut=true&callback=%22exampleCallBack%22

A working example is at http://orcid.github.io/test/log-user-out-jsonp.html (project in Github)

The user is also signed out if they visit the sign out page at https://orcid.org/signout.

 

Skipping authorization

If an active access token already exists with the same scopes that your OAuth authorization URL requests, 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 you want to require a user to grant authorization every time they connect, use the force sign-out process described above.