Versions Compared

Old Version 22

changes.mady.by.user Tim Donohue

Saved on

compared with

New Version 23

changes.mady.by.user Tom Desair

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Returns string "REST api is running", for testing that the API is uphttpstestExample ResponseRESTapi is running.

Receive information about the currently authenticated user token, or the API itself (e.g. version information).

Example Request (XML by default):

curl -v --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8"
MethodEndpointDescription
GET/REST API static documentation page
POST/login

Login to the REST API using a DSpace EPerson (user). It returns a JSESSIONID cookie, that can be used for future authenticated requests.

Example Request:

Code Block
# Can use either POST or GET (POST recommended). Must pass the parameters "email" and "password".
curl -v -X POST --data "email=admin@dspace.org&password=mypass" https://dspace.myu.edu/rest/login

Example Response:

Code Block
HTTP/1.1 200 OK
Set-Cookie: JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8; Path=/rest/; Secure; HttpOnly

Example of using JSESSIONID cookie for subsequent (authenticated) requests:

Code Block
curl -v --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8" https://dspace.myu.edu/rest/status
# This should return <authenticated>true</authenticated>, and information about the authenticated user session

Invalid email/password combinations will receive an HTTP 401 Unauthorized response.

Please note, special characters need to be HTTP URL encoded.
For example, an email address like dspacedemo+admin@gmail.com (notice the + special character) would need to be encoded as dspacedemo%2Badmin@gmail.com.

POST
GET/logoutshibboleth-login

Login to

Logout from

the REST API

, by providing a JSESSIONID cookie. After being posted this cookie will no longer work.Example Request

using Shibboleth authentication. In order to work, this requires additional Apache configuration. To authenticate, execute the following steps:

1. Call the REST Shibboleth login point with a Cookie jar:

Code Block
curl -v -
X
L
POST --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8" https:
-c cookiejar "https://dspace.myu.edu/rest/
logout

After posting a logout request, cookie is invalidated and the "/status" path should show you as unauthenticated (even when passing that same cookie). For example:

shibboleth-login"

2. This should take you again to the IdP login page. You can submit this form using curl using the same cookie jar. However this is IdP dependant so we cannot provide an example here.

3. Once you submit the form using curl, you should be taken back to the /rest/shibboleth-login URL which will return you the JSESSIONID.

4. Using that JSESSIONID, check if you have authenticated successfully:

Code Block
curl -v "http://localhost:8080/dspace-rest/status" --cookie "JSESSIONID=
6B98CF8648BCE57DCD99689FE77CB1B8" https://dspace.myu.edu/rest/status # This should show <authenticated>false</authenticated>

Invalid token will result in HTTP 400 Invalid Request

GET/test
0633C6379266A283E53F65DF8EF61AB9"


POST/logout

Logout from the REST API, by providing a JSESSIONID cookie. After being posted this cookie will no longer work.

Example Request:

Code Block
curl 
-v -X POST --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8" https://dspace.myu.edu/rest/
logout

After posting a logout request, cookie is invalidated and the "/status" path should show you as unauthenticated (even when passing that same cookie). For example:

Code Block
curl
GET/status
Code Block
-v --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8" https://dspace.myu.edu/rest/status
# This should show <authenticated>false</authenticated>

Invalid token will result in HTTP 400 Invalid Request

GET/test

Returns string "REST api is running", for testing that the API is up.

Example Request:

Code Block
curl

Example Request (JSON):

Code Block
curl -v -H "Accept: application/json" --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8" https://dspace.myu.edu/rest/statustest

Example JSON Response:

Code Block
{
REST  "okay":true,
  "authenticated":true,
  "email":"admin@dspace.org",
  "fullname":"DSpace Administrator",
  "sourceVersion":"6.0",
  "apiVersion":"6"
}api is running.


GET/status

Receive information about the currently authenticated user token, or the API itself (e.g. version information).

Example Request (XML by default):

Code Block
curl -v --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8" https://dspace.myu.edu/rest/status

Example Request (JSON):

Code Block
curl -v -H "Accept: application/json" --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8" https://dspace.myu.edu/rest/status

Example JSON Response:

Code Block
{
  "okay":true,
  "authenticated":true,
  "email":"admin@dspace.org",
  "fullname":"DSpace Administrator",
  "sourceVersion":"6.0",
  "apiVersion":"6"
}


Shibboleth Apache configuration for the REST API

Before Shibboleth authentication for the REST API will work, you need to secure the /rest/shibboleth-login endpoint. Add this configuration section to your Apache HTTPD Shibboleth configuration:

Code Block
<Location "/rest/shibboleth-login">
         AuthType shibboleth
         ShibRequireSession On
         # Please note that setting ShibUseHeaders to "On" is a potential security risk. 
         # You may wish to set it to "Off". See the mod_shib docs for details about this setting:
         # https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig#NativeSPApacheConfig-AuthConfigOptions
         # Here's a good guide to configuring Apache + Tomcat when this setting is "Off": 
         # https://www.switch.ch/de/aai/support/serviceproviders/sp-access-rules.html#javaapplications
         ShibUseHeaders On
         require valid-user
</Location>

You can test your configuration in 3 different ways:

  1. Using a web browser:
    1. Go to https://dspace.myu.edu/rest/shibboleth-login, this should redirect you to the login page of your IdP if you don't have a Shibboleth session yet.
    2. Enter your test credentials and this should take you back to the /rest/shibboleth-login URL. You should then see a blank page but in the response headers, the JSESSIONID cookie should be present.
    3. Then go to /rest/status and you should see information on the current authenticated ePerson.
  2. Using curl without a Shibboleth Session
    1. Call the REST Shibboleth login point with a Cookie jar: 


      Code Block
      curl -v -L -c cookiejar "https://dspace.myu.edu/rest/shibboleth-login"


    2. This should take you again to the IdP login page. You can submit this form using curl using the same cookie jar. However this is IdP dependant so I cannot provide an example here.
    3. Once you submit the form using curl, you should be taken back to the /rest/shibboleth-login URL which will return you the JSESSIONID.

    4. Using that JSESSIONID, check if you have authenticated successfully: 

      Code Block
      curl -v "https://dspace.myu.edu/dspace-rest/status" --cookie "JSESSIONID=0633C6379266A283E53F65DF8EF61AB9"


  3. Using curl with a Shibboleth Session (cookie)
    1. When you post the Shibboleth login form, the Shibboleth daemon on the DSpace server also returns you a Shibboleth Cookie. This cookie looks like _shibsession_64656661756c74687... You can also grab this cookie from your browser.

    2. Double check that the cookie you took is valid:

      Code Block
      curl -v 'https://dspace-url/Shibboleth.sso/Session' -H 'Cookie: _shibsession_64656661756c7468747470733a2f2f7265706f7369746f72792e636172646966666d65742e61632e756b2f73686962626f6c657468=_a8d3ad20d8b655250c7357f7ac0e2910;'


    3. This should give you information if the Shibboleth session is valid and on the number of attributes. 

    4. Use this cookie to obtain a Tomcat JSESSIONID:

      Code Block
      curl -v 'https://dspace-url/rest/shibboleth-login' -H 'Cookie: _shibsession_64656661756c7468747470733a2f2f7265706f7369746f72792e636172646966666d65742e61632e756b2f73686962626f6c657468=_a8d3ad20d8b655250c7357f7ac0e2910;'


    5. Use the returned JSESSIONID to check if you have authenticated successfully:

      Code Block
      curl -v "http://dspace-url/rest/status" --cookie "JSESSIONID=0633C6379266A283E53F65DF8EF61AB9"


Communities

Communities in DSpace are used for organization and hierarchy, and are containers that hold sub-Communities and Collections. (ex: Department of Engineering)

...