Site Resource Settings

Configure settings for resources on the platform such as alerts, apps, APIs, connections, comments, discussions, groups, tickets, users, reviews, and business security.

This section contains information about the configuration settings defined within the Akana API Platform, which apply to the entire Community Manager developer portal.

For information about the configuration settings defined in the Akana Administration Console, which apply only to the specific container, refer to Admin Console Settings.

Table of Contents

Where do I configure settings for the platform?

You can configure many basic settings that control various aspects of the platform and how it operates.

Note: When you change a setting, it might take up to five minutes for the change to take effect.

You can control settings for the following resources:

The following additional site configuration settings are available:

How do I configure settings for alerts?

You can configure alert settings to determine which features will be available for alerts on the platform.

Note: When you change a setting, it might take up to five minutes for the change to take effect.

This setting... Controls this feature...
Alert Comment Workflow Definition The workflow definition that will apply to new comments on alerts on the platform (existing comments are not affected).
Markdown Support

Indicates whether Markdown is supported for alerts. Markdown support includes linking and file upload. If disabled, alerts are plain text.

For more information about Markdown support, see How do I enable Markdown for Forum items?

External Link Support Indicates whether external links are supported in Markdown for alerts. Applicable only if Markdown Support is enabled.

To configure alert settings

  1. Log in as a Site Admin and go to the Admin section.
  2. Go to More > Admin >Settings > Alerts.
  3. Change the settings as needed. For explanations of your choices, refer to the table above.
  4. Click Save.

    If needed, you can use the Reset button at any point before saving to remove changes you just made.

How do I configure settings for APIs?

You can configure API settings to determine which features will be available for all APIs on the platform. If a feature is disabled in the API settings page, it will not be present in the user interface.

Unless otherwise noted, settings are either enabled or disabled.

You can configure the API settings shown in the tables below:

Note: When you change a setting, it might take up to five minutes for the change to take effect.

General API Settings

This setting... Controls this feature...
Add a new API Determines whether users can create an API that isn't already set up as a service in the API Gateway. Choose this option if users won't need to take advantage of the advanced capabilities offered by the API Gateway. (Default: enabled)
Publish an existing service as an API Determines whether users can create an API by referencing a service already defined in the API Gateway. Choose this option if users might want to use the flexible service definition model offered by the API Gateway. (Default: disabled)
API Scope Groups Determines whether scope groups (API Scope Groups) can be created (groups created in the context of a specific API, that are related only to that API). If this option is enabled, the API Admin can create groups via the API > Visibility > Groups page.
API Promotion Applicable only if the promotion feature is enabled: Determines whether API Admins can promote APIs between environments. If the API Promotion setting is disabled, the API Admin sees the API's topology chain, but there is no Promote button to promote the API to the next environment in the chain. For more information on API promotion, see Using Custom Metadata in the Community Manager developer portal (for Site Admins) and Promoting an API to the Next Environment (for information on how the feature works for API Admins).
Validate Unique Hostname/Context Path

Determines whether the Community Manager developer portal validates that the hostname/context path is unique for each API (for example, http://www.acmepaymentscorp.com/api/payments). If disabled, the same combination of URL and context path is allowed for multiple APIs.

Note: Unless APIs have their own vanity URLs, APIs on the platform will have the same hostname. Each API must have a unique endpoint, and the platform's validation that the context path is unique ensures that the API endpoint will be unique. If you are sure that each API that is/will be hosted on your Community Manager developer portal will have a unique context path, you can disable this setting. Otherwise, leave it enabled (the default). If your Community Manager developer portal includes more than one API with the same endpoint, results will not be as expected.

API Workflow Definition The workflow definition that will apply to all new APIs on the platform (existing APIs are not affected).

Public API Settings

This setting... Controls this feature...
Supported Determines whether public APIs are supported on the platform. Public APIs are visible to all users, including anonymous users. If this setting is disabled, only private APIs are allowed.
Ratings Determines whether users can rate public APIs. If disabled, the ratings feature does not appear in the user interface for public APIs.
Sandbox Endpoint Determines whether public APIs will have the option of having a Sandbox endpoint.
Reviews Determines whether users can write and share reviews of public APIs. If disabled, the reviews feature does not appear in the user interface for public APIs.
Sandbox Auto Approval Determines whether public APIs with a Sandbox endpoint will allow access to it automatically upon request, or will explicitly approve or deny each request.
Scopes Determines whether the Admin will have the option to define scopes (part of the Licenses feature). If implemented, individual API operations can be assigned to different scopes for packaging into different licenses.
Live Endpoint Determines whether public APIs will have the option of having a Live endpoint.
Live Auto Approval Determines whether public APIs with a Live endpoint will allow access to it automatically upon request, or will explicitly approve or deny each request.

Private API Settings

This setting... Controls this feature...
Supported Determines whether private APIs are supported on the platform. Private APIs are visible only to invited users. If this setting is disabled, only public APIs are allowed.
Sandbox Endpoint Determines whether private APIs will have the option of having a sandbox endpoint.
Sandbox Auto Approval Determines whether private APIs with a sandbox endpoint will allow sandbox access automatically upon request, or will explicitly approve or deny each request.
Live Endpoint Determines whether private APIs will have the option of having a Live endpoint.
Live Auto Approval Determines whether private APIs with a Live endpoint will allow access to it automatically upon request, or will explicitly approve or deny each request.
Independent Group Determines whether private APIs will have the option of having API Scope Groups associated with them.
Ratings Determines whether users can rate private APIs. If disabled, the ratings feature does not appear in the user interface for private APIs.
Reviews Determines whether users can write and share reviews of private APIs. If disabled, the reviews feature does not appear in the user interface for private APIs.
Scopes Determines whether the Admin will have the option to define scopes (part of the Licenses feature). If implemented, API operations can be assigned to different scopes for packaging into different licenses.

To configure API settings

  1. Log in as a Site Admin and go to the Admin section.
  2. Go to More > Admin >Settings > APIs.
  3. Change the settings as needed. For explanations of your choices, refer to the tables above.
  4. Click Save.

    If needed, you can use the Reset button at any point before saving to remove changes you just made.

How do I configure settings for apps?

You can configure app settings to determine which features will be available for all apps on the platform. If a feature is disabled in the app settings page it will not be present in the user interface.

Unless otherwise noted, settings are either enabled or disabled.

Available app configuration settings are shows in the tables below:

Note: When you change a setting, it might take up to five minutes for the change to take effect.

General App Settings

This setting... Controls this feature...
User-Defined Identity

Determines whether users can define their own unique App ID for the app. If this field is enabled, two additional fields appear on the Add/Edit App Info page, so users can define their own values for the following:

  • App ID
  • Shared Secret

Valid values: Enabled for Site Admins Only / Enabled / Disabled

Simultaneous Access to Sandbox and Live If enabled, grants access to both environments in one request.
Shared Secret Display

Determines how an app’s Shared Secret is displayed when viewed on the App Details page; either in plain text or encrypted.

Note: If you change this setting when there are existing apps on the platform, it is effective immediately for all apps. If you make a change, make sure app developers are notified.

App Workflow Definition

The workflow definition that will apply to all new apps on the platform (existing apps are not affected).

There is no default app workflow. One out-of-the-box workflow is available:

  • appversion-workflow-template1
App Team Membership Workflow Definition

The workflow definition that will apply to all new app team members on the platform (existing app team members are not affected).

App Promotion

Applicable only if the promotion feature is enabled: Determines whether app developers can promote apps between environments. If the App Promotion setting is disabled, the app developer sees the app's topology chain, but there is no Promote button to promote the app to the next environment in the chain (taxonomy).

Note: For app promotion to work, the User-Defined Identity setting must also be enabled (either of the two Enabled settings is fine).

Show policies on API Access wizard (API Platform Version: 2020.1.0 and later)

By default, all the QoS (Quality of Service) policies that are defined on the Community Manager developer portal are shown as part of the API Access wizard when an app requests a contract with an API (see, How do I get API access for my app?). Disable this setting if you do not want the app developer to see the available QoS policies when requesting API access.

Public App Settings

This setting... Controls this feature...
Supported Determines whether apps with a visibility setting of Public will be supported on the platform. Public apps are visible to all users; login is not required.
Reviews Determines whether users will be able to write and share reviews of apps with a visibility setting of Public. If this setting is disabled, the reviews feature does not appear in the user interface for public apps.
Ratings Determines whether users will be able to rate apps with a visibility setting of Public. If this setting is disabled, the ratings feature does not appear in the user interface for public apps.

Private App Settings

This setting... Controls this feature...
Supported Determines whether apps with a visibility setting of Private will be supported on the platform. Private apps are visible only to invited users.
Reviews Determines whether users will be able to write and share reviews of apps with a visibility setting of Private. If this setting is disabled, the reviews feature does not appear in the user interface for private apps.
Ratings Determines whether users will be able to rate apps with a visibility setting of Private. If this setting is disabled, the ratings feature does not appear in the user interface for private apps.

Registered User Settings

This setting... Controls this feature...
Supported Determines whether apps with a visibility setting of Registered Users will be supported on the platform. Apps with this setting are visible only to users who are logged in.
Reviews Determines whether users will be able to write and share reviews of apps with a visibility setting of Registered Users. If this setting is disabled, the reviews feature does not appear in the user interface for apps with this visibility setting.
Ratings Determines whether users will be able to rate apps with a visibility setting of Registered Users. If this setting is disabled, the ratings feature does not appear in the user interface for apps with this visibility setting.

To configure app settings

  1. Log in as a Site Admin and go to the Admin section.
  2. Go to More > Admin >Settings > Apps.
  3. Change the settings as needed. For explanations of your choices, refer to the tables above.
  4. Click Save.

    If needed, you can use the Reset button at any point before saving to remove changes you just made.

How do I configure App OAuth Profile Authorization settings?

As part of app setup, app developers can specify which settings they want to use when connecting to an API using OAuth. These settings are configured from the App Details page: App Details > OAuth Profile.

There are five groups of settings on this page. The first four are controlled by the app developer and are detailed in What are the settings available on the App OAuth Profile page? (app developer help):

  • Branding Settings
  • Access Token Settings
  • Authentication Settings
  • ID Token Settings

Settings in the last group are controlled by the Site Admin or specially authorized app developers only:

  • Authorization Settings

The last set, Authorization Settings are normally not visible to the app developer. In most cases, these settings can only be configured by the Site Admin. However, the Site Admin can implement a custom workflow that allows app developers to modify these settings. If the custom workflow is in place, app developers will see the settings.

Note: These settings give the app developer significant responsibility. In most cases, app developers should not be able to configure these settings for their apps. Only implement the custom workflow that allows app developers to modify these settings if you are absolutely sure they fully understand the meaning of the various settings and will use them appropriately.

Information about the additional Authorization settings normally available only to a Site Admin is given in the following table.

Authorization Settings

Setting Explanation / possible values
Allowed Grant Types

By default, all grant types supported by the OAuth Provider are allowed (Global Setting). To restrict the OAuth grant types allowed, click and then specify which grant types are allowed for this app. Possible values for selection based on the OAuth Provider configuration are:

  • Global Setting
  • HTTP Form-Based Authentication
  • Private Key JWT
  • Client Secret JWT
  • HTTP Basic Authentication

If you choose Global Setting, all authentication methods supported by the OAuth Provider are valid for the app, including Secret and PKI. If you choose one of the other settings, Secret and PKI are supported also.

OpenID Connect Supported If the application supports OpenID Connect for OAuth, check this box.
PKCE Required

If the application requires PKCE support, check this box.

If you choose PKCE Required checkbox, the app performs authorization and requests an access token to access the API using PingFederate as an external OAuth provider. It syncs the app details with PingFederate.

By default, the value is false.

Note: Applicable for PingFederate version 9.x and above.

Grant Expiration By default, the grant expiration time is derived based on the OAuth Provider configuration (Global Setting). To specify a longer or shorter grant expiration time for the app, click the Enter number of hours button and specify the number of hours until the grant expires.
Access Token Expiration By default, the access token expiration time is derived based on the OAuth Provider configuration (Global Setting). To specify a longer or shorter access token expiration time for the app, click the Enter number of hours button and specify the number of seconds until the grant expires.
Bypass Authorization If OAuth authentication for this application should bypass the authorization page, check this box. For example, this might be appropriate for an internal application.

To configure app OAuth profile settings

  1. Log in to the Community Manager developer portal.
  2. Go to the App Details page for the app, and click OAuth Profile.
  3. Change the settings as needed. For explanations of your choices, refer to the table above.
  4. Click Save.

For information about how to implement custom workflow to enable these settings for app developers on the OAuth Profile page, refer to Custom Workflows in the Community Manager developer portal.

How do I configure settings for comments?

You can configure settings to determine which features will be available for all comments on the platform.

When you change a setting, it might take up to five minutes for the change to take effect.

Note: There is an additional setting relating to comments, that limits the types of files users can upload to comments on discussions, tickets, alerts, or reviews. It's in the security settings since it relates to platform security; see, How do I configure settings for business security?

This setting... Controls this feature...
Publishing of Comments Indicates whether comments are published automatically or must be approved by a moderator (Admin).
Markdown Support

Indicates whether Markdown is supported for comments. Markdown support includes linking and file upload. If disabled, comments are plain text.

For more information about Markdown support, see How do I enable Markdown for Forum items?

External Link Support Indicates whether external links are supported in Markdown for comments. Applicable only if Markdown Support is enabled.

To configure comment settings

  1. Log in as a Site Admin and go to the Admin section.
  2. Go to More > Admin >Settings > Comments.
  3. Change the setting as needed. For explanations of your choices, refer to the table above.
  4. Click Save.

    If needed, you can use the Reset button at any point before saving to remove changes you just made.

How do I configure settings for app/API connections?

You can configure connection settings to determine which features will be available for app/API connections on the platform. If a feature is disabled in the connection settings page it will not be present in the user interface.

Unless otherwise noted, settings are either enabled or disabled.

Note: When you change a setting, it might take up to five minutes for the change to take effect.

General App/API Connection Settings

This setting... Controls this feature...
Sandbox Contract Workflow Definition The workflow definition that will apply to all new sandbox contracts on the platform (existing contracts are not affected).
Live Contract Workflow Definition The workflow definition that will apply to all new Live contracts on the platform (existing contracts are not affected).
Sandbox Contract Comment Workflow Definition The workflow definition that will apply to new comments on sandbox contracts on the platform (existing comments are not affected).
Live Contract Comment Workflow Definition The workflow definition that will apply to new comments on Live contracts on the platform (existing comments are not affected).

To configure app/API connection settings

  1. Log in as a Site Admin and go to the Admin section.
  2. Go to More > Admin >Settings > Connections.
  3. Change the settings as needed. For explanations of your choices, refer to the table above.
  4. Click Save.

    If needed, you can use the Reset button at any point before saving to remove changes you just made.

How do I configure settings for discussions?

You can configure settings to determine which features will be available for discussions on the platform.

Note: When you change a setting, it might take up to five minutes for the change to take effect.

Discussion Settings

This setting... Controls this feature...
Discussion Workflow Definition The workflow definition that will apply to all new discussions on the platform. Existing discussions are not affected.
Discussion Comment Workflow Definition The workflow definition that will apply to all new discussion comments on the platform. Existing discussion comments are not affected.
Publishing of Discussions Indicates whether discussions are published automatically or must be approved by a moderator (Admin).
Markdown Support

Indicates whether Markdown is supported for discussions. Markdown support includes linking and file upload. If disabled, discussions are plain text.

For more information about Markdown support, see How do I enable Markdown for Forum items?

External Link Support Indicates whether external links are supported in Markdown for discussions. Applicable only if Markdown Support is enabled.

To configure discussion settings

  1. Log in as a Site Admin and go to the Admin section.
  2. Go to More > Admin >Settings > Discussions.
  3. Change the settings as needed. For the workflow definition, you can:
    • Choose the out-of-the box workflow, workflow:definition:discussion.
    • Choose a custom workflow, if a Site Admin or Business Admin uploaded a custom workflow for discussions.
    • Revert to the default, no workflow for discussions, if a workflow was previously assigned.
  4. Click Save.

    If needed, you can use the Reset button at any point before saving to remove changes you just made.

How do I configure settings for groups?

You can configure group settings to determine which features will be available for all groups on the platform. If a feature is disabled in the group settings page it will not be present in the user interface.

Unless otherwise noted, settings are either enabled or disabled.

Available group configuration settings are shows in the tables below:

Note: When you change a setting, it might take up to five minutes for the change to take effect.

General Group Settings

This setting... Controls this feature...
Group Support Determines whether groups are supported on the platform. If this setting is disabled, nothing about groups appears in the platform and no other options relating to groups are available.
Group Membership Workflow Definition The workflow definition that will apply to all new groups on the platform (existing groups are not affected).
Group Membership Comment Workflow Definition The workflow definition that will apply to all new comments on groups on the platform (existing comments are not affected).

Public Group Settings

This setting... Controls this feature...
Supported

Determines whether public groups are supported on the platform. Public groups are visible to all users, including anonymous users. If this setting is disabled, only private groups are allowed. Valid values:

  • Enabled for Admins
  • Enabled
  • Disabled
Ratings Determines whether users can rate public groups. If disabled, the ratings feature does not appear in the user interface for public groups.
Reviews Determines whether users can write and share reviews of public groups. If disabled, the reviews feature does not appear in the user interface for public groups.

Private Group Settings

This setting... Controls this feature...
Supported Determines whether private groups will be supported on the platform. Private groups are visible only to invited users. If this setting is disabled, only public groups are allowed. Valid values:
  • Enabled for Admins
  • Enabled
  • Disabled
Ratings Determines whether users can rate private groups. If disabled, the ratings feature does not appear in the user interface for private groups.
Reviews Determines whether users can write and share reviews of private groups. If disabled, the reviews feature does not appear in the user interface for private groups.

To configure group settings

  1. Log in as a Site Admin and go to the Admin section.
  2. Go to More > Admin >Settings > Groups.
  3. Change the settings as needed. For explanations of your choices, refer to the tables above.
  4. Click Save.

    If needed, you can use the Reset button at any point before saving to remove changes you just made.

How do I configure settings for login policy?

You can configure login policy settings to control the login rules for local users logging in to the platform and for the Community Manager developer portal session configuration.

A value of 0 (zero) in one of these fields indicates that there is no value specified, with the exception of Active Login Session Timeout (see below).

Note: When you change a setting, it might take up to five minutes for the change to take effect.

Login Policy Settings

This setting... Controls this feature...
Maximum Number of Consecutive Failed Attempts

The maximum number of consecutive failed login attempts before the user's account is disabled.

Default: 6

Time Period for Max Failed Attempts

The period of time, in minutes, over which the number of failed login attempts is calculated.

Default: 8

Suspension Time (Minutes)

The period of time, in minutes, for which the user's account is locked after failed login attempts.

Default: 30

Inactive Login Session Timeout (Minutes)

The period of time, in minutes, after which the user is automatically logged out of the Community Manager developer portal user interface (any theme) if the session is inactive.

Default: 30

Active Login Session Timeout (Minutes)

The period of time, in minutes, after which the user is automatically logged out of the Community Manager developer portal user interface (any theme) even if the session is active. Users are prompted shortly before the timeout, so that they can save their work before the forced timeout.

Note: In versions prior to 2019.1.34, the user's login cookie (authorization token) was always 30 minutes. If Active Login Session Timeout was specified, the user interface managed the timeout, and if the value was greater than 30, it renewed the cookie in the background. API users had to renew the token manually. In version 2019.1.34 and later, If Active Login Session Timeout is specified, the session cookie is set to match the Active Login Session Timeout value.

Support Persistent Sessions

Determines whether the session cookie persists when the browser is closed. A security setting.

Default: enabled, which means that the session cookie persists if the browser is closed, until it expires. If this setting is disabled, for added security, the cookie expires if the browser is closed. Exact behavior might vary according to the user's browser version and preferences. For more information, see How can I set up the Community Manager developer portal so that the cookies are not persistent?

Allow Concurrent Sessions

Determines whether a user can have more than one session running concurrently in multiple browsers or on multiple devices. If this setting is disabled, only one session is allowed. A security setting.

Default: enabled, which means that the user can have more than one session running concurrently in different browsers or on different devices.

Note: The user can run a session in multiple tabs in the same browser. This is the same session.

To configure login policy settings

  1. Log in as a Site Admin and go to the Admin section.
  2. Go to More > Admin >Settings > Login Policy.
  3. Change the settings as needed. For explanations of your choices, refer to the table above.
  4. Click Save.

    If needed, you can use the Reset button at any point before saving to remove changes you just made.

How do I configure settings for model objects?

For model objects, you can upload a custom workflow document in More > Admin > Workflows (see, How do I set up and manage custom workflows?) and then assign it in More > Admin > Settings > Models.

This setting... Controls this feature...
Model Workflow Definition

The workflow definition that will apply to new model objects on the platform (existing model objects are not affected).

Note: This workflow applies to model objects defined across all organizations in the Community Manager developer portal. Model objects defined in the context of a specific API are not controlled by the model object workflow.

To configure model object settings

  1. Log in as a Site Admin and go to the Admin section.
  2. Go to More > Admin >Settings > Models.
  3. Change the workflow definition. If your custom workflow does not appear on the drop-down list, it was not yet uploaded or an incorrect resource type was assigned to it. See, I uploaded a custom workflow, but it isn't showing as available. What do I do?
  4. Click Save.

    If needed, you can use the Reset button at any point before saving to remove changes you just made.

How do I configure settings for password policy?

You can configure settings to control password policy for local users logging in to the platform.

Note: When you change a setting, it might take up to five minutes for the change to take effect.

User Settings

This setting... Controls this feature...
Minimum Password Length The minimum number of characters allowed in a password.
Maximum Password Length The maximum number of characters allowed in a password.
Minimum Letter Count The minimum number of letters required in a password.
Minimum Number Count The minimum number of whole numbers required in a password.
Minimum Uppercase Letters The minimum number of uppercase letters required in a password.
Minimum Special Characters The minimum number of special characters required in a password. If no value is specified, all characters are allowed.
Special Characters Allowed The special characters allowed in the password. If a value is provided for MinSpecialCharCount, at least one allowed special character must be defined.
Number of Previous Passwords Checked for Match Indicates the number of previous passwords that the new password is checked against, and rejected if there is a match.
Force Password Change Period (Days) Indicates the time interval, in days, before a user is prompted to change the password. If set to 0 (zero), password changing is not enforced.
Can Password Contain Spaces? Indicates whether a password can include spaces.
Is Password Case-Sensitive? Indicates whether a password is case sensitive.
Can Password Match Username? Indicates whether the password and the username can be the same.
Can Password Match Email? Indicates whether the password and the email address can be the same.

To configure password policy settings

  1. Log in as a Site Admin and go to the Admin section.
  2. Go to More > Admin >Settings > Password Policy.
  3. Change the settings as needed. For explanations of your choices, refer to the table above.
  4. Click Save.

    If needed, you can use the Reset button at any point before saving to remove changes you just made.

How do I configure settings for reviews?

You can configure settings to determine which features will be available for reviews on the platform.

Note: When you change a setting, it might take up to five minutes for the change to take effect.

Review Settings

This setting... Controls this feature...
Review Workflow Definition The workflow definition that will apply to all new reviews on the platform. Existing reviews are not affected.
Publishing of Reviews Indicates whether reviews are published automatically or must be approved by a moderator (Admin).
Markdown Support

Indicates whether Markdown is supported for reviews. Markdown support includes linking and file upload. If disabled, reviews are plain text.

For more information about Markdown support, see How do I enable Markdown for Forum items?

External Link Support Indicates whether external links are supported in Markdown for reviews. Applicable only if Markdown Support is enabled.

To configure review settings

  1. Log in as a Site Admin and go to the Admin section.
  2. Go to More > Admin >Settings > Reviews.
  3. Change the settings as needed. For the workflow definition, you can:
    • Choose the out-of-the box workflow, workflow:definition:review.
    • Choose a custom workflow, if a Site Admin or Business Admin uploaded a custom workflow for reviews.
    • Revert to the default, no workflow for reviews, if a workflow was previously assigned.
  4. Click Save.

    If needed, you can use the Reset button at any point before saving to remove changes you just made.

How do I configure settings for business security?

You can configure settings to control the level of security associated with platform elements, and to control certain elements relating to security that affect platform users.

You can use the default out-of-the-box user workflow in combination with user settings and business security settings relating to users, to control user experience on the platform and if needed to restrict what users can do. If you need more flexibility, you can design your own custom workflow.

Note: When you change a setting, it might take up to five minutes for the change to take effect.

Business Security Settings

This setting... Controls this feature...
CSRF Support for Read Requests

If enabled, a CSRF token must be sent with the request for all Read requests that require login. The CSRF token is sent on login; including it in requests helps prevent malicious CSRF attacks.

Default: Disabled.

Note: If this setting is disabled, and you enable it, you and any other users already logged in when the setting change takes effect (up to five minutes) will need to refresh, or log out and log back in again.

CSRF Support for Write Requests

If enabled, a CSRF token must be sent with all Write requests. The CSRF token is sent on login; including it in requests helps prevent malicious CSRF attacks.

Note: If this setting is disabled, and you enable it, you and any other users already logged in when the setting change takes effect (up to five minutes) will need to refresh, or log out and log back in again.

Authentication and CSRF Token Cookie Attribute - Domain

(Valid in Version: 2019.1.35 and later)

Allows you to specify a value to be set for the Community Manager developer portal cookies, for the Domain attribute, which can limit the domains for which the cookie can be valid. Applies to both the login cookie (authentication cookie) and the CSRF cookie.

Options:

  • No explicit setting: The Domain attribute is not set in the cookie. With this option, the value defaults to the hostname of the originating server. This is the default behavior, and is the behavior for earlier versions of the Akana product.
  • Complete Hostname of Tenant: The Domain attribute is set to the complete hostname of the tenant URL that the user is accessing. Example: if the developer portal URL is https://apiportal.example.com, the Domain attribute of the cookie is set to apiportal.example.com. This is the most secure option.
  • Only Domain of Tenant: The Domain attribute is set to the domain of the tenant URL that the user is accessing. Example: If the developer portal URL is https://apiportal.example.com, the Domain attribute of the cookie is set to example.com. In most cases, this allows access for all subdomains within the specified domain, though different browsers might have different behavior. This option is less restrictive than specifying the complete hostname, but more secure than having no Domain setting.

Authentication and CSRF Token Cookie Attribute - SameSite

(Valid in Version: 2019.1.35 and later)

Allows you to specify a value to be set for the Community Manager developer portal cookies, for the SameSite attribute, which can limit the scope of the cookie so that it will only be valid for same-site requests. Applies to both the login cookie (authentication cookie) and the CSRF cookie.

One example of how this setting applies is if API documentation is being displayed in an iframe on a third-party portal, where the third-party portal domain is different from the developer portal domain (see, Can my API documentation be rendered on a third-party portal?). In this scenario, if a user is on a newer browser that defaults to a SameSite attribute of Lax, the API documentation will not display correctly unless the SameSite field is set to None.

Options:

  • No explicit setting: The SameSite attribute is not set in the cookie (default behavior for backward compatibility). With this setting, the behavior depends on the browser default. In older browser versions, the default value is None; in newer browser versions the default value is Lax.
  • Lax: The cookie is not sent for a normal cross-site request (for example, to load images or frames into a third-party site), but is sent when a user is navigating to the origin site, such as when following a link.

    For more information, see "Strict" and "Lax" enforcement (Section 5.3.7.1 of RFC6265). Lax enforcement is more secure than having no setting, but not as secure as strict enforcement.

  • Strict: The cookie is only sent with "same-site" requests: that is, requests from the same domain. Cookies are not sent with requests initiated by third-party websites.

    For more information, see "Strict" and "Lax" enforcement (Section 5.3.7.1 of RFC6265).

  • None: The cookie is sent in all contexts, with same-site requests and with cross-site requests.

    Note: If SameSite=None is set, the Secure attribute must also be set for the cookie, or the cookie will be blocked. The Secure attribute is set automatically if the tenant runs on HTTPS and the console address for the tenant theme is set to https://.

Allow User Enum If disabled, additional security is in effect for new account setup and password reset scenarios, to help prevent user enumeration. For more information, refer to How can I protect from vulnerability in Signup and Forgot Password scenarios?
CAPTCHA Supported If enabled, CAPTCHA challenges are used in the Community Manager developer portal; for example, on the Forgot Password page. See, How do I configure CAPTCHA on the platform? below.
Keywords for cross-site scripting prevention

A comma-delimited list of keywords that are disallowed in certain input fields, such as app, API, and group Name, Summary, and Description fields and forum discussions and tickets, to help prevent cross-site scripting (XSS) attacks.

The following defaults are displayed:

onload,onerror,onmouseout,onmouseover,eval

You can add additional keywords, or you can remove one or more of the existing defaults.

Enforce allowlist for cross-site scripting prevention

/

Additional allowlisted characters allowed

(Valid in Version: 2019.1.11 and later)

If the Enforce Allowlist field is enabled, only characters on the allowlist are accepted in certain input fields, such as app and API Name, Summary, and Description, for cross-site scripting prevention.

The Additional Characters field allows you to define a list of additional characters that are allowed, in addition to platform defaults, when the allowlist is enforced. Default characters allowed (not displayed in the list) are:

  • alphanumeric characters (a–z, A–Z, 0–9)
  • comma (,)
  • period (.)
  • hyphen (-)
  • space ( )

Specify additional characters, without spaces. Example: ()/ allows these three characters in addition to the defaults.

Default value:

  • Version 2019.1.11 to 2019.1.18: Enforce Allowlist (previously called Enforce Whitelisting) is disabled by default, and all characters are allowed.
  • Version 2019.1.19 and later: Enforce Allowlist is enabled by default, with the following list of additional characters allowed:
    /#[]()'";?!_<=>@'~&
Encrypt Challenge Answers If enabled, the user's answers to security challenge questions are encrypted in the database.
Challenge Count

Determines how many security challenge questions a single user must answer. Cannot exceed the total number of questions defined.

Note: If you want to require security challenge questions but no challenge count is available, you must first set up the questions. See, How do I configure security challenge questions?

Allow users to modify their own profiles If enabled, a user can modify the profile information, including the email address if it is associated with a local account.
Allow Site Admin to initiate user email address update

If this setting is disabled, only the individual user can update his/her email address. Enabling this setting allows the Site Admin to help a user who loses access to an email account, but authenticating the validity of the request is the Site Admin's responsibility. The behavior is a little different for platform accounts/third-party accounts:

  • Platform accounts: The Site Admin can initiate an email address change on behalf of a platform account. Email notifications are sent to the old and new accounts. To complete the change initiated by the Site Admin, the user must change the password on the account. For more information, see How do I change the email address for a user?
  • Third-party accounts (Valid in version: 2020.1.0 and later): The Site Admin can change the email address for a third-party account. Email notifications are sent to the old and new accounts. The change is immediate.
Allow display of external content in developer portal content pages If enabled, users can view external webpages if they are referenced in platform content pages. For more information, see How do I prevent referencing external sites in Community Manager developer portal content pages? below.

Limit file types allowed for upload

(Valid in Version: 2019.1.0 and later)

Optional security feature allows limiting of file types that users can upload. Default (*) allows any valid media type. To limit upload, specify a delimited list of media types. Delimiter can be comma, space, or both. Examples:

  • application/json, text/plain, image/jpg
  • image/gif,image/jpg,image/png
  • application/json image/jpg application/pdf

Default value:

  • Version 2019.1.0 to 2019.1.18: All values allowed by default.
  • Version 2019.1.19 and later: The following file types are allowed by default:
    text/plain,image/png,image/jpeg,application/pdf,application/zip
  • Version 2020.1.2 and later, 2019.1.23 and later: The following file types are allowed by default:
    text/plain,text/x-yaml,application/json,application/xml,application/wsdl+xml,image/png,image/jpeg,application/pdf,application/zip,image/bmp,image/gif
    

Apply strict policy to upload file types

(Valid in Version: 2020.1.2 and later, 2019.1.23 and later)

Only applicable if the Limit file types allowed for upload setting is enabled. Optional security feature to apply stricter rules for limiting file types.

With strict policy enabled, only the exact specified media types are allowed. If this setting is disabled, supertypes of the allowed file types are allowed. For example, if text/plain is allowed, then html, application/json, and other text-based media types are allowed.

To configure business security settings

  1. Log in as a Site Admin and go to the Admin section.
  2. Go to More > Admin >Settings > Security.
  3. Change the settings as needed. For explanations of your choices, refer to the table above.
  4. Click Save.

    If needed, you can use the Reset button at any point before saving to remove changes you just made.

When a user logs in to the Community Manager developer portal, a session cookie is created. The cookie is named: AtmoAuthToken_{fedmemberID}.

The cookie includes information that affects the user's session, such as:

  • Login information
  • Time the session started, and time it is valid for (might be default values or customized in settings)
  • The user's permissions to add, modify, delete, and view resources such as apps, APIs, and groups
  • In some cases, information about the domain. See, How do I configure settings for business security? above. The Domain and SameSite attributes are set for the cookie if these fields are enabled in the security settings.

As an added security step, you can define the domain attribute in the session cookie for the Community Manager developer portal.

There are three possible values for this setting, as shown below.

domain attribute value Meaning
com.soa.auth.token.cookie.domain.hostname

There should not be a Domain attribute on the Set-Cookie header.

This is the default.

com.soa.auth.token.cookie.domain.hostname.mustset

There must be a Domain attribute on the Set-Cookie header with the complete hostname for the tenant being accessed.

The hostname for the Domain attribute is determined either by the Host header or the X-Forwarded-Host header, whichever resolves to a tenant in that order.

com.soa.auth.token.cookie.domain.domainname

The first part of the domain should cut off to use the subdomain.

For example, if the host is open.akana.com, the Domain attribute value in the Set-Cookie header should be akana.com and the same value should appear in the cookie in the browser.

To set this up, you'll need to run the database query shown below. Where placeholder values in square brackets are shown below, specify the appropriate values for your installation:

  • The appropriate value from the three options above
  • Your FedmemberID
SELECT * FROM BUSINESS_SECURITY_SETTINGS;
update BUSINESS_SECURITY_SETTINGS set AUTH_TOKEN_COOKIE_DOMAIN = '[domain_attribute_value]' 
where BUSINESSID = (SELECT BUSINESSID FROM TENANTS WHERE fedmemberid = '[FedmemberID]');

Examples

The example below uses the second attribute value, com.soa.auth.token.cookie.domain.hostname.mustset, and a FedmemberID of acmepaymentscorp.

SELECT * FROM BUSINESS_SECURITY_SETTINGS;
update BUSINESS_SECURITY_SETTINGS set AUTH_TOKEN_COOKIE_DOMAIN = 'com.soa.auth.token.cookie.domain.hostname.mustset' 
where BUSINESSID = (SELECT BUSINESSID FROM TENANTS WHERE fedmemberid = 'acmepaymentscorp');

Sample cookie with the com.soa.auth.token.cookie.domain.hostname.mustset setting enabled. The Domain value is in the last line.

Set-Cookie: AtmoAuthToken_atmosphere=TokenID%3D337b02b3-24de-11e9-975c-e9caa5f7441a%2Cclaimed_id%3Durn%3Aatmosphere%3Auser%3Aatmosphere%3A5f138d5a-cae8-4ab7-ba4a-e87791e669bd%2CissueTime%3D1548887237660%2CexpirationTime%3D1548889097655%2CUserName%3DJaneMead%2CUserFDN%3D5f138d5a-cae8-4ab7-ba4a-e87791e669bd%252Eatmosphere%2CAttributesIncluded%3Dfalse%2Csig%3DFwCSv4diSnn2-HqT46YsyR_l-d73HXDl3zL34cPnjKodxdHNzhmk8LvO5tO6nwKYBZAGDYAHZU0czjLykjPt-gMnFh7hDQ76NT5wIj41_1SkVExO7SnRjgCSw56htRdoVxJIw5uF96JNjzAtmVzPm7G5yWLoOrr4wZAhfVmxPj8_b95BrhLM4oRPCYEIZtNireJ_ljrLwCDnASPkmNZhChn-F1787fVyWigF-0Id-KnWmWEanl-3ONaNWPJDyNkaLw5Kpc7uGPs6Pp1WmO1qgudForBXFakYi8G7Lyf-a7I4FM2L0Z6l7Ra6tsESrZIkAKrt019IU7ReOQqnY4goZQ;path=/;HttpOnly;Domain=portal-4.api.acmepaymentscorp.com;expires=Wed, 30 Jan 2019 22:58:17 GMT

Sample cookie with the com.soa.auth.token.cookie.domain.domainname setting enabled. The Domain value is in the last line.

Set-Cookie: AtmoAuthToken_atmosphere=TokenID%3Dea60ad03-24dc-11e9-975c-e9caa5f7441a%2Cclaimed_id%3Durn%3Aatmosphere%3Auser%3Aatmosphere%3A5f138d5a-cae8-4ab7-ba4a-e87791e669bd%2CissueTime%3D1548886685517%2CexpirationTime%3D1548888545512%2CUserName%3DJaneMead%2CUserFDN%3D5f138d5a-cae8-4ab7-ba4a-e87791e669bd%252Eatmosphere%2CAttributesIncluded%3Dfalse%2Csig%3DJqN9yPJwB4T-BnzexNGZ-kSSR3TqD5rg9TIM3FoJkdAUhSw4-epHGT4aKGgsMrfnCpzoiAkIHHOq9oEO54nCHy2LFc5D7-jZnJIdi2837LshgiSc1m-aCcZj74or1DOS7ZBFyeE8re63-zze3fTyb-igjQ_IT-CNN9qNbMx8fqEl84Qa8Dyq0M6kXQA1YH12ibEHgA-laJr07B4phZP2wo2EmhxfSgk8XwacKd6OeoGZPYhYN6pfcnVAtGrH5aPan7APg_f9BOf9FnSgnbOiz6UAqKpqwr3o3yeDfPbcGSGbKmIO4nUWMHtLfAr2X_f8hpeGFgOaYFBmLjw1CMKmqg;path=/;HttpOnly;Domain=api.acmepaymentscorp.com;expires=Wed, 30 Jan 2019 22:49:05 GMT

How do I configure CAPTCHA on the platform?

The Community Manager developer portal's security features include the capability for the Site Admin to enable CAPTCHA challenge/response tests on certain pages. Using a CAPTCHA helps ensure that the entity performing the action is a human, not a bot.

The feature supports Google reCAPTCHA, reCAPTCHA v2, for validation of users by means of the "I'm not a robot" check box.

Note: This feature does not support invisible reCAPTCHA or reCAPTCHA Android.

If you enable CAPTCHA support in the security settings, users will have to answer CAPTCHA challenges on these pages:

  • Sign Up
  • Forgot Password

Before enabling the feature, you must set up a Google reCAPTCHA account. Set up the correct domain for your Community Manager developer portal in the reCAPTCHA account, without protocol (for example, acmepaymentscorp.com), and get the values for the Site Key and the Secret.

Once the Google reCAPTCHA account is set up with the domain value for the Community Manager developer portal (for example, acmepaymentscorp.com), and the Community Manager developer portal setting is enabled and set up with the CAPTCHA values, users signing up or clicking Forgot Password will be presented with a CAPTCHA challenge which they must pass as part of entering information on those pages.

To enable CAPTCHA support in the Community Manager developer portal

  1. Log in as a Site Admin and go to the Admin section.
  2. Go to More > Admin >Settings > Security.
  3. In the CAPTCHA Support field, click Enabled.
  4. In the CAPTCHA Site Key field, enter the Site Key value for your reCAPTCHA account.
  5. In the CAPTCHA Secret Key field, click Edit, and then enter the secret value for your reCAPTCHA account.

    Note: The CAPTCHA Secret Key is never displayed anywhere in the Community Manager developer portal user interface. In addition, the Community Manager developer portal API doesn't return the secret key. It's encrypted and stored securely in the database.

    Click Save.

    If needed, you can use the Reset button at any point before saving, to remove changes you just made.

How do I configure settings for tickets?

You can configure ticket settings to determine which features will be available for tickets on the platform. If a feature is disabled in the ticket settings page it will not be present in the user interface.

Unless otherwise noted, settings are either enabled or disabled.

Note: When you change a setting, it might take up to five minutes for the change to take effect.

General Ticket Settings

This setting... Controls this feature...
Ticket Support Determines whether tickets are supported on the platform. If this setting is disabled, nothing about tickets appears in the platform and no other options relating to tickets are available.
Ticket Workflow Definition The workflow definition that will apply to all new tickets on the platform (existing tickets are not affected).
Ticket Comment Workflow Definition The workflow definition that will apply to new comments on tickets on the platform (existing comments are not affected).
Visibility

Determines who can see unpublished tickets. Valid choices:

  • Public: Visible to anyone who has visibility of the associated API.
  • Private: Visible only to the submitter, API Admins, and app team members only if the ticket was submitted in the context of a specific API.
Markdown Support

Indicates whether Markdown is supported for tickets. Markdown support includes linking and file upload. If disabled, tickets are plain text.

For more information about Markdown support, see How do I enable Markdown for Forum items?

External Link Support Indicates whether external links are supported in Markdown for tickets. Applicable only if Markdown Support is enabled.

To configure ticket settings

  1. Log in as a Site Admin and go to the Admin section.
  2. Go to More > Admin >Settings > Tickets.
  3. Change the settings as needed. For explanations of your choices, refer to the table above.
  4. Click Save.

    If needed, you can use the Reset button at any point before saving to remove changes you just made.

How do I configure settings for users?

You can configure user settings to determine which features will be available for users on the platform. If a feature is disabled in the user settings page it will not be present in the user interface.

Unless otherwise noted, settings are either enabled or disabled.

Note: When you change a setting, it might take up to five minutes for the change to take effect.

User Settings

This setting... Controls this feature...
User Workflow Definition The workflow definition that will apply to all new users on the platform. Existing users are also added to the workflow when they log in if the Upgrade CM Models action is invoked as part of upgrade.
Validity Period for Account Added by Site Admin (days)

The period, in days, for which a new user account added by a Site Admin is valid. If the user doesn't log in during the validity period, the account expires.

Choices: any single digit 1–30; 45, 60, 90, 120, 150, or 180. You can also choose Never Expire.

Validity Period for Password Reset Code (in hours)

The period, in hours, for which a password reset code is valid.

Choices: 2, 4, 8, 12, 16, 20, 24, 28, 32, 36, 40, 44, 48, 60, 120, 180, or 240. You can also choose Never Expire.

Default: 48 hours.

Validity Period for Update Email Code (in hours)

The validity period, in hours, for the code sent to a user who initiates change of email address on the user account.

For more information about the process when a user initiates change of email address, see How do I change my email address?

Validity Period for Signup Code (in days)

The period, in days, for which a signup code is valid. The signup code is issued in the email confirmation for self-signup registration.

Choices: any single digit 1–14; you can also choose Never Expire.

Default: 7 days.

Validity Period for Invitation Code (in days)

The period, in days, for which an invitation code is valid. The invitation code is issued in an email when a group/team member invites a non-platform user to join the group/team.

Choices: any single digit 1–30; you can also choose Never Expire.

Default: 7 days.

News Update Notification If enabled, news update notifications can be sent to all users, as long as the users have not opted out by clearing the Email me news updates check box on the user profile page. For more information, see How do I enable or disable email notifications?
Enforce Challenge Questions on Login

If enabled, users must provider answers to security challenge questions when logging in to the platform for the first time.

For information on configuring the security challenge questions, see How do I configure security challenge questions?

User Self-Signup

Determines whether the platform signup page is generally available for users to sign themselves up.

Default: Enabled.

Invite Unregistered Users

Determines whether unregistered users can be invited to sign up to the platform or to join platform groups.

By default, all users can be invited; unregistered users are invited to sign up and then invite the group membership invitation. If this option is disabled, an unregistered user cannot be invited to sign up to the platform or to join a platform group.

Note: If this option is disabled, the option to invite new users is removed from the menu.

Default: Enabled.

Max Allowed APIs in My Dashboard

(Valid in Version: 2020.1.0 and later)

The maximum number of APIs allowed on a user's My Dashboard, the top APIs metrics summary.

Default, and maximum allowable, is 10. If needed, you can set it to a lower number.

To configure user settings

  1. Log in as a Site Admin and go to the Admin section.
  2. Go to More > Admin >Settings > Users.
  3. Change the settings as needed. For explanations of your choices, refer to the table above.
  4. Click Save.

    If needed, you can use the Reset button at any point before saving to remove changes you just made.

How do I configure settings for two-factor authentication of users (2FA)?

You can configure user settings to determine whether two-factor authentication is in use in the platform, and if so, to specify values that guide the authentication process.

For information about how to implement 2FA, see How do I implement two-factor authentication for platform users?

2FA Settings

This setting... Controls this feature...
Require Two-Factor Authentication for Login Indicates whether a verification code will be required as part of the login process, in addition to user credentials such as username/password.
Validity Period for Authentication Code (in seconds) The period, in seconds, for which a verification code will be valid for login.
Maximum Attempts The maximum number of login attempts a user can make with one verification code. After that point, the user will have to request a new code.
Authentication Code Frequency Requirements The rules determining how often and under what circumstances the current two-factor authentication expires and the user must authenticate again. If login is per device or for a specified time period, specify the name of the cookie set by the two-factor authentication. For time period, specify the time in minutes. Valid values:
  • For each login (no extra values needed)
  • Once per device: specify the name of the cookie that will be used during 2FA login
  • After a specific time period: specify the name of the cookie that will be used during 2FA login and also the number of minutes before the verification code expires.
Cookie Name The name of the cookie that will be used during 2FA login.
Interval (in minutes) The number of minutes before the verification code expires.

To configure user 2FA settings

  1. Log in as a Site Admin and go to the Admin section.
  2. Go to More > Admin >Settings > User 2FA.
  3. On the Two-Factor Verification Settings page, change the settings as needed. For explanations of your choices, refer to the table above.
  4. Click Save.

    If needed, you can use the Reset button at any point before saving to remove changes you just made.

How do I prevent referencing external sites in Community Manager developer portal content pages?

It's possible to reference an external website within an <iframe> tag in a Community Manager developer portal content page, using the &doc parameter:

{protocol}://{hostname}/{tenant}/#!{sitepage}&doc={URL-encoded external URL}

The example below illustrates how this might look using the Simple Developer theme's documentation page, and referencing the external website http://www.example.com:

http://acmepaymentscorp.com/acmepaymentscorp/#!documentation&doc=http%3A%2F%2Fexample.com

However, this feature could be an insecurity, since the external site to be displayed could potentially be modified via a malicious content injection. For Site Admins who want to disable the ability to reference external sites in a Community Manager developer portal content page, there is a security setting, Allow display of external content in developer portal content pages. See How do I configure settings for business security? above.