Configuring and Managing Permission Sets

Introduction

Permission Sets enable SGNL Administrators to grant granular control over the features and objects within the SGNL product.

Permission Sets are groups of permissions, able to be assigned to Users and/or Teams to provide them with the level of access they need to complete their tasks.

What are Permission Sets

Within each Permission Set there is a group of permissions.

An example Permission Set within SGNL is the Global Admin Permission Set. This should be granted sparingly to only a small set of Administrators that require full, global access to all features and objects within the SGNL Platform.

Within the Global Admin Permission Set, we see a range of Permissions that are expressed as the Resource, a period delimieter, then the level of access that is allowed, e.g. being granted the policies.read permission as part of the Permission Set would allow a User or member of a Team to read policies.

Users or Teams can be assigned 0 or more Permission Sets. Note A user having no Permission Sets assigned (either directly or through a team) will result in the user being unable to sign-in to the product or use any APIs, effectively disabling their access.

If more than 1 permission set is assigned (either directly or through a team), the permissions will be additive for the user. What this means is that if one Permission Set were to grant policies.read and another was to grant policies.create and policies.update all 3 of the aforementioned permissions would be granted to the user.

Scoping

Permission Sets can have scoping applied through SGNL Labels. When Permission Sets are scoped, it means that all or some subset of the permissions they grant will be scoped only to the objects that have the label that the permission set is scoped to.

Given that not all objects in SGNL have or require a label, scoping a Permission Set will often (but not always) result in a mix of Global and Scoped Permissions.

Take for example the Policy Admin Permission Set. If I choose to Scope the assignment of that Policy for a given team, to the label Central IAM Team – SGNL will ensure that the team assigned this Permission Set will only be able to administer the Policies, Policy Versions, Snippets, and Snippet Versions (among others) that have the Central IAM Team label. These Policy Admins will however be able to see the Metrics and Logs globally within SGNL.

Assigning Permission Sets

If your User account has sufficient permission, you’re able to review and assign/unassign Permission Sets.

  1. Launch the SGNL Console and select Admin from the left navigation menu.
  2. Select the type of object you want to assign a Permission Set to, either a User directly or a Team (recommended)
  3. You can see the currently assigned Permission Sets alongside the list of teams
  4. To change the assigned Permission Sets, select the caret to the left of the team and select to Add Permission Set or hover an existing Permission Set to activate the Remove Permission Set context menu
  5. If Adding a Permission Set, click the button and choose the Permission Set – upon selection you’ll see the list of permissions associated with the set before saving
  6. Optionally, choose the permission scope by selecting a label to scope the permission set to
  7. You’ll have a final chance to review the permissions and any scoping before saving

Session-Based Permission Sets

Session-Based Permission Sets provide dynamic permission assignment during OIDC Single Sign-On. Instead of statically assigning permissions to users or teams, permissions are granted based on claims in the user’s ID token at sign-in time.

Prerequisites

  • OIDC SSO must be configured in SGNL (see Configuring SSO with OpenID Connect)
  • An Identity Provider (IdP) that supports additional claims in ID tokens
  • Administrative access to both SGNL and your IdP

Enabling Session-Based Permission Sets

  1. Navigate to Admin > Security in the SGNL Console
  2. In the Identity Provider Details section, toggle Enable Session-Based Permission Sets and Scopes
  3. Two links will appear:
    • View Permission Sets - Displays all available permission sets with their IDs
    • View Labels - Displays all available labels (used for scoping) with their IDs
  4. Optionally, click Map IdP Claims to configure claim-based permission mapping

Configuration Methods

There are two methods to implement Session-Based Permission Sets:

Method 1: Using SGNL’s Native Claim Format

This method involves configuring your IdP to include permission sets directly in the ID token using SGNL’s specific format.

Token Structure Example:

{
  "sub": "user@example.com",
  "iat": 1721026800,
  "exp": 1721113200,
  "iss": "https://your-idp.example.com",
  "aud": "https://your-client.sgnl.cloud",
  "permissionSets": [
    {
      "permissionSetId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "scopeId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
    },
    {
      "permissionSetId": "e4d909c2-90d0-4037-8c3f-6c8b4c7b6d5e"
    }
  ]
}

Key Points:

  • permissionSetId (required): The UUID of the permission set to grant
  • scopeId (optional): The UUID of a label to scope the permissions to
  • Permission set and label IDs can be found by clicking the respective “View” links in Admin > Security

Method 2: Using Claim Mappings

This method allows you to map existing IdP claims (such as group membership) to SGNL permission sets.

Configuration Steps:

  1. In Admin > Security, click Map IdP Claims
  2. Configure mappings between IdP claim values and SGNL permission sets
  3. Example mapping:
    • IdP Claim Name: groups
    • IdP Claim Value: Auditors
    • SGNL Permission Set: Log Reader

How it works:

  • SGNL examines the configured claims in the ID token
  • For string claims: checks if the value matches any configured mappings
  • For array claims: iterates through each value checking for matches
  • If a match is found, the corresponding permission set is assigned for the session

Example ID Token:

{
  "sub": "alice@wholesalechips.co",
  "groups": ["Everyone", "Auditors"],
  "department": "Audit and Compliance"
}

With the mapping above, this user would receive the Log Reader permission set for their session.

Configuring your IdP to support dynamic claims using SGNL’s native format

Both Entra ID and Okta support the ability to insert Custom Claims into User Tokens. You can read more about performing this function within their respective help documentation.

  • Entra ID

  • Okta

    Note: To insert Custom Claims, Okta requires their customers to have purchased a SKU that allows the creation of Custom Authorization Servers. The Default Org Authorization Service is not able to add Custom Claims.

For Both Entra ID and Okta (where a Custom Authorization Server is available) – you can also configure SGNL to dynamically determine the suitable SGNL Claims to issue during Sign-In at your IdP. Refer to the below documentation for general guides in protecting Applications during SSO.

Configuring Okta for Session-Based Permission Sets with Groups Claim Mapping

The most simplistic configuration with Okta is to use Groups Claim Mapping. You can configure this on the OIDC Application, by configuring a filter for Group Claims to be sent.

SGNL - Authentication

Enabling Group Claims in Okta

  1. Navigate to your OIDC application in Okta
  2. Go to Authentication
  3. Scroll to OpenID Connect ID Token
  4. Click Edit
  5. Specify a filter for the claims to send to SGNL
  6. Save

The groups will be included in the ID token and can be mapped to SGNL permission sets using the claim mapping configuration.

Configuring Entra ID for Session-Based Permission Sets with Groups Claim Mapping

For Microsoft Entra ID, you can use Method 2 (claim mappings) with group claims.

SGNL - Authentication

Enabling Group Claims in Entra ID

  1. Navigate to your OIDC application in Azure Portal
  2. Go to Token configuration
  3. Click Add optional claim
  4. Select ID token type
  5. Add the groups claim
  6. Configure any additional group filters if needed

The groups will be included in the ID token and can be mapped to SGNL permission sets using the claim mapping configuration.

Validation and Troubleshooting

Verifying Permission Assignment

  1. After signing in with SSO, navigate to Admin > Audit Logs
  2. Select to filter for Login events
  3. The audit log will show:
    • Which permission sets were assigned
    • Whether they were assigned via session claims
    • Any scoping (labels) applied

Common Issues and Solutions

No permissions granted at login:

  • Verify the ID token contains the expected claims (check IdP logs)
  • Ensure claim names match exactly (case-sensitive)
  • Check that permission set IDs are correct
  • Verify Session-Based Permission Sets is enabled

Wrong permissions granted:

  • Review claim mappings in Admin > Security
  • Check for overlapping mappings that might cause unexpected assignments (e.g. users are a member of a team with additional permissions)
  • Verify the transform configuration in Protected Systems

Permissions not scoped correctly:

  • Ensure scopeId/labelId values are valid UUIDs
  • Verify the labels exist and are applied to relevant objects
  • Check that the permission set supports scoping

Security Considerations

  • Token Security: Protect ID tokens as they now carry authorization information
  • Claim Validation: SGNL validates all permission set and label IDs; invalid values are ignored
  • Session Duration: Permissions are granted for the duration of the user’s session
  • Audit Trail: All session-based permission assignments are logged for compliance
  • Principle of Least Privilege: Grant only necessary permissions through session claims

Best Practices

  1. Start with Testing: Test permission assignments in a non-production environment first
  2. Use Scoping: Apply label-based scoping to limit permissions where appropriate
  3. Regular Audits: Review audit logs regularly to ensure permissions are assigned as expected
  4. Documentation: Document your claim mappings and permission assignment logic
  5. Gradual Rollout: Start with a small group of users before organization-wide deployment