Contribute to the DSpace Development Fund
The newly established DSpace Development Fund supports the development of new features prioritized by DSpace Governance. For a list of planned features see the fund wiki page.
For DSpace 7 the REST authentication has been rewritten from the ground up. It makes use of Spring Security and JSON Web tokens to support stateless sessions.
Authenticate
To authenticate yourself, you have to send a POST request to the /api/authn/login endpoint with the following parameters:
parameter | value |
---|---|
user | email/id of user |
password | password of user |
Example call with curl:
curl -v -X POST --data "user=test@dspace.com&password=p4ssword" "http://{spring-rest.url}/api/authn/login"
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.
Authentication Status
The authentication status can be checked by sending your received token to the status endpoint in the Authorization header:
curl -v "http://{spring-rest.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://localhost:8080/dspace7-rest/api/eperson/epersons/2245f2c5-1bed-414b-a313-3fd2d2ec89d6"
},
"self" : {
"href" : "http://localhost:8080/dspace7-rest/api/statuses"
}
},
"_embedded" : {
"eperson" : {
"uuid" : "2245f2c5-1bed-414b-a313-3fd2d2ec89d6",
"email" : "atmirenv@gmail.com",
...
}
}
}
}
Fields
Field | Meaning |
---|---|
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 |
_embedded | Embeds the authenticated eperson |
JSON Web Token
The authentication token is JWT and is base64url encoded. For more information about JWT: https://jwt.io/introduction/
By default the JWT token will have a couple of claims already, which we can see if we decode the token:
Claim | Data |
---|---|
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 |
Add extra claims
Extra claims can be added by creating more beans which implement the JWTClaimProvider interface. Spring will scan for these and use them to automatically add new claims to the tokens.
The JWTClaimProvider interface requires three methods to be implemented:
getKey(): String
This method should return a string, this string will be used as key for the claim (for example "eid" for the eperson id claim)
getValue(Context context, HttpServletRequest request): Object
This method should return the value