From aac59bc0609a9433bebf093b0a4f211098e183cb Mon Sep 17 00:00:00 2001 From: mayabarak Date: Thu, 11 Jul 2024 17:55:47 +0300 Subject: [PATCH 01/13] add login doc --- docs/embeddable-uis/element-login.mdx | 211 ++++++++++++++++++ .../element/user-management.mdx | 2 +- src/components/elements/codeBlock.json | 4 +- 3 files changed, 214 insertions(+), 3 deletions(-) create mode 100644 docs/embeddable-uis/element-login.mdx diff --git a/docs/embeddable-uis/element-login.mdx b/docs/embeddable-uis/element-login.mdx new file mode 100644 index 00000000..3580e1fd --- /dev/null +++ b/docs/embeddable-uis/element-login.mdx @@ -0,0 +1,211 @@ +--- +sidebar_position: 1 +title: Login Method +--- + +import HelpSupportTile from "@site/src/components/elements/HelpSupportTile.js"; +import ActionContainer from "@site/src/components/elements/ActionContainer.js"; +import ActionTile from "@site/src/components/elements/ActionTile.js"; +import CodeDropdown from "@site/src/components/elements/CodeDropdown.js"; +import FlexWrapper from "@site/src/components/elements/FlexWrapper.js"; +import code from "@site/src/components/elements/codeBlock.json"; + +import userManagementElementInstances from "/static/ui-videos/embeddable-uis/user-management-element.mp4"; + +The Login Method for Permit Elements is a simple and secure way to embed Permit Elements into your application. + +### Server-side Login method + +In the server side, We have the `loginAs` function takes two parameters. +You need to pass in the unique `userId` you get from your **JWT** (JSON Web Token),and a `tenant_key` or `tenantId`. +Passing in the tenant is **compulsory** when logging in a user **server-side**. + +```js +permit.elements.loginAs({ userId, tenant }); +``` +:::info IMPORTANT +The **user must belong to the tenant** that he will be logged into. If he is not, you will see a login error saying `USER_NOT_FOUND`. + +If the user gets logged out, he also exits the current tenant specificed in the `loginAs` method. If you want to **change tenants** for +a user, you need to **log them out**, and **log them back in** to a different tenant. +::: + + + +##### How to use the `loginAs` function + +You need to create a route in your backend server to allow your client to `loginAs` themselves and get access the Permit Element. + +The backend `loginAs` route is matched based on the Authentication methods you have implemented inside your App. Most applications +authenticate with the **Bearer Token** or **Cookies**, but we also allows you to use any other **HTTP Security Header**. The important +part here is, that you use the appropriate code example below based on your Authentication method. + + + + + + + If you use custom Authentication Header to authenticate to your backend, add this route to your + backend. + + + For FrontendOnly Login, please check our [Embedded Elements](/embeddable-uis/overview) documentation. + + +### Install Permit-js + +Once you have your application ready, you need to install Permits's JS SDK. This gives you access to our prebuilt embeddable Element components. + +Run the following command to install the Permit-js SDK in your project: + +```bash +npm install @permitio/permit-js +``` + + +### Client-side login method + +In the client side, you need to call the `login` function to log in the user. This function is used to log in the user to the Permit Element +and get access to the Element. + +This is the permit element object that is calling the backend route we have +configured previously and logging in the user. + +```js +permit.elements.login({ + loginUrl: 'https://your_app_url.com/login_cookie, + tenant: 'your_tenant_key', + token:'', + loginMethod: LoginMethod.bearer + }).then((res: any) => {//optional handle success + }).catch((err: any) => {//handle error + });", +``` + +There are few things that need to be configured here: + +1. `loginUrl` - The url that corresponds to your backend login route you created in the last step. +2. `loginMethod` - The login method you are using in your backend. +3. `tenant` (Optional) - Required for frontendOnly login method. the name of the tenant that the user is part of, you can set it at your backend as well, if you are using frontendOnly this is required. +4. `token` (Optional) - Required for bearer token login method, you need to pass the token here. +5. `headers` (Optional) - Required for custom headers login method, you need to pass the headers here. +6. `userJwt` (Optional) - Required for frontendOnly login method, you need to pass the user jwt here. +7. `envId` (Optional) - Required for frontendOnly login method, you need to pass the env id here. + + +This function should be called as early as possible in your App. This is best done inside a `App`/`index` file; **right after** the users +had just had their identity confirmed by the Authorization provider you are using, but **just before** the Embedded component is loaded. + +With any of these login frontend methods, it's **optional** to pass in your **tenant key**, in comparison to the server-side call where **it +is required**. The server-side tenant will **always take precedence**. We do however encourage passing in the same tenant in your frontend +and backend login calls for best practices and for adding clarity to your code. + +##### How to use the `login` function + +There are **4 supported login options** choose the one that you are using in your backend. + + + The **loginMethod** here should be set to: `LoginMethod: LoginMethod.cookie`. + + + + The **loginMethod** here should be set to: `LoginMethod: LoginMethod.bearer` and the **token** + should be set to the current user token. + + + + The **loginMethod** here should be set to: `LoginMethod: LoginMethod.header` + and you should pass the **headers** to the current user auth headers. + + + For FrontendOnly Login, please check our [Embedded Elements](/embeddable-uis/overview) documentation. + + +After you run login successfully you will **get a cookie** called `permit_session` which will allow you to +load your Permit Element securely and successfully. + +### Client-side logout method + +This function should be called along with the logging-out logic that you have within your App, to make sure the user does not +continue to have access to the Permit Element. + +This logout method **should be called** as part of the logic of logging your user out with your +authentication solution. + +```javascript +permit.elements.logout(); +``` + +### Login Errors + +There are a few possible errors you might find yourself come across while working with the embedding of Permit Elements. + +| Error | Description | +| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `USER_NOT_FOUND` | This error can appear if you are trying to log in as a particular user, but that **user does not exist within Permit**. You can also experience this login error when you are trying to login a user into a **tenant that he does not belong to**. | +| `TENANT_NOT_FOUND` | This error can appear when you are passing in a tenant, either in the frontend `permit.elements.login` function, or in your backend URL endpoint, where the tenant has not been created in Permit. | +| `INVALID_PERMISSION_LEVEL` | This error will emerge when you are trying to access part of the Element which you have not been given access too. This usually means the role that the person obtained has remained in the **Hidden Roles** permission level. | +| `FORBIDDEN_ACCESS` | This error will emerge when you are trying to login to an Element you have not been given permission to see. | + diff --git a/docs/embeddable-uis/element/user-management.mdx b/docs/embeddable-uis/element/user-management.mdx index fc7b1ce9..969a9e87 100644 --- a/docs/embeddable-uis/element/user-management.mdx +++ b/docs/embeddable-uis/element/user-management.mdx @@ -12,7 +12,7 @@ import code from "@site/src/components/elements/codeBlock.json"; import userManagementElementInstances from "/static/ui-videos/embeddable-uis/user-management-element.mp4"; -# User Management Element +# z Effortlessly manage users and their permissions as a single secure, embeddable UI component. diff --git a/src/components/elements/codeBlock.json b/src/components/elements/codeBlock.json index f9fcb83b..140c3a5d 100644 --- a/src/components/elements/codeBlock.json +++ b/src/components/elements/codeBlock.json @@ -16,9 +16,9 @@ "bearer_dotnet": "using PermitSDK;\n namespace PermitOnboardingApp\n {\n class HttpServer\n {\n public static HttpListener listener;\n public static string url = \"http://localhost:4000/login_cookie\";\n public static async Task HandleIncomingConnections()\n {\n bool runServer = true;\n while (runServer)\n HttpListenerContext ctx = await listener.GetContextAsync();\n HttpListenerResponse resp = ctx.Response;\n // In the next 6 lines we have the acutal code that is relevant to the Permit SDK\n // string testUserId = getUserIdFromJWT();\n EmbeddedLoginContentRequestOutput ticket = await permit.Elements.LoginAs(testUserId, TENANT_ID);\n byte[] data = Encoding.UTF8.GetBytes(ticket.Content);\n resp.StatusCode = 200;\n await resp.OutputStream.WriteAsync(data, 0, data.Length);\n resp.OutputStream.Close();\n }\n public static void Main(string[] args)\n {\n // Create a Http server and start listening for incoming connections\n listener = new HttpListener();\n listener.Prefixes.Add(url);\n listener.Start();\n Console.WriteLine(\"Listening for connections on {0}\", url);\n // Handle requests\n Task listenTask = HandleIncomingConnections();\n listenTask.GetAwaiter().GetResult();\n // Close the listener\n listener.Close();\n }\n }\n }\n ", "bearer": "@routes.get('/permit/login')\nasync def login(request):\n tenant = request.query.get('tenant', 'default')\n user_id = session.get_user_identifier(session)\n token, url = await permit.elements.login_as(user_id, tenant)\n url_obj = {'url': url}\n return JsonResponse(text=f'{json.dumps(url_obj)}', content_type='application/json')", "loginHeaders": "permit.elements.login({\n loginUrl: backendUrl,\n tenant: 'your_tenant_key',\n loginMethod: LoginMethod.bearer,\n token: JWT_secret\n}).then((res: any) => {//optional handle success\n }).catch((err: any) => {//handle error\n});", - "elementLogin": "permit.elements.login({\n loginUrl: 'https://your_app_url.com/permit_login,\n tenant: 'your_tenant_key',\n token:'',\n loginMethod: LoginMethod.bearer\n}).then((res: any) => {//optional handle success\n }).catch((err: any) => {//handle error\n});", + "elementLogin": "permit.elements.login({\n loginUrl: 'https://your_app_url.com/login_cookie,\n tenant: 'your_tenant_key',\n token:'',\n loginMethod: LoginMethod.bearer\n}).then((res: any) => {//optional handle success\n }).catch((err: any) => {//handle error\n});", "frontendOnlyLogin": "permit.elements.login({\n loginMethod:LoginMethod.frontendOnly,\n userJwt: ,\n tenant:,\n envId: }).then((res: any) => {\n console.log('success', res);\n}).catch((err: any) => {\n // you can handle the error either here or in your BE\n console.log('err', err);\n});", "elementLogout": "permit.elements.logout();", - "loginDefault": "permit.elements.login({\n loginUrl: 'https://your_app_url.com/permit_login,\n tenant: 'your_tenant_key'\n}).then((res: any) => {//optional handle success\n }).catch((err: any) => {//handle error\n});", + "loginDefault": "permit.elements.login({\n loginUrl: 'https://your_app_url.com/login_cookie,\n tenant: 'your_tenant_key'\n}).then((res: any) => {//optional handle success\n }).catch((err: any) => {//handle error\n});", "other_headers": "permit.elements.login({\n loginUrl: backendUrl,\n tenant: 'your_tenant_key',\n loginMethod: LoginMethod.header,\n headers: {'': 'secret'}\n}).then((res: any) => {//optional handle success\n }).catch((err: any) => {//handle error\n});" } \ No newline at end of file From 5197cd63ae56cd2934fd6a6f5cc3789cd16ded94 Mon Sep 17 00:00:00 2001 From: mayabarak Date: Thu, 11 Jul 2024 18:07:46 +0300 Subject: [PATCH 02/13] remove login from elements docs and move operation approval api file --- .../examples}/operation_approval.mdx | 0 docs/embeddable-uis/element-login.mdx | 21 +- .../embeddable-uis/element/access-request.mdx | 266 -------------- .../element/approval-management.mdx | 252 ------------- docs/embeddable-uis/element/audit-logs.mdx | 295 --------------- .../element/operation-approval.mdx | 250 ------------- .../element/user-management.mdx | 347 ------------------ 7 files changed, 20 insertions(+), 1411 deletions(-) rename docs/{embeddable-uis/element => api/examples}/operation_approval.mdx (100%) diff --git a/docs/embeddable-uis/element/operation_approval.mdx b/docs/api/examples/operation_approval.mdx similarity index 100% rename from docs/embeddable-uis/element/operation_approval.mdx rename to docs/api/examples/operation_approval.mdx diff --git a/docs/embeddable-uis/element-login.mdx b/docs/embeddable-uis/element-login.mdx index 3580e1fd..865e4182 100644 --- a/docs/embeddable-uis/element-login.mdx +++ b/docs/embeddable-uis/element-login.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +sidebar_position: 6 title: Login Method --- @@ -34,6 +34,25 @@ a user, you need to **log them out**, and **log them back in** to a different te ##### How to use the `loginAs` function +### Initializing Permit + + + {/* If you are already using Permit, you can skip this step. */} + In order to use Permit Elements, you need to be a **user of Permit**. When starting to use Permit, you will need to + initialize an instance of Permit in your backend logic. This **only needs to be done once**, both to use Permit and + Elements. + Please remember to copy your `SDK Secret Key` and pass it into the initialized Permit object. + + + + You need to create a route in your backend server to allow your client to `loginAs` themselves and get access the Permit Element. The backend `loginAs` route is matched based on the Authentication methods you have implemented inside your App. Most applications diff --git a/docs/embeddable-uis/element/access-request.mdx b/docs/embeddable-uis/element/access-request.mdx index 29079ccc..3e530911 100644 --- a/docs/embeddable-uis/element/access-request.mdx +++ b/docs/embeddable-uis/element/access-request.mdx @@ -141,269 +141,3 @@ Once the iframe is ready, we need to embed it. To do that, you'll need to create allowFullScreen > - -### Initializing Permit - - - {/* If you are already using Permit, you can skip this step. */} - In order to use Permit Elements, you need to be a **user of Permit**. When starting to use Permit, you will need to - initialize an instance of Permit in your backend logic. This **only needs to be done once**, both to use Permit and - Elements. - Please remember to copy your `SDK Secret Key` and pass it into the initialized Permit object. - - - -### Server-side Login Route - -You need to create a route in your backend server to allow your client to `loginAs` themselves and get access the Permit Element. - -The backend `loginAs` route is matched based on the Authentication methods you have implemented inside your App. Most applications -authenticate with the **Bearer Token** or **Cookies**, but we also allows you to use any other **HTTP Security Header**. The important -part here is, that you use the appropriate code example below based on your Authentication method. - -The `loginAs` function takes two parameters. You need to pass in the unique `userId` you get from your **JWT** (JSON Web Token), -and a `tenant_key` or `tenantId`. - -```js -permit.elements.loginAs({ userId, tenant }); -``` - -:::info IMPORTANT -The **user must belong to the tenant** that he will be logged into. If he is not, you will see a login error saying `USER_NOT_FOUND`. - -If the user gets logged out, he also exits the current tenant specificed in the `loginAs` method. If you want to **change tenants** for -a user, you need to **log them out**, and **log them back in** to a different tenant. -::: - -Passing in the tenant is **compulsory** when logging in a user **server-side**. - - - - - - - If you use custom Authentication Header to authenticate to your backend, add - this route to your backend. - - - First open your Permit Dashboard and go to the **Elements** page. Then click - on **Configure JWKS** on the upper left corner and add your JWKS to the - dialog. Then paste your JWKS into the text dialog and click **OK**. - _![Configure JWKS](/img/elements/configure-jwks.png)_ Now make sure that your - Permit user key is the same as the jwt sub. You can see your permit user key - in the **Users** page in the Permit Dashboard. You can see your jwt sub with - sites like [jwt.io](https://jwt.io/). Just paste your jwt token into the text - dialog check in the left side the sub field. - - -### Install Permit-js - -Once you have your application ready, you need to install Permits's JS SDK. This gives you access to our prebuilt embeddable Element components. - - - Add the Permit JavaScript SDK to you app: - - -### Client-side login method - -This function should be called as early as possible in your App. This is best done inside a `App`/`index` file; **right after** the users -had just had their identity confirmed by the Authorization provider you are using, but **just before** the Embededd component is loaded. - -With any of these login frontend methods, it's **optional** to pass in your **tenant key**, in comparison to the server-side call where **it -is required**. The server-side tenant will **always take precedence**. We do however encourage passing in the same tenant in your frontend -and backend login calls for best practices and for adding clarity to your code. - - - This is the permit element object that is calling the backend route we have - configured previously and logging in the user. - - - -There are **four** things that need to be configured here: - -1. `loginUrl` - The url that corresponds to your backend login route you created in the last step. -2. `loginMethod` - The login method you are using in your backend. -3. `tenant` (Optional) - Required for frontendOnly login method. the name of the tenant that the user is part of, you can set it at your backend as well, if you are using frontendOnly this is required. -4. `token` (Optional) - Required for bearer token login method, you need to pass the token here. -5. `headers` (Optional) - Required for custom headers login method, you need to pass the headers here. -6. `userJwt` (Optional) - Required for frontendOnly login method, you need to pass the user jwt here. -7. `envId` (Optional) - Required for frontendOnly login method, you need to pass the env id here. - -There are **4 supported login options** choose the one that you are using in your backend. - - - The **loginMethod** here should be set to: `LoginMethod: LoginMethod.cookie`. - - - - The **loginMethod** here should be set to: `LoginMethod: LoginMethod.bearer` - and the **token** should be set to the current user token. - - - - The **loginMethod** here should be set to: `LoginMethod: LoginMethod.header` - and you should pass the **headers** to the current user auth headers. - - - The **loginMethod** here should be set to: `LoginMethod: LoginMethod.frontendOnly` - **userJwt** should be set to the current user token. - **tenant** should be set to the tenant you want to get access to, the current user must have role assigned to him in - this tenant. - **envId** should be set to the environment id you want to get access to, you need to make sure you have set the JWKS - in this env see step 2.4, you can get your env id with [this api - call](https://api.permit.io/v2/docs#/Environments/list_environments).Or take it from the get code dialog in the - Permit Elements Dashboard. - **userKeyClaim** (Optional) - Optional for frontendOnly login method, if your user key in Permit isn't the same as - the jwt `sub` claim, you need to pass the key of the claim here. - - -After you run login successfully you will **get a cookie** called `permit_session` which will allow you to -load your Permit Element securly and successfully. - -### Client-side logout method - -This function should be called along with the logging-out logic that you have within your App, to make sure the user does not -continue to have access to the Permit Element. - - - This logout method **should be called** as part of the logic of logging your - user out with your authentication solution. - - -### Login Errors - -There are a few possible errors you might find yourself come across while working with the embedding of Permit Elements. - -| Error | Description | -| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `USER_NOT_FOUND` | This error can appear if you are trying to log in as a particular user, but that **user does not exist within Permit**. You can also experience this login error when you are trying to login a user into a **tenant that he does not belong to**. | -| `TENANT_NOT_FOUND` | This error can appear when you are passing in a tenant, either in the frontend `permit.elements.login` function, or in your backend URL endpoint, where the tenant has not been created in Permit. | -| `INVALID_PERMISSION_LEVEL` | This error will emerge when you are trying to access part of the Element which you have not been given access too. This usually means the role that the person obtained has remained in the **Hidden Roles** permission level. | -| `FORBIDDEN_ACCESS` | This error will emerge when you are trying to login to an Element you have not been given permission to see. | - - - - -### Early Access - -Permit.io Approval Flows is currently in Early Access, and we will gradually open the feature to more users. -If you are interested in participating, please fill out the form below - - - diff --git a/docs/embeddable-uis/element/approval-management.mdx b/docs/embeddable-uis/element/approval-management.mdx index 87cbdbe8..8ad279a4 100644 --- a/docs/embeddable-uis/element/approval-management.mdx +++ b/docs/embeddable-uis/element/approval-management.mdx @@ -126,255 +126,3 @@ Once the iframe is ready, we need to embed it. To do that, you'll need to create allowFullScreen > - -### Initializing Permit - - - {/* If you are already using Permit, you can skip this step. */} - In order to use Permit Elements, you need to be a **user of Permit**. When starting to use Permit, you will need to - initialize an instance of Permit in your backend logic. This **only needs to be done once**, both to use Permit and - Elements. - Please remember to copy your `SDK Secret Key` and pass it into the initialized Permit object. - - - -### Server-side Login Route - -You need to create a route in your backend server to allow your client to `loginAs` themselves and get access the Permit Element. - -The backend `loginAs` route is matched based on the Authentication methods you have implemented inside your App. Most applications -authenticate with the **Bearer Token** or **Cookies**, but we also allows you to use any other **HTTP Security Header**. The important -part here is, that you use the appropriate code example below based on your Authentication method. - -The `loginAs` function takes two parameters. You need to pass in the unique `userId` you get from your **JWT** (JSON Web Token), -and a `tenant_key` or `tenantId`. - -```js -permit.elements.loginAs({ userId, tenant }); -``` - -:::info IMPORTANT -The **user must belong to the tenant** that he will be logged into. If he is not, you will see a login error saying `USER_NOT_FOUND`. - -If the user gets logged out, he also exits the current tenant specificed in the `loginAs` method. If you want to **change tenants** for -a user, you need to **log them out**, and **log them back in** to a different tenant. -::: - -Passing in the tenant is **compulsory** when logging in a user **server-side**. - - - - - - - If you use custom Authentication Header to authenticate to your backend, add - this route to your backend. - - - First open your Permit Dashboard and go to the **Elements** page. Then click - on **Configure JWKS** on the upper left corner and add your JWKS to the - dialog. Then paste your JWKS into the text dialog and click **OK**. - _![Configure JWKS](/img/elements/configure-jwks.png)_ Now make sure that your - Permit user key is the same as the jwt sub. You can see your permit user key - in the **Users** page in the Permit Dashboard. You can see your jwt sub with - sites like [jwt.io](https://jwt.io/). Just paste your jwt token into the text - dialog check in the left side the sub field. - - -### Install Permit-js - -Once you have your application ready, you need to install Permits's JS SDK. This gives you access to our prebuilt embeddable Element components. - - - Add the Permit JavaScript SDK to you app: - - -### Client-side login method - -This function should be called as early as possible in your App. This is best done inside a `App`/`index` file; **right after** the users -had just had their identity confirmed by the Authorization provider you are using, but **just before** the Embededd component is loaded. - -With any of these login frontend methods, it's **optional** to pass in your **tenant key**, in comparison to the server-side call where **it -is required**. The server-side tenant will **always take precedence**. We do however encourage passing in the same tenant in your frontend -and backend login calls for best practices and for adding clarity to your code. - - - This is the permit element object that is calling the backend route we have - configured previously and logging in the user. - - - -There are **four** things that need to be configured here: - -1. `loginUrl` - The url that corresponds to your backend login route you created in the last step. -2. `loginMethod` - The login method you are using in your backend. -3. `tenant` (Optional) - Required for frontendOnly login method. the name of the tenant that the user is part of, you can set it at your backend as well, if you are using frontendOnly this is required. -4. `token` (Optional) - Required for bearer token login method, you need to pass the token here. -5. `headers` (Optional) - Required for custom headers login method, you need to pass the headers here. -6. `userJwt` (Optional) - Required for frontendOnly login method, you need to pass the user jwt here. -7. `envId` (Optional) - Required for frontendOnly login method, you need to pass the env id here. - -There are **4 supported login options** choose the one that you are using in your backend. - - - The **loginMethod** here should be set to: `LoginMethod: LoginMethod.cookie`. - - - - The **loginMethod** here should be set to: `LoginMethod: LoginMethod.bearer` - and the **token** should be set to the current user token. - - - - The **loginMethod** here should be set to: `LoginMethod: LoginMethod.header` - and you should pass the **headers** to the current user auth headers. - - - The **loginMethod** here should be set to: `LoginMethod: LoginMethod.frontendOnly` - **userJwt** should be set to the current user token. - **tenant** should be set to the tenant you want to get access to, the current user must have role assigned to him in - this tenant. - **envId** should be set to the environment id you want to get access to, you need to make sure you have set the JWKS - in this env see step 2.4, you can get your env id with [this api - call](https://api.permit.io/v2/docs#/Environments/list_environments).Or take it from the get code dialog in the - Permit Elements Dashboard. - **userKeyClaim** (Optional) - Optional for frontendOnly login method, if your user key in Permit isn't the same as - the jwt `sub` claim, you need to pass the key of the claim here. - - -After you run login successfully you will **get a cookie** called `permit_session` which will allow you to -load your Permit Element securly and successfully. - -### Client-side logout method - -This function should be called along with the logging-out logic that you have within your App, to make sure the user does not -continue to have access to the Permit Element. - - - This logout method **should be called** as part of the logic of logging your - user out with your authentication solution. - - -### Login Errors - -There are a few possible errors you might find yourself come across while working with the embedding of Permit Elements. - -| Error | Description | -| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `USER_NOT_FOUND` | This error can appear if you are trying to log in as a particular user, but that **user does not exist within Permit**. You can also experience this login error when you are trying to login a user into a **tenant that he does not belong to**. | -| `TENANT_NOT_FOUND` | This error can appear when you are passing in a tenant, either in the frontend `permit.elements.login` function, or in your backend URL endpoint, where the tenant has not been created in Permit. | -| `INVALID_PERMISSION_LEVEL` | This error will emerge when you are trying to access part of the Element which you have not been given access too. This usually means the role that the person obtained has remained in the **Hidden Roles** permission level. | -| `FORBIDDEN_ACCESS` | This error will emerge when you are trying to login to an Element you have not been given permission to see. | - - - diff --git a/docs/embeddable-uis/element/audit-logs.mdx b/docs/embeddable-uis/element/audit-logs.mdx index d08aed2c..9a508104 100644 --- a/docs/embeddable-uis/element/audit-logs.mdx +++ b/docs/embeddable-uis/element/audit-logs.mdx @@ -37,298 +37,3 @@ _![Audit Logs Element](/img/elements/audit-logs-full.png)_ allowFullScreen > - -### Initializing Permit - - - {/* If you are already using Permit, you can skip this step. */} - In order to use Permit Elements, you need to be a **user of Permit**. When starting to use Permit, you will need to - initialize an instance of Permit in your backend logic. This **only needs to be done once**, both to use Permit and Elements. - Please remember to copy your `SDK Secret Key` and pass it into the initialized Permit object. - - - -### Server-side Login Route - -You need to create a route in your backend server to allow your client to `loginAs` themselves and get access the Permit Element. - -The backend `loginAs` route is matched based on the Authentication methods you have implemented inside your App. Most applications -authenticate with the **Bearer Token** or **Cookies**, but we also allows you to use any other **HTTP Security Header**. The important -part here is, that you use the appropriate code example below based on your Authentication method. - -The `loginAs` function takes two parameters. You need to pass in the unique `userId` you get from your **JWT** (JSON Web Token), -and a `tenant_key` or `tenantId`. - -```js -permit.elements.loginAs({ userId, tenant }); -``` - -:::info IMPORTANT -The **user must belong to the tenant** that he will be logged into. If he is not, you will see a login error saying `USER_NOT_FOUND`. - -If the user gets logged out, he also exits the current tenant specificed in the `loginAs` method. If you want to **change tenants** for -a user, you need to **log them out**, and **log them back in** to a different tenant. -::: - -Passing in the tenant is **compulsory** when logging in a user **server-side**. - - - - - - - If you use custom Authentication Header to authenticate to your backend, add - this route to your backend. - - - First open your Permit Dashboard and go to the **Elements** page. Then click - on **Configure JWKS** on the upper left corner and add your JWKS to the - dialog. Then paste your JWKS into the text dialog and click **OK**. - _![Configure JWKS](/img/elements/configure-jwks.png)_ Now make sure that your - Permit user key is the same as the jwt sub. You can see your permit user key - in the **Users** page in the Permit Dashboard. You can see your jwt sub with - sites like [jwt.io](https://jwt.io/). Just paste your jwt token into the text - dialog check in the left side the sub field. - - -### Install Permit-js - -Once you have your application ready, you need to install Permits's JS SDK. This gives you access to our prebuilt embeddable Element components. - - - Add the Permit JavaScript SDK to you app: - - -### Client-side login method - -This function should be called as early as possible in your App. This is best done inside a `App`/`index` file; **right after** the users -had just had their identity confirmed by the Authorization provider you are using, but **just before** the Embededd component is loaded. - -With any of these login frontend methods, it's **optional** to pass in your **tenant key**, in comparison to the server-side call where **it -is required**. The server-side tenant will **always take precedence**. We do however encourage passing in the same tenant in your frontend -and backend login calls for best practices and for adding clarity to your code. - - - This is the permit element object that is calling the backend route we have - configured previously and logging in the user. - - - -There are **four** things that need to be configured here: - -1. `loginUrl` - The url that corresponds to your backend login route you created in the last step. -2. `loginMethod` - The login method you are using in your backend. -3. `tenant` (Optional) - Required for frontendOnly login method. the name of the tenant that the user is part of, you can set it at your backend as well, if you are using frontendOnly this is required. -4. `token` (Optional) - Required for bearer token login method, you need to pass the token here. -5. `headers` (Optional) - Required for custom headers login method, you need to pass the headers here. -6. `userJwt` (Optional) - Required for frontendOnly login method, you need to pass the user jwt here. -7. `envId` (Optional) - Required for frontendOnly login method, you need to pass the env id here. - -There are **4 supported login options** choose the one that you are using in your backend. - - - The **loginMethod** here should be set to: `LoginMethod: LoginMethod.cookie`. - - - - The **loginMethod** here should be set to: `LoginMethod: LoginMethod.bearer` - and the **token** should be set to the current user token. - - - - The **loginMethod** here should be set to: `LoginMethod: LoginMethod.header` - and you should pass the **headers** to the current user auth headers. - - - The **loginMethod** here should be set to: `LoginMethod: LoginMethod.frontendOnly` - **userJwt** should be set to the current user token. - **tenant** should be set to the tenant you want to get access to, the current user must have role assigned to him in this tenant. - **envId** should be set to the environment id you want to get access to, you need to make sure you have set the JWKS in this env see step 2.4, you can get your env id with [this api call](https://api.permit.io/v2/docs#/Environments/list_environments).Or take it from the get code dialog in the Permit Elements Dashboard. - **userKeyClaim** (Optional) - Optional for frontendOnly login method, if your user key in Permit isn't the same as the jwt `sub` claim, you need to pass the key of the claim here. - - -After you run login successfully you will **get a cookie** called `permit_session` which will allow you to -load your Permit Element securly and successfully. - -### Client-side logout method - -This function should be called along with the logging-out logic that you have within your App, to make sure the user does not -continue to have access to the Permit Element. - - - This logout method **should be called** as part of the logic of logging your - user out with your authentication solution. - - -### Login Errors - -There are a few possible errors you might find yourself come across while working with the embedding of Permit Elements. - -| Error | Description | -| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `USER_NOT_FOUND` | This error can appear if you are trying to log in as a particular user, but that **user does not exist within Permit**. You can also experience this login error when you are trying to login a user into a **tenant that he does not belong to**. | -| `TENANT_NOT_FOUND` | This error can appear when you are passing in a tenant, either in the frontend `permit.elements.login` function, or in your backend URL endpoint, where the tenant has not been created in Permit. | -| `INVALID_PERMISSION_LEVEL` | This error will emerge when you are trying to access part of the Element which you have not been given access too. This usually means the role that the person obtained has remained in the **Hidden Roles** permission level. | -| `FORBIDDEN_ACCESS` | This error will emerge when you are trying to login to an Element you have not been given permission to see. | - -## Customizing your Element - -Each element offers customization and configuration. - -### Match your brand - -With every new element, you will be able to adjust several setting to make the look and feel of the element really your own. - -
-
    -
  • - - Change the background and primary colour of any element to match your - brand. - -
    • -
  • - - Give the element a title that makes sense to your end user, or hide it - fully. - -
    • -
  • - - Decide if you want to display your users Email, Full Name or both on the - element. - -
    • -
-
- -_![Audit Logs Element](/img/elements/configuration.png)_ - -## Embedding the iFrame - -After you finish configuring and customising your element, you are ready to it into your App. A code snippet for the element -will be generated for you. -This will be an ` - -### Initializing Permit - - - {/* If you are already using Permit, you can skip this step. */} - In order to use Permit Elements, you need to be a **user of Permit**. When starting to use Permit, you will need to - initialize an instance of Permit in your backend logic. This **only needs to be done once**, both to use Permit and - Elements. - Please remember to copy your `SDK Secret Key` and pass it into the initialized Permit object. - - - -### Server-side Login Route - -You need to create a route in your backend server to allow your client to `loginAs` themselves and get access the Permit Element. - -The backend `loginAs` route is matched based on the Authentication methods you have implemented inside your App. Most applications -authenticate with the **Bearer Token** or **Cookies**, but we also allows you to use any other **HTTP Security Header**. The important -part here is, that you use the appropriate code example below based on your Authentication method. - -The `loginAs` function takes two parameters. You need to pass in the unique `userId` you get from your **JWT** (JSON Web Token), -and a `tenant_key` or `tenantId`. - -```js -permit.elements.loginAs({ userId, tenant }); -``` - -:::info IMPORTANT -The **user must belong to the tenant** that he will be logged into. If he is not, you will see a login error saying `USER_NOT_FOUND`. - -If the user gets logged out, he also exits the current tenant specificed in the `loginAs` method. If you want to **change tenants** for -a user, you need to **log them out**, and **log them back in** to a different tenant. -::: - -Passing in the tenant is **compulsory** when logging in a user **server-side**. - - - - - - - If you use custom Authentication Header to authenticate to your backend, add - this route to your backend. - - - First open your Permit Dashboard and go to the **Elements** page. Then click - on **Configure JWKS** on the upper left corner and add your JWKS to the - dialog. Then paste your JWKS into the text dialog and click **OK**. - _![Configure JWKS](/img/elements/configure-jwks.png)_ Now make sure that your - Permit user key is the same as the jwt sub. You can see your permit user key - in the **Users** page in the Permit Dashboard. You can see your jwt sub with - sites like [jwt.io](https://jwt.io/). Just paste your jwt token into the text - dialog check in the left side the sub field. - - -### Install Permit-js - -Once you have your application ready, you need to install Permits's JS SDK. This gives you access to our prebuilt embeddable Element components. - - - Add the Permit JavaScript SDK to you app: - - -### Client-side login method - -This function should be called as early as possible in your App. This is best done inside a `App`/`index` file; **right after** the users -had just had their identity confirmed by the Authorization provider you are using, but **just before** the Embededd component is loaded. - -With any of these login frontend methods, it's **optional** to pass in your **tenant key**, in comparison to the server-side call where **it -is required**. The server-side tenant will **always take precedence**. We do however encourage passing in the same tenant in your frontend -and backend login calls for best practices and for adding clarity to your code. - - - This is the permit element object that is calling the backend route we have - configured previously and logging in the user. - - - -There are **four** things that need to be configured here: - -1. `loginUrl` - The url that corresponds to your backend login route you created in the last step. -2. `loginMethod` - The login method you are using in your backend. -3. `tenant` (Optional) - Required for frontendOnly login method. the name of the tenant that the user is part of, you can set it at your backend as well, if you are using frontendOnly this is required. -4. `token` (Optional) - Required for bearer token login method, you need to pass the token here. -5. `headers` (Optional) - Required for custom headers login method, you need to pass the headers here. -6. `userJwt` (Optional) - Required for frontendOnly login method, you need to pass the user jwt here. -7. `envId` (Optional) - Required for frontendOnly login method, you need to pass the env id here. - -There are **4 supported login options** choose the one that you are using in your backend. - - - The **loginMethod** here should be set to: `LoginMethod: LoginMethod.cookie`. - - - - The **loginMethod** here should be set to: `LoginMethod: LoginMethod.bearer` - and the **token** should be set to the current user token. - - - - The **loginMethod** here should be set to: `LoginMethod: LoginMethod.header` - and you should pass the **headers** to the current user auth headers. - - - The **loginMethod** here should be set to: `LoginMethod: LoginMethod.frontendOnly` - **userJwt** should be set to the current user token. - **tenant** should be set to the tenant you want to get access to, the current user must have role assigned to him in - this tenant. - **envId** should be set to the environment id you want to get access to, you need to make sure you have set the JWKS - in this env see step 2.4, you can get your env id with [this api - call](https://api.permit.io/v2/docs#/Environments/list_environments).Or take it from the get code dialog in the - Permit Elements Dashboard. - **userKeyClaim** (Optional) - Optional for frontendOnly login method, if your user key in Permit isn't the same as - the jwt `sub` claim, you need to pass the key of the claim here. - - -After you run login successfully you will **get a cookie** called `permit_session` which will allow you to -load your Permit Element securly and successfully. - -### Client-side logout method - -This function should be called along with the logging-out logic that you have within your App, to make sure the user does not -continue to have access to the Permit Element. - - - This logout method **should be called** as part of the logic of logging your - user out with your authentication solution. - - -### Login Errors - -There are a few possible errors you might find yourself come across while working with the embedding of Permit Elements. - -| Error | Description | -| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `USER_NOT_FOUND` | This error can appear if you are trying to log in as a particular user, but that **user does not exist within Permit**. You can also experience this login error when you are trying to login a user into a **tenant that he does not belong to**. | -| `TENANT_NOT_FOUND` | This error can appear when you are passing in a tenant, either in the frontend `permit.elements.login` function, or in your backend URL endpoint, where the tenant has not been created in Permit. | -| `INVALID_PERMISSION_LEVEL` | This error will emerge when you are trying to access part of the Element which you have not been given access too. This usually means the role that the person obtained has remained in the **Hidden Roles** permission level. | -| `FORBIDDEN_ACCESS` | This error will emerge when you are trying to login to an Element you have not been given permission to see. | - diff --git a/docs/embeddable-uis/element/user-management.mdx b/docs/embeddable-uis/element/user-management.mdx index 969a9e87..f3756395 100644 --- a/docs/embeddable-uis/element/user-management.mdx +++ b/docs/embeddable-uis/element/user-management.mdx @@ -70,350 +70,3 @@ Once you've set permissions, the UI visualization on the right side of the eleme allowFullScreen > - -### Initializing Permit - - - {/* If you are already using Permit, you can skip this step. */} - In order to use Permit Elements, you need to be a **user of Permit**. When starting to use Permit, you will need to - initialize an instance of Permit in your backend logic. This **only needs to be done once**, both to use Permit and Elements. - Please remember to copy your `SDK Secret Key` and pass it into the initialized Permit object. - - - -### Server-side Login Route - -You need to create a route in your backend server to allow your client to `loginAs` themselves and get access the Permit Element. - -The backend `loginAs` route is matched based on the Authentication methods you have implemented inside your App. Most applications -authenticate with the **Bearer Token** or **Cookies**, but we also allows you to use any other **HTTP Security Header**. The important -part here is, that you use the appropriate code example below based on your Authentication method. - -The `loginAs` function takes two parameters. You need to pass in the unique `userId` you get from your **JWT** (JSON Web Token), -and a `tenant_key` or `tenantId`. - -```js -permit.elements.loginAs({ userId, tenant }); -``` - -:::info IMPORTANT -The **user must belong to the tenant** that he will be logged into. If he is not, you will see a login error saying `USER_NOT_FOUND`. - -If the user gets logged out, he also exits the current tenant specificed in the `loginAs` method. If you want to **change tenants** for -a user, you need to **log them out**, and **log them back in** to a different tenant. -::: - -Passing in the tenant is **compulsory** when logging in a user **server-side**. - - - - - - - If you use custom Authentication Header to authenticate to your backend, add this route to your - backend. - - - First open your Permit Dashboard and go to the **Elements** page. Then click on **Configure JWKS** - on the upper left corner and add your JWKS to the dialog. Then paste your JWKS into the text - dialog and click **OK**. _![Configure JWKS](/img/elements/configure-jwks.png)_ Now make sure that - your Permit user key is the same as the jwt sub. You can see your permit user key in the **Users** - page in the Permit Dashboard. You can see your jwt sub with sites like [jwt.io](https://jwt.io/). - Just paste your jwt token into the text dialog check in the left side the sub field. - - -### Install Permit-js - -Once you have your application ready, you need to install Permits's JS SDK. This gives you access to our prebuilt embeddable Element components. - - - Add the Permit JavaScript SDK to you app: - - -### Client-side login method - -This function should be called as early as possible in your App. This is best done inside a `App`/`index` file; **right after** the users -had just had their identity confirmed by the Authorization provider you are using, but **just before** the Embedded component is loaded. - -With any of these login frontend methods, it's **optional** to pass in your **tenant key**, in comparison to the server-side call where **it -is required**. The server-side tenant will **always take precedence**. We do however encourage passing in the same tenant in your frontend -and backend login calls for best practices and for adding clarity to your code. - - - This is the permit element object that is calling the backend route we have - configured previously and logging in the user. - - - -There are **four** things that need to be configured here: - -1. `loginUrl` - The url that corresponds to your backend login route you created in the last step. -2. `loginMethod` - The login method you are using in your backend. -3. `tenant` (Optional) - Required for frontendOnly login method. the name of the tenant that the user is part of, you can set it at your backend as well, if you are using frontendOnly this is required. -4. `token` (Optional) - Required for bearer token login method, you need to pass the token here. -5. `headers` (Optional) - Required for custom headers login method, you need to pass the headers here. -6. `userJwt` (Optional) - Required for frontendOnly login method, you need to pass the user jwt here. -7. `envId` (Optional) - Required for frontendOnly login method, you need to pass the env id here. - -There are **3 supported login options** choose the one that you are using in your backend. - - - The **loginMethod** here should be set to: `LoginMethod: LoginMethod.cookie`. - - - - The **loginMethod** here should be set to: `LoginMethod: LoginMethod.bearer` and the **token** - should be set to the current user token. - - - - The **loginMethod** here should be set to: `LoginMethod: LoginMethod.header` - and you should pass the **headers** to the current user auth headers. - - - The **loginMethod** here should be set to: `LoginMethod: LoginMethod.frontendOnly` - **userJwt** should be set to the current user token. - **tenant** should be set to the tenant you want to get access to, the current user must have role assigned to him in this tenant. - **envId** should be set to the environment id you want to get access to, you need to make sure you have set the JWKS in this env see step 2.4, you can get your env id with [this api call](https://api.permit.io/v2/docs#/Environments/list_environments).Or take it from the get code dialog in the Permit Elements Dashboard. - **userKeyClaim** (Optional) - Optional for frontendOnly login method, if your user key in Permit isn't the same as the jwt `sub` claim, you need to pass the key of the claim here. - - -After you run login successfully you will **get a cookie** called `permit_session` which will allow you to -load your Permit Element securely and successfully. - -### Client-side logout method - -This function should be called along with the logging-out logic that you have within your App, to make sure the user does not -continue to have access to the Permit Element. - - - This logout method **should be called** as part of the logic of logging your user out with your - authentication solution. - - -### Login Errors - -There are a few possible errors you might find yourself come across while working with the embedding of Permit Elements. - -| Error | Description | -| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `USER_NOT_FOUND` | This error can appear if you are trying to log in as a particular user, but that **user does not exist within Permit**. You can also experience this login error when you are trying to login a user into a **tenant that he does not belong to**. | -| `TENANT_NOT_FOUND` | This error can appear when you are passing in a tenant, either in the frontend `permit.elements.login` function, or in your backend URL endpoint, where the tenant has not been created in Permit. | -| `INVALID_PERMISSION_LEVEL` | This error will emerge when you are trying to access part of the Element which you have not been given access too. This usually means the role that the person obtained has remained in the **Hidden Roles** permission level. | -| `FORBIDDEN_ACCESS` | This error will emerge when you are trying to login to an Element you have not been given permission to see. | - -## Customizing your Element - -Each element offers customization and configuration. - -### Match your brand - -With every new element, you will be able to adjust several setting to make the look and feel of the element really your own. - -
-
    -
  • - Change the background and primary colour of any element to match your brand. -
    • -
  • - Give the element a title that makes sense to your end user, or hide it fully. -
    • -
  • - Decide if you want to display your users Email, Full Name or both on the element. -
    • -
-
- -_![Audit Logs Element](/img/elements/configuration.png)_ - -### Configure your webhook - -Webhooks are automated messages sent from apps when something happens. They carry data in 'payloads', which are sent to a -unique URL, essentially a place where your API can accept data. - -With some Permit Elements, you will get the option to configure a webhook to stay informed of the actions that are performed -by the end users. - -_![Webhook](/img/elements/webhook.png)_ - -:::info EXAMPLE -The User Management Element's webhook provides an array of functionalities. For example, you can leverage it to receive -notifications each time a new user is created in your system, or to initiate the sending of a welcome message to recently -invited users. -::: - -#### Setting Up the URL Endpoint - -Before setting up a URL endpoint, it's important to note that the URL endpoint is the URL to which the webhook delivers data -each time an event occurs. This endpoint should be set up on your server or a third-party service, depending on your preference. - -#### Choose Your Platform: - -Decide whether you want to set up your endpoint on your own server or use a third-party service. If you're comfortable -managing a server and can handle potential scaling, security, and uptime issues, you may prefer to host it yourself. -Otherwise, consider using a third-party service, many of which handle these issues for you. - -#### Create the Endpoint: - -Create a new endpoint on your server or within your chosen third-party service. This is often a case of creating a new -URL route. For example, `/new-element-sure` or `/send-elements-email`. - -#### Implement Webhook Handling: - -Your endpoint needs to be able to receive POST requests, as webhooks will typically send data via this method. This -means your endpoint needs to be set up to read the payload from incoming POST requests and then process it as required. -This usually involves parsing JSON, although the exact format may vary. - -The expected payload of the webhook will include the following fields: - -- Email -- Tenant id -- Role -- Permission level -- Type - -Here is an example for the payload: - -``` -{ - "email": "example@gmail.com", - "role": "admin", - "tenant_key": "default", - "permission_level": "LEVEL_3" - "type: "create_user" - } -``` - -#### Secure Your Endpoint: - -Webhooks contain data, and you should ensure it's secure from potential malicious use. Within the Permit configuration screen, -we provide a input box so you can enter your secret, and use it to validate incoming data. This will ensure that the data is coming -from a trusted source. Also, ensure your endpoint uses HTTPS, encrypting data in transit. - -_![Webhook](/img/elements/webhook-2.png)_ - -#### Respond to the Webhook: - -After receiving a POST request, it's good practice to send a 200 HTTP status code to acknowledge receipt of -the data. If your endpoint fails to do this, the webhook may consider the delivery a failure and retry, -causing unnecessary traffic. - -## Embedding the iFrame - -After you finish configuring and customising your element, you are ready to it into your App. A code snippet for the element -will be generated for you. -This will be an `