System APIs

1. Overview

This page contains the APIs that are used for retrieving and updating the system configuration. The

The following APIs provide a subset of the System Configuration without an API Key.

2. Retrieve the System Configuration

This API is used to retrieve the System Configuration.

2.1. Request

Retrieve the System Configuration

URI

GET /api/system-configuration

2.2. Response

The response for this API contains the System Configuration.

Table 1. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@inversoft.com for assistance.

500

There was an internal error. A stack trace is provided and logged in the Passport log files. The response will be empty.

Table 2. Response Body

systemConfiguration.backendServers [Array<String>]

The list of Passport Backend servers. This list allows Passport to communicate between different instances. Passport manages this list and it is not user modifiable.

systemConfiguration.cookieEncryptionIV [String]

The Base64 encoded initialization vector used to encrypt saved request cookies for the Passport Backend. This value has been auto-generated and may not be modified.

systemConfiguration.cookieEncryptionKey [String]

The Base64 encoded encryption key used to encrypt saved request cookies for the Passport Backend. This value has been auto-generated and may not be modified.

systemConfiguration.emailConfiguration.enabled [Boolean] Available Since 1.12.0

Indicates that the SMTP email configuration is available for use by Passport.

systemConfiguration.emailConfiguration.host [String]

The host name of the SMTP server that Passport will use.

systemConfiguration.emailConfiguration.password [String]

An optional password Passport will use to authenticate with the SMTP server.

systemConfiguration.emailConfiguration.port [Integer]

The port of the SMTP server that Passport will use.

systemConfiguration.emailConfiguration.security String

The type of security protocol Passport will use when connecting to the SMTP server. The possible values are:

  • NONE - no security will be used. All communications will be sent plaintext.

  • SSL - SSL will be used to connect to the SMTP server. This protocol is not recommended unless it is the only one your SMTP server supports.

  • TLS - TLS will be used to connect to the SMTP server. This is the preferred protocol for all SMTP servers.

systemConfiguration.emailConfiguration.username [String]

An optional username Passport will to authenticate with the SMTP server.

systemConfiguration.eventConfiguration.events [Object]

A mapping of the configuration for each event type that Passport sends. The event types that are the keys into this Object are:

  • user.bulk.create - When multiple users are created in bulk (i.e. during an import)

  • user.create - When a user is created

  • user.deactivate - When a user is deactivated

  • user.delete - When a user is deleted

  • user.reactivate - When a user is reactivated

  • user.update - When a user is updated

  • user.action - When a user action event

  • jwt.refresh-token.revoke - When a JWT Refresh Token is revoked Available Since 1.10.4

  • jwt.public-key.update - When a JWT RSA Public / Private keypair may have been changed Available Since 1.10.4

systemConfiguration.eventConfiguration.events[type].enabled [Boolean]

Whether or not Passport should send these types of events to any configured Webhooks.

systemConfiguration.eventConfiguration.events[type].transactionType String

The transaction type that Passport uses when sending these types of events to any configured Webhooks. The transaction types are:

  • None - No Webhooks are required to succeed for the Passport transaction to be committed.

  • Any - Only a single Webhook is required to succeed for the Passport transaction to be committed.

  • SimpleMajority - A simple majority (50% or more) of Webhooks are required to succeed for the Passport transaction to be committed.

  • SuperMajority - A super majority (2/3 or more) of Webhooks are required to succeed for the Passport transaction to be committed.

  • AbsoluteMajority - Every Webhook must succeed for the Passport transaction to be committed.

systemConfiguration.externalIdentifierConfiguration.authorizationGrantIdTimeToLiveInSeconds [Integer] Available Since 1.19.0

The time in seconds until a OAuth authorization code in no longer valid to be exchanged for an access token. This is essentially the time allowed between the start of an Authorization request during the Authorization code grant and when you request an access token using this authorization code on the Token endpoint.

systemConfiguration.externalIdentifierConfiguration.changePasswordIdTimeToLiveInSeconds [Integer] Available Since 1.16.0

The time in seconds until a change password Id is no longer valid and cannot be used by the Change Password API.

systemConfiguration.externalIdentifierConfiguration.emailVerificationIdTimeToLiveInSeconds [Integer] Available Since 1.16.0

The time in seconds until a email verification Id is no longer valid and cannot be used by the Verify Email API.

systemConfiguration.externalIdentifierConfiguration.registrationVerificationIdTimeToLiveInSeconds [Integer] Available Since 1.21.0

The time in seconds until a registration verification Id is no longer valid and cannot be used by the Verify Registration API.

systemConfiguration.externalIdentifierConfiguration.setupPasswordIdTimeToLiveInSeconds [Integer] Available Since 1.16.0

The time in seconds until a setup password Id is no longer valid and cannot be used by the Change Password API.

systemConfiguration.externalIdentifierConfiguration.twoFactorIdTimeToLiveInSeconds [Integer] Available Since 1.16.0

The time in seconds until a two factor Id is no longer valid and cannot be used by the Two Factor Login API.

systemConfiguration.externalIdentifierConfiguration.twoFactorTrustIdTimeToLiveInSeconds [Integer] Available Since 1.19.0

The time in seconds until an issued Two Factor trust Id is no longer valid and the User will be required to complete Two Factor authentication during the next authentication attempt.

systemConfiguration.failedAuthenticationConfiguration.actionDuration [Long] Available Since 1.6.2

The duration of the User Action. This value along with the actionDurationUnit will be used to set the duration of the User Action.

systemConfiguration.failedAuthenticationConfiguration.actionDurationUnit [String] Available Since 1.6.2

The unit of time associated with a duration. The possible values are:

  • MINUTES

  • HOURS

  • DAYS

  • WEEKS

  • MONTHS

  • YEARS

systemConfiguration.failedAuthenticationConfiguration.resetCountInSeconds [Integer] Available Since 1.6.2

The length of time in seconds before the failed authentication count will be reset.

For example, if tooManyAttempts is set to 5 and you fail to authenticate 4 times in a row, waiting for the duration specified here will cause your fifth attempt to start back at 1.

systemConfiguration.failedAuthenticationConfiguration.tooManyAttempts [Integer] Available Since 1.6.2

The number of failed attempts considered to be too many. Once this threshold is reached the specified User Action will be applied to the user for the duration specified.

systemConfiguration.failedAuthenticationUserActionId [UUID] Available Since 1.6.2

The Id of the User Action that is applied when the threshold is reached for too many failed authentication attempts.

systemConfiguration.forgotEmailTemplateId [UUID]

The Id of the Email Template that is used when a user is sent a forgot password email.

systemConfiguration.httpSessionMaxInactiveInterval [Integer]

The time in seconds until an inactive session will be invalidated. Used when creating a new session in the Passport Front End.

application.jwtConfiguration.algorithm [String]

The algorithm used to sign the JSON Web Token (JWT). The following available JSON Web Algorithms (JWA) as described in RFC 7518 are available.

  • HS256 - HMAC using SHA-256

  • HS384 - HMAC using SHA-384

  • HS512 - HMAC using SHA-512

  • RS256 - RSASSA-PKCS1-v1_5 using SHA-256

  • RS384 - RSASSA-PKCS1-v1_5 using SHA-384

  • RS512 - RSASSA-PKCS1-v1_5 using SHA-512

  • none - Unsecured

systemConfiguration.jwtConfiguration.enabled [Boolean] Available Since 1.6.2

This value will always be true. The JWT configuration may not be disabled for the System Configuration.

systemConfiguration.jwtConfiguration.issuer [String] Available Since 1.6.2

The name or issuer of the JWT, this is generally something unique such as a fully qualified domain name.

For example, www.inversoft.com.

systemConfiguration.jwtConfiguration.privateKey [String] Available Since 1.6.2

The private key used when an RSA signing algorithm has been selected. The private key will be used to sign the JWT. This key will be returned in a PEM encoded format.

systemConfiguration.jwtConfiguration.publicKey [String] Available Since 1.6.2

The public key used when an RSA signing algorithms has been selected. The public key will be used to verify JWTs signed with the private key. This key will be returned in a PEM encoded format.

systemConfiguration.jwtConfiguration.refreshTokenTimeToLiveInMinutes [Integer] Available Since 1.6.2

The length of time in minutes the JWT refresh token will live before it is expired and is not able to be exchanged for a JWT.

systemConfiguration.jwtConfiguration.secret [String] Available Since 1.6.2

The secret used when an HMAC based signing algorithm has been selected. This secret is used to sign and verify JWTs.

systemConfiguration.jwtConfiguration.timeToLiveInSeconds [Integer] Available Since 1.6.2

The length of time in seconds the JWT will live before it is expired. This value is used to calculate the exp (expiration) identity claim.

systemConfiguration.logoutURL [String]

The logout redirect URL when sending the user’s browser to the /oauth2/logout URI of the Passport Front End. This value is only used when a logout URL is not defined in your Application.

systemConfiguration.maximumPasswordAge.days [Integer] Available Since 1.10.4

The password maximum age in days. The number of days after which Passport will require a user to change their password.

systemConfiguration.maximumPasswordAge.enabled [Boolean] Available Since 1.10.4

Indicates that the maximum password age is enabled and being enforced.

systemConfiguration.minimumPasswordAge.seconds [Integer] Available Since 1.10.4

The password minimum age in seconds. When enabled Passport will not allow a password to be changed until it reaches this minimum age.

systemConfiguration.minimumPasswordAge.enabled [Boolean] Available Since 1.10.4

Indicates that the minimum password age is enabled and being enforced.

systemConfiguration.passwordEncryptionConfiguration.encryptionScheme [String] Available Since 1.9.4

The selected default encryption scheme.

systemConfiguration.passwordEncryptionConfiguration.encryptionSchemeFactor [String] Available Since 1.9.4

The factor used by the password encryption scheme. Generally this will be used as an iteration count to generate the hash. The actual use of this value is up to the PasswordEncryptor implementation.

systemConfiguration.passwordEncryptionConfiguration.modifyEncryptionSchemeOnLogin [Boolean] Available Since 1.9.4

When enabled a user’s hash configuration will be modified to match these configured settings.

systemConfiguration.passwordExpirationDays [Integer] Deprecated

The number of days after which Passport will automatically expire passwords for all users. If this isn’t set, Passport will not expire passwords ever. Prefer the use of systemConfiguration.maximumPasswordAge.days once available.

systemConfiguration.passwordValidationRules.maxLength [Integer]

The maximum number of characters that are allowed for user passwords.

systemConfiguration.passwordValidationRules.minLength [Integer]

The minimum number of characters that are required for user passwords.

systemConfiguration.passwordValidationRules.rememberPreviousPasswords.count [Integer] Available Since 1.10.4

The number of previous passwords that should be remembered so they are not re-used by the User.

systemConfiguration.passwordValidationRules.rememberPreviousPasswords.enabled [Boolean] Available Since 1.10.4

Indicates that the remember previous password validation is enabled and being enforced.

systemConfiguration.passwordValidationRules.requireMixedCase [Boolean]

Indicates that passwords require an uppercase and lowercase character to be valid.

systemConfiguration.passwordValidationRules.requireNonAlpha [Boolean]

Indicates that passwords require a non-alphanumeric character to be valid.

systemConfiguration.passwordValidationRules.requireNumber [Boolean] Available Since 1.19.0

Indicates that passwords require at least one number to be valid.

systemConfiguration.reportTimezone [String]

The timezone that all reports will be generated in. Since reports are usually rolled up hourly, this timezone will be used for demarcating the hours. This must be a valid java.util.time.ZoneId String. (see https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html)

systemConfiguration.setPasswordEmailTemplateId [UUID]

The Id of the Email Template that is used when a user had their account created for them and they must set their password manually and they are sent an email to set their password.

systemConfiguration.uiConfiguration.headerColor [String] Available Since 1.10.4

A hexadecimal color to override the default menu color in the user interface.

systemConfiguration.uiConfiguration.loginTheme.enabled [Boolean] Available Since 1.19.0

Indicates that the login theme is enabled and will be used to style the login pages.

systemConfiguration.uiConfiguration.loginTheme.stylesheet [String] Available Since 1.19.0

A stylesheet used to style the login page and other templates such as forgot password, and verify email.

systemConfiguration.uiConfiguration.logoURL [String] Available Since 1.10.4

A URL of a logo to override the default Passport logo in the user interface.

systemConfiguration.uiConfiguration.menuFontColor [String] Available Since 1.10.4

A hexadecimal color to override the default menu font color in the user interface.

systemConfiguration.verificationEmailTemplateId [UUID]

The Id of the Email Template that is used to send the verification emails to users. These emails are used to verify that a user’s email address is valid. If the verifyEmail field is true this field is required.

systemConfiguration.verifyEmail [Boolean]

Whether or not user’s email addresses are verified when the register with your application.

systemConfiguration.verifyEmailWhenChanged [Boolean]

Whether or not user’s email addresses are verified when the user changes them.

Example Response JSON
{
  "systemConfiguration": {
    "backendServers": [
      "http://localhost:9011"
    ],
    "emailConfiguration": {
      "enabled": true,
      "host": "smtp.sendgrid.net",
      "password": "password",
      "port": 587,
      "security": "TLS",
      "username": "username"
    },
    "eventConfiguration": {
      "user.create": {
        "enabled": true,
        "transactionType": "AbsoluteMajority"
      }
    },
    "externalIdentifierConfiguration" : {
      "authorizationGrantIdTimeToLiveInSeconds" : 30,
      "changePasswordIdTimeToLiveInSeconds" : 300,
      "emailVerificationIdTimeToLiveInSeconds" : 86400,
      "setupPasswordIdTimeToLiveInSeconds" : 86400,
      "twoFactorIdTimeToLiveInSeconds" : 300,
      "twoFactorTrustIdTimeToLiveInSeconds" : 2592000
    },
    "failedAuthenticationUserActionId": "16cfc707-268c-4c5b-8989-f71f3ee156d4",
    "failedAuthenticationConfiguration" : {
      "actionDuration" : 3,
      "actionDurationUnit" : "MINUTES",
      "resetCountInSeconds" : 60,
      "tooManyAttempts" : 5
    },
    "forgotEmailTemplateId": "49aba1de-0225-45d7-a2b1-f9fe46b0242c",
    "httpSessionMaxInactiveInterval": 3600,
    "logoutURL": "http://example.com/logout",
    "maximumPasswordAge": {
      "days": 180,
      "enabled": true
    },
    "minimumPasswordAge": {
      "enabled": true,
      "seconds": 60
    },
    "passwordEncryptionConfiguration": {
      "encryptionScheme": "salted-pbkdf2-hmac-sha256",
      "encryptionSchemeFactor": 24000,
      "modifyEncryptionSchemeOnLogin": false
    },
    "passwordExpirationDays": 30,
    "passwordValidationRules": {
      "maxLength": 256,
      "minLength": 8,
      "rememberPreviousPasswords": {
        "count": 2,
        "enabled": true
      },
      "requireMixedCase": true,
      "requireNonAlpha": true,
      "requireNumber": true
    },
    "reportTimezone": "America/Denver",
    "setPasswordEmailTemplateId": "a9aba13e-0125-4fd7-a2b1-aaa146b02423",
    "uiConfiguration": {
      "loginTheme": {
        "enabled": false
      }
    },
    "verificationEmailTemplateId": "8da42c09-461c-45f3-b931-6e9f63b87a00",
    "verifyEmail": true,
    "verifyEmailWhenChanged": true
  }
}

3. Update the System Configuration

This API is used to update System Configuration.

3.1. Request

Update the System Configuration

URI

PUT /api/system-configuration

Table 3. Request Body

systemConfiguration.emailConfiguration.enabled Optional [Boolean] Available Since 1.12.0 defaults to false

Indicates that the SMTP email configuration is available for use by Passport.

systemConfiguration.emailConfiguration.host [String] Optional

The host name of the SMTP server that Passport will use. Required when systemConfiguration.emailConfiguration.enabled is set to true.

systemConfiguration.emailConfiguration.password [String] Optional

An optional password Passport will use to authenticate with the SMTP server.

systemConfiguration.emailConfiguration.port [Integer] Optional

The port of the SMTP server that Passport will use. Required when systemConfiguration.emailConfiguration.enabled is set to true.

systemConfiguration.emailConfiguration.security String Optional defaults to NONE

The type of security protocol Passport will use when connecting to the SMTP server. The possible values are:

  • NONE - no security will be used. All communications will be sent plaintext.

  • SSL - SSL will be used to connect to the SMTP server. This protocol is not recommended unless it is the only one your SMTP server supports.

  • TLS - TLS will be used to connect to the SMTP server. This is the preferred protocol for all SMTP servers.

systemConfiguration.emailConfiguration.username [String] Optional

An optional username Passport will to authenticate with the SMTP server.

systemConfiguration.eventConfiguration.events [Object] Optional defaults to {}

A mapping of the configuration for each event type that Passport sends. The event types that are the keys into this Object are:

  • user.bulk.create - When multiple users are created in bulk (i.e. during an import)

  • user.create - When a user is created

  • user.deactivate - When a user is deactivated

  • user.delete - When a user is deleted

  • user.reactivate - When a user is reactivated

  • user.update - When a user is updated

  • user.action - When a user action event

  • jwt.refresh-token.revoke - When a JWT Refresh Token is revoked Available Since 1.10.4

  • jwt.public-key.update - When a JWT RSA Public / Private keypair may have been changed Available Since 1.10.4

systemConfiguration.eventConfiguration.events[type].enabled [Boolean] Optional defaults to false

Whether or not Passport should send these types of events to any configured Webhooks.

systemConfiguration.eventConfiguration.events[type].transactionType String Optional

The transaction type that Passport uses when sending these types of events to any configured Webhooks. The transaction types are:

  • None - No Webhooks are required to succeed for the Passport transaction to be committed.

  • Any - Only a single Webhook is required to succeed for the Passport transaction to be committed.

  • SimpleMajority - A simple majority (50% or more) of Webhooks are required to succeed for the Passport transaction to be committed.

  • SuperMajority - A super majority (2/3 or more) of Webhooks are required to succeed for the Passport transaction to be committed.

  • AbsoluteMajority - Every Webhook must succeed for the Passport transaction to be committed.

systemConfiguration.externalIdentifierConfiguration.authorizationGrantIdTimeToLiveInSeconds [Integer] Required Available Since 1.19.0

The time in seconds until a OAuth authorization code in no longer valid to be exchanged for an access token. This is essentially the time allowed between the start of an Authorization request during the Authorization code grant and when you request an access token using this authorization code on the Token endpoint.

Value must be greater than 0 and less than or equal to 600.

systemConfiguration.externalIdentifierConfiguration.changePasswordIdTimeToLiveInSeconds [Integer] Required Available Since 1.16.0

The time in seconds until a change password Id is no longer valid and cannot be used by the Change Password API. Value must be greater than 0.

systemConfiguration.externalIdentifierConfiguration.emailVerificationIdTimeToLiveInSeconds [Integer] Required Available Since 1.16.0

The time in seconds until a email verification Id is no longer valid and cannot be used by the Verify Email API. Value must be greater than 0.

systemConfiguration.externalIdentifierConfiguration.registrationVerificationIdTimeToLiveInSeconds [Integer] Required Available Since 1.21.0

The time in seconds until a registration verification Id is no longer valid and cannot be used by the Verify Registration API. Value must be greater than 0.

systemConfiguration.externalIdentifierConfiguration.setupPasswordIdTimeToLiveInSeconds [Integer] Required Available Since 1.16.0

The time in seconds until a setup password Id is no longer valid and cannot be used by the Change Password API. Value must be greater than 0.

systemConfiguration.externalIdentifierConfiguration.twoFactorIdTimeToLiveInSeconds [Integer] Required Available Since 1.16.0

The time in seconds until a two factor Id is no longer valid and cannot be used by the Two Factor Login API. Value must be greater than 0.

systemConfiguration.externalIdentifierConfiguration.twoFactorTrustIdTimeToLiveInSeconds [Integer] Required Available Since 1.19.0

The time in seconds until an issued Two Factor trust Id is no longer valid and the User will be required to complete Two Factor authentication during the next authentication attempt. Value must be greater than 0.

systemConfiguration.failedAuthenticationConfiguration.actionDuration [Long] Available Since 1.6.2

The duration of the User Action. This value along with the actionDurationUnit will be used to set the duration of the User Action.

systemConfiguration.failedAuthenticationConfiguration.actionDurationUnit [String] Available Since 1.6.2

The unit of time associated with a duration. The possible values are:

  • MINUTES

  • HOURS

  • DAYS

  • WEEKS

  • MONTHS

  • YEARS

systemConfiguration.failedAuthenticationConfiguration.resetCountInSeconds [Integer] Available Since 1.6.2

The length of time in seconds before the failed authentication count will be reset.

For example, if tooManyAttempts is set to 5 and you fail to authenticate 4 times in a row, waiting for the duration specified here will cause your fifth attempt to start back at 1.

systemConfiguration.failedAuthenticationConfiguration.tooManyAttempts [Integer] Available Since 1.6.2

The number of failed attempts considered to be too many. Once this threshold is reached the specified User Action will be applied to the user for the duration specified.

systemConfiguration.failedAuthenticationUserActionId [UUID] Available Since 1.6.2

The Id of the User Action that is applied when the threshold is reached for too many failed authentication attempts.

systemConfiguration.forgotEmailTemplateId [UUID] Required

The Id of the Email Template that is used when a user is sent a forgot password email.

systemConfiguration.httpSessionMaxInactiveInterval [Integer] Required defaults to 60 minutes

The time in seconds until an inactive session will be invalidated. Used when creating a new session in the Passport Front End.

application.jwtConfiguration.algorithm [String] Required

The algorithm used to sign the JSON Web Token (JWT). The following available JSON Web Algorithms (JWA) as described in RFC 7518 are available.

  • HS256 - HMAC using SHA-256

  • HS384 - HMAC using SHA-384

  • HS512 - HMAC using SHA-512

  • RS256 - RSASSA-PKCS1-v1_5 using SHA-256

  • RS384 - RSASSA-PKCS1-v1_5 using SHA-384

  • RS512 - RSASSA-PKCS1-v1_5 using SHA-512

  • none - Unsecured

systemConfiguration.jwtConfiguration.issuer [String] Required Available Since 1.6.2

The name or issuer of the JWT, this is generally something unique such as a fully qualified domain name.

For example, www.inversoft.com.

systemConfiguration.jwtConfiguration.privateKey [String] Optional Available Since 1.6.2

The private key used when an RSA signing algorithm has been selected. The private key will be used to sign the JWT. This key is expected to be in a PEM encoded format. Required when algorithm is set to an RSA based value.

systemConfiguration.jwtConfiguration.publicKey [String] Optional Available Since 1.6.2

The public key used when an RSA signing algorithms has been selected. The public key will be used to verify JWTs signed with the private key. This key is expected to be in a PEM encoded format. Required when algorithm is set to an RSA based value.

systemConfiguration.jwtConfiguration.refreshTokenTimeToLiveInMinutes Required [Integer] Available Since 1.6.2

The length of time in minutes the JWT refresh token will live before it is expired and is not able to be exchanged for a JWT.

systemConfiguration.jwtConfiguration.secret [String] Optional Available Since 1.6.2

The secret used when an HMAC based signing algorithm has been selected. This secret is used to sign and verify JWTs. Required when algorithm is set to an HMAC based value.

systemConfiguration.jwtConfiguration.timeToLiveInSeconds [Integer] Required Available Since 1.6.2

The length of time in seconds the JWT will live before it is expired. This value is used to calculate the exp (expiration) identity claim.

systemConfiguration.logoutURL [String] Optional

The logout redirect URL when sending the user’s browser to the /oauth2/logout URI of the Passport Front End. This value is only used when a logout URL is not defined in your Application.

systemConfiguration.maximumPasswordAge.days [Integer] Optional Available Since 1.10.4

The password maximum age in days. The number of days after which Passport will require a user to change their password. Required when systemConfiguration.maximumPasswordAge.enabled is set to true.

systemConfiguration.maximumPasswordAge.enabled [Boolean] Optional Available Since 1.10.4

Indicates that the maximum password age is enabled and being enforced.

systemConfiguration.minimumPasswordAge.seconds [Integer] Optional Available Since 1.10.4

The password minimum age in seconds. When enabled Passport will not allow a password to be changed until it reaches this minimum age. Required when systemConfiguration.minimumPasswordAge.enabled is set to true.

systemConfiguration.minimumPasswordAge.enabled [Boolean] Optional Available Since 1.10.4

Indicates that the minimum password age is enabled and being enforced.

systemConfiguration.passwordEncryptionConfiguration.encryptionScheme [String] Optional Available Since 1.9.4

The default method for encrypting the User’s password. The following encryptors are provided with Passport:

systemConfiguration.passwordEncryptionConfiguration.encryptionSchemeFactor [String] Optional Available Since 1.9.4

The factor used by the password encryption scheme. If not provided, the PasswordEncryptor provides a default value. Generally this will be used as an iteration count to generate the hash. The actual use of this value is up to the PasswordEncryptor implementation.

systemConfiguration.passwordEncryptionConfiguration.modifyEncryptionSchemeOnLogin [Boolean] Optional Available Since 1.9.4

When enabled a user’s hash configuration will be modified to match these configured settings. This can be useful to increase a password hash strength over time or upgrade imported users to a more secure encryption scheme after an initial import.

systemConfiguration.passwordExpirationDays [Integer] Optional Deprecated

The number of days after which Passport will automatically expire passwords for all users. If this value is omitted, Passport will not expire passwords. Prefer the use of systemConfiguration.maximumPasswordAge.days once available.

systemConfiguration.passwordValidationRules.maxLength [Integer] Required

The maximum number of characters that are allowed for user passwords.

systemConfiguration.passwordValidationRules.minLength [Integer] Required

The minimum number of characters that are required for user passwords.

systemConfiguration.passwordValidationRules.rememberPreviousPasswords.count [Integer] Optional Available Since 1.10.4

The number of previous passwords that should be remembered so they are not re-used by the User. Required when systemConfiguration.passwordValidationRules.rememberPreviousPasswords.count is set to true.

systemConfiguration.passwordValidationRules.rememberPreviousPasswords.enabled [Boolean] Optional Available Since 1.10.4

Indicates that the remember previous password validation is enabled and being enforced.

systemConfiguration.passwordValidationRules.requireMixedCase [Boolean] Optional defaults to false

Indicates that passwords require an uppercase and lowercase character to be valid.

systemConfiguration.passwordValidationRules.requireNonAlpha [Boolean] Optional defaults to false

Indicates that passwords require a non-alphanumeric character to be valid.

systemConfiguration.passwordValidationRules.requireNumber [Boolean] Optional defaults to false Available Since 1.19.0

Indicates that passwords require at least one number to be valid.

systemConfiguration.reportTimezone [String] Required

The timezone that all reports will be generated in. Since reports are usually rolled up hourly, this timezone will be used for demarcating the hours. This must be a valid java.util.time.ZoneId String. (see https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html)

systemConfiguration.setPasswordEmailTemplateId [UUID] Optional

The Id of the Email Template that is used when a user had their account created for them and they must set their password manually and they are sent an email to set their password.

systemConfiguration.uiConfiguration.headerColor [String] Optional Available Since 1.10.4

A hexadecimal color to override the default menu color in the user interface.

Example: 000000 would set the menu color to black.

systemConfiguration.uiConfiguration.loginTheme.enabled [Boolean] Optional Available Since 1.19.0 defaults to false

Indicates that the login theme is enabled and will be used to style the login pages.

systemConfiguration.uiConfiguration.loginTheme.stylesheet [String] Optional Available Since 1.19.0

A stylesheet used to style the login page and other templates such as forgot password, and verify email.

systemConfiguration.uiConfiguration.logoURL [String] Optional Available Since 1.10.4

A URL of a logo to override the default Passport logo in the user interface.

systemConfiguration.uiConfiguration.menuFontColor [String] Optional Available Since 1.10.4

A hexadecimal color to override the default menu font color in the user interface.

Example: FFFFFF would set the menu font color to white.

systemConfiguration.verificationEmailTemplateId [UUID] Optional

The If of the Email Template that is used to send the verification emails to users. These emails are used to verify that a user’s email address is valid. If the verifyEmail field is true this field is required.

systemConfiguration.verifyEmail [Boolean] Optional defaults to false

Whether or not user’s email addresses are verified when the register with your application.

systemConfiguration.verifyEmailWhenChanged [Boolean] Optional defaults to false

Whether or not user’s email addresses are verified when the user changes them.

Example Request JSON
{
  "systemConfiguration": {
    "emailConfiguration": {
      "enabled": true,
      "host": "smtp.sendgrid.net",
      "password": "password",
      "port": 587,
      "security": "TLS",
      "username": "username"
    },
    "eventConfiguration": {
      "user.create": {
        "enabled": true,
        "transactionType": "AbsoluteMajority"
      }
    },
    "externalIdentifierConfiguration" : {
      "authorizationGrantIdTimeToLiveInSeconds" : 30,
      "changePasswordIdTimeToLiveInSeconds" : 300,
      "emailVerificationIdTimeToLiveInSeconds" : 86400,
      "setupPasswordIdTimeToLiveInSeconds" : 86400,
      "twoFactorIdTimeToLiveInSeconds" : 300,
      "twoFactorTrustIdTimeToLiveInSeconds" : 2592000
    },
    "failedAuthenticationUserActionId": "16cfc707-268c-4c5b-8989-f71f3ee156d4",
    "failedAuthenticationConfiguration" : {
      "actionDuration" : 3,
      "actionDurationUnit" : "MINUTES",
      "resetCountInSeconds" : 60,
      "tooManyAttempts" : 5
    },
    "forgotEmailTemplateId": "49aba1de-0225-45d7-a2b1-f9fe46b0242c",
    "httpSessionMaxInactiveInterval": 3600,
    "logoutURL": "http://example.com/logout",
    "maximumPasswordAge": {
      "days": 180,
      "enabled": true
    },
    "minimumPasswordAge": {
      "enabled": true,
      "seconds": 60
    },
    "passwordEncryptionConfiguration": {
      "encryptionScheme": "salted-pbkdf2-hmac-sha256",
      "encryptionSchemeFactor": 24000,
      "modifyEncryptionSchemeOnLogin": false
    },
    "passwordExpirationDays": 30,
    "passwordValidationRules": {
      "maxLength": 256,
      "minLength": 8,
      "rememberPreviousPasswords": {
        "count": 2,
        "enabled": true
      },
      "requireMixedCase": true,
      "requireNonAlpha": true,
      "requireNumber": true
    },
    "reportTimezone": "America/Denver",
    "setPasswordEmailTemplateId": "a9aba13e-0125-4fd7-a2b1-aaa146b02423",
    "verificationEmailTemplateId": "8da42c09-461c-45f3-b931-6e9f63b87a00",
    "verifyEmail": true,
    "verifyEmailWhenChanged": true
  }
}

3.2. Response

The response for this API contains the System Configuration.

Table 4. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@inversoft.com for assistance.

500

There was an internal error. A stack trace is provided and logged in the Passport log files. The response will be empty.

Table 5. Response Body

systemConfiguration.backendServers [Array<String>]

The list of Passport Backend servers. This list allows Passport to communicate between different instances. Passport manages this list and it is not user modifiable.

systemConfiguration.cookieEncryptionIV [String]

The Base64 encoded initialization vector used to encrypt saved request cookies for the Passport Backend. This value has been auto-generated and may not be modified.

systemConfiguration.cookieEncryptionKey [String]

The Base64 encoded encryption key used to encrypt saved request cookies for the Passport Backend. This value has been auto-generated and may not be modified.

systemConfiguration.emailConfiguration.enabled [Boolean] Available Since 1.12.0

Indicates that the SMTP email configuration is available for use by Passport.

systemConfiguration.emailConfiguration.host [String]

The host name of the SMTP server that Passport will use.

systemConfiguration.emailConfiguration.password [String]

An optional password Passport will use to authenticate with the SMTP server.

systemConfiguration.emailConfiguration.port [Integer]

The port of the SMTP server that Passport will use.

systemConfiguration.emailConfiguration.security String

The type of security protocol Passport will use when connecting to the SMTP server. The possible values are:

  • NONE - no security will be used. All communications will be sent plaintext.

  • SSL - SSL will be used to connect to the SMTP server. This protocol is not recommended unless it is the only one your SMTP server supports.

  • TLS - TLS will be used to connect to the SMTP server. This is the preferred protocol for all SMTP servers.

systemConfiguration.emailConfiguration.username [String]

An optional username Passport will to authenticate with the SMTP server.

systemConfiguration.eventConfiguration.events [Object]

A mapping of the configuration for each event type that Passport sends. The event types that are the keys into this Object are:

  • user.bulk.create - When multiple users are created in bulk (i.e. during an import)

  • user.create - When a user is created

  • user.deactivate - When a user is deactivated

  • user.delete - When a user is deleted

  • user.reactivate - When a user is reactivated

  • user.update - When a user is updated

  • user.action - When a user action event

  • jwt.refresh-token.revoke - When a JWT Refresh Token is revoked Available Since 1.10.4

  • jwt.public-key.update - When a JWT RSA Public / Private keypair may have been changed Available Since 1.10.4

systemConfiguration.eventConfiguration.events[type].enabled [Boolean]

Whether or not Passport should send these types of events to any configured Webhooks.

systemConfiguration.eventConfiguration.events[type].transactionType String

The transaction type that Passport uses when sending these types of events to any configured Webhooks. The transaction types are:

  • None - No Webhooks are required to succeed for the Passport transaction to be committed.

  • Any - Only a single Webhook is required to succeed for the Passport transaction to be committed.

  • SimpleMajority - A simple majority (50% or more) of Webhooks are required to succeed for the Passport transaction to be committed.

  • SuperMajority - A super majority (2/3 or more) of Webhooks are required to succeed for the Passport transaction to be committed.

  • AbsoluteMajority - Every Webhook must succeed for the Passport transaction to be committed.

systemConfiguration.externalIdentifierConfiguration.authorizationGrantIdTimeToLiveInSeconds [Integer] Available Since 1.19.0

The time in seconds until a OAuth authorization code in no longer valid to be exchanged for an access token. This is essentially the time allowed between the start of an Authorization request during the Authorization code grant and when you request an access token using this authorization code on the Token endpoint.

systemConfiguration.externalIdentifierConfiguration.changePasswordIdTimeToLiveInSeconds [Integer] Available Since 1.16.0

The time in seconds until a change password Id is no longer valid and cannot be used by the Change Password API.

systemConfiguration.externalIdentifierConfiguration.emailVerificationIdTimeToLiveInSeconds [Integer] Available Since 1.16.0

The time in seconds until a email verification Id is no longer valid and cannot be used by the Verify Email API.

systemConfiguration.externalIdentifierConfiguration.registrationVerificationIdTimeToLiveInSeconds [Integer] Available Since 1.21.0

The time in seconds until a registration verification Id is no longer valid and cannot be used by the Verify Registration API.

systemConfiguration.externalIdentifierConfiguration.setupPasswordIdTimeToLiveInSeconds [Integer] Available Since 1.16.0

The time in seconds until a setup password Id is no longer valid and cannot be used by the Change Password API.

systemConfiguration.externalIdentifierConfiguration.twoFactorIdTimeToLiveInSeconds [Integer] Available Since 1.16.0

The time in seconds until a two factor Id is no longer valid and cannot be used by the Two Factor Login API.

systemConfiguration.externalIdentifierConfiguration.twoFactorTrustIdTimeToLiveInSeconds [Integer] Available Since 1.19.0

The time in seconds until an issued Two Factor trust Id is no longer valid and the User will be required to complete Two Factor authentication during the next authentication attempt.

systemConfiguration.failedAuthenticationConfiguration.actionDuration [Long] Available Since 1.6.2

The duration of the User Action. This value along with the actionDurationUnit will be used to set the duration of the User Action.

systemConfiguration.failedAuthenticationConfiguration.actionDurationUnit [String] Available Since 1.6.2

The unit of time associated with a duration. The possible values are:

  • MINUTES

  • HOURS

  • DAYS

  • WEEKS

  • MONTHS

  • YEARS

systemConfiguration.failedAuthenticationConfiguration.resetCountInSeconds [Integer] Available Since 1.6.2

The length of time in seconds before the failed authentication count will be reset.

For example, if tooManyAttempts is set to 5 and you fail to authenticate 4 times in a row, waiting for the duration specified here will cause your fifth attempt to start back at 1.

systemConfiguration.failedAuthenticationConfiguration.tooManyAttempts [Integer] Available Since 1.6.2

The number of failed attempts considered to be too many. Once this threshold is reached the specified User Action will be applied to the user for the duration specified.

systemConfiguration.failedAuthenticationUserActionId [UUID] Available Since 1.6.2

The Id of the User Action that is applied when the threshold is reached for too many failed authentication attempts.

systemConfiguration.forgotEmailTemplateId [UUID]

The Id of the Email Template that is used when a user is sent a forgot password email.

systemConfiguration.httpSessionMaxInactiveInterval [Integer]

The time in seconds until an inactive session will be invalidated. Used when creating a new session in the Passport Front End.

application.jwtConfiguration.algorithm [String]

The algorithm used to sign the JSON Web Token (JWT). The following available JSON Web Algorithms (JWA) as described in RFC 7518 are available.

  • HS256 - HMAC using SHA-256

  • HS384 - HMAC using SHA-384

  • HS512 - HMAC using SHA-512

  • RS256 - RSASSA-PKCS1-v1_5 using SHA-256

  • RS384 - RSASSA-PKCS1-v1_5 using SHA-384

  • RS512 - RSASSA-PKCS1-v1_5 using SHA-512

  • none - Unsecured

systemConfiguration.jwtConfiguration.enabled [Boolean] Available Since 1.6.2

This value will always be true. The JWT configuration may not be disabled for the System Configuration.

systemConfiguration.jwtConfiguration.issuer [String] Available Since 1.6.2

The name or issuer of the JWT, this is generally something unique such as a fully qualified domain name.

For example, www.inversoft.com.

systemConfiguration.jwtConfiguration.privateKey [String] Available Since 1.6.2

The private key used when an RSA signing algorithm has been selected. The private key will be used to sign the JWT. This key will be returned in a PEM encoded format.

systemConfiguration.jwtConfiguration.publicKey [String] Available Since 1.6.2

The public key used when an RSA signing algorithms has been selected. The public key will be used to verify JWTs signed with the private key. This key will be returned in a PEM encoded format.

systemConfiguration.jwtConfiguration.refreshTokenTimeToLiveInMinutes [Integer] Available Since 1.6.2

The length of time in minutes the JWT refresh token will live before it is expired and is not able to be exchanged for a JWT.

systemConfiguration.jwtConfiguration.secret [String] Available Since 1.6.2

The secret used when an HMAC based signing algorithm has been selected. This secret is used to sign and verify JWTs.

systemConfiguration.jwtConfiguration.timeToLiveInSeconds [Integer] Available Since 1.6.2

The length of time in seconds the JWT will live before it is expired. This value is used to calculate the exp (expiration) identity claim.

systemConfiguration.logoutURL [String]

The logout redirect URL when sending the user’s browser to the /oauth2/logout URI of the Passport Front End. This value is only used when a logout URL is not defined in your Application.

systemConfiguration.maximumPasswordAge.days [Integer] Available Since 1.10.4

The password maximum age in days. The number of days after which Passport will require a user to change their password.

systemConfiguration.maximumPasswordAge.enabled [Boolean] Available Since 1.10.4

Indicates that the maximum password age is enabled and being enforced.

systemConfiguration.minimumPasswordAge.seconds [Integer] Available Since 1.10.4

The password minimum age in seconds. When enabled Passport will not allow a password to be changed until it reaches this minimum age.

systemConfiguration.minimumPasswordAge.enabled [Boolean] Available Since 1.10.4

Indicates that the minimum password age is enabled and being enforced.

systemConfiguration.passwordEncryptionConfiguration.encryptionScheme [String] Available Since 1.9.4

The selected default encryption scheme.

systemConfiguration.passwordEncryptionConfiguration.encryptionSchemeFactor [String] Available Since 1.9.4

The factor used by the password encryption scheme. Generally this will be used as an iteration count to generate the hash. The actual use of this value is up to the PasswordEncryptor implementation.

systemConfiguration.passwordEncryptionConfiguration.modifyEncryptionSchemeOnLogin [Boolean] Available Since 1.9.4

When enabled a user’s hash configuration will be modified to match these configured settings.

systemConfiguration.passwordExpirationDays [Integer] Deprecated

The number of days after which Passport will automatically expire passwords for all users. If this isn’t set, Passport will not expire passwords ever. Prefer the use of systemConfiguration.maximumPasswordAge.days once available.

systemConfiguration.passwordValidationRules.maxLength [Integer]

The maximum number of characters that are allowed for user passwords.

systemConfiguration.passwordValidationRules.minLength [Integer]

The minimum number of characters that are required for user passwords.

systemConfiguration.passwordValidationRules.rememberPreviousPasswords.count [Integer] Available Since 1.10.4

The number of previous passwords that should be remembered so they are not re-used by the User.

systemConfiguration.passwordValidationRules.rememberPreviousPasswords.enabled [Boolean] Available Since 1.10.4

Indicates that the remember previous password validation is enabled and being enforced.

systemConfiguration.passwordValidationRules.requireMixedCase [Boolean]

Indicates that passwords require an uppercase and lowercase character to be valid.

systemConfiguration.passwordValidationRules.requireNonAlpha [Boolean]

Indicates that passwords require a non-alphanumeric character to be valid.

systemConfiguration.passwordValidationRules.requireNumber [Boolean] Available Since 1.19.0

Indicates that passwords require at least one number to be valid.

systemConfiguration.reportTimezone [String]

The timezone that all reports will be generated in. Since reports are usually rolled up hourly, this timezone will be used for demarcating the hours. This must be a valid java.util.time.ZoneId String. (see https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html)

systemConfiguration.setPasswordEmailTemplateId [UUID]

The Id of the Email Template that is used when a user had their account created for them and they must set their password manually and they are sent an email to set their password.

systemConfiguration.uiConfiguration.headerColor [String] Available Since 1.10.4

A hexadecimal color to override the default menu color in the user interface.

systemConfiguration.uiConfiguration.loginTheme.enabled [Boolean] Available Since 1.19.0

Indicates that the login theme is enabled and will be used to style the login pages.

systemConfiguration.uiConfiguration.loginTheme.stylesheet [String] Available Since 1.19.0

A stylesheet used to style the login page and other templates such as forgot password, and verify email.

systemConfiguration.uiConfiguration.logoURL [String] Available Since 1.10.4

A URL of a logo to override the default Passport logo in the user interface.

systemConfiguration.uiConfiguration.menuFontColor [String] Available Since 1.10.4

A hexadecimal color to override the default menu font color in the user interface.

systemConfiguration.verificationEmailTemplateId [UUID]

The Id of the Email Template that is used to send the verification emails to users. These emails are used to verify that a user’s email address is valid. If the verifyEmail field is true this field is required.

systemConfiguration.verifyEmail [Boolean]

Whether or not user’s email addresses are verified when the register with your application.

systemConfiguration.verifyEmailWhenChanged [Boolean]

Whether or not user’s email addresses are verified when the user changes them.

Example Response JSON
{
  "systemConfiguration": {
    "backendServers": [
      "http://localhost:9011"
    ],
    "emailConfiguration": {
      "enabled": true,
      "host": "smtp.sendgrid.net",
      "password": "password",
      "port": 587,
      "security": "TLS",
      "username": "username"
    },
    "eventConfiguration": {
      "user.create": {
        "enabled": true,
        "transactionType": "AbsoluteMajority"
      }
    },
    "externalIdentifierConfiguration" : {
      "authorizationGrantIdTimeToLiveInSeconds" : 30,
      "changePasswordIdTimeToLiveInSeconds" : 300,
      "emailVerificationIdTimeToLiveInSeconds" : 86400,
      "setupPasswordIdTimeToLiveInSeconds" : 86400,
      "twoFactorIdTimeToLiveInSeconds" : 300,
      "twoFactorTrustIdTimeToLiveInSeconds" : 2592000
    },
    "failedAuthenticationUserActionId": "16cfc707-268c-4c5b-8989-f71f3ee156d4",
    "failedAuthenticationConfiguration" : {
      "actionDuration" : 3,
      "actionDurationUnit" : "MINUTES",
      "resetCountInSeconds" : 60,
      "tooManyAttempts" : 5
    },
    "forgotEmailTemplateId": "49aba1de-0225-45d7-a2b1-f9fe46b0242c",
    "httpSessionMaxInactiveInterval": 3600,
    "logoutURL": "http://example.com/logout",
    "maximumPasswordAge": {
      "days": 180,
      "enabled": true
    },
    "minimumPasswordAge": {
      "enabled": true,
      "seconds": 60
    },
    "passwordEncryptionConfiguration": {
      "encryptionScheme": "salted-pbkdf2-hmac-sha256",
      "encryptionSchemeFactor": 24000,
      "modifyEncryptionSchemeOnLogin": false
    },
    "passwordExpirationDays": 30,
    "passwordValidationRules": {
      "maxLength": 256,
      "minLength": 8,
      "rememberPreviousPasswords": {
        "count": 2,
        "enabled": true
      },
      "requireMixedCase": true,
      "requireNonAlpha": true,
      "requireNumber": true
    },
    "reportTimezone": "America/Denver",
    "setPasswordEmailTemplateId": "a9aba13e-0125-4fd7-a2b1-aaa146b02423",
    "uiConfiguration": {
      "loginTheme": {
        "enabled": false
      }
    },
    "verificationEmailTemplateId": "8da42c09-461c-45f3-b931-6e9f63b87a00",
    "verifyEmail": true,
    "verifyEmailWhenChanged": true
  }
}

4. Retrieve the Password Validation Rules

Available Since Version 1.16.0

This API is used to retrieve the Password Validation Rules. This configuration is a subset of the System Configuration.

4.1. Request

Retrieve the Password Validation Rules

URI

GET /api/system-configuration/password-validation-rules

4.2. Response

The response for this API contains the Password Validation Rules.

Table 6. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

402

Your license has expired. The response will be empty. Contact sales@inversoft.com for assistance.

500

There was an internal error. A stack trace is provided and logged in the Passport log files. The response will be empty.

Table 7. Response Body

systemConfiguration.passwordValidationRules.maxLength [Integer]

The maximum number of characters that are allowed for user passwords.

systemConfiguration.passwordValidationRules.minLength [Integer]

The minimum number of characters that are required for user passwords.

systemConfiguration.passwordValidationRules.rememberPreviousPasswords.count [Integer]

The number of previous passwords that should be remembered so they are not re-used by the User.

systemConfiguration.passwordValidationRules.rememberPreviousPasswords.enabled [Boolean]

Indicates that the remember previous password validation is enabled and being enforced.

systemConfiguration.passwordValidationRules.requireMixedCase [Boolean]

Indicates that passwords require an uppercase and lowercase character to be valid.

systemConfiguration.passwordValidationRules.requireNonAlpha [Boolean]

Indicates that passwords require a non-alphanumeric character to be valid.

systemConfiguration.passwordValidationRules.requireNumber [Boolean] Available Since 1.19.0

Indicates that passwords require at least one number to be valid.

Example Response JSON
{
  "passwordValidationRules": {
    "maxLength": 256,
    "minLength": 8,
    "rememberPreviousPasswords": {
      "count": 2,
      "enabled": true
    },
    "requireMixedCase": true,
    "requireNonAlpha": true,
    "requireNumber": true
  }
}