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

Video tutorial explaining the simple steps to integerate the cidaas interceptor into your java REST (JAX-RS) applications:

Tutorial Youtube Link

https://www.youtube.com/embed/NnWoXdS94T4

The steps here will guide you to integrate the cidaas-interceptor into the java rest services.

Click here for Sample Project.

Prerequisites

1. The cidaas-interceptor requires a java and resteasy based development environment

2. By now the cidaas-interceptor is tested in a Apache Tomcat environment

3. 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)

4. Setup of your Rest service project shown below

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>oauth2-interceptor</artifactId>
</dependency>

2: In web.xml add entry:

<!-- OAuth-Interceptor -->
<context-param>
<param-name>resteasy.providers</param-name>
<param-value>de.cidaas.oauth.interceptor.OAuthInterceptor</param-value>
</context-param>

How it works

1. Each call to your Rest services is now intercepted by OAuth-Interceptor to check the existence and validity of the AccessToken.
2. The caller has to provide the access_token as http header param.
3. The access_token is issued by the OAuthService 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:

•  no annotation, only valid AccessToken is required.
• @PermitAll Deactivates any security checks even an AccessToken is not required.
• @DenyAll Deactivates the rest service in total, call lead to 403 Forbidden.
• @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 in UserAccount object. 403 Forbidden 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 oauth2-login/oauth2/token.
• A user/system which would like to access this service has to be registered in advance in the oauth-service. Identification is done by a client_id and a client_secret.

oauth-service/rest/oauth2/token is a HTTP-Post call, which requires following post params:

• grant_type=client_credentials Die Art der Autentifizierung (Mit AppAccess)
• client_id=[client_id] Die client_id des AppAccess
• client_secret=[client_secret] Das client_secret des AppAccess

The result on successful call of the service is:

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

Property files need to be added

Mandatory property

vim oauth2service.properties

user_info_by_token=your_cidaas_baseurl/token/userinfobytoken
update_token_check_url=your_cidaas_baseurl/token/updateusage

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

Optional Property

vim oauth2service.properties

tokenKey=access_token
JWE_Private_Key_Path=path to your private key. if the JWE enabled on the app accessor

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