Introduction

Restdude applications are stateless by default and use Spring Security, a framework that focuses on providing both authentication and authorization to Java applications and can be easily extended to meet custom requirements. Spring Security supports varuous technologies out of the box, including in-memory, JDBC, LDAP, OAuth, SAML, Kerberos and others.

This document describes the core authentication and authorization mechanisms used in restdude.

JWT

Access Tokens

To obtain a JWT Access token while authenticating, make an HTTP request as follows:

// POST /api/auth/jwt/access
// Headers: Accept=application/json; charset=UTF-8
//		Content-Type=application/json; charset=UTF-8
// Body:
{
    "password": "foo",
    "username": "bar"
}

If the credentials are valid, you will receive a JSON response body with the corresponding user details and an access_token cookie that contains the compact, signed JWT Access token:

// HTTP/1.1 201 Created
// Content-Type: application/json;charset=utf-8
// Set-Cookie: access_token=eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1c2Vycy80ZjBmY2ZmMC1jOTQyLTRmYjEtYThjYS0xOGM4NDMyYWQwNmQiLCJuYW1lIjoiQWRtaW4gVXNlciIsImdpdmVuX25hbWUiOiJBZG1pbiIsImZhbWlseV9uYW1lIjoiVXNlciIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwibG9jYWxlIjoiZW4iLCJzY29wZXMiOlsiUk9MRV9BRE1JTiIsIlJPTEVfVVNFUiJdLCJleHAiOjE0ODk3MDA2MjR9.NPuRqNojx1EsaE3r844aF6syj2Vg0qkrWpxWMFZRfTALygaugkmA95zmwIXM_utrmi5Z8BqDJyTLx32Pa7XItQ;Path=/;Domain=.localhost
// Set-Cookie: refresh_token=eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhZG1pbiIsInNjb3BlcyI6WyJST0xFX1JFRlJFU0hfVE9LRU4iXSwiZXhwIjoxNDg5NzAwNjI0fQ.hF76jw_BPReJy9W-dATjMbGFSO6j71KqNqIzaLfVPzRMU67bvxZ3jD9cW0Cd3IroJdR53GOq-wdCa4gQK9YhSg;Path=/;Domain=.localhost
// Body
    {
    "pk": "4f0fcff0-c942-4fb1-a8ca-18c8432ad06d",
    "username": "foo",
    "lastPassWordChangeDate": null,
    "emailHash": "6ae965c1342be697f5fd386090e2c22e",
    "firstName": "Foo",
    "lastName": "Bar",
    // other members...
    "roles": [
        {"authority": "ROLE_ADMIN"},
        {"authority": "ROLE_USER"}
    ]
}

Refresh Tokens

Add documentation

JWT Settings

The following application properties control JWT generation:

• restdude.jwt.accessTokenMinutes: The amount of minutes JWT Access tokens are valid.
• restdude.jwt.refreshTokenMinutes: The amount of minutes JWT Refresh tokens are valid. Should be greater than the above.
• restdude.jwt.tokenIssuer: The token issuer.
• restdude.jwt.tokenSigningKey: The secret key used to sign and verify JWTs.

Basic Auth

Restdude also supports Basic Authentication, mostly as a convenience during development.

To login and further access the app using Basic Auth, make an HTTP request as follows:

// POST /api/auth/basic
// Headers: Accept=application/json; charset=UTF-8
//		Content-Type=application/json; charset=UTF-8
// Body:
{
    "password": "foo",
    "username": "bar"
}

If the credentials are valid, you will receive a JSON response body with the corresponding user details and a restdude-sso cookie that iwill be the equivalent of an Authentication: Basic header when transparently sent back to the server in subsequent requests:

// HTTP/1.1 201 Created
// Content-Type: application/json;charset=utf-8
// Set-Cookie: restdude-sso=YWRtaW46YWRtaW4=;Path=/;Domain=.localhost
// Body
{
    "pk": "4f0fcff0-c942-4fb1-a8ca-18c8432ad06d",
    "username": "foo",
    "lastPassWordChangeDate": null,
    "emailHash": "6ae965c1342be697f5fd386090e2c22e",
    "firstName": "Foo",
    "lastName": "Bar",
    // other members...
    "roles": [
        {"authority": "ROLE_ADMIN"},
        {"authority": "ROLE_USER"}
    ]
}

Anonymous Auth

Add documentation

Social Sign-in

Restdude provides transparent registration and social sign-in using Spring Social. Linkedin, Facebook, Github and other networks are supported.

Add documentation

Cookies Configuration

Cookies are perhaps the most secure way of storing information on the client, provided SSL is used and cookies are configured as secure and HTTP-Only, i.e. not accessible by scripts. The following application properties control cookies configuration:

• restdude.cookies.httpOnly: true/false.
• restdude.cookies.secure: true/false.

CSRF Protection

Add documentation

Dynamic CORS

Restdude supports both static and dynamic Cross-Origin Resource Sharing (CORS) configuration, the latter down to entity model instance.

Add documentation

Authorization Metadata

Restdude allows configuring authorization by annotating your models using Spring Expression Language (SpEL) expressions.

Add documentation