From 286617f8a5c90426ab553b1aa372c4f32032ec4e Mon Sep 17 00:00:00 2001 From: Asaf Cohen Date: Thu, 27 Jan 2022 19:18:53 +0200 Subject: [PATCH] add java docs --- docs/reference/SDKs/java.mdx | 179 +++++++++++++++++++++++++++++++++ docs/reference/SDKs/nodejs.mdx | 8 +- docs/tutorials/quickstart.mdx | 1 + docusaurus.config.js | 1 + 4 files changed, 185 insertions(+), 4 deletions(-) create mode 100644 docs/reference/SDKs/java.mdx diff --git a/docs/reference/SDKs/java.mdx b/docs/reference/SDKs/java.mdx new file mode 100644 index 00000000..e2ecb356 --- /dev/null +++ b/docs/reference/SDKs/java.mdx @@ -0,0 +1,179 @@ +--- +sidebar_position: 3 +title: Java +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +# Java + +## Add the SDK to your Java application + +Init the Java SDK and check for permissions. + +1. Install the Permit.io SDK: + + + + +For [Maven](https://maven.apache.org/) projects, use: + +```xml + + io.permit + permit-sdk-java + 0.0.11 + +``` + + + + +For [Gradle](https://gradle.org/) projects, configure `permit-sdk-java` as a dependency in your `build.gradle`: + +```groovy +dependencies { + // ... + + implementation 'io.permit:permit-sdk-java:0.0.11' +} +``` + + + + +2. Create a new instance of the Permit SDK in your code: + You can find instructions on getting an API key [here](../../tutorials/quickstart#2-get-permitio-api-key) + +```java +import io.permit.sdk.Permit; +import io.permit.sdk.PermitConfig; + +// This line initializes the SDK and connects your Java app +// to the Permit.io PDP container you've set up in the previous step. +Permit permit = new Permit( + new PermitConfig.Builder("[YOUR_API_KEY]") + // in production, you might need to change this url to fit your deployment + .withPdpAddress("http://localhost:7000") + .build() + ); +``` + +3. Sync the user to the permissions system + +When the user first logins, and after you check if he authenticated successfully (i.e: by checking the JWT) +you need to declare the user in the permission system so you can run `permit.check()` on that user: + +```java +// init your user (only needed ONCE, after the user first logins successfully) +User user = new User.Builder("[A_USER_ID]") + .withEmail("johndoe@permit.io") + .withFirstName("John") + .withLastName("Doe") + // you can assign role to the user at login + .withRoles(new ArrayList<>(List.of(new AssignedRole[]{ + new AssignedRole("roleId", "tenantId"), + // example assign the user (at login) to the default tenant with an admin role + new AssignedRole("admin", "default"), + }))) + .build(); + +// You need to call sync user in order to create the user in the +// permission system and be able to ask permit.check() on that user +permit.api.syncUser(user); +``` + +4. Check for permissions: + +```java +import io.permit.sdk.enforcement.Resource; +import io.permit.sdk.enforcement.User; + +boolean permitted = permit.check( + user, + "create", + Resource.fromString("document") +); + +if (permitted) { + System.out.println("User is PERMITTED to create a document"); +} else { + System.out.println("User is NOT PERMITTED to create a document"); +} +``` + +## Full app example + +Assuming a Spring Boot app with a single file, with the SDK installed: + +```java +package com.example.myproject; + +import io.permit.sdk.Permit; +import io.permit.sdk.PermitConfig; +import io.permit.sdk.api.PermitApiException; +import io.permit.sdk.enforcement.Resource; +import io.permit.sdk.enforcement.User; +import org.springframework.boot.SpringApplication; +import org.springframework.boot.autoconfigure.SpringBootApplication; +import org.springframework.http.HttpStatus; +import org.springframework.http.ResponseEntity; +import org.springframework.web.bind.annotation.GetMapping; +import org.springframework.web.bind.annotation.RestController; + +import java.io.IOException; + +@RestController +@SpringBootApplication +public class DemoApplication { + // You can open http://localhost:4000 to invoke this http + // endpoint, and see the outcome of the permission check. + @GetMapping("/") + ResponseEntity home() throws IOException, PermitApiException { + // init the permit SDK + Permit permit = new Permit( + new PermitConfig.Builder("[YOUR_API_KEY]") + // in production, you might need to change this url to fit your deployment + .withPdpAddress("http://localhost:7000") + .build() + ); + + // init your user (only needed ONCE, after the user first logins successfully) + User user = new User.Builder("[A_USER_ID]") + .withEmail("johndoe@permit.io") + .withFirstName("John") + .withLastName("Doe") + .withRoles(new ArrayList<>(List.of(new AssignedRole[]{ + new AssignedRole("roleId", "tenantId"), + // assign the user the admin role inside the default tenant + new AssignedRole("admin", "default"), + }))) + .build(); + + // You need to call sync user in order to create the user in the + // permission system and be able to ask permit.check() on that user + permit.api.syncUser(user); + + boolean permitted = permit.check( + user, // you may also call User.fromString("[A_USER_ID]"), + "create", + Resource.fromString("document") + ); + + if (permitted) { + return ResponseEntity.status(HttpStatus.OK).body( + "User is PERMITTED to create a document" + ); + } else { + return ResponseEntity.status(HttpStatus.FORBIDDEN).body( + "User is NOT PERMITTED to create a document" + ); + } + } + + public static void main(String[] args) { + SpringApplication.run(DemoApplication.class, args); + } +} +``` diff --git a/docs/reference/SDKs/nodejs.mdx b/docs/reference/SDKs/nodejs.mdx index 42bfeab8..977fa212 100644 --- a/docs/reference/SDKs/nodejs.mdx +++ b/docs/reference/SDKs/nodejs.mdx @@ -22,7 +22,7 @@ const { Permit } = require("permitio"); ``` 3. Create a new instance of the SDK: -You can find instructions on getting an API key [here](../../tutorials/quickstart#2-get-permitio-api-key) + You can find instructions on getting an API key [here](../../tutorials/quickstart#2-get-permitio-api-key) ```js // This line initializes the SDK and connects your Node.js app @@ -40,9 +40,9 @@ const permit = new Permit({ ```js const permitted = await permit.check(user.id, "create", "document"); if (permitted) { - console.log("User is permitted to create a document"); + console.log("User is PERMITTED to create a document"); } else { - console.log("is NOT PERMITTED to create document!"); + console.log("User is NOT PERMITTED to create a document"); } ``` @@ -72,7 +72,7 @@ app.get("/", async (req, res) => { // Example user object // You would usually get the user from your authenticantion layer (e.g. Auth0, Cognito, etc) via a JWT token or a database. const user = { - id: "[A_USER_ID]",]]", + id: "[A_USER_ID]", firstName: "John", lastName: "Doe", email: "johndoe@permit.io", diff --git a/docs/tutorials/quickstart.mdx b/docs/tutorials/quickstart.mdx index b4f12a69..c04594cf 100644 --- a/docs/tutorials/quickstart.mdx +++ b/docs/tutorials/quickstart.mdx @@ -39,5 +39,6 @@ docker run \ 1. [Node.js](/reference/SDKs/nodejs) 2. [Python](/reference/SDKs/python) +3. [Java](/reference/SDKs/java) more SDKs coming soon... diff --git a/docusaurus.config.js b/docusaurus.config.js index ddc3a872..6a9d0e04 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -106,6 +106,7 @@ const config = { prism: { theme: lightCodeTheme, darkTheme: darkCodeTheme, + additionalLanguages: ["java", "csharp", "groovy"], }, //search configuration ...searchConfig,