Identify System Setup

When setting up Safewhere Identify with the Configurator, many parameters are set automatically. If you have made any mistakes in any of them or need to fine-tune the settings, find the System Setup page under the connections module. The settings for the system are explained below:

Entity ID: A name that uniquely defines the instance of Safewhere Identify in a federation.

After creating a new tenant, the Entity ID is initially assigned a default value. This default usually works fine, but if you need to switch it to something else – like the NemLog-In service, which needs it to start with "saml" – it's best to change it before doing any other setup. Otherwise, you could face encryption problems, like with the os2faktor key in OS2faktor OTP configuration, since the Entity ID value is used as the discriminator for encrypting operations.

Base URL: The (base) URL of the instance of Safewhere Identify. For example, if the Runtime and Admin modules of a Safewhere Identify instance are set up at https://company.safewhere.com/runtime and https://company.safewhere.com/admin, respectively, the base URL is https://company.safewhere.com.

Tenant ID: Because Safewhere Identify supports multi-tenancy, each tenant needs a unique ID. The tenant ID usually forms the first fragment of the base URL, e.g. "company" in the above-mentioned example.

Role Claim Type: The claim type that stores the roles that are used for granting access to the admin part of the Safewhere Identify application.

Email Claim Type: The claim type that stores users' emails. This setting is important if you want the forgotten password feature to work on the Username and Password Authentication Connection. You can only choose claim types for this setting if all current users in the system have unique values for it.

Device Activation Code Claim Type: The claim type that stores a user's mobile activation code.

Use for Identity Model: When checked, Safewhere Identify uses the value in the system configuration for identity model instead of using the value from web.config. This is especially important to set when changing certificates and needing Identify Admin to still work in the federation.

Signing Certificate:

  • Find Value: Specifies the value that is used for searching for a signing certificate in a store. This certificate is used to sign requests/responses from this instance of Safewhere Identify to other parties.
  • Get certificates button: Allows users to select a new cert.
  • Find Type: Defines how a certificate should be searched. Possible values are FindByThumbprint, FindBySubjectName, FindBySubjectDistinguishedName, FindByIssuerName, FindByIssuerDistinguishedName, FindBySerialNumber, FindByTimeValid, FindByTimeNotYetValid, FindByTimeExpired, FindByTemplateName, FindByApplicationPolicy, FindByCertificatePolicy, FindByExtension, FindByKeyUsage, and FindBySubjectKeyIdentifier
  • Store Location: Specifies the location of the certificate store. Possible values are CurrentUser and LocalMachine.
  • Store Name: Specifies a specific store name at the location above. Possible values are AddressBook, AuthRoot, CertificateAuthority, Disallowed, and My

Organization Display Name: The name, as it will be displayed to visiting users, of the organization that owns the Safewhere Identify installation.

Organization Name: The official name of the organization that owns the Safewhere Identify installation.

Organization URL: The official web site address of the organization that owns the Safewhere Identify installation.

Contact Email: The contact email of the person who can be contacted by other partners in the federation to handle federation issues.

Send email with correlation: When an error is submitted, a notification email will be sent to the email address(es) specified in the "Contact email".

Contact Given Names: The first name(s) of the person who can be contacted by other partners in the federation to handle federation issues.

Contact Family Name: The last name of the person who can be contacted by other partners in the federation to handle federation issues.

Contact Telephone Number: The phone number of the person who can be contacted by other partners in the federation to handle federation issues.

Malformed request page: Safewhere Identify exposes endpoints that other parties can send requests and responses to. For example, BaseUrl/runtime/WSFederation/WSFederation.idp is the endpoint that a WSFederation service provider should use to send authentication requests to. However, not all the requests are well-formed and some might not contain all necessary parameters. When such a malformed request occurs, the user is redirected to this error page instead of the default ASP.NET Server Error page when no dedicated malformed request error page exists for the specific plug-in. Notice that not all endpoints are protected right now. The built-in error page can be found at [BaseUrl]/runtime/PlugIn/MalformedRequest, which is the easiest page for you to link to when setting up the installation.

NemID plugin's malformed request error page: When this field has a URL, all malformed requests happening in connection with the NemID connections are redirected to this page.

Saml2 plugin's malformed request error page: When this field has a URL then all malformed requests happening in connection with the SAML2.0 connections are redirected to this page.

WS-Federation plugin's malformed request error page: When this field has a URL, all malformed requests happening in connection with the WS-Federation connections are redirected to this page.

Username and Password plugin's malformed request error page: When this field has a URL, all malformed requests happening in connection with the Username and Password connections are redirected to this page.

OTP plugin's malformed request error page: When this field has a URL, all malformed requests happening in connection with the OTP connections are redirected to this page.

OAuth 2.0 provider plugin's malformed request error page: When this field has a URL, all malformed requests happening in connection with the OAuth 2.0 provider connections are redirected to this page.

Device-based plugin's malformed request error page: When this field has a URL, all malformed requests happening in connection with the Device-based connections are redirected to this page.

LDAP plugin's malformed request error page: When this field has a URL, all malformed requests happening in connection with the LDAP connections are redirected to this page.

GenericProvider plugin's malformed request error page: When this field has a URL, all malformed requests happening in connection with the generic provider connections are redirected to this page.

Show Consent Page: When this is activated, users on the authentication list page (also known as the selector page), are shown a link to the consent page. On the consent page, users can give consent to issue data to the different service providers registered in the system.

Sign metadata: When this is activated, SAML 2.0 metadata that Safewhere Identify generates is signed.

Show Home Realm Discovery configuration: When this is enabled, it enables users to select which HRD mechanisms will be applied for an RP. When this option is not enabled, all HRD mechanism are applied.

STS Default Certificate Claim Type: The default certificate claim type value that is used with the STS Plugin provider.

STS Default Name Claim Type: The numerable value of name claim type option. When UseDefault is selected, the default certificate Claim type value that is used with the STS Plugin provider will be used for the username endpoint and mixed username endpoint.

STS Default Name Token Type: The default token type value that is used with the STS Plugin provider.

STS Default Token Life Time: The default token lifetime value that is used with the STS Plugin provider.

STS Maximum Token Life Time: The maximum token lifetime value that is used with the STS Plugin provider.

STS Default Name Identifier Claim Type of Received Security Token: The default name identifier claim type value of received security token that is used with the STS Plugin provider.

STS Attribute name storing the name identifier claim type of Received Security Token: The attribute name storing the name identifier claim type of received security token that is used with the STS Plugin provider.

STS Enable WS Trust 14 Certificate Message Endpoint: An endpoint that authenticates the client with an X.509 certificate. The client credentials are included in the header of a SOAP message. Confidentiality is preserved by encryption inside the SOAP message.

STS Enable WS Trust 14 Certificate Mixed Endpoint: An endpoint that authenticates the client with an X.509 certificate. The client credentials are included in the header of a SOAP message. Confidentiality is preserved at the Transport layer (SSL).

STS Enable WS Trust 14 Username Message Endpoint: An endpoint that authenticates the client with its username and password. The client credentials are included in the header of a SOAP message. Confidentiality is preserved by encryption inside the SOAP message.

STS Enable WS Trust 14 Username Mixed Endpoint: An endpoint that authenticates the client with its username and password. The client credentials are included in the header of a SOAP message. Confidentiality is preserved at the Transport layer (SSL).

STS Enable WS Trust OIO IDWS Endpoint: An endpoint that authenticates the client with OIO IDWS profile. The client credentials are included in the header of a SOAP message. Confidentiality is preserved at the Transport layer (SSL).

STS Enable WS Trust 14 Issuedtokensymmetricbasic256sha256 Endpoint: An endpoint that accepts client credential as an issued token instead of username/password or certificate. The client credentials are included in the header of a SOAP message. Confidentiality is preserved by encryption inside the SOAP message.

STS Enable WS Trust 14 Issuedmixedtokensymmetricbasic256sha256 Endpoint: An endpoint that accepts client credentials as an issued token instead of username/password or certificate. The client credentials are included in the header of a SOAP message. Confidentiality is preserved at the Transport layer (SSL).

STS Service Certificate: The Service Certificate is used to sign requests/responses from this instance of STS Plugin to other parties.

  • Find Value: Specifies the value that is used for searching for a signing certificate in a store. This certificate is used to sign requests/responses from this instance of Safewhere Identify to other parties.
  • Get certificates button: Allows users to select a new cert.
  • Find Type: Defines how a certificate should be searched. Possible values are FindByThumbprint, FindBySubjectName, FindBySubjectDistinguishedName, FindByIssuerName, FindByIssuerDistinguishedName, FindBySerialNumber, FindByTimeValid, FindByTimeNotYetValid, FindByTimeExpired, FindByTemplateName, FindByApplicationPolicy, FindByCertificatePolicy, FindByExtension, FindByKeyUsage, and FindBySubjectKeyIdentifier.
  • Store Location: Specifies the location of the certificate store. Possible values are CurrentUser and LocalMachine.
  • Store Name: Specifies a specific store name at the location above. Possible values are AddressBook, AuthRoot, CertificateAuthority, Disallowed, and My.

Password settings

password-settings

Expired Password Renewal Logic: Allows users with expired passwords to use Reset Password Page to renew it. When set to True, the user request will receive the 'forgotten password mail' after making the request from the 'forgotten password page' although the password is expired.

Reset password email link expiry time in minutes: This setting determines the number of minutes after which a reset password link that the forget password/reset password feature sends to a user will expire. The default value is 60 minutes.

New account password email link expiry time in minutes: This setting determines the number of minutes after which the new account password link that is sent to a user after his or her account has been created will expire. The default value is 1440 minutes (one day).

The expiry time for the Reset password email should be significantly lower than that of the new account password email.

The number of old password remembered in history: This setting determines the number of old passwords that are saved for an account in the history. Users cannot reuse passwords that are still kept in the history table.

Offer manual update of users' passwords on user form: When activated, a field called "New Password" will be placed on the Update user form, that when filled in and saved will be validated and updated for the user record. Also for a new user, this field will be displayed when the value is set to "Set new password manually." Further, a set password option will appear in the context drop-down on the user list.

OAuth 2.0

OAuth access token retention days: This setting determines the timeframe, measured in days, during which an expired token will be retained. The default value is set to 7 days, meaning an expired token will be retained for 7 days following its expiration date.

OAuth access token clean up execution time (minutes): This setting defines the timeout for the cleanup process in minutes. It specifies the maximum duration allowed for the cleanup operation to complete its tasks, preventing it from running indefinitely and potentially impacting system performance. You can adjust this value to meet the specific requirements and resources of your system. The default value is 60 minutes.

OAuth access token clean up cron: This setting sets the schedule for automated tasks responsible for removing expired and invalid OAuth access tokens from the system. The default value, "0 0 * * *" (every midnight), indicates that the cleanup process runs daily at midnight.

You can customize these setting based on your organization's security policies and operational needs, choosing alternative schedules or frequencies as necessary.

Security

Allowed CORS Origins Domains: This is a multi-values field, available from version 5.4 which is related to Identify OAuth 2.0 workflows. In other words, from 5.4 version, a SPA application is able to execute a crossed site request to negotiate token from Identify OAuth 2.0 using implicit flow. That means the granted applications' domain URIs must be filled in this setting using the following constraints:

  • For the multi-domains, they are separated by comma (",")
  • Specifying the "*" wildcard in this field means all domains are accepted
  • Any changes of this field needs 1-2 minutes before taking effect in Identify and does not require IIS reset

Enable REST API Access token revocation check: When enabled, the Identify REST API will perform a revocation check on the authorization access token. If the token has been revoked through the revocation endpoint or no longer exists in Identify's database (for example, due to deletion by other means), the REST API will respond with an error, accompanied by an Unauthorized error code (401).

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "status": "401",
  "scimType": null,
  "detail": "The access token had been revoked. RequestId: 01844378-ced3-4316-99fa-e6a5156a91fd."
}

Others

Metadata monitoring interval (minutes): specify how often you want the background Hangfire job for monitoring metadata to be run. The "Metadata monitoring interval" setting has up until now been capped at 60 minutes (if you enter a bigger value, the job still runs every 60 minutes).

Metadata monitoring cron: Cron expression is a flexible way to schedule the metadata monitoring background Hangfire job. The quick and simple editor for cron schedule expressions can be found here

Certificate revocation check cron: Cron expression is a flexible way to schedule the certificate revocation check background Hangfire job.

Certificates revocation check result validity period: The number of minutes that revocation check status of a certificate remains valid since the last time it is validated until the next time it needs to be validated again.

Use database certificate revocation checks: Specify if Identify uses a background job to do certificate revocation checks and cache results in the Identify's database instead of doing online checks.

Suppress all certificate revocation checks: Turn all revocation checks off.

SQL command timeout: Customize the SQL command timeout (in seconds) for all database queries and commands. This setting applies to both MSSQL provider and MariaDB provider. If not specified, the default value is 30 seconds.