README.md

//: # (This document was created for the i2 TechEx Workshop on 2016.09.25 in Miami, Fl. It was updated on 2017.05.08 to support v2.0 of the ORCID API schema.)

i2-workshop-2016

Internet 2 Tech Exchange, Sept 2016

Hands on with the ORCID API:
Getting Authenticated ORCID iDs & Permissions Through Your IdP

see the full agenda

In February 2016, ORCID enabled IdP SSO for all eduGAIN member institutions, allowing the first direct connection between the systems. More recently, ORCID introduced a process that enables IdPs to request authenticated ORCID iDs and user permissions to access their ORCID record, using a process that requires little programming or custom code for institutions. In this hands-on tutorial each participant will set up such a connection in the ORCID test sandbox site (https://sandbox.orcid.org/signin).

##Workshop Agenda (4 hrs) ###1. PRESENTATION: WHAT IS ORCID? (30 min)

Learn about ORCID and ORCID iDs and how they work. Understand how organizations are using the ORCID registry to collect and display ORCID iDs, and connect and sync information between ORCID records and their own system.

###2. ACTIVITY: EXPLORE THE ORCID REGISTRY (20 min)

Set up an ORCID iD in our test environment, and explore signing in with your IdP. Understand ORCID’s provenance model and its implications. Learn about the components of an ORCID record, how they get populated, and how they get used.

###3. PRESENTATION: ABOUT THE ORCID APIs (30 min)

Discover ORCID API types and features, and understand ORCID’s test environment and the technologies that ORCID uses.

###4. ACTIVITY: OAUTH BASICS (30 min)

ORCID’s API uses OAuth 2.0 as its protocol for a system client to obtain user permission to access the information stored in their ORCID record. In this section you will obtain system client credentials, and execute basic commands to request permission using a basic OAuth 2.0 3-legged flow. (Don’t know what that is? don’t worry! It will be covered in the session.)

###5. PRESENTATION: THE CROSS-LINK BREAKDOWN (15 min)

Breakdown of the cross-link functionality.

###6. PRESENTATION: API CREDENTIAL SETUP (30 min)

Set up ORCID Member API credentials to enable IdP cross linking. We will try it out, using Google OAuth playground to simulate the IdP website.

###7. ACTIVITY: THE USER EXPERIENCE (30 min)

The technical connection is only part of the overall solution. What should you display to users when they authorize your system to connect with their ORCID records? What you should tell them if they deny your request? Using an ORCID template as a starting point, workshop participants will work together to craft messages and customize templates that will resonate with their audiences.

###8. ACTIVITY: POST AN AFFILIATION TO YOUR UNIVERSITY (50 min)

Format data about the person’s relationship to your institution and post it to their ORCID record. Update the data that you’ve already posted to simulate updating data when an affiliation relationship changes.

###9. REFERENCE MATERIALS

--

#1. WHAT IS ORCID? (30 min) PRESENTATION

Presented as a power point presentation

-top-

#2. EXPLORE THE ORCID REGISTRY (20 min) ACTIVITY

2.1 Create an ORCID iD

In order to try out API calls, such as a reading a record and adding information to it, you will also need to create a test ORCID record. This can be done through the user interface, much like in the live ORCID registry.

1. Open a web browser and navigate to https://sandbox.orcid.org/signin
    
2. Click Register for an ORCID iD.
    
3. Complete the form with a name, email, and password. You will need to remember this information for future steps.

IMPORTANT! Don’t use a real email address! Instead, make up an address ending in @mailinator.com (use any prefix, e.g. sgarcia@mailinator.com).

4. Choose the green anyone visibility setting so you'll be able to see any new items added on your public record.
    
5. Click the I consent… checkbox and click Register.
    
6. After completing the registration process, you will be taken to your new testing ORCID record. Make note of the 16-digit ORCID iD for this record – you will need this in order to make API calls later during the workshop.
   
    

-top-

2.2 Explore the ORCID record

In this section we will learn about the parts of an ORCID record, and explore ORCID's provenance model.

1. Using the interface, add a sentence or two to serve as the biography for your test record. The biography section is located at the top of the right column, and the edit button is the pencil icon in the upper right corner of this section, next to the visibility selector.
    
2. In the Employment section, click Add employment > Add manually to add employment information.
    
3. After saving your employment information, notice the information on the bottom of the "card" you just created. There is a Source field (that matches your name because you added this information) and the date that you created this addition to your record. This provenance information is recorded for all information added to an ORCID record.
    
4. In the main menu at the top of the screen, click on the Account settings link to display your account preferences. Notice each section to see what iD holders can control with their ORCID accounts.
    
5. In the main menu at the top of the screen, click on the Developer tools link. In this section a user may obtain credentials to access the public API. Note that this API is different from the member API that we will be discussing today.

-top-

2.3 Connect your new iD with your IdP

Since there are over 2.5 million ORCID iDs, many people already have an ORCID iD when they link to their IdP. To experience this process, we will sign out of your test record and start from the prospective of someone who has an iD, and notices that they can sign in with IdP credentials.

1. Sign out of the ORCID record you just created by clicking the Sign out button in the upper right corner. Alternatively, you can navigate to the URL: https://sandbox.orcid.org/signout.
    
2. On the Sign in page (https://sandbox.orcid.org/signin), choose Sign in using your Institutional Account to see the list of supported eduGAIN institutions.
    
3. Enter your organization's name in the box, or choose to pick it from the list. If you do not have credentials at an eduGAIN-included institution, you may use United ID for this example. (you will need 2-factor authentication to use United ID.)
    
4. After signing into your institution, you will be asked to finish linking the accounts by providing your ORICD sign in credentials. Type in the email address / ORCID iD and Password that you created in the previous step. Click Sign into ORCID to finish linking your accounts.
    
5. On the my-orcid page that appears, notice an orange alert box confirming that the accounts are linked, and suggesting that you connect to the university's account. This is an example, of the cross linking that we will be exploring further today. We will ignore this message for now.

-top-

#3. ABOUT THE ORCID APIs (30 min) PRESENTATION

3.1 ORCID API types & features

ORCID offers two APIs (Application Programming Interfaces) that allow your systems to connect to the ORCID registry, including reading from and writing to ORCID records. Some API functions are freely available to anyone; others are available to organizations that financially support ORCID with an annual membership subscription.

API Version	Access	Features
Public API	Freely available to anyone	Authenticate: Obtain a user’s authenticated ORCID iD Read (Public): Search/retrieve public data Create: Create new ORCID records on demand
Member API	Available to organizations that support ORCID with an annual membership subscription Sandbox Member API freely available to all for testing	Read (Limited): Search/retrieve limited-access data Add: Post new items to a record (affiliations, works, etc.) Update: Edit or delete items you previously added Register 1 API application
Premium Member API	Available to organizations that support ORCID with an annual membership subscription Premium Sandbox Member API freely available to all for testing	Webhook notifications: Receive a notice every time a user's ORCID record is updated Register 5 API applications

-top-

3.2 Sandbox test environment

In addition to the production Registry and APIs, ORCID also offers a testing environment, the ORCID Sandbox, which we will be using for this boot camp. The Sandbox is open to all users and provides a place to develop and test applications without affecting data in the live ORCID registry.

The Sandbox includes:

• Sandbox Registry: Simulates the ORCID Registry
   
• Sandbox Member API: Simulates the Member API
   
• Sandbox Public API: Simulates the Public API

The sandbox behaves the same way as the production ORCID Registry with a few exceptions:

• Search & Link tools do not function.
   
• To avoid unintentional spamming, the Sandbox sends emails only to @mailinator.com addresses. Mailinator.com is an inbox testing service that is free and requires no registration. To receive emails from the Sandbox, use an @mailinator.com email address when creating Sandbox record(s).
   
• Links in the top menu bar (For Researchers, For Organizations, About, etc.) do not function.

-top-

3.3 ORCID API technologies

All of the ORCID APIs are based on the same set of technologies:

1. REST: ORCID APIs are “RESTful”, which means that they use HTTP (hyper-text transfer) calls to transfer information.
    
2. OAuth: ORCID APIs use the OAuth 2.0 authentication protocol in order to grant client applications access to users’ ORCID records.
    
3. XML/JSON: ORCID APIs support data exchange in either XML or JSON format.

-top-

3.4 ORCID API Tools

In order to use the ORCID APIs you will need the following software tools:

1. Web browser: Firefox (33+), Chrome (38+), Internet Explorer (10+), Safari (6+)
    
2. Internet connection
    
3. Plain text editor: TextEdit (Mac), Notepad++ (Win), or your preferred plain text editor
    
4. Software capable of making HTTP requests:
• cURL: free, command-line application available for Mac or Windows at http://curl.haxx.se/download.html (pre-installed on most Mac OS versions; accessible within Terminal application)
   
• Online tools, e.g. hurl.it or Google OAuth Playground
   
• Your own web application, in a language such as Java, Ruby, Python, PHP, etc.

For this workshop, we will be using the online tool Google OAuth Playground.

-top-

#4. OAUTH BASICS (30 min) ACTIVITY

As discussed in section 3.1, the Public API can only be used to read and search ORCID records, and to get authenticated ORCID iDs. The Member API, however, can be used to add new information to ORCID records, as well as to update information previously added. To do these actions, one must obtain permission from the user/data subject. This section describes the standard OAuth process for requesting this permission.

4.1 Accessing the Sandbox Member API

Client credentials consisting of a client ID and a client secret are needed in order to access the Member API. Client Credentials for the Member APIs are issued by ORCID. For this workshop, you can use the sample Sandbox Client Credentials, but we recommend that you obtain your own Member API Sandbox Client Credentials using the request form at https://orcid.org/content/register-client-application for experimentation and testing that you do outside of this workshop.

-top-

4.2 Setting up the OAuth Playground

We’ll use the Google Developers’ OAuth Playground for the next exercises. To get started, we will need to configure the environment to work with the ORCID Member API.

1. Visit https://developers.google.com/oauthplayground
    
2. Click the gear icon in the upper right corner to open the configuration form.
    



3. Enter the following:

   OAuth flow	Server-side
   OAuth endpoints	Custom
   Authorization endpoint	https://sandbox.orcid.org/oauth/authorize
   Token endpoint	https://sandbox.orcid.org/oauth/token
   Access token location	Authorization header w/Bearer prefix
   OAuth Client ID	Your Sandbox Member API client ID (e.g. APP-E422WM33OPZWKKMQ)
   OAuth Client Secret	Your Sandbox Member API client secret (e.g. ae857cfb-446b-4c3f-8a09-55436bf602dc)

4. The configuration screen should look similar to the image at right. After you’ve entered the settings, click Close in the lower left corner of the configuration screen.

-top-

4.3 Getting permission (an Access Token) to access ORCID records

To access an ORCID record via the Member API, you first need to get permission from the owner of the record in the form of an Access Token. ORCID uses the standard protocol, OAuth 2.0, to obtain this permission. Generally there are two steps:

1. Get an Authorization Code.
    
2. Exchange the Authorization Code for an Access Token.
    

4.3.1 Get an Authorization Code

To get an Authorization Code, you’ll need to prompt the user to sign into their ORCID account and grant permission to your application. In a real-world situation, this is done using an authorization URL that you construct using your client ID, your required access permission scopes, and your redirect uri -- the landing page users will go to after they authorize the connection. This URL looks something like

https://sandbox.orcid.org/oauth/authorize?client_id=[your client ID]&response_type=code&scope=/activities/update%20/read-limited&redirect_uri=https%3A%2F%2Fyourdomain.edu%2Fyourlandingpage

With the OAuth Playground, however, this step is done by configuring some additional settings and clicking a button.

1. Beneath Step 1: Select & authorize APIs on the left side of the Google OAuth Playground screen, type "/activities/update /read-limited" in the text box (do not select any of the options presented in the box above).
    
2. Click the Authorize APIs button.
    
    
3. An ORCID OAuth permission screen will appear. If you are already signed into your test Sandbox account, click the Authorize button to grant permission. If you are not yet signed in, type in your Sandbox test account sign in credentials, and click Authorize to grant the permissions.
    
4. Clicking Authorize will send the user back to the OAuth Playground. A 6-character code will appear in the Authorization Code field.
    

4.3.2 Exchange the Authorization Code for an Access Token

Once you have an Authorization Code, you can exchange it for an Access Token, which allows you to read from/write to a user’s ORCID record. In a real-world situation, this exchange would be done by your system, using a programming language such as PHP, Java, or Ruby on Rails. This call is a RESTful call with information similar to the following

HTTP method: GET
Header:   Accept: application/json 
Data:     client_id=[your client ID]&
          client_secret=[your client secret]&
          grant_type=authorization_code&
          code=[the authorization code]&
          redirect_uri=https://developers.google.com/oauthplayground
Endpoint: https://sandbox.orcid.org/oauth/token"

With the OAuth Playground, however, this step is done by clicking a button.

1. Beneath the Authorization Code field, click Exchange authorization code for tokens.
    
2. The token will appear in the Access Token field.
    

3. Note that you are provided with additional information in the Request/Response section on the right side of the screen, such as the name and ORCID iD of the user who granted permission, the lifespan of the token (20 years), and the scope for which the token is valid.
    
    

-top-

#5. THE CROSS-LINK BREAKDOWN (15 min) PRESENTATION

The basic steps for cross linking are:

1. The user creates an ORCID iD and links to the IdP (as we did in earlier in the workshop)
2. ORCID kicks off the OAuth permission based on information that the IdP has provided (see the next section for this information)
3. The user grants permission to the IdP (as we did earlier in the workshop)
4. The IdP processes the permission and provides feedback to the user, in the form of a webpage.
5. The IdP redirects the user back to the ORCID /my-orcid page where they started.

-top-

#6. API CREDENTIAL SETUP (30 min) PRESENTATION

To get started setting up the institutional sign-in cross-link process described in the previous section, you'll need to:

1. Get ORCID Member API credentials. Not a member? Everyone can use the Sandbox Member API for testing. On the production (live) server, you can use the ORCID Public API to obtain users' authenticated ORCID iDs, but you won't be able to update their ORCID records to display their institutional affiliation, works, or other data.
2. Configure your identity provider settings for your API credentials.

##6.1 Get ORCID Member API Credentials

To use the ORCID Member API, you'll need credentials consisting of a Client ID (consumer KEY) and Client Secret (consumer SECRET). These work like a username and password that allow your application to access the API.

We require that all new Member API applications be built and tested using our Developers Sandbox, which mirrors production environment behavior, but does not contain production data. Learn more about the Developers Sandbox.

Fill in the ORCID Sandbox Member API Client Application form to get Sandbox API credentials. Note: The process is not automated. ORCID staff will usually issue your credentials within 24 hours.

When requesting credentials, you'll be asked for the following information:

1. Notes for ORCID Staff: let us know if you're using a vendor system, need additional redirect URIs, or have any other questions or notes.
2. Name of your organization
3. Contact email address Use a valid email – we send your credentials to this address!
4. Name of your client application: Name displayed on authorization screen and list of trusted organizations in users' records
5. Short description of your client application: Displayed on authorization screen when users click the question mark icon
6. URL of the home page of your application: Displayed on the list of trusted organizations in users' records
7. Redirect URIs: URL(s) in your web application where users should be returned to after they authorize access to their ORCID record data. (Note: All Redirect URIs must be HTTPS on the production server, however HTTP is fine for the Developers Sandbox.)
8. Type of credentials: Basic allows you to read from/write to records, while premium allows read/write access and also lets you register webhooks. We recommend that all Sandbox clients apply for premium credentials

##6.2 Configure identity provider settings for your API credentials

The process for adding identity provider settings to your API credentials currently is not automated.

Please send ORCID a request with the following information:

• Client ID
• Your identity provider entity ID (e.g. https://idp.example.org/idp/shibboleth)
• Your Redirect URI: The page on your site that users should be directed to after they complete the cross-link process. This can be different from the redirect URI you use for other ORCID API applications.
• The permission scope(s) that you would like. We support the following scopes:
  • /authenticate: obtain the authenticated ORCID iD (public API)
  • /read-limited: read limited data on the ORCID record and obtain the authenticated ORCID iD (member API)
  • /activities/update: add/update an affiliation for your organization in the employment or education section of the ORCID record
  • /person/update: add/update a unique identifier for your organization in the other IDs section, or a link to the user's faculty webpage in the websites section of the of the ORCID record

For new API credential requests, you can also include this info in the notes section of the request form.

-top-

#7. THE USER EXPERIENCE (30 min) ACTIVITY

So far, we've spent most of this tutorial focused on technical aspects of building an ORCID integration. The technical nuts and bolts are important, but the user experience is just as critical in a successful integration.

In this section, we'll switch directions and discuss some of the key considerations in making sure that users can connect their ORCID iD to your institution quickly and easily, and that they understand the value of doing so, including:

• Redirect pages
• Local support resources
• User communication

##7.1 Redirect pages

While much of the cross-link interaction takes place on the ORCID site, there are (minimally) 2 pages or response messages that you'll need to create on your own site:

1. Redirect page/message – user authorized the connection: this is the URL that you provide in your API credential registration.
2. Redirect page – user denied permission:

It's important to include messaging and graphics on these pages that help users understand what's happening, and to provide them with resources in case they have questions or run into trouble.

###7.1.1 Redirect page - user authorized the connection

• Confirmation message, customized with the user's name/ORCID iD
• Link/button back to user's ORCID record; use https://orcid.org/my-orcid to send the user to their personal ORCID record
• Contact information at your institution for help/questions about ORCID and your IdP
• Link to resources about how your institution uses ORCID iDs and how it has integrated with ORCID
• Link to contact ORCID Support
• Link to information about ORCID
• Link to the ORCID user Knowledge Base
• ORCID branding/graphics

###7.1.2 Redirect page - user denied permission

• Message describing what happened: The user can sign into ORCID using their institutional account, but your institution doesn't know their ORCID iD and can't update their record
• Message listing the benefits of connecting an ORCID iD to your institution
• ORCID-branded button with custom OAuth link to complete the ORCID authorization
• Contact information at your institution for help/questions about ORCID
• Link to resources about how your institution uses ORCID
• ORCID branding/graphics

##7.2 Local support resources

ORCID's support team can help your users with general ORCID questions and issues, but for help related to your institution's ORCID integration you'll need to create some resources of your own for your users. These can include:

• Knowledge Base/help articles
• LibGuides
• Tutorials
• Videos<

You should also provide users with contact information for someone at your institution who can provide assistance with ORCID-related questions.

###7.2.1 Example resources

• HKBU iD connect tutorial video
• University of Michigan LibGuide
• King Abdullah University of Science and Technology LibGuide
• More resources

##7.3 Communications

• Plan a communication timeline: make sure that users are aware of your ORCID project and plans well before you launch!
• Get high-level buy-in: send communications from dean/provost-level channels if possible<
• Promote your ORCID project at libraries, faculty/staff/TA trainings and orientations, campus events, etc.
• Make it an ongoing effort: ensure that new faculty/staff/TAs are in the loop

###7.3.1 Outreach resources

We're here to help! Find logos, fliers, videos, presentation, and other downloadable templates that you use to help get the word out about ORCID at: ORCID Outreach Resources

.

##7.4 Activity: Build your own redirect pages!

Use the samples provided to create your own custom redirect pages.

1. Download sample-redirect-pages.zip to your computer.
2. Unzip the files.
3. Open redirect-success.html and redirect-deny.html in a browser to view their current content.
4. Using a text editor, edit redirect-success.html and redirect-deny.html to customize the messages, links, graphics, etc. Make sure to keep the files inside the sample-redirect-pages folder, so that the style sheets remain linked!
5. Save your changes and refresh the pages in your browser to see the results.

-top-

#8. POST AN AFFILIATION TO YOUR INSTITUTION (50 min) ACTIVITY

In this section we will add and update an employment affiliation to your Sandbox test ORCID record using the permission that you have already received from the earlier exercise. Note: It is also possible to post an education affiliation using [different slightly different XML and endpoints](sample-education-affiliation.xml).

8.1 Post an employment affiliation to your ORCID record

1. Beneath Step 3: Configure request to API, set HTTP Method to POST.
    
2. Click Add headers and enter the following values:
• Header name: accept
• Header value: application/vnd.orcid+xml
  



3. Click Add to add another header and enter the following values:
• Header name: Content-type
• Header value: application/vnd.orcid+xml
   
4. Click Add again, then click Close.
    
5. In the Request URI field, enter https://api.sandbox.orcid.org/v2.0/[orcid-id]/employment, replacing [orcid-id] with the ORCID iD of the Sandbox record that you created earlier (e.g. https://api.sandbox.orcid.org/v2.0/0000-0002-3791-8427/employment)
   
   
    
6. Click Enter request body. Here is where you’ll enter the XML for the works you wish to add.
    
7. Go to [sample-employment-affiliation.xml](sample-employment-affiliation.xml) and copy the XML.
    
8. Paste the copied content into the Request Body text box.
    
9. Customize the text to reflect your institution. For the disambiguated-organization-identifier, replace XXXXXX with the Ringgold identifier for your institution.
    
10. Click Close.
    
    

 
11. Click Send the request.
     
12. The results will appear in the Request/Response section on the right side of the screen. Scroll to the bottom – if you see HTTP/1.1 201 Created, the affiliation was successfully posted!
     
     
13. Each item added to the ORCID record has a unique put-code that can be used to read the full metadata of the item, or to edit or delete the item using the client that has added it to the record. The put-code is displayed in the response following Location: https://api.sandbox.orcid.org/v2.0/[orcid-id]/employment/[put-code]. In a real-world situation, your system would store this put-code along with the affiliation data in your database.
    
14. Visit the public view of your Sandbox record at https://sandbox.orcid.org/[Your sandbox iD] to see the work that you added in the user interface.

-top-

8.2 Updating an affiliation

In a real-world situation, you may need to update a researcher's affiliation when they finish a degree, change departments, or finish a contract. To update an affiliation, you will require the unique put-code for the affiliation.

1. Beneath Step 3: Configure request to API, set HTTP Method to PUT, which is required to update the item.
    
2. At the end of the request URI, add the put-code of the affiliation you just created, e.g. https://api.sandbox.orcid.org/v2.0/0000-0002-3791-8427]/employment/employment/26651. Without the put-code, you cannot update the affiliation.
    
3. Click Enter request body. This is where you’ll enter the XML for the work that you wish to edit.
    
4. Go to [sample-employment-affiliation-edit.xml](sample-employment-affiliation-edit.xml) and copy the XML.
    
5. Paste the XML in the Request Body field and amend to reflect your institution.
   Tip: The amended area are lines 1 (edit) and lines 13-11 (new data). You can copy line one and use it to replace the first line of your data; enter the unique put-code in place of "put-code="XXXXX"". The new data begins begins with <common:end-date>, and you can can paste it after the </common:start-date> in the active Request Body.)
   
    
6. Click Close.
    
7. Click Send the Request.
    
8. The results will appear in the Request/Response section on the right side of the screen. Scroll down – if you see HTTP/1.1 200 OK, the affiliation was successfully posted!
   If you receive an error, be sure to check that the headers value under Add headers have not been changed to garbled text, e.g. "application%2Fvnd.orcid%2Bxml".
   
    
9. Visit the public view of your Sandbox record at https://sandbox.orcid.org/[Your sandbox iD] to see the changes to the work in the user interface.

-top-

#9. REFERENCE MATERIALS

• See example implementations and workflow guides at our Member Support Center
   
• Read our API technical documentation
   
• Find sample calls and XML in the ORCID Github repository
   
• Join the ORCID API Users Group
   
• Sign up for a Technical Webinar
   
• Contact us for help