Skip to main content

Developer's Guide

Step 1: Keycloak Setup​

  1. Go to the Keycloak page.
  2. Create a realm with the name cognaize-realm.
  3. Create two clients - ssoclient and jwtclient.

ssoclient Configuration:​

  • Root URL: Web user interface webapp root link, e.g., https://mywebapp.cognaize.com
  • Home URL: https://mywebapp.cognaize.com
  • Valid Redirect URIs: https://mywebapp.cognaize.com/*
  • Valid Post Logout Redirect URIs: https://mywebapp.cognaize.com/*
  • Web Origins: https://mywebapp.cognaize.com

Capability Config:

  • Client Authentication: false
  • Direct Access Grants: false

jwtclient Configuration:​

Capability Config:

  • Client Authentication: true
  • Direct Access Grants: true

Step 2: Include Library in build.gradle​

Add the following dependency to your build.gradle:

implementation("com.cognaize:cognaizesecurity:1.0")

Step 3: Create Role Enum​

Create a Role enum in your project as follows:

import com.cognaize.cognaizesecurity.dto.security.role.IRole;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.annotation.JsonValue;
import com.google.common.collect.Maps;
import java.util.Map;
import lombok.Getter;

@Getter
public enum Role implements IRole {
  @JsonProperty("security.rolegroup.read")
  SEC_ROLE_GROUP_READ(
      Role.Name.R_SEC_ROLE_GROUP_READ, "Read role group"),

  @JsonProperty("log.create")
  LOG_CREATE(Role.Name.R_LOG_CREATE, "Create log"),
  @JsonProperty("log.read")
  LOG_READ(Role.Name.R_LOG_READ, "Read log");

  @JsonValue
  private final String roleName;
  private final String description;

  Role(String name, String description) {
    this.roleName = name.replaceFirst("ROLE_", "");
    this.description = description;
  }

  public static final class Name {
    public static final String R_LOG_CREATE = "ROLE_log.create";
    public static final String R_LOG_READ = "ROLE_log.read";

    private Name() {
      super();
    }
  }
}

Step 4: Create Spring Boot Configuration​

Create a Spring Boot configuration class:

@Configuration
public class RolesConfig {

  @Bean
  List<IRole> roles() {
    return Lists.newArrayList(Role.values());
  }
}

Step 5: Create Configuration YAML​

Configure your application with the following application.yml

spring:
  security:
    realm: ${KEYCLOAK_REALM:cognaize-realm}
    admin:
      uri: ${KEYCLOAK_URI:https://keycloak-url}
      realm: ${KEYCLOAK_ADMIN_REALM:master}
      client: ${KEYCLOAK_ADMIN_CLIENT:admin-cli}
      clientSecret: ${KEYCLOAK_ADMIN_CLIENT_SECRET:master-admin-cli-secret}
      userName: ${KEYCLOAK_ADMIN_USERNAME:admin}
      password: ${KEYCLOAK_ADMIN_PASSWORD:admin}
    jwt:
      client-id: ${KEYCLOAK_CLIENT:jwtclient}
      client-secret: ${KEYCLOAK_SECRET:{jwtclient-secret}}
    oauth2:
      client:
        provider:
          external:
            issuer-uri: https://keycloak-url/realms/cognaize-realm
        registration:
          allowOrigins:
            - https://mywebapp.cognaize.com
          external:
            provider: external
            client-name: ssoclient
            client-id: ssoclient
            scope:
              - openid
              - offline_access
              - profile
            authorization-grant-type: authorization_code
      resourceserver:
        jwt:
          issuer-uri: ${spring.security.admin.uri}/realms/${KEYCLOAK_REALM:realm}
          jwk-set-uri: ${spring.security.admin.uri}/realms/${KEYCLOAK_REALM:realm}/protocol/openid-connect/certs