Page History
...
Method | Endpoint | Description | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
GET | / | REST API static documentation page | ||||||||||||||
POST | /login | Login to the REST API using a DSpace EPerson (user). It returns a Example Request:
Example Response:
Example of using JSESSIONID cookie for subsequent (authenticated) requests:
Invalid email/password combinations will receive an Please note, special characters need to be HTTP URL encoded. | ||||||||||||||
GET | /logoutshibboleth-login | Login to the REST API JSESSIONID cookie. After being posted this cookie will no longer work.Example Requestusing 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:
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:
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:
Invalid token will result in HTTP 400 Invalid Request | GET | /test | Returns string "REST api is running", for testing that the API is up
| |||||||||||
POST | /logout | Logout from the REST API, by providing a Example Request:
| https
| testExample Response
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:
| REST
| api is running.GET | /status | |||||||||
Code Block |
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:
Example Request (JSON):
Example JSON Response:
| ||||||||||||||
GET | /status | Receive information about the currently authenticated user token, or the API itself (e.g. version information). Example Request (XML by default):
Example Request (JSON):
Example JSON Response:
|
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:
- Using a web browser:
- 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. - 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. - Then go to
/rest/status
and you should see information on the current authenticated ePerson.
- Go to
- Using curl without a Shibboleth Session
- Call the REST Shibboleth login point with a Cookie jar:
Code Block curl -v -L -c cookiejar "https://dspace.myu.edu/rest/shibboleth-login"
- 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.
- Once you submit the form using curl, you should be taken back to the
/rest/shibboleth-login
URL which will return you the JSESSIONID. Using that JSESSIONID, check if you have authenticated successfully:
Code Block curl -v "https://dspace.myu.edu/dspace-rest/status" --cookie "JSESSIONID=0633C6379266A283E53F65DF8EF61AB9"
- Call the REST Shibboleth login point with a Cookie jar:
- Using curl with a Shibboleth Session (cookie)
- 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. Double check that the cookie you took is valid:
Code Block curl -v 'https://dspace-url/Shibboleth.sso/Session' -H 'Cookie: _shibsession_64656661756c7468747470733a2f2f7265706f7369746f72792e636172646966666d65742e61632e756b2f73686962626f6c657468=_a8d3ad20d8b655250c7357f7ac0e2910;'
- This should give you information if the Shibboleth session is valid and on the number of attributes.
Use this cookie to obtain a Tomcat JSESSIONID:
Code Block curl -v 'https://dspace-url/rest/shibboleth-login' -H 'Cookie: _shibsession_64656661756c7468747470733a2f2f7265706f7369746f72792e636172646966666d65742e61632e756b2f73686962626f6c657468=_a8d3ad20d8b655250c7357f7ac0e2910;'
Use the returned JSESSIONID to check if you have authenticated successfully:
Code Block curl -v "http://dspace-url/rest/status" --cookie "JSESSIONID=0633C6379266A283E53F65DF8EF61AB9"
- When you post the Shibboleth login form, the Shibboleth daemon on the DSpace server also returns you a Shibboleth Cookie. This cookie looks like
Communities
Communities in DSpace are used for organization and hierarchy, and are containers that hold sub-Communities and Collections. (ex: Department of Engineering)
...