Safewhere Identify 5.17 REST API Release Notes

This document summarizes all changes made to Identify REST API in version 5.17.

User endpoint

The GET /users/.filter endpoint can impact your filtering results when searching for users who do not have any value in a specific claim type (value ne ""). Safewhere Identify now treats an empty claim value as a special value.

GET /admin/api/rest/v2/users/.filter

Previous behavior

When filtering users based on the value in a specific claim type, the filter would return users who matched the conditions specified by the operator.

Example: To select all users who have the claim type http://schemas.microsoft.com/ws/2008/06/identity/claims/role with a claim value not equal to "ClaimAdmin" with this query:

urn:scim:schemas:extension:safewhere:identify:1.0[Claims[(type eq "http://schemas.microsoft.com/ws/2008/06/identity/claims/role" and value ne "ClaimAdmin")]]

This would return users who have the claim type http://schemas.microsoft.com/ws/2008/06/identity/claims/role with a claim value not equal to "ClaimAdmin".

Current behavior

When filtering users based on the value in a specific claim type, the filter returns users who match the conditions specified by the operator, including users with an empty value for this claim type. Note that a claim without a value is considered to have an empty value.

Example: To select all users who have the claim type http://schemas.microsoft.com/ws/2008/06/identity/claims/role with a claim value not equal to "ClaimAdmin" with this query:

urn:scim:schemas:extension:safewhere:identify:1.0[Claims[(type eq "http://schemas.microsoft.com/ws/2008/06/identity/claims/role" and value ne "ClaimAdmin")]]

This would return users who have the claim type http://schemas.microsoft.com/ws/2008/06/identity/claims/role with a claim value not equal to "ClaimAdmin", including users with an empty claim value("").

To select all users who have the claim type http://schemas.microsoft.com/ws/2008/06/identity/claims/role with a claim value not equal to "ClaimAdmin" and explicitly exclude those with an empty value, use the following query:

urn:scim:schemas:extension:safewhere:identify:1.0[Claims[(type eq "http://schemas.microsoft.com/ws/2008/06/identity/claims/role" and value ne "ClaimAdmin")]] and urn:scim:schemas:extension:safewhere:identify:1.0[Claims[(type eq "http://schemas.microsoft.com/ws/2008/06/identity/claims/role" and value pr)]]

Default page size validation in resource list

When invoking the GET method to retrieve Identify resources with a negative number in the pagesize parameter:

  • Previous behavior: The maximum page is 5000
  • Current behavior: The maximum page is 1000

Connections endpoint

The OAuth connection configuration section model has some new attributes:

{
    ...,
    "allowTokenExchange": false,
    "clientCertificateRevocationCheck": "None",
    "actAsAuthorizationClaimRules": [
        {
            "claimType": "urn:claimtype1",
            "value": "claimvalue1"
        },
        {
            "claimType": "urn:claimtype2",
            "value": "claimvalue2"
        }
    ],
    "applicationType": "Unspecified"
    ...,
},

  • New configuration fields:

    • allowTokenExchange:
      • Supported value: true or false
      • Default value: false
    • clientCertificateRevocationCheck:
      • Supported value: None, CheckEndCert, CheckEndCertCacheOnly, CheckChain, CheckChainCacheOnly, CheckChainExcludeRoot, CheckChainExcludeRootCacheOnly
      • Default value: None
    • actAsAuthorizationClaimRules:
      • Supported value: An array of JSON objects, each containing two string fields: claimType and value.
      • Default value: []
    • applicationType:
      • Supported value: Unspecified, Web, Native, JavaScript
      • Default value: Unspecified

  • Affected operations: GET /connections, POST /connections, PUT /connections.

  • Behaviors:

    Name Data type Require? Default value Description
    allowTokenExchange boolean ⬜️ false Enable if allow token exchange requests for the connection.
    clientCertificateRevocationCheck string ⬜️ None Specify the Certificate Revocation Check option for the client certificate.
    actAsAuthorizationClaimRules list of objects ⬜️ N/A The list of ActAs authorization claim rules.
    applicationType string ⬜️ Unspecified Specifies the type of application for the connection to guide which token endpoint authentication method should be used.

Users endpoint

GET /inactiveusers endpoint

New GET /inactiveusers endpoint with some parameters: pageIndex, pageSize, daysSinceLastLogin, includeDisabledUsers, and excludedOrganizations.

  • Affected operations: GET /inactiveusers.

  • Supported parameters:

    Name Data type Require? Default value Description
    pageIndex number ⬜️ 1 Page index want to return. If 0 or invalid page index will set to 1 and page size set to 100.
    pageSize number ⬜️ 1000 Page size want to return. If 0 or invalid page size will set to 1000 and page index set to 1. Maximum value of page size is 1000. If input pageSize > 1000, then page size is 1000.
    daysSinceLastLogin number ⬜️ 1 Specifies the number of days since the last login; the value must be a positive integer. Only users who have not logged in within this specified number of days will be considered inactive.
    includeDisabledUsers boolean ⬜️ false Specifies whether to include disabled users, default value is false.
    excludedOrganizations string ⬜️ N/A Allows excluding specific organizations. This parameter accepts a comma-separated list of organization names.

New inactive user model for the GET /inactiveusers endpoint.

  • Affected operations: GET /inactiveusers.
{
  "id": "74a5835b-62b2-4db4-ad4c-7812e4f3ad39",
  "externalId": "user74a5835b-62b2-4db4-ad4c-7812e4f3ad39@globeteam.com",
  "meta": {
    "created": "0001-01-01T00:00:00Z",
    "lastModified": "0001-01-01T00:00:00Z",
    "location": "/admin/api/rest/v2/users/74a5835b-62b2-4db4-ad4c-7812e4f3ad39",
    "version": null,
    "attributes": null
  },
  "userName": "user74a5835b-62b2-4db4-ad4c-7812e4f3ad39@globeteam.com",
  "displayName": "user74a5835b-62b2-4db4-ad4c-7812e4f3ad39@globeteam.com",
  "active": true,
  "numberOfRegisteredMFADevices": 0,
  "lastLoggedInDateTime": "2024-01-26T13:26:56.857",
  "urn:scim:schemas:extension:safewhere:identify:1.0": {
    "forceResetPasswordAfterFirstTimeLogin": false,
    "activationCodes": null,
    "claims": [
      {
        "operation": null,
        "employeeNumber": null,
        "type": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
        "primary": null,
        "display": null,
        "value": "user74a5835b-62b2-4db4-ad4c-7812e4f3ad39@globeteam.com",
        "$ref": null
      },
      {
        "operation": null,
        "employeeNumber": null,
        "type": "urn:email",
        "primary": null,
        "display": null,
        "value": "user74a5835b-62b2-4db4-ad4c-7812e4f3ad39@globeteam.com",
        "$ref": null
      }
    ]
  }
}

  • Behaviors:

    Name Data type Description
    id string User's ID
    externalId string Some deployments may use this attribute to store users' IDs from their own or third-party systems
    userName string The username of the user
    displayName string The display name of the user
    active boolean Indicates whether the user is active
    numberOfRegisteredMFADevices integer The number of registered MFA devices for the user
    lastLoggedInDateTime string The last login date and time of the user
    urn:scim:schemas:extension:safewhere:identify:1.0 object Extended attributes
    forceResetPasswordAfterFirstTimeLogin boolean Indicates whether the user is required to reset password after first login
    activationCodes array Activation codes for the user
    claims array Claims associated with the user
    operation string Operation related to the claim
    employeeNumber string Employee number of the user
    type string Type of the claim
    primary boolean Indicates whether the claim is primary
    display string Display value of the claim
    value string Value of the claim
    $ref string Reference link for the claim

GET /users/.filter endpoint

The behavior change in filtering claims for users based on specific claim values, particularly focusing on how empty claim values ("") are handled.

Previous behavior:

  • When filtering users based on the value in a specific claim type, the filter would return users who matched the conditions specified by the operator.

  • Example: To select all users who have roles but not "ClaimAdmin": urn:scim:schemas:extension:safewhere:identify:1.0[Claims[(type eq "http://schemas.microsoft.com/ws/2008/06/identity/claims/role" and value ne "ClaimAdmin")]]

    This will return users who have the claim type http://schemas.microsoft.com/ws/2008/06/identity/claims/role with claim value not equal to "ClaimAdmin".

Current behavior:

  • When filtering users based on the value in a specific claim type, the filter now returns users who match the conditions specified by the operator as well as users having an empty value for this claim type. Note that a claim without value is considered to have an empty value.

  • Example: To select all users who have roles but not "ClaimAdmin": urn:scim:schemas:extension:safewhere:identify:1.0[Claims[(type eq "http://schemas.microsoft.com/ws/2008/06/identity/claims/role" and value ne "ClaimAdmin")]]

    This will return users who have the claim type http://schemas.microsoft.com/ws/2008/06/identity/claims/role with claim value not equal to "ClaimAdmin", including users with an empty claim value ("").

    To explicitly select all users who have roles but not "ClaimAdmin" and exclude those with an empty value, use the following query:

    urn:scim:schemas:extension:safewhere:identify:1.0[Claims[(type eq "http://schemas.microsoft.com/ws/2008/06/identity/claims/role" and value ne "ClaimAdmin")]] and urn:scim:schemas:extension:safewhere:identify:1.0[Claims[(type eq "http://schemas.microsoft.com/ws/2008/06/identity/claims/role" and value pr)]]

Claims endpoint

New GET /claimreports/{claimType} endpoint with parameter: claimType

  • Affected operations: GET /claimreports/{claimType}.

  • Supported parameters:

    Name Data type Require? Default value Description
    claimType string ✅ Claimtype of Identify claim definition 
{
  "claimType": "email",
  "claimUsageContexts": [
    {
      "resource": "Identity providers",
      "adminEndpoint": "https://identify01.safewhere.local/adminv2/identity-providers/edit/saml20/saml20/SAML%20idp",
      "restApiEndpoint": "https://identify01.safewhere.local/admin/api/rest/v2/connections/SAML%20idp",
      "settingField": "Identity bearing claim"
    }
  ]
}

New claim reports model for the GET /claimreports/{claimType} endpoint.

  • Behaviors:

    Name Data type Description
    claimType string The specific claim type addressed in the report.
    claimUsageContexts array An array of objects, each representing a context where the claim type is utilized
    resource string The resource name applying the claim type
    adminEndpoint string The admin UI URL for direct resource management access
    restApiEndpoint boolean The REST API call endpoint URL
    settingField integer The setting where the claim type is employed

Transformations endpoint

New GET /transformationreports/{claimTransformationName} endpoint with parameter: claimTransformationName

  • Affected operations: GET /transformationreports/{claimTransformationName}.

  • Supported parameters:

    Name Data type Require? Default value Description
    claimTransformationName string ✅ Claim transformation name of Identify claim transformation 
{
  "claimTransformationName": "Scripting01",
  "claimTransformationContexts": [
    {
      "resource": "Identity providers",
      "adminEndpoint": "https://identify01.safewhere.local/adminv2/identity-providers/edit/saml20/saml20/SAML%20idp",
      "restApiEndpoint": "https://identify01.safewhere.local/admin/api/rest/v2/connections/SAML%20idp",
    }
  ]
}

New transformations reports model for the GET /transformationreports/{claimTransformationName} endpoint.

  • Behaviors:

    Name Data type Description
    claimTransformationName string The designated name of the claim transformation
    claimTransformationContexts array An array of objects, each delineating a context where the claim transformation is implemented
    resource string The resource applying the claim transformation
    adminEndpoint string The admin UI URL for direct management of the resource
    restApiEndpoint boolean The URL endpoint for REST API operations