Operation Approval Element
The Operation Approval Element is a frontend component that enables users to request approval for specific actions in your application.When a request is made, it will display in the "Approval Management" Element, where users with the appropriate permissions can view all pending requests and approve or deny them.
Once the request is approved or denied, the user will receive approval for the requested action. Additionally, a webhook will be triggered to notify your application about the approval or denial of the request.
Overview
The Operation Approval Element enables users to submit operation approvals using a dedicated user interface embedded in your application. This allows you, as the administrator, to restrict end-users from taking specific actions on objects and resources, and require an approval process before these actions are executed. After a user submits a request, it is sent for approval by an admin, who can either approve or deny it.
This element is especially useful for critical actions in your system that require approval by a higher authority before execution.
Using the "Operation Approval" Element is simple – just embed it into your Frontend application. Once embedded, users can request approval for restricted resources by clicking the "Request Approval" button. Later, users with the relevant permissions can view a list of all pending operation approvals in the "Approval Management" Element, where they can approve or deny them.
Example:
Let's take the example of a bank where users can transfer funds to other users. We want to ensure that all transfers above a certain amount are approved by a manager before they are executed. In this case, we can use the "Operation Approval" Element to allow users to request approval for large transfers.
Upon receiving the operational approval, the manager reviews it to decide whether to approve this transfer request or not.
Creating and Connecting the Element
1. In the Elements Screen, under "Operation Approval", click on "Create Element".
2. Select Resource from the dropdown menu, which will be the resource that connects to this element.
When the "Operation Approval" Element is created, it will create by default two roles: " _reviewer_ " with the permission to review, approve and deny requests, and "_requester_" with the "operate" permission.
3. Give the element a name, and click on "Create".
Element Customization
With every new element, you will be able to adjust it to ensure the look and feel of it fits your application.
- You can change the background color and the color of the button
- You can change the title, message and button text to make it more user friendly
Creating an iFrame
In your newly created element, click the "Generate Code" button on the top of the screen
A code snippet for the element will be generated for you.
This will be an <iframe> that you can insert anywhere into your application. It will look like the code snippet below:
Note that it is crutial to select the Tennant relevant for this element for it to fuction properly.
The dynamic values in src are:
- <ELEMENT_NAME> - The name of the element you have created.
- <SOME_UNIQUE_ID> - The unique id of the environment you are using.
- <TENANT_KEY> - The tenant key you are using.
- <RESOURCE_INSTANCE_KEY> - The resource instance key you are using or new resource instance key.
Replace them with your values.
<iframe
title="Permit Element Name"
src="https://embed.permit.io/<ELEMENT_NAME>?envId=<SOME_UNIQUE_ID>&darkMode=false&resourceInstanceKey=<RESOURCE_INSTANCE_KEY>&tenantKey=<TENANT_KEY>"
width="100%"
height="100%"
style="border: none;"
/>
Once the iframe is ready, we need to embed it. To do that, you'll need to create a login. In the next section, we'll walk you through logging in. Choose a way to log in that's convenient for you:
You need to generate resource instance key for each request, and assign a reviewer to this request. you will pass the resource instance key in the url of the iframe, for example:
<iframe
title="Permit Element Name"
src="https://embed.permit.io/<ELEMENT_NAME>?envId=<SOME_UNIQUE_ID>&darkMode=false&tenantKey=<TENANT_KEY>&resourceInstanceKey=<RESOURCE_INSTANCE_KEY>"
width="100%"
height="100%"
style="border: none;"
/>
New Operation Approval
When a user needs to request approval for a specific action, they should provide a reason for the request and then click the "Request Approval" button to submit it. Once the request is submitted, the user should obtain the key of the resource instance from the new request and assign a reviewer to it.
For example, if a user wants to seek approval for a $1000 transfer to another user and the key of the resource instance is "transfer-1", they should assign a relevant user with ReBAC permissions in the following format: transfer:transfer-1#_reviewer_.
You can find all pending requests on the "Approval Page." There, you can view all pending requests (based on your permissions) and take action by clicking the "Approve" or "Deny" buttons.
Embedding the Element
Initializing Permit
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.
permit.elements.loginAs({ userId, tenant });
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.
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:
# Navigate to your application's root directory
cd yourapp
npm install –-save @permitio/permit-jsClient-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.
1
2
3
4
5
6
7
8
permit.elements.login({
loginUrl: 'https://your_app_url.com/permit_login,
tenant: 'your_tenant_key',
token:'<TOKEN>',
loginMethod: LoginMethod.bearer
}).then((res: any) => {//optional handle success
}).catch((err: any) => {//handle error
});There are four things that need to be configured here:
loginUrl- The url that corresponds to your backend login route you created in the last step.loginMethod- The login method you are using in your backend.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.token(Optional) - Required for bearer token login method, you need to pass the token here.headers(Optional) - Required for custom headers login method, you need to pass the headers here.userJwt(Optional) - Required for frontendOnly login method, you need to pass the user jwt here.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.
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.
1
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. |