Integrate cidaas-interceptor: Java REST (JAX-RS)

The steps here will guide you to integrate the cidaas-interceptor into the java REST(JAX-RS) services.

Prerequisites

The cidaas-interceptor requires a java and RESTEasy based development environment
Configuration of cidaas-interceptor is based on a set of properties kept in a configuration file. Configuration file is loaded by widas-util ConfigurationLoader. Which requires a single environment variable (use "-D" warc.homepath=path-to-conf directory)

Setup your Rest service project

1: Using maven, in your project pom.xml the following dependency for oauth-interceptor is required

<dependency>
    <groupId>de.cidaas</groupId>
    <artifactId>cidaas-interceptor-java</artifactId>
    <version>...</version>
</dependency>

Find the latest interceptor here : http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22cidaas-interceptor-java%22

2: In web.xml add entry:

<!-- OAuth-Interceptor -->
<context-param>
<param-name>resteasy.providers</param-name>
</context-param>

How it works

Each call to your Rest services is now intercepted by OAuth-Interceptor to check the existence and validity of the AccessToken.
The caller has to provide the access_token or Authorization Bearer as http header param
The access_token is issued by the cidaas after successful login.

Example: access_token: baf0c1db07291d175fa7521594dc2064

Annotations of Interceptor

It is highly recommended to use following annotations to add further security checks:

Supported javax.annotation.security annotations:

If no annotation, validates only the expire time
@PermitAll Deactivates any security checks even an AccessToken is not required.
@DenyAll Deactivates the rest service in total, call lead to 401 Access Denied.
@OAuthScopes(scopes = { "antrag:search", ... }) checks if a caller has one of the scopes defined in scopes. E.g. one scope per Rest service is used.
@RolesAllowed(value = { "role1", "role2", ... }) checks if a caller has the one of the roles defined in this annotation. The role check is based on the role settings. 401 Access Denied is returned, if AccessToken is valid, but current user is anonymous or does not have the appropriate role.

Technical explanation

A token is issued if an individual (a person) identifies itself or if a "system" identifies itself. The service that issues an AccessToken is access token endpoint.
A user/system which would like to access this service has to be registered in advance in the cidaas. Identification is done by a client_id and a client_secret.

access token endpoint is a HTTP-Post call, which requires following post params:

grant_type=[client_credentials,password,implicit,authorization_code,refresh_token]
client_id=[client_id]
client_secret=[client_secret]

The result on successful call of the service is:

{
expires_in: 86400
refresh_token: "ccb8516a2245dd2a0b76789a69ba37f4"
access_token: "2ccc5f38a5223c5a558071e94f9fc86b"
}

Property files need to be added

Mandatory property

Set the -D warc.homepath=<your-config-directory>
Create a conf directroy inside your <your-config-directory>
Create a cidaas_config.properties file inside conf directory.
Final file stucture <your-config-directory>/conf/cidaas_config.properties

cidaas_config.properties

base_url=https://<cidaas-base-url>.cidaas.de
client_id=<non-interactive-app-client-id>
client_secret=<non-interactive-app-client-secret>

Note The Urls you can get it from your admin dashboard's OAuth Endpoint section.

Check Scope

@POST
@OAuthScopes(scopes = { "access:write"})
@Path("/employee/create")
public Response createEmployee(@Context HttpHeaders hh, @Context HttpServletRequest request) {
OAuthUser userInfo = ResteasyProviderFactory.getContextData(OAuthUser.class);
System.out.println(userInfo.userId);
System.out.println(userInfo.oauthToken);
// your logic
}

Check Role

@GET
@RolesAllowed(value = { "ACCOUNTANT", "ADMIN" })
@Path("/salary/list")
public Response viewEmployeeSalary(@Context HttpHeaders hh, @Context HttpServletRequest request) {
OAuthUser userInfo = ResteasyProviderFactory.getContextData(OAuthUser.class);
System.out.println(userInfo.userId);
System.out.println(userInfo.oauthToken);
// your logic
}

Check Role and Scope

@GET
@OAuthScopes(scopes = { "access:read"})
@RolesAllowed(value = { "ACCOUNTANT", "ADMIN" })
@Path("/leaves/list")
public Response viewEmployeeLeaves(@Context HttpHeaders hh, @Context HttpServletRequest request) {
OAuthUser userInfo = ResteasyProviderFactory.getContextData(OAuthUser.class);
System.out.println(userInfo.userId);
System.out.println(userInfo.oauthToken);
// your logic
}

DenyAll

@POST
@DenyAll
public Response deleteEmployee(@Context HttpHeaders hh, @Context HttpServletRequest request) {
OAuthUser userInfo = ResteasyProviderFactory.getContextData(OAuthUser.class);
System.out.println(userInfo.userId);
System.out.println(userInfo.oauthToken);
// your logic
}

PermitAll

@GET
@PermitAll
public Response viewCompanyAddress(@Context HttpHeaders hh, @Context HttpServletRequest request) {
OAuthUser userInfo = ResteasyProviderFactory.getContextData(OAuthUser.class);
System.out.println(userInfo.userId);
System.out.println(userInfo.oauthToken);
// your logic
}

Context variables (Magic variables)

Once the validation passed , cidaas will automatically add the OAuthUser in the Current Resteasy Request Context.

OAuthUser userInfo = ResteasyProviderFactory.getContextData(OAuthUser.class);
System.out.println(userInfo.userId);
System.out.println(userInfo.oauthToken);

It contains the userid of the access_token and the passed access_token

JAX-RS