Merge pull request #384 from permitio/maya/per-10280-embed-element-guide

add embeds element guide

docs/embeddable-uis/embedding-elements.mdx

@@ -0,0 +1,128 @@
+---
+sidebar_position: 5
+title: Embedding Elements
+---
+
+import ElementTile from "@site/src/components/elements/ElementTile.js";
+import ActionContainer from "@site/src/components/elements/ActionContainer.js";
+import EmailUpdatesBox from "@site/src/components/elements/EmailUpdatesBox.js";
+import HelpSupportTile from "@site/src/components/elements/HelpSupportTile.js";
+
+Integrate UI components into your application to enable comprehensive access control and user management functionality.
+
+## Creating a new element
+
+In this example, we will create and embed a new `User Management` element using the `FrontendOnly` login method.
+
+First, navigate to the Elements section in Permit UI and click on Create Element located just below the `User Management` element.
+
+_![add element](/img/elements/user-management/CreateElement.png)_
+
+Next, you will be prompted to fill in the details of the new element. The following fields need to be completed:
+
+- **Name:** The name of the element.
+- **Permission Model:** The permission model for the element (RBAC / ReBAC).
+- **Roles Levels:** The role levels for the element.
+
+_![add element](/img/elements/user-management/ElementsFormEdit.png)_
+
+Additionally, you can manage the default settings of the element and customize the iframe's general design:
+
+- Change the background and primary color of any element to match your brand.
+- Assign a title to the element that makes sense to your end user, or choose to hide it entirely.
+- Decide whether to display your users' email, full name, or both on the element.
+- Configure webhooks to receive automatic updates on actions taken by your users. For more information about webhooks, refer to
+  the [Permit Webhooks documentation](/embeddable-uis/element/user-management/#configure-your-webhook).
+
+_![iFrame visualization](/img/elements/user-management/IFrameDesign.png)_
+
+## Previewing the element
+
+On the right side of the screen, you will see the End User Element Preview, which displays how the element will appear in the
+end user's dashboard.
+
+_![add element](/img/elements/user-management/ElementPreview.png)_
+
+After clicking on Save, the element will be created, and you will be redirected to the element's page. Now, you can click on the
+`**Get Code**` button to obtain the Element Embed Code. This iframe code will be used to embed the element in your application.
+
+_![Embed](/img/elements/user-management/EmbedCode.png)_
+
+## Configuring JWKS for your environment
+
+First, open your Permit Dashboard and go to the **Settings** page. Then click on **JWKS Config** on the upper sidebar and configure
+your JWKS for the environment you want to use. Paste your JWKS in the text dialog and click **Save**.
+
+_![Configure JWKS](/img/elements/user-management/ConfigureJwks.png)_
+
+Make sure your Permit user key is the same as the JWT sub. You can see your Permit user key on 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
+and check the left side of the sub field.
+
+For more information about the JWKS configuration, you can read the [Permit JWKS Configuration](/foaz/fetching-jwks/#what-are-jwks)
+documentation.
+
+## Installing Permit-js
+
+Once your application is ready, you need to install Permit’s JS SDK. This will give 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 using FrontendOnly
+
+To successfully integrate Permit’s login functionality into your application, you'll need to configure several key parameters.
+Below are detailed instructions on how to set these parameters correctly:
+
+The **loginMethod** 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 access. The current user must have a role assigned to them in this tenant.
+- **envId** should be set to the environment ID you want to access. Ensure you have set the JWKS in this environment. You can get your environment ID with [this API call](https://api.permit.io/v2/redoc#tag/Environments/operation/list_environments) or from the "Get Code" dialog in the Permit Elements Dashboard.
+- **userKeyClaim** (optional) - This is optional for the `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.
+
+```javascript
+permit.elements
+  .login({
+    loginMethod: LoginMethod.frontendOnly,
+    userJwt: "<YOUR_USER_JWT>",
+    tenant: "<YOUR_TENANT_KEY>",
+    envId: "<YOUR_ENV_ID>",
+  })
+  .then((res: any) => {
+    console.log("success", res);
+  })
+  .catch((err: any) => {
+    // you can handle the error either here or in your BE
+    console.log("err", err);
+  });
+```
+
+After you run the login successfully, you will receive a **cookie** called `permit_session`, which will enable you to load your
+Permit Element securely and successfully.
+
+## Client-side logout method
+
+This function should be called along with the logout logic within your app to ensure the user no longer has access to the
+Permit Element.
+
+This logout method **should be called** as part of the process 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.                                                                                                                                       |