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

Logout

To logout and invalidate the token, send the token in the Authorization header with the bearer scheme to the following endpoint:

/api/authn/logout

E.G.

curl -v "http://{spring-rest.url}/api/authn/logout" -H "Authorization: Bearer eyJhbG...COdbo"

This will log the user out on every device/browser.

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, HttpServletRequest): Object

This method should return the value of the claim, This can be any object, as long as it is Serialisable.

parseClaim(Context, HttpServletRequest, JWTClaimSet)

This method should parse the claim when someone issues a token. In this method you should handle what has to happen with it (for example setting special groups on the context object)

NOTE: add @Component to your ClaimProviders so Spring can find them.

Refresh Token

When a token is about to expire (Which can be checked with the exp claim), you can request a new token with a new expiration time (by default 30 minutes). To do so send the token to the login endpoint without "user" and "password" parameters. As a response you'll get a new freshly issued token (again in the Authorization header of the response).