Skip to main content
Version: 2.0.0

Connect Your Authentication

Permit.io enables simple authorization management by working seamlessly with most authentication providers. This integration allows for a smooth transition between verifying a user's identity and managing their access within your application. The process happens in a part we call the "handoff point" which occurs immediately after authentication and just before granting thr user access to the application.

This document outlines the steps required to ensure a successful integration, focusing on session management, JWT token issuance, user synchronization, and role assignment.

Session Management and JWT Token Issuance​

Upon successful authentication, two key components are created for the user: a session and a JSON Web Token (JWT). The JWT is especially crucial as it encapsulates the user's unique identity. This token not only serves as a bearer of identity but also is important in you being able to synchronize the user's details inside of Permit.io and assigning them a specific role based on predefined policies.

The Handoff Point​

The handoff point is a middleware layer that you should create to facilitate the transition from authentication to authorization. It operates as follows:

  1. Authentication Confirmation: The user's identity is confirmed by the authentication provider.
  2. Session and JWT Issuance: A session is established, and a JWT containing the user's unique identity is issued.
  3. User Synchronization: The JWT is used to sync the user's identity into Permit.io as a new user entity.
  4. Role Assignment: Based on the application's policy, a relevant role is assigned to the newly synchronized user.

User Synchronization and Role Assignment​

Permit.io requires the user's unique identity to be integrated into its system to manage authorization effectively. This integration can occur in real-time or in bulk via the Permit.io API.

  • Real-time Synchronization: At the handoff point, the user's identity is extracted from the JWT and synchronized with Permit.io, where a corresponding user entity is created.
  • Bulk Synchronization: For scenarios requiring the synchronization of multiple users at once, Permit.io offers an API endpoint to facilitate bulk user creation and role assignment.

API Endpoints​

Monitoring Monthly Active Users​

Permit.io measures usage through what we call Monthly Active Users (MAUs), which are unique identities against which permissions are checked within a given month.

note

Regardless of the number of permission checks performed for a user per month, they are counted as a single MAU (single identity).

Bulk User Synchronization with Permit.io​

Integrating an existing user base into Permit efficiently, especially when dealing with a significant number of users, requires a structured approach to bulk user synchronization. This method ensures that your users are seamlessly imported into Permit.io, enabling immediate application of authorization policies and role assignments.

Understanding Bulk Synchronization​

Bulk synchronization involves uploading a large number of user identities to Permit.io in a single operation. This process is essential for applications transitioning to Permit.io for authorization management or when periodically syncing user databases to ensure all user records are up-to-date.

When to Use Bulk Synchronization​

  • Initial Integration: When first integrating with Permit.io and you need to sync an existing user base.
  • Periodic Updates: To ensure that any changes in the user database (new users, role changes, etc.) are reflected in Permit.io.

Step-by-Step Bulk Synchronization Process​

  1. Prepare User Data: Organize your user data, ensuring each user's unique identity and any relevant attributes (e.g., roles, permissions) are accurately represented.

  2. Format Data: Convert your user data into the format required by Permit.io's bulk API endpoint. This often involves structuring the data into JSON or another specified format.

  3. API Call: Utilize the Permit.io API to submit your bulk user data. The specific endpoint and method will be detailed in the API documentation. Ensure that your API request includes all necessary authentication and headers.

    Example endpoint: POST https://api.permit.io/v2/facts/{proj_id}/{env_id}/bulk/users

  4. Handle Responses: Upon submitting your bulk upload, handle the API response. Success responses will confirm the data has been processed. Error responses should be reviewed to identify and correct any issues with the data or request.

  5. Verify Synchronization: After a successful upload, verify that the users have been correctly synchronized to Permit.io by performing a test query or using the Permit.io dashboard.

Contents