omkar-tenkale / ktor-role-based-auth

A simple yet powerful role based authorization plugin for ktor server

UPDATE: Read official announcement for role based auth in Ktor 2023 roadmap
Simplifying support for authorization and authentication. Providing end-to-end support for database authentication and session management, as well as role-based authorization

Ktor Role based Auth

ktor-role-based-auth is an easy to use and intuitive role-based access control library for Ktor Server

It works with the official ktor-server-auth library and adds role based authorization on top of it

Supported methods

• HTTP authentication (Basic/Digest/Bearer)
• Form-based authentication
• JWT
• Session
• OAuth
• LDAP
• Custom authentication

Installation

Step 1. Add the JitPack repository in build.gradle.kts

repositories {
    mavenCentral()
    maven { url = uri("https://jitpack.io") }
}

Step 2. Add the dependency

dependencies {
    implementation("com.github.omkar-tenkale:ktor-role-based-auth:0.2.0")
}

Usage

Initialize the plugin when configuring authentication

fun Application.configureSecurity(){
    authentication {
        jwt {
            // Configure jwt authentication
        }
        roleBased {
            extractRoles { principal ->
                //Extract roles from JWT payload
                (principal as JWTPrincipal).payload.claims?.get("roles")?.asList(String::class.java)?.toSet() ?: emptySet()
            }
        }
    }
}

fun Application.routing() {
    route("/") {
        
        //No authentication required to access this route
        get {
            call.respondText("Welcome!")
        }

        authenticate {

            //JWT authenticated route
            route("/profile") {
                get {
                    call.respondText("Joined: 2 years ago")
                }
            }

            //JWT authenticated + role authorized route
            route("/dashboard") {
                withAnyRole("ADMIN", "SUPER_ADMIN") {
                    get {
                        call.respondText("Total users: 2443")
                    }
                }
            }
            
            //JWT authenticated + role authorized route
            route("/system-stats") {
                withRole("SUPER_ADMIN") {
                    get {
                        call.respondText("CPU: 34%")
                    }
                }
            }
        }
    }
}

The plugin responds with 403 (Forbidden) by default if roles don't match Optionally, follow these steps to send a custom response

1. Set throwErrorOnUnauthorizedResponse to true

fun Application.configureSecurity(){
    authentication {
        jwt {
            // Configure jwt authentication
        }
        roleBased {
            extractRoles { principal ->
                //Extract roles from JWT payload
                (principal as JWTPrincipal).payload.claims?.get("roles")?.asList(String::class.java)?.toSet() ?: emptySet()
            }
            throwErrorOnUnauthorizedResponse = true
        }
    }
}

2. Catch the UnauthorizedAccessException exception globally with help of StatusPages plugin

fun Application.configureSecurity() {
    install(StatusPages) {
        exception<Throwable> { call, cause ->
            if (cause is UnauthorizedAccessException) {
                call.respondText(text = "You don't have enough permissions to access this route", status = HttpStatusCode.Forbidden)
            }
        }
    }
}

For complete example, Check out tests

Thanks

• Joris Portegies Zwart - Original implementation with pipelines and phases for older ktor versions

ktor-role-based-auth's Issues

create a new pipeline

I have a big problem, maybe you can help.
I have an api, with Ktor, that receives an encrypted JWT token.
I need to create a pipeline to decrypt it before entering the authentication phase.
my method is
String.decrypt()
it accepts an encrypted string and returns a string
As an example, I get

MIAGCSqGSIb3DQEHA6CAMIACAQAxggLIMIICxAIBADCBqzCBkjELMAkGA1UEBhMCQlIxETAPBgNVBAgMCE1hcmFuaGFvMREwDwYDVQQHDAhTYW8gTHVpczEVMBMGA1UECgwMVFIgU29sdXRpb25zMRowGAYDVQQDDBEqLnRyc29sdXRpb25zLmNvbTEqMCgGCSqGSIb3DQEJARYbcm9kcmlnb19kZXZlbG1zQGhvdG1haWwuY29tAhRRj2k/Y1nMRD9Ywg3SorVzgT2UCTANBgkqhkiG9w0BAQEFAASCAgAlKpNm335GymToookeZS7SIbgzja2otRt+pGg1lFZCkcqk783apxy7DKorQBKwKuFanq5Y+SUuZKBMXGIbPF5fayXwU+UreGihswR30Ugup7i09nG6lw+l6//nn2dZWIoLL5zcCbrUXdMrHwuMst1wD5OOPjrJ2/08JVsqGbscDP+IRrfpLunOdjC7i+N9HieTyriVqUSxL9RMoTWxJXClxkbdexthngZp7kF4+pSHXKVCima7v9AIU/4+C3Ws2ixbrFQDuyllSc4jI4H4HuL/q1x42ENoCVgBYhGuuOtVY0PeBfV2//l5VOfqfwa1OBC1Uzm0IPWsNeIe7MwI7PpPHURte1/ANLTacaqzYaZO+OC3/wcTX8dgdiS1nqme1k11lp+zRWQV0CygfvCzoYKBusG5iNH3XdXc25SXP2ZoRzgRIoFZgVnlkoYGsYXdfdus+JNbP2o1e8+Y0NyHvQSpX7qx08uL2oEbW1i0q/BaT5b1riB8/eDvFdUzxiHv6etuxjUJDvKoEZHoiIYZZm3DwBfz12QpBIfCPl1WwafIk4v62JhImBvK3HM+GtSjogCmauFTtE9vEpD0bNGCcoUbKwLdlFZEiX6GuLEkM5RVtnmqvR6Zq+rXpSfA1VAbawNe58v4k/OOeWs6ZxTEbTbNqeAfVGod/Q4/z2KTukO3bjCABgkqhkiG9w0BBwEwHQYJYIZIAWUDBAEqBBDDtm14PPXdQJewx3HiGEIzgIICkJ81QxOAamSExdknDLZYSSPM6I1PK5qrj7vDk/nf80A3vHwN0BeUtZs2W812DWnvgUlb6XHwGEKNZxPdCN3HSh5ZtkG0OKInpgKKpThag+LlKe1i/lxqF6slhmlg1M/ZxvyFjkcs889yv6CUQv8jAYvcS3NkACl8R0NG/ecqk9QPq5Hlzs9B5Ifsiq5W3HUbBHb16+gIeinGDAG7Kipyh1hsInE0SNaPyDHafpEuyPh19oBnxHXEh7mObAwu33LcaHMp4PelI5PNf4/1B/2mDOEuoCvd69LP3lKvWfTN+WGCA0N4I93lCyLBFX/O6BNLkubBqPqTZV+AKFpBtfPCE+kt2VZgUY1dCQ9cgqynMYpctfEalQMQxkzoH8B+5PbH1Jv/ZB0FF1wSJdE85azmoQmKshkS2AopOOce2WYIvME9b+HLym0y6DaMF16mdoDCHwHr8pIvMJkbSIuCcspolqoTvAyZcOvkf+GTSJu0epUbb5znMs+Hn8fDl+nmRAOt6smzXwymHeuE/7pykO4QeH/edCQzMfKxWIBBPW9S/mTdSSMBNJ/TPLL2NDd1i4zAAgS3C2kng46h7GQyBZ+6nunI/3l/fW9+RdYDcikXxyewkS8OPzSbEzgzpvlK0w/J90eVyFMYHkRxQGwerOFzTItDn31TGgFIUkq54Hr9vIhi00cmvkVixdfHjOepOLZ10Nsf5aRTrYpWJeR487iZrNxi5gMA0FS6aNek+EPgY+HNpgKHh1T9IyZglRildvWTyq7/t254KzjUB15xqirtjB/kcBSIROFZ047/e6nLJhRWvqzMLPozNwEb0R7pcazES5WOLeFIeOgH62klQAzJ36icmAJmpXJ24uprONLlpNH3AAAAAAAAAAA=

and have to return
Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

io.ktor.server.application.DuplicatePluginException when using an RBAC route

whenever i add the rbac functions to a route, i get a DuplicatePluginException, when i check the code, it is trying to install the plugin on every request, why is this and how to solve it?

i.e.

fun Route.withAnyRole(roles: Set<Role>, build: suspend PipelineContext<Unit, ApplicationCall>.() -> Unit) {
    install(RoleBasedAuthPlugin) {
        any = roles.toSet()
    }
    handle { build() }
}