Safewhere Identify 5.18 REST API Release Notes

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

Organization-level authorization

Safewhere Identify has implemented stricter access rules known as the organization-level authorization policy, which impacts all REST API endpoints. For more information, please refer to the Organization-level authorization policy document.

Default page size validation in resource list

The pageSize parameter has been enhanced with the following new implementation:

The maximum number of records per page is now 5000. If the pageSize parameter is set to a value greater than 5000, it will default to 5000.
If the pageSize parameter is set to 0 or an invalid value, the maximum number of records per page will default to 1000.

Certificate endpoint

Purge all unused expired certificates

Affected operation: DELETE /api/rest/v2/certificates/purgeunusedexpiredcertificates
Parameter:

Name	Data type	Require?	Default value	Description
forceDeleteInUse	boolean	⬜️	false	When set to `true`, force the deletion of certificates even if they are currently in use.

{
  "NumberOfCertificatesPurged": 27,
  "NumberOfCertificatesFailedToPurgeDueToInUse": 3
}

Behaviors:

Name	Data type	Description
NumberOfCertificatesPurged	integer	The number of certificates successfully purged.
NumberOfCertificatesFailedToPurgeDueToInUse	integer	The number of certificates that failed to purge because they are currently in use.

Support new `ignoreInUseCheck` parameter

The most time-consuming operation when using the GET /api/rest/v2/certificates endpoint is checking whether a certificate is being used by other resources. The ignoreInUseCheck parameter bypasses this check to improve the endpoint's performance.

Affected operation: GET /api/rest/v2/certificates
Parameter:

Name	Data type	Require?	Default value	Description
ignoreInUseCheck	boolean	⬜️	false	When set to `true`, the endpoint will return certificates without checking its in-use status.

User endpoints

Additional sorting fields for `sortBy` parameter

The sortBy parameter in the User endpoints now supports additional sorting fields.

Affected operations: GET /api/rest/v2/users, GET /api/rest/v2/users/.filter
Parameter:

Name	Data type	Require?	Default value	Description
sortBy	string	⬜️	displayName	The supported values for the `sortBy` parameter are: displayName, active, groups, organization, forceResetPasswordAfterFirstTimeLogin, userName, externalId and user claims. If `sortBy` is left blank or set to an invalid value, the default sorting attribute is displayName.

Additional filter fields for `filter` parameter

The filter parameter in the GET /api/rest/v2/users/.filter endpoint now supports additional filter fields.

Affected operations: GET /api/rest/v2/users/.filter
Parameter:

Name	Data type	Require?	Default value	Description
filter	string	⬜️	Empty	The supported properties for the `filter` parameter are: userName, displayName, groups, organization, externalId, active and user claims.

MessageQueues endpoints

The MessageQueue configuration model includes some new attributes:

publishDomainEvents
publishLogs

{
  ...
  "publishDomainEvents": true,
  "publishLogs": true,
  ...
}

Affected operations: POST /api/rest/v2/messagequeues, PUT /api/rest/v2/messagequeues, GET /api/rest/v2/messagequeues, GET /api/rest/v2/messagequeues/.filter, GET /api/rest/v2/messagequeues/{displayName}.
Behaviors:

Name	Data type	Require?	Default value	Description
publishDomainEvents	boolean	⬜️	false	When set to `true`, domain events are published to the message queue.
publishLogs	boolean	⬜️	false	When set to `true`, log messages are published to the message queue.

Connection endpoint

OAuth/OIDC application

The OAuth application configuration model includes a new attribute:

allowedCORSOriginsDomains

{
  ...,
  "configurations": [
    {
      ...,
      "allowedCORSOriginsDomains": ["https://*.identify.safewhere.com", "https://*.sp.safewhere.com"]
      
      ...
    }
  ]
}

Affected operations: GET /api/rest/v2/connections, POST /api/rest/v2/connections, PUT /api/rest/v2/connections, GET /api/rest/v2/connections/.filter, GET /api/rest/v2/connections/{connectionName}.
Behaviors:

Name	Data type	Require?	Default value	Description
allowedCORSOriginsDomains	array	⬜️	Empty	Specifies the allowed CORS origin domains for the connection.

OIDC identity provider

The OAuth Identity Provider configuration model includes some new attributes:

usePkce
defaultClaimMappingAction

{
  ...,
  "configurations": [
    {
      ...,
      "defaultClaimMappingAction": "DoNotMapToStandardClaimTypes",
      "usePkce": true,
      ...
    }
  ]
}

Affected operations: GET /api/rest/v2/connections, POST /api/rest/v2/connections, PUT /api/rest/v2/connections, GET /api/rest/v2/connections/.filter, GET /api/rest/v2/connections/{connectionName}.
Behaviors:

Name	Data type	Require?	Default value	Description
usePkce	boolean	⬜️	false	When set to `true`, requests from Identify to an upstream IDP will include the required parameters for the Authorization Code flow with PKCE.
defaultClaimMappingAction	string	⬜️	MapToStandardClaimTypesWithClaimProviderPrefix	Specifies the mapping action for incoming claims: MapToStandardClaimTypesWithClaimProviderPrefix, MapToStandardClaimTypesWithoutClaimProviderPrefix, DoNotMapToStandardClaimTypes

This setting is available for the generic OIDC provider and all social OIDC providers

SAML 2.0 Identity Provider

The SAML 2.0 Identity Provider configuration model renames some attributes:

SupportsScope is now supportsScope.
ProductType is now productType.

{
  ...,
  "configurations": [
    {
      ...,
      "supportsScope": "",
      "productType": "",
      ...
    }
  ]
}

Affected operations: GET /api/rest/v2/connections, POST /api/rest/v2/connections, PUT /api/rest/v2/connections, GET /api/rest/v2/connections/.filter, GET /api/rest/v2/connections/{connectionName}.

Generic Identity Provider

The Generic Identity Provider configuration model includes a new attribute:

scriptName

{
  ...,
  "configurations": [
    {
      ...,
      "scriptName": "",
      ...
    }
  ]
}

Affected operations: GET /api/rest/v2/connections, POST /api/rest/v2/connections, PUT /api/rest/v2/connections, GET /api/rest/v2/connections/.filter, GET /api/rest/v2/connections/{connectionName}.
Behaviors:

Name	Data type	Require?	Default value	Description
scriptName	string	⬜️	false	Specifies the script to be used by the Generic Provider authentication connection.

Support for interceptorScriptName in application and Identity Provider configuration

Most application and Identity Provider configurations (except OTP) now include a new attribute in the interceptor service section.

interceptorScriptName

{
  ...,
  "configurations": [
    {
      ...,
      "interceptorService": {
        ...,
        "interceptorScriptName": ""
      }
      ...
    }
  ]
}

Affected operations: GET /api/rest/v2/connections, POST /api/rest/v2/connections, PUT /api/rest/v2/connections, GET /api/rest/v2/connections/.filter, GET /api/rest/v2/connections/{connectionName}.
Behaviors:

Name	Data type	Require?	Default value	Description
interceptorScriptName	string	⬜️	Empty	Specifies the script to be used by the interceptor.

Removal of NemID Identity Provider

The NemID Identity Provider has been deprecated due to the shutdown of NemID services. As a result, the plugin no longer functions.

Affected operations: GET /api/rest/v2/connections, POST /api/rest/v2/connections, PUT /api/rest/v2/connections, GET /api/rest/v2/connections/.filter, GET /api/rest/v2/connections/{connectionName}.

Organization endpoint

Delete existing organizations by names

Affected operations: DELETE /api/rest/v2/organizations/many

Previous behavior

Status code 400 returned when one of the ogranization names was not found

Sample:

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "status": "400",
  "scimType": null,
  "detail": "The organization named 'Org NotFound' is not found. RequestId: c1bd6a42-c42f-4cc5-aa56-05e61120d98e."
}

New behavior

Status code 200 is returned when one of the organization names is not found. Additionally, the organization attribute in the faultyInputOrganizations section has been renamed to organizationName.

Sample:

{
  "affectedOrganizations": [
    {
      "name": "demo",
      "accessOrganizationName": "Root",
      ...
      "endpoint": "/admin/api/rest/v2/organizations",
      "schema": "urn:scim:schemas:core:2.0:Organization",
      "schemaExtensions": null,
      "schemaExtensionsDetail": null
    }
  ],
  "faultyInputOrganizations": [
    {
      "organizationName": "Org NotFound",
      "reason": "The organization named 'Org NotFound' is not found."
    }
  ]
}

SystemSetup endpoint

`nemIdMalformedRequestErrorPageUrl` parameter removal

The nemIdMalformedRequestErrorPageUrl parameter has been removed from the SystemSetup configuration model. This means the SystemSetup model will skip the nemIdMalformedRequestErrorPageUrl parameter when it exists in a request body.

Affected operations: GET /api/rest/v2/systemsetup, PUT /api/rest/v2/systemsetup.

New attributes in SystemSetup

The SystemSetup configuration model includes some new attributes:

sqlCommandTimeout
sendPasswordEmailToUser
enforceRoleSubsetInAccessToken

{
    ...,
    "sqlCommandTimeout":30,
    "sendPasswordEmailToUser":true,
    "enforceRoleSubsetInAccessToken": false
    ...
},

Affected operations: GET /api/rest/v2/systemsetup, PUT /api/rest/v2/systemsetup.
Behaviors:

Name	Data type	Require?	Default value	Description
sqlCommandTimeout	integer	⬜️	30	Specifies the SQL command timeout duration in seconds.
sendPasswordEmailToUser	boolean	⬜️	true	When set to `true`, this setting ensures that the `Send password email to user` setting on the new user form is always enabled
enforceRoleSubsetInAccessToken	boolean	⬜️	false	When set to `true`, this setting ensures that the roles included in the access token are limited to a subset of the roles assigned to the user

Support new logTargets

The logTargets parameter in the Systemsetup configuration model now supports an additional log target: MessageBus.

Affected operations: GET /api/rest/v2/systemsetup, PUT /api/rest/v2/systemsetup.
Behaviors:

Name	Data type	Require?	Default value	Description
logTargets	array	⬜️	N/A	A list of targets where the log messages are sent. Available log target values include: SerilogSinks, TextFile, WindowsEvent, ApplicationInsights and MessageBus

Support `dd-MM-yyyy HH:mmZ` format in promoteSecondaryCertificateToPrimaryAt

The promoteSecondaryCertificateToPrimaryAt parameter in the Systemsetup configuration model now supports an additional datetime format: dd-MM-yyyy HH:mmZ.

Affected operations: PUT /api/rest/v2/systemsetup.
Behaviors:

Name	Data type	Require?	Default value	Description
promoteSecondaryCertificateToPrimaryAt	string	⬜️	N/A	Specifies the specific time stamp when Identify will promote the secondary certificate to be the primary one.

Audit log endpoint

loginmetrics endpoint

The new GET /api/rest/v2/auditlogs/loginmetrics returns login metrics, such as login attempts, account lockouts, and faulty logins, for selected Identity Provider connections. Results are filtered based on connection IDs and date ranges if provided. The response includes detailed metrics for each Identity Provider connection.

This endpoint requires the AuditLogs.Read permission. This means the urn:identify:rest-api:role claim in the access token must include either the Administrator role or the MonitorObserver role to access the login metrics data.
Supported parameters:

Name	Data type	Require?	Default value	Description
connectionIds	string	⬜️	Empty	Comma-separated list of Identity provider connection IDs to retrieve metrics for. Empty means all connections will be included.
fromDate	string	✅	N/A	Start date for filtering metrics. Format: `dd/MM/yyyy` or `dd-MM-yyyy`.
toDate	string	✅	N/A	End date for filtering metrics. Format: `dd/MM/yyyy` or `dd-MM-yyyy`.

Note: A larger date range may slow response time. Consider limiting the range to optimize performance.

URI parameters:

GET /api/rest/v2/auditlogs/loginmetrics?connectionIds=344c7506-a02d-40b2-a262-5eb0428779a6,4308b53a-64b4-4f93-adf9-88c50d18c7d7&fromDate=01/10/2024&toDate=31/10/2024

Sample:

[{
    "Date": "2024-10-23",
    "AuthenticationConnectionId": "344c7506-a02d-40b2-a262-5eb0428779a6",
    "AuthenticationConnectionName": "Username & password",
    "NumberOfFaultyLogins": [
      {
        "ConnectionId": "All service providers",
        "ConnectionName": "All service providers",
        "Count": 0
      }
    ],
    "NumberOfAccountLockouts": [
      {
        "ConnectionId": "All service providers",
        "ConnectionName": "All service providers",
        "Count": 0
      }
    ],
    "NumberOfLoginAttemptsPerConnection": [
      {
        "ConnectionId": "f64830db-32f9-4af0-bf64-67aa9ef1c3fc",
        "ConnectionName": "identify01.identify.safewhere.com",
        "Count": 6
      }
    ]
  },
  ...
  {
    "Date": "2024-10-23",
    "AuthenticationConnectionId": "4308b53a-64b4-4f93-adf9-88c50d18c7d7",
    "AuthenticationConnectionName": "OAuth IDP login.microsoftonline.com",
    "NumberOfFaultyLogins": [
      {
        "ConnectionId": "All service providers",
        "ConnectionName": "All service providers",
        "Count": 0
      }
    ],
    "NumberOfAccountLockouts": [
      {
        "ConnectionId": "All service providers",
        "ConnectionName": "All service providers",
        "Count": 0
      }
    ],
    "NumberOfLoginAttemptsPerConnection": [
      {
        "ConnectionId": "9233ae1b-1d56-4b36-9284-8de86c40b2fa",
        "ConnectionName": "oidcidentify01.sp.safewhere.com",
        "Count": 1
      },
      {
        "ConnectionId": "d1eeaf57-25e1-48d8-9222-c086a5362412",
        "ConnectionName": "https://saml2wif.sp.safewhere.com",
        "Count": 3
      }
    ]
  }
]

Field	Type	Description
Date	string	The date for which metrics are collected. Format: `yyyy-MM-dd`
AuthenticationConnectionId	string	Unique identifier of the authentication connection.
AuthenticationConnectionName	string	Name of the authentication connection.
NumberOfFaultyLogins	array of objects	Array of objects, each containing data about faulty login attempts.
NumberOfAccountLockouts	array of objects	Array of objects, each containing data about account lockouts.
NumberOfLoginAttemptsPerConnection	array of objects	Array of objects, each containing data about login attempts.

Each of these arrays (NumberOfFaultyLogins, NumberOfAccountLockouts, NumberOfLoginAttemptsPerConnection) contains objects with the following structure:

Field	Type	Description
ConnectionId	string	Unique identifier of the connection.
ConnectionName	string	Name of the connection.
Count	integer	Count of events (faulty logins, lockouts, attempts) for the connection.

Note: For federation logins, the count in NumberOfFaultyLogins and NumberOfAccountLockouts is 0.

apitoken endpoint

Affected operation: POST admin/api/rest/v2/apitoken

Previous behavior

The POST admin/api/rest/v2/apitoken endpoint did not accept any parameters in its Body content.

The REST API role associated with a generated refresh token was Administrator, and its token lifetime was set to 2 years.

New behavior

The endpoint POST admin/api/rest/v2/apitoken has some new parameters:

Name	Data type	Require?	Default value	Description
Name	string	✅	N/A	The refresh token name
TokenLifetime	number	⬜️	2 years	The refresh token lifetime
SelectedRoles	array	✅	N/A	Role values associated with the refresh token

URL

POST admin/api/rest/v2/apitoken

Sample:

{
    "Name": "RefreshTokenName",
    "TokenLifetime": 70,
    "SelectedRoles": ["ClaimObserver", "ClaimTransformationContributor"]
}

Safewhere Identify 5.18 REST API Release Notes

Organization-level authorization

Default page size validation in resource list

Certificate endpoint

Purge all unused expired certificates

Support new ignoreInUseCheck parameter

User endpoints

Additional sorting fields for sortBy parameter

Additional filter fields for filter parameter

MessageQueues endpoints

Connection endpoint

OAuth/OIDC application

OIDC identity provider

SAML 2.0 Identity Provider

Generic Identity Provider

Support for interceptorScriptName in application and Identity Provider configuration

Removal of NemID Identity Provider

Organization endpoint

Delete existing organizations by names

Previous behavior

New behavior

SystemSetup endpoint

nemIdMalformedRequestErrorPageUrl parameter removal

New attributes in SystemSetup

Support new logTargets

Support dd-MM-yyyy HH:mmZ format in promoteSecondaryCertificateToPrimaryAt

Audit log endpoint

loginmetrics endpoint

apitoken endpoint

Previous behavior

New behavior

Support new `ignoreInUseCheck` parameter

Additional sorting fields for `sortBy` parameter

Additional filter fields for `filter` parameter

`nemIdMalformedRequestErrorPageUrl` parameter removal

Support `dd-MM-yyyy HH:mmZ` format in promoteSecondaryCertificateToPrimaryAt