Safewhere Identify 5.16 REST API Release Notes

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

System Setup endpoint

The System Setup has some new attributes:

{
  ...,
  "oauthAccessTokenRetentionDays": 7, 
  "oauthAccessTokenCleanupExecutionTimeInMinutes": 60, 
  "oauthAccessTokenCleanupCron": "0 0 * * *",
  "enableRestApiAccessTokenRevocationCheck": false,
  "notifyUsersAboutChangesMadeToTheirAuthenticators": false,
  "passwordHashAlgorithm": "Bcrypt",
  "bcryptCostFactor": 10,
  "passwordLeakCheck": false,
  "passwordLeakCheckThreshold": 100,
  ...,
}

New configuration fields:
- oauthAccessTokenRetentionDays
- oauthAccessTokenCleanupExecutionTimeInMinutes
- oauthAccessTokenCleanupCron
- enableRestApiAccessTokenRevocationCheck
- notifyUsersAboutChangesMadeToTheirAuthenticators
- passwordHashAlgorithm
- bcryptCostFactor
- passwordLeakCheck
- passwordLeakCheckThreshold
Affected operations: GET /systemsetup, PUT /systemsetup.

Behaviors:

Name	Data type	Require?	Default value	Description
oauthAccessTokenRetentionDays	number	⬜️	7	OAuth access token retention days.
oauthAccessTokenCleanupExecutionTimeInMinutes	number	⬜️	60	OAuth access token clean up execution time in minutes.
oauthAccessTokenCleanupCron	string	⬜️	0 0 * * *	OAuth access token clean up cron.
enableRestApiAccessTokenRevocationCheck	boolean	⬜️	false	When enabled, the Identify REST API will conduct a revocation check on the authorization access token. If the token has been revoked through the revocation endpoint, the REST API will respond with an error, accompanied by an Unauthorized error code (401).
notifyUsersAboutChangesMadeToTheirAuthenticators	boolean	⬜️	false	When enabled, notify users about changes made to their authenticators.
passwordHashAlgorithm	string	⬜️	Bcrypt	Specifies the algorithm utilized for hashing passwords.
bcryptCostFactor	integer	⬜️	10	The cost factor is used to determine the iteration count required to generate a hash. This cost factor can be increased to slow down the process as hardware power increases. The higher the cost factor, the more secure the hash and the slower the process.
passwordLeakCheck	boolean	⬜️	false	When enabled, it conducts rigorous checks against an extensive password leak database each time users create or update their passwords.
passwordLeakCheckThreshold	number	⬜️	100	This setting allows users to customize the threshold for password appearances in the leak database. If it exceeds this threshold, Identify will show the error message "The password is not secure because it has been found in a database of leaked passwords." and prompt users to choose other passwords.

Connections endpoint

The Generic OIDC authentication connection and Social Medias connection configuration section model have a new attribute:

{
    ...,
    "setAccessAndRefreshTokenToClaimsPrincipal": false,
    ...,
},

New configuration fields:
- setAccessAndRefreshTokenToClaimsPrincipal:
  - Supported value: true or false
  - Default value: false
Affected operations: GET /connections, POST /connections, PUT /connections.

Behaviors:

Name	Data type	Require?	Default value	Description
setAccessAndRefreshTokenToClaimsPrincipal	boolean	⬜️	false	When enabled, it returns both access token and a refresh token from an upstream OAuth Identity Provider to its Service Provider

The OAuth20 application has some new attributes:

{
    ...,
    "allowTokenRevocationAndIntrospection": false,
    "issuerSymmetricSigningKeys": [
        {
            "issuer": "https://identify01.identify.safewhere.com/runtime/oauth2",
            "symmetricSigningKey": "/cFhfr9oXjKSBvolKqRWOq2Wb1yji/KCvzO9lfDfMlOXmJX8gElLbOLAmHG9V8ME199ai3bjkFUVVxdIy4jBig=="
        },
        {
            "issuer": "https://identify02.identify.safewhere.com/runtime/oauth2",
            "symmetricSigningKey": "nH1bDmU0sucEjxfOO8h/9QHWBaId8kZx+LFV04JP3RpgRhe3W5BuwdxavFYDTJLr"
        }
            ],
    ...,
},

New configuration fields:
- allowTokenRevocationAndIntrospection:
  - Supported value: true or false
  - Default value: false
- issuerSymmetricSigningKeys.
Affected operations: GET /connections, POST /connections, PUT /connections.

Behaviors:

Name	Data type	Require?	Default value	Description
allowTokenRevocationAndIntrospection	boolean	⬜️	false	When enabled, tokens from this specific Service Provider can be introspected or revoked
issuerSymmetricSigningKeys	list of objects	⬜️	N/A	issuer symmetric signing keys

The configuration section model of the SAML Identity Provider, SAML Service Provider, and OAuth20 Service Provider has a new attribute:

"configurations": [
        {
            ...
            "useNameIdToMatchLogoutRequestWithSession": false,
            ...
        }
]

New configuration fields:
- useNameIdToMatchLogoutRequestWithSession
Affected operations: POST /api/rest/v2/connections, PUT /api/rest/v2/connections.

Behaviors:

Name	Data type	Require?	Default value	Description
useNameIdToMatchLogoutRequestWithSession	boolean	⬜️	false	When enabled, Identify will exclusively rely on the NameID for finding the logout candidate.

ScriptLibraries endpoint

{
    "name": "Assign an authentication context class",
    "script": "if(requestedAuthenticationContextModel.MinimumNeededAuthnContext == \"https://data.gov.dk/concept/core/nsis/loa/Low\")\r\n{\r\n    requestedAuthenticationContextModel.Comparison = AuthenticationContextComparison.Minimum;\r\n    requestedAuthenticationContextModel.MinimumNeededAuthnContext = \"https://data.gov.dk/concept/core/nsis/loa/Substantial\";\r\n\r\n    SystemLogger.Instance.WriteDebug(\"[ScriptLibrary] Assign an authentication context class\");\r\n}",
    "scriptType": 0,
    "additionalNamespaces": [],
    "additionalAssemblyReferences": []
}

Updated configuration fields:
- scriptType

Behaviors: The scriptType attribute has seven more types added, making it a total of 14 types.

No.	scriptType Name	scriptType Value	Description
1	Claims transformation	31	This script type is supported since the previous version.
2	Customize an AuthnRequest that is sent to an upstream Identity Provider	51	This is a new script type.
3	Customize authentication context class that is sent via an AuthnRequest to an upstream Identity Provider	2	This script type is supported since the previous version. Its name was changed from Map a requested authentication context class to a value that will be sent to this Identity Provider.
4	Customize second factor authentication policy script	21	This script type is supported since the previous version. Its name was changed from Customize second factor authentication.
5	Customize step-up behavior	3	This script type is supported since the previous version.
6	Home realm discovery	41	This is a new script type.
7	Map authentication context method class of the second factor to a desired value	61	This is a new script type.
8	Policy that specifies whether a token can be issued for a specific login	23	This is a new script type.
9	Policy that specifies whether a user is allowed to register an MFA method	22	This is a new script type.
10	Policy that specifies whether an authentication request should be processed or rejected	24	This is a new script type.
11	Select second factor methods that users can use	71	This is a new script type.
12	Select which Identity Providers a Service Provider can use (connection dependency customization)	11	This script type is supported since the previous version. Its name was changed from Select what Identity Providers that this Service Provider can use.
13	Validate authentication context class that is returned from an upstream Identity Provider	1	This script type is supported since the previous version. Its name was changed from Validate authentication context class that is returned from this Identity Provider.
14	Validate authentication context class that is sent via an AuthnRequest from a Service Provider	0	This script type is supported since the previous version. Its name was changed from Validate authentication context class that is sent via an AuthnRequest from this Service Provider.