Skip to main content

Access Requests & Approvals

Add an access request and approval flow to your application with Permit.io. Your users request access from inside your application, and admins approve or deny each request. This walkthrough is for developers who have a Permit policy and an application with user sign-in. Each step has short instructions, a link to the page with the full reference, and a video.

Prerequisites​

  • An application where users sign in and your authentication provider issues JSON Web Tokens (JWTs)
  • Your users synced to Permit, with the same user key as the JWT sub claim (Sync users)
  • Roles in your Permit policy (Configure your first RBAC policy)

What are Permit Elements?​

Permit Elements are embeddable UI components for access management. You embed an element in your application as an iframe. Your policy in Permit decides what each user can do in the element. For access requests, you use two elements:

ElementWho uses itWhat it does
User ManagementAdmins in your applicationLists users and their roles, and shows pending access requests to approve or deny.
Access RequestUsers who lack accessSends a request for access, for example for a role the user doesn't have.

To require approval for a single action instead of a role, for example a large funds transfer, use the Operation Approval and Approval Management elements.

Demo of Permit Elements​

1

1. Configure JWKS for your environment​

A JSON Web Key Set (JWKS) is the set of public keys that verify the JWTs your authentication provider issues. Permit uses your JWKS to confirm that a user who logs in to an element holds a valid token.

  1. In the Permit dashboard, open Settings and select JWKS Config.
  2. Paste your JWKS for the environment and click Save.
  3. Confirm that each user's key in Permit matches the sub claim of the user's JWT. If the key is in another claim, pass that claim name as userKeyClaim when you log the user in (step 5).

See Configuring JWKS for your environment.

2

2. Connect your application to Permit​

Install the Permit SDK in your backend and run a policy decision point (PDP), so your application enforces the same policy the elements manage. Then install the @permitio/permit-js package in your frontend. The frontend uses it to log users in to the elements.

See Use the Permit API and SDK, Run the PDP, and Installing Permit-js.

3

3. Build the authorization policy​

Define what users can do in your application. In Policy, create the resources, their actions, and the roles, and grant each role its permissions in the Policy Editor. Then assign roles to your users in Directory.

The roles are what users request. For example, a user with the viewer role can't write blog posts, and requests the editor role through the Access Request element.

See Configure your first RBAC policy.

4

4. Create and configure the elements​

Create a User Management element first. The Access Request element connects to it.

  1. Open the Elements screen. Under User Management, click Create Element.
  2. Enter a Name, select the Permission Model (RBAC or ReBAC), and set the Role Levels, which map your roles to permission levels in the element. Click Save.
  3. On the Elements screen, under Access Request, click Create Element.
  4. Select the User Management element to connect, enter a name, and click Create.
  5. Open the User Management element again. Under Approval Component in user management, select the Access Request element you created.

Each element has settings for its look and text: background and button colors, the title, the message, and the button text. See Access Request element customization.

5

5. Embed the elements and log users in​

  1. Open each element and click Generate Code. Permit generates an iframe snippet. In the snippet's src, set the tenant key the element applies to. See Creating an iFrame.
  2. Add the iframe snippets to your application's pages: the Access Request element where users ask for access, and the User Management element in your admin area.
  3. Log the signed-in user in to the elements before the iframes load. With the client-side login method, call permit.elements.login() from @permitio/permit-js with the user's JWT, the tenant key, and your environment ID. See Login method.

After a successful login, the element acts on behalf of the signed-in user.

Verify the approval flow​

  1. Sign in to your application as a user without the role to request, for example a viewer. In the Access Request element, click Request Access.
  2. Sign in as a user whose role is at Level 1 in the User Management element, for example an admin. The request appears in the element's list of pending users.
  3. Approve the request.
  4. In the Permit dashboard, open Directory. The requesting user has the approved role.

What you built​

  • Configured JWKS, so Permit verifies the users who log in to elements.
  • Created a User Management element and an Access Request element connected to it.
  • Embedded both elements in your application and logged users in to them.

What's next?

You finished the walkthroughs.

Contents

Edit this page

Need help?