Safewhere Identify 5.5 Release Notes

Related Posts

Safewhere Identify is a new kind of user identification and administration service, providing externalized and seamless authentication and authorization across organizations. Safewhere Identify allows an organization to handle user identification and administration centrally and externally to all web applications and web services. Safewhere Identify allows you to support basically any kind of authentication due to its modular and open nature and it supports many authentication methods “out of the box”. Apart from built-in methods for authentication such as username and password, it also supports all the popular authentication methods, including:

  • Social logins from Facebook, Google, Twitter, LiveID, LinkedIn
  • Two-factor authentication using one time passwords and Device Code authentication
  • Federation protocols including SAML 2.0, WS-Federation, OpenID Connect, and OAuth 2.0
  • Generic Provider that allows you to easily create your own authentication provider.

Among the many other unique properties of Safewhere Identify are its multi-instance architecture that allows you to effectively run many separate federation servers on the same hardware, its ability to handle multiple logins (Multi SSO), and its support of performing intelligent home realm discovery.
This new release includes a number of incremental improvements as well as several important new features. Read more about these improvements and many others in the following sections.

New features and improvements

Identify Configurator

Option to add security HTTP headers

An option to allow using Identify Configurator to add default security HTTP headers when creating/upgrading/replicating Identify instances. Some relevant issues causing by new added HTTP headers are also fixed.

Option to deploy Safewhere Admin for existing instance

New option in Identify Configurator to allow the user to deploy Safewhere Admin by re-configuring the existing instance.

Support SQL session state

SQL session state is now re-supported due to the needs of configuring load balancing where sticky session is not available. As a side note, the feature doesn’t work with Azure SQL.

Support MultiSubnetFailover

This feature will add “MultiSubnetFailover=True;” to the connection strings in web.config so that customers who use SQL Server failover cluster don’t have to do that manually for every Identify instances like before. The new setting can be found in one of the Configurator’s installation steps.

Easier selection of SSL and token signing certificates

SSL and token signing certificates dropdown lists are now sorted alphabetically to help select certificates easier.

Support bind SSL certificate later

In the previous versions, SSL certificate is used for binding must be assigned in Identify configurator before creating a new tenant. From version 5.5, binding SSL certificate can be assigned after a new tenant is created.

OAuth 2.0

Support option “consent” for prompt parameter

Identify version 5.4 already supported the “none” and “login” options for the prompt parameter. From version 5.5, we add support for the “consent” option.

Device flow - Optimization for Non-textual Verification URIs

If the user_code exists in URL of User Code Verification form, it is filled automatically into the user code textbox with a message “please confirm that the code [...] matches the one appeared in your device”.

Support Hybrid OpenID Provider

Hybrid flow is another new OAuth 2.0 feature for which Identify has support.
You can find samples for ASPNetWebMvc and NancyOwinClient on our GitHub repository that illustrate how to execute a hybrid flow request against Identify OAuth 2.0 authorization server. Please note that in order to use the hybrid flow, a client must have 2 options “Allow code flow” and “Allow implicit flow” enabled.

Support Form Post OpenID Provider

From the version 5.5, the Form Post Response Mode is supported when you use the “form_post” as the response_mode on the authorization request.

OpenID Connect Dynamic Registration

In order for an OpenID Connect client to use Identify as an OpenID Connect Provider, the client needs to register a connection to Identify as well as needs some specific information such as the client identifier. From this version, you can register OpenID Connect clients dynamically by using the new OpenID Connect Dynamic Client Registration feature.

OIDC compliance

We tested Identify against the OIDC official compliance tool and made a few changes to fix compatibility issues:

  • The claims that are issued from the userinfo endpoint are now restricted correspondingly to the scopes associated with the authenticated access token.
  • If email/phone claim is negotiated from userinfo endpoint, it will be issued along with a claim email_verified/phone_number_verified whose value is false since the email or phone number is not verified explicitly by Identify.
  • Correct the error code to invalid_grant when either the code or refresh token in an access token request is unspecified by the Identify OAuth 2.0.
  • Irrelevant claims such as aud, iss, etc are removed from userinfo response.
  • The auth_time claim is included in the authorization response if a request has the max_age parameter.
  • For most of the authorization error responses, except the invalid redirect_uris error, they will be redirected to service provider instead of throwing exception on Identify side.
  • Correct the response mode for authorization error response on implicit flow to fragment instead of query as before.
  • Token request on code flow will be rejected if its authorization code is used twice.

Multiple Factor Authentication

Second factor policy

This is one of the most requested features. By using the new scripting second factor policy feature, you now can write simple C# script to enforce or ignore 2-factor authentication based on some particular conditions such as whether client IP is/is not in some specific IP ranges, or if a user has/does not have a specific claim, or when a user comes from a specific service provider.

OTP OS2faktor implementation

A new 2-factor method, beside Email, SMS and Authenticator, that offers users another option to do 2-factor login via various clients such as Chrome Extension, mobile apps (Android & iOS), Windows Desktop application, and YubiKey.
Latest build also implement filter to only allow users to use devices that have pin codes set up.

OTP Authenticator

A new Safewhere Admin feature that allows administrators to reset users’ Authenticator’s secret codes so that they can re-onboard when logging in next time.
In addition, users now can not only reset their Authenticator’s secret codes but also re-onboard themselves when the “Always allow users to do authenticator onboarding from his or her profile page” setting is enabled. You can find that setting in the OTP configuration UI.

Offer OTP methods selection

Before version 5.5, although you can always set up multiple OTP methods for a connection, Identify only offer a user the first method that Identify finds that it can use to send OTP code to the user. Users don’t have a chance to select a method that is more convenient to them at a specific point of time. From version 5.5, if a user can use multiple methods, e.g. if he or she has an email address, a phonenumber, and Authenticator, Identify will still pick one method for the user as before, but also offer selection for the other two methods.

Limit OTP deliveries

We added a new “OTP delivery interval (seconds)” setting to put a wait time between OTP send out using SMS or Email to prevent Identify from being abused to spam SMS or Email.


Closure of a SMTP session after sending emails

It used to be that Identify used a single SmtpClient object per mail server for all requests which ended up with block and wait time because emails were sent out sequentially. Our new code has improved SmtpClient objects handling so that Email gateway improvement by closing the SMTP session right after sending email so that the next outgoing email will not have to wait for the previous session to be closed as in previous version.

Support HTTP POST for HTTP Request SMS gateway

HTTP POST method is now supported when sending an SMS message via the HTTPRequest SMS gateway.

Hosted forms

New hosted forms

We added support for more hosted forms:

# Form name Original Razor file
1 Login AuthenticationList.cshtml
2 Reset Password ForgotPasswordPage.cshtml
3 My Profile This is a custom css for my profile page
4 Simple Login UserNamePasswordAuthentication.cshtml
5 Error Error.cshtml
6 Report Error ReportError.cshtml
7 Change Password ChangePassword.cshtml
8 Change Password Result ChangePasswordResult.cshtml
9 Renew Password Page RenewPasswordPage.cshtml
10 Renew Password email sent success RenewPasswordEmailSentSuccess.cshtml
11 Renew Password Successfully RenewPasswordSuccessfully.cshtml
12 Renew Password Unsuccessfully RenewPasswordUnsuccessfully.cshtml
13 OTP Malformed Request Error OtpMalformedRequestError.cshtml
14 Enable Authenticator EnableAuthenticator.cshtml
15 Login With Authenticator LoginWithAuthenticator.cshtml
16 OTP Authentication OtpAuthentication.cshtml
17 OTP Authentication Failed OtpAuthenticationFailed.cshtml
18 OS2faktor Device Registration OS2faktorDeviceRegistration.cshtml
19 OS2faktor No Device OS2faktorNoDevice.cshtml
20 OS2faktor User Rejected OS2faktorUserRejected.cshtml
21 OS2faktor Error OS2faktorError.cshtml
22 OS2faktor Pick Device OS2faktorPickDevice.cshtml
23 OS2faktor Login OS2faktorLogin.cshtml

Support text resource in hosted forms

To use text resources (localization) in Liquid hosted forms, you can use the {{ Resources.TextResourceFileName.TextResourceKey }} syntax. Please refer to for more detail.

Support option to activate or inactivate a hosted form

We have added a new switch on Safewhere Admin for you to activate/disactivate a hosted form. When a hosted form is set to “inactive”, Identify switches back to use the Razor file view.

Monitor metadata

This is another big and most requested feature. You can use the new settings we added to Identify Admin, Safewhere Admin, and REST API to enable metadata monitoring. The new feature can monitor certificate changes in metadata of SAML and WsFederation plugins, log the change status and auto-import the new metadata. Please note that Identify only detects certificate changes.

Account lockout

In order to protect the users from password brute-force attack, when an account reaches the maximum number of failed attempts to log in using Username & Password or to get a token using the OAuth Resource Owner Password flow, the account will be locked out. The locked account will be automatically unlocked after a pre-configured duration. For Username & Password login, that duration is a configurable setting in connection and the default value is 24 hours. For OAuth Resource Owner Password flow, the hardcoded maximum number of attempts is 10 times and lock-out duration is 1 hour.

Other features

Retrieve the GUID of the current Identify user via claim

If a log in user exists in local store, Identify now issues the user’s id via the urn:internal:userid claim. Besides, OAuth2.0 login flows used to use the user_id claim type for the same user id value, and it is now changed to use urn:internal:userid.

Make Connection EntityIds available in API for external code

When making extensions to Identify using many of its extensible points, there are times that you would like to know from what Service Provider or what Identity Provider that a request or a response comes from. You can now use our sample code to get those pieces of information.

Address warm-up time problem

Some improvements were made to reduce the Identify start-up time:

  • Drop support for 51degrees mobile library
  • Pre-build and cache Entity Framework’s EDMX models
  • Upgrade AutoMapper to the latest version and remove unnecessary mappings

Razor view compilation time is a big issue that the .NET team does not give us any option. Using hosted forms maybe a good workaround option. ## Identify REST API

Support REST API to localize text resource

SharedConfigurableSettings API now supports PATCH method and as well as localization for Help text and Error message. More details can be found at
Please note that while the sample uses en and nl, other languages are supported.

Support REST API for authenticator

New REST APIs are added that allows a user gets list of authenticators, reset authenticator and onboard authenticator:

  • get /api/rest/v2/users/authenticators
  • delete /api/rest/v2/users/resetauthenticator
  • post /api/rest/v2/users/onboardauthenticator

Support REST API for getting license information

The Safewhere Identify’s license information can be viewed with API get /api/rest/v2/systemsetup/license

Support REST API to delete a custom content

From the version 5.5, a custom content (hosted form) can be deleted with API delete /api/rest/v2/customcontents/{name}

Improve REST API for claim

Update validation to allow changing discrete claim type from single to multiple and vice versa.

Safewhere Admin

New License tab for Settings page

You can view the Safewhere Identify’s license information from Safewhere Admin by opening the License tab of the Settings page.

New setting for connectors

Some new settings are added to the following connectors:

  • OpenID Connect application: Allow Code flow, Allow Implicit flow, advance settings section, Home Realm Discovery tab
  • OAuth 2.0 application: advance settings section, Home Realm Discovery tab
  • Saml2 application/identity provider: advance settings section
  • WS Federation application/identity provider: advance settings section

New client type: SPA for OAuth2.0 and OpenIDConnect

User can quickly create a SPA sample that connects to Identify using the OAuth2.0 and OpenID Connect by using the Safewhere Admin’s client tab.

Other improvements

There are lots of improvements on Safewhere Admin:

  • “Select certificate dialog” now shows more certificate’s properties such as Issue to, thumbprint or expired date
  • More help text for Script Claim Transformation
  • Improve Inline Manual appearance for the show/hide section/form on Safewhere Admin pages
  • Multiple methods selection is now supported for One Time Password identity provider
  • Ability to drag & drop to change the order of connection dependency in Identity Providers tab of an application or Applications tab of an identity provider
  • Allow for enabling/disabling Inline Manual to boost performance

Other improvements

Framework upgrade

Upgraded all 3rd libraries used in both front-end and back-end of Safewhere Admin as well as upgraded its .NET framework to 4.7.2. Identify Runtime is still using .NET framework 4.6.2.

Remove OpenId plugins (Authentication and Protocol)

OpenId plugins are now removed. We recommended our customers to switch to OAuth2 or OpenId Connect.

Support disk and/or database encryption for Identify databases

From the version 5.5, the user can apply the encryption at the database level for Identify.

OAuth 2.0 samples

We added code to do url encode for all parameters used in OAuth 2.0/OpenIDConnect samples. The samples include OAuth2Client, ASPNetWebMvc, and OIDCClient applications.

Bug fixes


Fixed: Billing log was not logged
Fixed: Reduce Billing log data for OAuth 2.0 by only logging path instead of full URL
Fixed: The error happened when saving/deleting Field Configuration with MongoDB because of missing event types.


Fixed: Prevent deletion of claim which is being used in NameID Format Transformation

NemID plugin

Fixed: NemID filter was broken by the new update of NemID client, but is now fixed

Multiple Factor Authentication

Fixed: Exception when doing 2-factor login with OTP for OAuth Provider
Fixed: Incorrect path error happened when launching OtpMalformedRequestError view

Identify Runtime

Fixed: Identify should not perform SLO when the user logins with different authentications. The correct behaviour is that if Service Provider 1 uses Identity Provider 1 to log in and Service Provider 2 uses Identity Provider 2 to log in in the same browser session, logging out of one Service Provider shouldn’t trigger logout of the other Service Provider.
Fixed: The verification_uri of the device endpoint of a discovery response was wrong if Identify’s entityid was changed.
Fixed: There were some error cases on OAuth 2.0 which threw exceptions and stopped at Identify while it should be redirected to SP. The related error types are login_required, consent_required, interaction_required, and invalid_scope.
Fixed: Scopes displayed on the consent page were not aligned.
Fixed: Bootstrap token was not available even though the “Set bootstrap token for ClaimsPrincipal” setting is enabled. This bug fix was also merged to release 5.4.
Fixed: more support for customer who needs out of band keyinfo. This bug fix was also merged to release 5.4.
Fixed: The merge fields are not extracted when using default HTTPRequest SMS gateway. This bug fix was also merged to release 5.4.
Fixed: The issuance claim are not logged when doing the login via the STS endpoints. This bug fix was also merged to release 5.4.
Fixed: TOTP authenticator registration loop.
Fixed: OAuth password grant type not all claims are retrieved.

Identify Admin

Fixed: Yubico authentication update was failed to save.
Fixed: Exception threw when deleting a LDAPWS whose name is a URL.
Fixed: Could not input multiple emails to Contact email in System Setup.

Identify REST API

Fixed: REST APIs for connections didn’t check MaxNumberOfAllowedProtocolConnections and MaxNumberOfAllowedAuthenticationConnections settings enforced by license file.

Safewhere Admin

Fixed: User is not logged out when the browser is closed
Fixed: Certificate selection on the SAML2.0 identity provider page did not allow users to choose Upload/Choose existing options.
Fixed: Metadata field of a connector page was reset to empty when an error happened when saving a connector.
Fixed: Password field of the My profile page was not reset to empty when an error happened when a user tried to update password. They are now cleared when an error happens.
Fixed: Consent tab of OAuth2.0 connector page was not aligned.
Fixed: Password field of the private certificate import page must be shown in wildcards.
Fixed: Add default value to Method class of an authentication context method class.

Identify configurator

Fixed: Identify configurator always used the default SQL port for the IdentifyAudit database although the customized port was supplied at the previous step.
Fixed: Identify configurator crashed when credentials provided at the tenant database step does not have enough database permission.
Fixed: There was a redundant execute action called “Start the website and application pool” after action “Stop the upgrading website when upgrading Identify instance.
Fixed: Rollbacking a replicated Identify on-premise database deleted wrong tenant from dbo.tenant. This bug was merged to Release 5.4.
Fixed: Add a new step “Stop the uninstall website before “Clean up website” in order to fix an error about locking file when deleting a tenant whose log files is locked.

Break changes

When upgrading Identify instance from previous version, you may experience some following unexpected issues or changes:

  • Configurator no longer fills up the default domain for a new Identify instance you are creating. Instead, you need to fill in a domain name. If you wish to use the default domain which is [tenantname].safewhere.local, you can click on the “Use default domain” button.
  • Adding security HTTP headers may cause some external resources (images, icons, etc...) in hosted form or your custom views blocked. Please refer to this link to troubleshoot. We recommend you test them out carefully before using for a production site.
  • In general, we have fixed as well as add many small changes here and there to comply with OpenId Connect’s conformance tests. The side-effect of those changes is that something that might work before because of non-compliance code suddenly stops working now. We encourage you to test your OAuth/OpenId Connect clients and will support troubleshoot any problems caused by those changes.
  • OAuth2.0 claim issuer is now corrected to use [tenant url]/runtime/oauth2/ per specified by OAuth specification. This means that you may need to update your client apps accordingly. For example, if you are using our sample client app for testing, you will need to update the ClaimsIssuer setting to https://#YourIdentifyDomain/runtime/oauth2.
  • Userinfo endpoint no longer issues all claims by default now. For example, if a request only has the openid scope, only sub, name, and userid are issued.
  • When a login can be mapped to a user in Identify’s local store, Identify will always issue the claim “urn:internal:userid”. If you don’t want to have it issued, you can use one of the following options:
    • Use an exclude claim transformation to filter it out.
    • Or create a claim definition whose type is urn:internal:userid and mark it “avoid issuing claims” so that it is not issued to service providers.
  • Because of a new fix we did for a Single Log Out bug, if you perform Identify upgrade while some users have active login sessions, their sessions will become broken. This means that if they try to log out after that, and/or try to a log in again, they will end up with an error. Technically speaking, this short of error happening right after an upgrade is hard to prevent. Therefore, we recommend that you perform an upgrade when your Identify instance have the least logged in users.
  • After upgraded to version 5.5, Locked out accounts from previous version are migrated to the data structure with locked out duration is 24 hours. This means that after 24 hours, those accounts will be unlocked automatically.
  • When we added hosted form supports for versions before 5.5, we had to add certain Liquid code to default cshtml views to help render hosted forms correctly. That was actually not a good solution, because cshtml views were mixed of both Razor code and Liquid code. From version 5.5, we implemented a Liquid view engine that can render hosted forms without the need to have Liquid code in cshtml views. This means that we are able to revert those cshtml views back to the state that contain Razor code only. If you upgrade from a previous version and want to use custom cshtml views, we encourage you to take the latest cshtml views and merge your custom bits to them.