Organization-level authorization policy

Introduction

Safewhere Identify first introduced fine-grained authorization for the REST API and the new Admin UI in version 5.14. Since then, we have continuously worked on implementing organization-level authorization (referred to as the 'org-authz' policy in this document). This feature is now fully implemented in version 5.18. In summary, this authorization model restricts user access to resources belonging to or under organizations the user has access to, as follows:

  • If you are a member of the Root organization (meaning your user account is registered directly under this organization), you will have access to all organizations in the system and the resources within them.
  • If you are a member of a child organization, you will not be able to see the parent organization(s) and resources located within them. You can only access resources within your organizational hierarchy.

Access token and REST API

The Identify Admin is built on top of the REST API, so authorization and security must be enforced at both the REST API and UI levels.

Access tokens must include the urn:internal:userid claim to specify the ID of an Identify user, which can be indirectly used to determine its owner organization. Additionally, the Identify user associated with this urn:internal:userid claim must be active and not locked out.

Example of a valid token with the necessary user ID and role claims:

{
  "unique_name": "Root_Administrator",
  "sub": "Root_Administrator",
  "uri:email": "Root_Administrator@example.com",
  "urn:identify:rest-api:role": "Administrator",
  "name": "Root_Administrator",
  "urn:internal:userid": "a442d7cf-f0a6-413d-bf8a-9f75a894b5ba",
  "client_id": "clientid-demo",
  "token_usage": "access_token",
  "jti": "e676a060-3ac8-4533-b360-7b1f080e6d1a",
  "scope": [
    "identify*scim",
    "offline_access"
  ],
  "aud": "https://identifydemoauto.safewhere.local/runtime/",
  "azp": "clientid-demo",
  "iat": 1730773484,
  "nbf": 1730773484,
  "exp": 1730777084,
  "iss": "https://identifydemoauto.safewhere.local/runtime/oauth2"
}

The authorization of REST API endpoints depends on the urn:internal:userid claim and the REST API role claim. The following table explains how these claims affect access.

IMPORTANT: As you will see in the following table and sections, Org-authz is not (and cannot be) strictly enforced for all resources except users. This is because resources in Identify depend on one another. For example, consider Org1, Org2, and Org3, which are not part of the same hierarchy. A connection in Org1 might use a claim transformation in Org2, which, in turn, depends on claims defined in Org3. If strict enforcement were applied to viewing or reading resources, displaying the connection without showing the related claim transformation would be very confusing. However, Org-authz is strictly enforced for creating and modifying resources.

Access token content Administrator role

No User ID claim		 Administrator role

User ID claim

Belongs to Root Organization		 Administrator role

User ID claim

Does not belong to Root Organization		 UserContributor role

No User ID claim		 UserContributor role

User ID claim

Belongs to Root Organization		 UserContributor role

User ID claim

Does not belong to Root Organization		 Other resource contributor role

No User ID claim		 Other resource contributor role

User ID claim

Belongs to Root Organization		 Other resource contributor Role

User ID claim

Does not belong to Root Organization		 No roles
User endpoints - Old behaviors No access Access to all resources in all organizations Access to all resources in all organizations No access Access to all resources in all organizations Access to all resources in all organizations No access No access No access No access
User endpoints - New behaviors No access Access to all resources in all organizations Org-authz policy No access Access to all resources in all organizations Org-authz policy No access No access No access No access
Other endpoints - Old behaviors Access to all resources in all organizations Access to all resources in all organizations Access to all resources in all organizations No access No access No access Access to all resources in all organizations Access to all resources in all organizations Access to all resources in all organizations No access
Other endpoints - New behaviors No access Access to all resources in all organizations Org-authz policy(*) No access No access No access No access Access to all resources in all organizations Org-authz policy (*) No access

Org-authz policy (*): This policy applies only to resources associated with an organization. Resources not linked to any organization retain their existing behavior.

Org-authz policy in Identify Admin portal and REST API

Org-authz policy in Identify Admin portal

The following resource list views are currently governed by the org-authz policy:

  • Organizations
  • Groups
  • Users
  • Applications
  • Attribute services
  • Identity providers
  • Claims / Claim sets / Uniqueness
  • Claim transformations

The following resource list views are not currently governed by the org-authz policy:

  • Hosted Forms
  • Localization
  • Messaging
  • Clients
  • Script Library
  • Integrations
  • Settings and its sub-tabs
  • Logging

Note: When you create a new client in the Clients list, its owner organization is set to the Root organization by default. Ensure that the currently logged-in user on the Identify Admin portal belongs to the Root organization when creating it; otherwise, a 403 error will display with the message: "You do not have permission to modify or access resources outside of your organization hierarchy."

Given the following organization hierarchy:

Root
|-Org1
  |--Org11
  |--Org12
|-Org2
  |--Org21
  |--Org22

The rules are as follows:

  • An administrator user in the Root organization has full access to all resources in all organizations, as usual.
  • An administrator user who is not part of the Root organization (referred to as Admin (Org1) hereafter) will have different levels of access depending on the type of resource, as detailed in the following sections.

My Profile

  1. Admin (Org1) can view all claims and edit claim values where the Editable via "My Profile" setting is enabled, even if the owner organization of these claims is outside the Org1 organization hierarchy. However, Admin (Org1) cannot view or edit claim values where the Restrict view and editing of sub-organizations setting is enabled, and the owner organization of these claims is outside the Org1 organization hierarchy.
  2. Admin (Org1) cannot create the OAuth 2.0 protocol connection named Identify OAuth2 Token for REST APIs on the My RES API Key page. However, they can generate a new refresh token once the Identify OAuth2 Token for REST APIs has already been created, just as usual.

Note: The Identify OAuth2 Token for REST APIs's owner organization is set to the Root organization by default. Ensure that the currently logged-in user on the Identify Admin portal belongs to the Root organization when creating it; otherwise, a 403 error will display with the message: "You do not have permission to modify or access resources outside of your organization hierarchy."

Users

Admin (Org1) can create, view, edit, and delete Identify users only within the Org1 organization hierarchy. When creating or editing an Identify user, the Org-authz rules are applied as follows:

  • Group: Admin (Org1) can assign the user to a group that belongs to the Org1 organizational hierarchy.
  • Owner organization: Admin (Org1) can assign the user to an organization that is part of the Org1 organizational hierarchy.
  • Claims: Admin (Org1) can view all claims and edit claim values even if the claims belong to organizations outside the Org1 hierarchy. However, if the Restrict view and editing of sub-organizations setting is enabled for these claims, Admin (Org1) cannot view or edit their values for the user.

Organizations

Admin (Org1) can create, view, edit, and delete organizations only within the Org1 organization hierarchy. However, Admin (Org1) cannot view or edit the parent organization to which they belong. In this example, only the Admin (Root) can view or edit the Org1 organization.

Groups

Admin (Org1) can only create, view, edit, and delete groups within the Org1 organization hierarchy. When creating or editing a group, the Org-authz rules are applied as follows:

  • Owner organization: Admin (Org1) can assign an organization only within the Org1 organization hierarchy for this group.
  • Claims: Admin (Org1) can view all claims and edit claim values even if the claims belong to organizations outside the Org1 hierarchy. However, if the Restrict view and editing of sub-organizations setting is enabled for these claims, Admin (Org1) cannot view or edit their values for the group.

Applications and Identity Providers

Admin (Org1) can only create, view, edit, and delete connections within the Org1 organization hierarchy. When creating or editing an application, the Org-authz rules are applied as follows:

  • Owner organization: Admin (Org1) can assign an organization only within the Org1 organization hierarchy for this application.
  • Identity providers: Admin (Org1) can view all identity providers even if the owner organization of these identity providers is outside the Org1 organization hierarchy.
  • Consent claim set: Admin (Org1) can view all claim sets even if the owner organization of these claim sets is outside the Org1 organization hierarchy.
  • Claim rules: Admin (Org1) can view all claim transformations even if the owner organization of these claim transformations is outside the Org1 organization hierarchy.
  • Authentication Name (available in WS-Federation or WS-Trust applications): Admin (Org1) can view all identity Providers, even if the owner organization of these identity Providers is outside the Org1 organization hierarchy.

When creating or editing an Identity provider, the Org-authz rules are applied as follows:

  • Owner organization and Specify organization of auto-created users: Admin (Org1) can assign an organization only within the Org1 organization hierarchy for this identity provider.
  • Applications: Admin (Org1) can view all applications even if the owner organization of these applications is outside the Org1 organization hierarchy.
  • Consent claim set: Admin (Org1) can view all claim sets even if the owner organization of these claim sets is outside the Org1 organization hierarchy.
  • Claim rules: Admin (Org1) can view all claim transformations even if the owner organization of these claim transformations is outside the Org1 organization hierarchy.
  • Second factor: Admin (Org1) can view all identity providers even if the owner organization of these identity providers is outside the Org1 organization hierarchy.
  • User templates and Identity bearing claim: Admin (Org1) can view all claims even if the owner organization of these claims is outside the Org1 organization hierarchy or if the Restrict view and editing of sub-organizations setting is enabled.

Note: The Identify runtime connection's owner organization is set to the Root organization by default. Ensure that the currently logged-in user on the Identify Admin portal belongs to the Root organization when creating it. Otherwise, a 403 error will display with the message: "You do not have permission to modify or access resources outside of your organization hierarchy.". Similarly, connections and all associated resources created by the IdentifyMe application are also created under the Root organization by default.

Lastly, certain application types require specific claim transformations, which are created under the Root organization:

  • Google, Dropbox, Salesforce or Zendesk requires the AnyIDNameIDFormatEmailAddressClaimTransformation.
  • Amazon WS requires the AnyIDNameIDFormatPersistentClaimTransformation.
  • Office 365 requires the Office365AnyIDNameIDFormatPersistentClaimTransformation.

Attribute services

Admin (Org1) can only create, view, edit, and delete attribute services within the Org1 organization hierarchy. When creating or editing an attribute service, the Org-authz rules are applied as follows:

  • Owner organization: Admin (Org1) can assign an organization only within the Org1 organization hierarchy for this attribute service.

Claims

Admin (Org1) can only create, view, edit, delete and import claims within the Org1 organization hierarchy. When creating or editing a claim or importing a claim list, the Org-authz rules are applied as follows:

  • Owner organization: Admin (Org1) can assign an organization only within the Org1 organization hierarchy for this claim.
  • Admin (Org1) can create, delete a new uniqueness constraint only within the Org1 organization hierarchy.

Similarly, the rules are applied to Claim sets as follows:

  • Owner organization: Admin (Org1) can assign an organization only within the Org1 organization hierarchy for this claim.
  • Claims: Admin (Org1) can view all claims even if the owner organization of these claims is outside the Org1 organization hierarchy or if the Restrict view and editing of sub-organizations setting is enabled.

Claim transformations

Admin (Org1) can create, view, edit, delete claim transformations only within the Org1 organization hierarchy. When creating or editing a claim transformation, the Org-authz rules are applied as follows:

  • Owner organization: Admin (Org1) can assign an organization only within the Org1 organization hierarchy for this claim.
  • Claims in the Setting tab: Admin (Org1) can view all claims even if the owner organization of these claims is outside the Org1 organization hierarchy or if the Restrict view and editing of sub-organizations setting is enabled.
  • Authentication connection pipeline and Protocol connection pipeline in the Condition tab: Admin (Org1) can view all connections even if the owner organization of these connections is outside the Org1 organization hierarchy.

Handling unauthorized requests

When an Admin (Org1) attempts to access resources which are outside the Org1 organization hierarchy, an error page like the one shown below will appear:

configure-email-server.png

Breaking changes

  • Identify users must now be assigned a specific role to access the Identify Admin portal.

Org-authz policy in REST API

The following API endpoints are currently governed by the org-authz policy:

  • ClaimDefinitions
  • Connections
  • Groups
  • Organizations
  • Transformations
  • Users
  • AttributeServices
  • ClaimSets
  • UserSelfService
  • Communication
  • UniqueFreeUserClaimValue

The following API endpoints are not currently governed by the org-authz policy:

  • Certificates
  • SystemSetup
  • MessageQueues
  • SharedConfigurableSettings
  • CustomContents
  • EmailConfiguration
  • SmsConfiguration
  • AuthenticationContextMethodClass
  • CorrelationError
  • Localization
  • LDAPAttributeDefinitions
  • LDAPWebServices
  • AuditLogs
  • SystemLogs
  • ScriptLibraries

Given the following organization hierarchy:

Root
|-Org1
  |--Org11
  |--Org12
|-Org2
  |--Org21
  |--Org22

The rules are as follows:

  1. User: For GET, PUT, POST, PATCH, and DELETE operations, the org-authz policy applies as detailed in the Org-authz policy in Identify Admin portal section.
  2. All other resources:
  • For PUT, POST, PATCH, and DELETE operations, the org-authz policy applies as detailed in the Org-authz policy in Identify Admin portal section.
  • For operations that retrieve or filter resources, a new REST API parameter, forceOrgAuthn, has been introduced. When forceOrgAuthn is omitted or set to false, REST API calls can retrieve or filter resources across all organizations, regardless of the user's organization specified by the user ID in the access token. As noted earlier in this document, strictly enforcing Org-authz for reading resources is not feasible. The forceOrgAuthn parameter is designed to help the Admin portal display the correct resources to users, enhancing the overall user experience. However, it has no impact on security.
GET /admin/api/rest/v2/groups?sortOrder=Ascending HTTP/1.1
Host: identify01.identify.safewhere.com
content-type: application/json

Response:

{
    "totalResults": 6,
    "pageIndex": 1,
    "pageSize": 1000,
    "sortBy": "name",
    "sortOrder": "Ascending",
    "resources": [
        {
            "accessOrganizationName": "Organization_Passwordage",
            "id": "5d1cdd0a-0d75-4fb5-97bf-617b603dba03",
            "name": "Organization_PasswordageGroupManagement",
			...
        },
        {
            "accessOrganizationName": "Org11",
            "id": "c8d8aede-8b49-41c3-9661-a73d0c7ffd65",
            "name": "GroupInOrg11",
			...
        },
        {
            "accessOrganizationName": "org2",
            "id": "014c34ff-677d-43ad-9e43-a473a43671cb",
            "name": "Grouporg2",
			...
        },
        {
            "accessOrganizationName": "org1",
            "id": "fa0ea376-8155-42f3-8667-430a8e86c4b3",
            "name": "newgroup02",
			...
        },
        {
            "accessOrganizationName": "Root",
            "id": "f5bd0733-5405-4949-8f91-27796f87ec86",
            "name": "Root_group",
			...
        },
        {
            "accessOrganizationName": "org1",
			"id": "a7240413-6464-457a-b493-56a19b7c6c28",
            "name": "newgroup01",
			...
        }
    ]
}

When forceOrgAuthn is set to true, REST API calls can retrieve or filter resources within a specific organizational hierarchy.

GET /admin/api/rest/v2/groups?sortOrder=Ascending&forceOrgAuthn=true HTTP/1.1
Host: identify01.identify.safewhere.com
content-type: application/json

Response:

{
    "totalResults": 3,
    "pageIndex": 1,
    "pageSize": 1000,
    "sortBy": "name",
    "sortOrder": "Ascending",
    "resources": [
        {
            "accessOrganizationName": "Org11",
            "id": "c8d8aede-8b49-41c3-9661-a73d0c7ffd65",
            "name": "GroupInOrg11",
			...
        },
        {
            "accessOrganizationName": "org1",
            "id": "fa0ea376-8155-42f3-8667-430a8e86c4b3",
            "name": "newgroup02",
			...
        },
        {
            "accessOrganizationName": "org1",
			"id": "a7240413-6464-457a-b493-56a19b7c6c28",
            "name": "newgroup01",
			...
        }
    ]
}

This forceOrgAuthn parameter parameter is supported by the following endpoints:

Resource Endpoint
Claims GET /api/rest/v2/claimdefinitions
GET /api/rest/v2/claimdefinitions/.filter
post /api/rest/v2/claimdefinitions/.search
GET /api/rest/v2/claimdefinitions/{claimType}
GET /api/rest/v2/claimdefinitions/{id}
Connections GET /api/rest/v2/connections
GET /api/rest/v2/connections/.filter
GET /api/rest/v2/connections/{connectionName}
GET /api/rest/v2/connections/certificate/{connectionName}
Groups GET /api/rest/v2/groups
GET /api/rest/v2/groups/.filter
GET /api/rest/v2/groups/{groupName}
Organizations GET /api/rest/v2/organizations
GET /api/rest/v2/organizations/.filter
GET /api/rest/v2/organizations/{organizationName}
GET /api/rest/v2/organizations/{organizationName}/childs
Transformations GET /api/rest/v2/transformations/.filter
GET /api/rest/v2/transformations/{claimTransformationName}
GET /api/rest/v2/transformations/transformationreports/{claimTransformationName}
AttributeServices GET /api/rest/v2/attributeservices
GET /api/rest/v2/attributeservices/.filter
GET /api/rest/v2/attributeservices/{attributeServiceName}
ClaimSets GET /api/rest/v2/claimsets
GET /api/rest/v2/claimsets/{claimSetName}
GET /api/rest/v2/claimsets/{id}
GET /api/rest/v2/claimsets/.filter
UniqueFreeUserClaimValues GET /api/rest/v2/uniquefreeuserclaimvalues

Handling unauthorized requests

If an access token without a user ID is used, a 401 error is returned:

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error"
    ],
    "status": "401",
    "scimType": null,
    "detail": "Token does not have enough information. RequestId: 0733d87d-8520-4239-8c4a-67240e5ac394."
}

If an access token with a user ID from a non-existing Identify user, a 401 error is returned:

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "status": "401",
  "scimType": null,
  "detail": "urn:internal:userid in token does not match with any user. RequestId: 8d8b7fb3-7f62-4bf1-9d6d-f1c63ef33ac0."
}

If an access token with a user ID from a disabled Identify user or locked-out Identify user, a 403 error is returned:

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "status": "403",
  "scimType": null,
  "detail": "The user account is either disabled or locked-out. Please contact your administrator for assistance. Access tokens from disabled or locked-out accounts are not permitted to call REST APIs. RequestId: a453dd06-d699-4625-b414-571efe212d8b."
}

If a user attempts to modify resources which are outside the organizational hierarchy, a 403 error is returned:

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error"
    ],
    "status": "403",
    "scimType": null,
    "detail": "You do not have permission to modify or access resources outside of your organization hierarchy. RequestId: b70a6459-f9dc-400e-b2fe-10ef0e1cf00d."
}

Restricting access token roles to user-Assigned role subset

To enhance security, we have added a new option under the Security section on the Settings page: Require that roles in access tokens must be a subset of the user's assigned roles. This setting enforces role subset restrictions for access tokens.

enforce-subset-roles.png

When enabled, the Identify REST API ensures that access tokens only contain roles assigned to the Identify user within the system. This prevents users from gaining elevated permissions beyond their assigned roles through other means, such as claim transformations.

Role validation

Identify ensures that all roles in an access token are covered by roles assigned to the user. For example, a user with the Observer role can have not only the Observer role but also its subset roles, such as ConfigurationObserver, UserObserver, and MonitorObserver, in their access token. If the access token includes additional roles outside of this subset, it will be considered invalid.

The table below shows the allowable roles in access tokens for each primary role assigned to a user:

User's role Subset roles
Administrator All roles
Observer ConfigurationObserver, UserObserver, MonitorObserver, OrganizationObserver, GroupObserver,ClaimTransformationObserver, ConnectionObserver, ClaimObserver, ScriptLibraryObserver, OtherSettingsObserver, CustomContentObserver
ConfigurationContributor ConfigurationObserver
UserContributor UserObserver
OrganizationContributor OrganizationObserver
GroupContributor GroupObserver
ClaimTransformationContributor ClaimTransformationObserver
ConnectionContributor ConnectionObserver
ClaimContributor ClaimObserver
ScriptLibraryContributor ScriptLibraryObserver
OtherSettingsContributor OtherSettingsObserver
CustomContentContributor CustomContentObserver

Handling unauthorized requests

If the roles included in an access token do not align with or are not a subset of the roles assigned to the user, a 401 error is returned:

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "status": "401",
  "scimType": null,
  "detail": "The roles [ConfigurationContributor, UserContributor] included in the access token do not match any roles assigned to the user. Please verify that the access token is generated with the correct roles associated with the user. RequestId: 3c0278a4-9277-48af-8be1-8ecf80d72e3b."
}

Breaking changes

  • DELETE api/rest/v2/uniquefreeuserclaimvalues: This endpoint exclusively deletes all free claim definition constraints within the organizational hierarchy.
  • When creating a new Identify resource where the body content does not specify the owner organization (e.g., if the accessOrganizationName parameter is missing when creating a new claim), the owner organization of the newly created resource is determined from the owner organization of the user ID in the applied access token.
  • GET api/rest/v2/users/myprofile: This endpoint no longer requires REST API role validation, meaning the access token does not need the urn:identify:rest-api claim. However, the urn:internal:userid claim must be included in the token.