Back to the list of all defined endpoints
The authentication mechanism since DSpace 7 is based on JSON Web Token (JWT / RFC 7519).
The authentication mechanism since DSpace 7 is based on JSON Web Token (JWT / RFC 7519).
Information about the underline implementation are available on the wiki
POST /api/authn/login
This endpoint only accepts the POST
method. Parameters and body structure depend on the authentication method to use.
A WWW-Authenticate
header is returned listing the different authentication method supported by the system.
Below an example listing the password and shibboleth authentication:
WWW-Authenticate: shibboleth realm="DSpace REST API", location="https://demo.dspace.org/Shibboleth.sso/Login?target=https%3A%2F%2Fdemo.dspace.org", password realm="DSpace REST API"
Return codes
- 200 Ok. If the authentication succeed. The JWT will be returned in the response Header Authorization.
- 401 Unauthorized. If the login fails. The response Header WWW-Authentication must be inspected to discover the supported authentication method
Parameters must be sent in the body of a x-www-form-urlencoded
request, i.e
curl -v -X POST https://{dspace-server.url}/server/api/authn/login --data "user=dspacedemo%2Badmin%40gmail.com&password=dspace" -H "X-XSRF-TOKEN: {csrf-token}" -b "DSPACE-XSRF-COOKIE={xsrf-cookie}"
Please note that authentication requires passing a valid CSRF token header and cookie, previously obtained from the REST API. Also note that curl
assumes -H 'Content-Type: application/x-www-form-urlencoded'
for a POST request as default.
This call will return a JWT (JSON Web Token) in the response in the Authorization header according to the bearer scheme. This token has to be used in subsequent calls to provide your authentication details. For example:
curl -v "https://{dspace-server.url}/api/core/items" -H "Authorization: Bearer eyJhbG...COdbo"
The shibboleth realm exposes a location attribute that must be followed by the client to establish a shibboleth session so that subsequent call to the login endpoint will succeed returning the JWT.
Tokens are only valid for a configurable amount of time (see below). When a token is about to expire (the timestamp provided in the exp claim, see below), you can request a new token with a new expiration time (by default 30 minutes). To do so send the token using the Header Authorization: Bearer ...
to the login endpoint without other parameters. As a response you'll get a new freshly issued token (again in the Authorization header of the response).
i.e
curl -v -X POST "http://{dspace-server.url}/api/authn/login" -H "Authorization: Bearer eyJhbG...COdbo" -H "X-XSRF-TOKEN: {csrf-token}"
Which will return something like this:
HTTP/1.1 200 OK
Authorization: Bearer edoDfG...S0df
The JWT contains the following claims
claim | description |
---|---|
eid | Contains the id of the eperson |
sg | Contains the id's of the special groups to which a user belongs |
exp | Contains the expiration date when a token will expire |
POST /api/authn/logout
This endpoint only accepts the POST
method.
To logout and invalidate the JWT token, send the token in the Authorization
header with the bearer scheme.
curl -v -X POST "https://{dspace-server.url}/api/authn/logout" -H "Authorization: Bearer eyJhbG...COdbo" -H "X-XSRF-TOKEN: {csrf-token}"
This invalidates the token on the server side which will results in logging out the user on every device or browser. It can also be called with params action and return, required by the Shibboleth Single Logout (front channel), with the same behaviour.
As this endpoint requires a POST, it requires passing a valid CSRF token.
Return code
- 204 No content.
- 302 Found. If a successful logout occurs, and a logout page URL is configured
Invalid or missing tokens are not reported, i.e. the endpoint will always return 204 also if no token is supplied, or the token is invalid
/api/authn/status
The authentication status can be checked by sending your received token to the status endpoint in the Authorization header in a GET request:
curl -v "http://{dspace-server.url}/api/authn/status" -H "Authorization: Bearer eyJhbG...COdbo"
This will return the authentication status, E.G.:
{
"okay" : true,
"authenticated" : true,
"type" : "status",
"_links" : {
"eperson" : {
"href" : "http://${dspace-server.url}/api/eperson/epersons/2245f2c5-1bed-414b-a313-3fd2d2ec89d6"
}
},
"_embedded" : {
"eperson" : {
"uuid" : "2245f2c5-1bed-414b-a313-3fd2d2ec89d6",
"email" : "test@dspace.com",
...
},
"specialGroups" : {
"_embedded" : {
"specialGroups" : [ {
"id" : "3d07510c-2c33-48f5-8a04-f63bc9a63296",
"uuid" : "3d07510c-2c33-48f5-8a04-f63bc9a63296",
"name" : "A Special Group",
... } ],
"page" : {
"number" : 0,
"size" : 20,
"totalPages" : 1,
"totalElements" : 1
},
"_links" : {
"self" : {
"href" : "http://${dspace-server.url}/api/authn/status/specialGroups"
}
}
}
}
}
Fields
- Okay: True if REST API is up and running, should never return false
- Authenticated: True if the token is valid, false if there was no token or the token wasn't valid
- Type: Type of the endpoint, "status" in this case
Links
- returns a link to the authenticated eperson
- specialGroups: return the special groups associated with the current authentication context. Please note that specialGroups can be present also without an authenticated user (i.e. via IPAuthentication)
Embedded
- Embeds the authenticated eperson
Return code
- 200 Ok in all the scenario both authenticated than not authenticated (valid token, invalid token or missing token)
For any request, an X-On-Behalf-Of
header can be included.
If the user is authorized to use this header (the user is an admin and login as is allowed), the request will be processed using the account of the provided user.
Verifying whether the user is authorized to use this header can happen using the "loginOnBehalfOf" feature, verified against the site
Sample request:
curl -v "http://{dspace-server.url}/server/api/core/items/1911e8a4-6939-490c-b58b-a5d70f8d91fb" -H "Authorization: Bearer eyJhbG...COdbo" -H "X-On-Behalf-Of: 028dcbb8-0da2-4122-a0ea-254be49ca107"
The Authorization header remains the same, still linked to the actual admin using the X-On-Behalf-Of
header.
Status codes:
- 400 Bad Request - if the X-On-Behalf-Of header doesn't contain a valid EPerson UUID
- 403 Forbidden - if you are not authorized to act on behalf of the given user
- Any status code of the functionality being used
POST /api/authn/shortlivedtokens
When clicking on a link to download a protected file in the UI no authentication header will be sent along. This endpoint can provide a short lived token (MAX 2 seconds) that the UI can append to file downloads.
The token follows the "JSON Web Token structure", same as the login tokens.
curl -v -X POST https://{dspace-server.url}/api/authn/shortlivedtokens -H "Authorization: Bearer eyJhbG...COdbo" -H "X-XSRF-TOKEN: {csrf-token}"
{
"token": "eyJhbGciOiJIUzI1NiJ9.eyJlaWQiOiJjZDgyNGE2MS05NWJlLTRlMTYtYmNjZC01MWZlYTI2NzA3ZDAiLCJzZyI6W10sImV4cCI6MTU5MDQxMzUwNn0.XRK4ldh9l4My45gJzLtcW97hVUpbtM5oAQsxuQ2V37c",
"_links": {
"self": {
"href": "http://${dspace-server.url}/api/authn/shortlivedtokens"
}
}
}
Return codes
- 200 Ok.
- 401 Unauthorized. If no user is logged in
POST /api/authn/machinetokens
This endpoint can provide a machine token, a long lived machine token that can be invalidated is a separated way from the login token.
The token follows the "JSON Web Token structure", same as the login tokens.
curl -v -X POST https://{dspace-server.url}/api/authn/machinetokens -H "Authorization: Bearer eyJhbG...COdbo" -H "X-XSRF-TOKEN: {csrf-token}"
{
"token": "eyJhbGciOiJIUzI1NiJ9.eyJlaWQiOiJjZDgyNGE2MS05NWJlLTRlMTYtYmNjZC01MWZlYTI2NzA3ZDAiLCJzZyI6W10sImV4cCI6MTU5MDQxMzUwNn0.XRK4ldh9l4My45gJzLtcW97hVUpbtM5oAQsxuQ2V37c",
"type": "machinetoken",
"_links": {
"self": {
"href": "http://${dspace-server.url}/api/authn/machinetokens"
}
}
}
Return codes
- 200 Ok.
- 401 Unauthorized. If no user is logged in
- 403 Forbidden. If the user used the login as feature
DELETE /api/authn/machinetokens
This endpoint invalidate the machine token generated from the current user, if any.
curl -v -X DELETE https://{dspace-server.url}/api/authn/machinetokens -H "Authorization: Bearer eyJhbG...COdbo" -H "X-XSRF-TOKEN: {csrf-token}"
Return codes
- 204 No content.
- 401 Unauthorized. If no user is logged in
- 403 Forbidden. If the user used the login as feature
GET /api/authn/shortlivedtokens
As of 7.5, this option is no longer supported. Please use POST instead (see above).
The request parameter below can be used for nearly every REST endpoint to perform it with authentication but without needing the authentication header:
- authentication-token: optional parameter that authenticates a user, a token needs to be requested from the following endpoint
The following endpoints are not allowed to use the authentication-token:
- POST /api/authn/login: refreshing your long-lived authentication header is not allowed using the short lived token
- POST /api/authn/shortlivedtokens: creating a new short lived token is not allowed using the short lived token