Configuration

Basic configuration information for the Community Manager developer portal.

Table of Contents

Configuration:

Cookies:

Configuration:

How do I configure separate notification addresses for different platform themes?

The platform sends out email notifications to keep platform users informed about specific events—for example, password reset or changes to a team that the user is a member of. Some of these notifications include the platform URL; for example, the Welcome email includes the platform homepage URL for logging in.

If you have more than one theme configured for your platform installation, each theme has a separate URL. If a developer using your theme B forgets his password, the notification with the reset password link must include the URL for Theme B, not for Theme A. Therefore, you will need to take some extra steps so that, where applicable, the notifications triggered by activity on a specific theme use the correct URL for that theme.

The theme that by default we call Simple Dev has a simpler user interface and is focused on a developer audience; Hermosa Themeboth include additional functionality, such as API and business management and Site Admin functions. Because of this, notifications for roles more applicable to Hermosa Theme are always sent out from the Hermosa Theme URL, even if the activity occurred in Simple Dev. These roles include:

  • Site Admin
  • Business Admin
  • API Admin

Notifications for the following roles use a theme-specific URL:

  • Anonymous user (not signed in as a platform user; for example, in a "forgot password" scenario)
  • Developer
  • App team member

For a full list of roles and the types of notifications that are sent to each role, see What are the user roles for notifications sent out from the platform?

When there are multiple themes configured for the tenant, you will need to run a script to load the TENANT_THEME_ROLES table and map the theme > roles list. This table tells the platform which theme is used for which notifications.

In the NOTIFICATION_ROLES table, each notification template is mapped to the role that it is meant for. Before a notification is sent out, the tenant.console.address variable is replaced with the theme-specific URL for the role that the specific notification template is mapped to.

In a few cases, multiple themes might be possible for the same notification. For example, a user of any theme might request a password reset. In this case, the platform uses the URL for the theme that caused the notification to be generated. The Forgot Password notification will include the address of the console for the theme in which the user initiated the Forgot Password request. In an upgrade scenario, or if the database modification to the TENANT_THEME_ROLES table, as below, has not been done, no themes will be mapped to any roles. In that case, we use the theme that is the default for the tenant.

The theme-specific feature cannot be configured in the user interface. Instead, you must run a database script. A template is shown below; this uses variable placeholders for theme name, role name, and tenant name.

insert into TENANT_THEME_ROLES select TENANTID, '{theme}', '{rolename}' from TENANTS where FEDMEMBERID='{tenant-name}';

If there is only one tenant, you can omit the tenant name, like this:

insert into TENANT_THEME_ROLES select TENANTID, '{theme}', '{rolename}' from TENANTS;

An example is shown below, using the theme names default and simpledev. In the below, substitute a value for the {tenant-name} variable or, if there is only one tenant, remove the where statement. If you are using different theme names, substitute the applicable values.

insert into TENANT_THEME_ROLES select TENANTID, 'default', 'Anonymous User' from TENANTS where FEDMEMBERID='{tenant-name}';
insert into TENANT_THEME_ROLES select TENANTID, 'default', 'ApiAdmin' from TENANTS where FEDMEMBERID='{tenant-name}';
insert into TENANT_THEME_ROLES select TENANTID, 'default', 'BusinessAdmin' from TENANTS where FEDMEMBERID='{tenant-name}';
insert into TENANT_THEME_ROLES select TENANTID, 'default', 'SiteAdmin' from TENANTS where FEDMEMBERID='{tenant-name}';
insert into TENANT_THEME_ROLES select TENANTID, 'simpledev', 'User' from TENANTS where FEDMEMBERID='{tenant-name}';
insert into TENANT_THEME_ROLES select TENANTID, 'simpledev', 'Anonymous User' from TENANTS where FEDMEMBERID='{tenant-name}';
insert into TENANT_THEME_ROLES select TENANTID, 'simpledev', 'AppAdmin' from TENANTS where FEDMEMBERID='{tenant-name}';
insert into TENANT_THEME_ROLES select TENANTID, 'simpledev', 'Developer' from TENANTS where FEDMEMBERID='{tenant-name}';

What is the CSRF prevention feature?

The CSRF prevention feature adds a layer of protection against malicious CSRF attacks, by means of a custom header.

A CSRF attack leverages the fact that the authorized user has already authenticated, and that the cookie is stored in the user's browser. The CSRF prevention feature requires an additional value to be sent as an extra header. If the extra header is not present, the request is rejected as unauthorized.

An authorized app developer can get the value from the cookie and compose and send the custom header with the request message.

The new header is the X-Csrf-Token_fedmemberID header. The app must take the value in the new Csrf-Token_fedmemberid cookie and send it as the value for the X-Csrf-Token_fedmemberID header in the following scenarios:

  • All POST operations
  • All PUT operations
  • All DELETE operations
  • All GET operations except those in the following services/activities:
    • Content upload and management
    • Resource upload and management (such as avatars)
    • Login

The Csrf-Token_fedmemberid cookie has the same timeout value as the AtmoAuthToken authorization cookie (as specified by the Site Admin, or 25 minutes by default).

For information on how to implement the CSRF prevention header, see How do I implement the CSRF prevention feature? below.

How do I implement the CSRF prevention feature?

If you're concerned about malicious CSRF attacks, make sure the CSRF prevention feature is in effect. This feature is turned on by default in new implementations, and turned off by default in existing implementations that upgrade to any version of the platform after version 7.1.3.

You can control CSRF prevention via the Business Security settings: see How do I configure settings for business security?

If you already have a custom client, refer to I want CSRF prevention, but we already have a custom client. What do I do? below.

I want CSRF prevention, but we already have a custom client. What do I do?

If your implementation includes the CSRF prevention feature, this requires all messages to POST, PUT, or DELETE operations to use the new X-Csrf-Token_fedmemberID custom header.

However, if you already have a client that sends and receives messages to the Akana API Platform, when you implement the new feature, messages from the client will be refused because they don't have the custom header.

To support this feature in scenarios where there is an existing client that doesn't use the custom headers, there is a configuration setting you can use to specify that your client is a trusted sender and the custom header is not required. When the sending client is listed in this configuration setting, the messages are processed without the custom header.

In the configuration settings, under com.soa.atmosphere, choose atmosphere.config.csrfHttpWriteSkipUserAgents. This setting supports Network Director and federated Akana API Platform scenarios invoking Akana API Platform APIs without having to send the CSRF token.

For more information about accessing and modifying this setting, see How do I get to the Akana API Platform Configuration Settings in the Akana Administration Console?

How do I configure security challenge questions?

The platform includes a feature whereby you can configure security challenge questions to be offered to user signing up.

By default, a user signing up is asked to answer three questions. The user's answers are stored securely in the database and the questions/answers are used as additional security for certain sensitive operations, such as when the user requests a password reset.

Later, as part of managing the user profile, the user can modify answers to existing questions, or can choose one or more different questions from the list provided and then answer the new questions.

In some cases, the user's answer might not be displayed, depending on the site's security settings.

The Site Admin can choose from certain questions that are set up by default, to be offered to users, or can compose different questions.

This feature adds another layer of security for the user's account.

For information on how to set up and manage security challenge questions, see How do I configure settings for security challenge questions?

Note: If you add security questions and later replace them with different ones, the older questions are maintained in the database since user might have set up answers to those questions. In this case, they are set to Inactive in the database (ACTIVE=N) since they are no longer in active use.

How do I enable Markdown for Forum items?

The platform supports the use of Markdown to add rich text formatting, inline images, and downloadable files in user-generated Forum entries.

If enabled, Markdown is supported for discussions, tickets, alerts, reviews, and comments.

For each type of Forum item that supports Markdown, there are two configurable settings:

  • Markdown Support
  • External Link Support

To enable Markdown for discussions, tickets, alerts, reviews, or comments

  1. Log in as a Site Admin and go to the Admin section.
  2. Go to More > Admin >Settings.
  3. Choose the type of setting:
  4. On the Markdown Support field, click Enabled.

    This enables the use of Markdown to add formatting such as heading styles, bold and italics, tables, and lines. It also allows image upload for the display of inline images, and file upload so that the content can include a link to a downloadable file.

  5. On the External Link Support field, click Enabled (or leave as Disabled).

    This enables the use of external links in Markdown. It's only applicable if Markdown support is enabled. One application of this setting is to restrict links to external sites for security reasons, by leaving external link support disabled, while allowing formatting and uploaded files by enabling the Markdown setting.

  6. Click Save.

For more information on using Markdown, see Using Markdown.

I need to monitor app security changes. What do I do?

By default, whenever an app developer makes a significant change to app credentials, the user is required to enter a comment regarding the action being done. A notification is posted to the app's Forum regarding the action, the user performing the action, and the user's comment. This acts as an audit trail which you can also access via the database.

Comments are collected, and Forum items generated, for the following events relating to app security:

  • App Shared Secret is regenerated.
  • Credentials are uploaded.
  • Credentials are modified.
  • Credentials are removed.

Cookies

Does the Community Manager developer portal use cookies?

Yes. The Community Manager developer portal uses two main cookies:

  1. Session authorization cookie (AtmoAuthToken)

    When a user logs in, an authorization cookie is sent, and is stored in the browser for the duration of the user's session. The session cookie is renewed as long as the session remains active, and is refreshed if the information stored in the cookie, such as the user's permission information, changes. It is removed when the user logs out. If the user does not log out, it expires after 30 minutes of inactivity. If the user closes the browser, the cookie remains valid until the 30-minute expiration time; if the user opens the browser again within this time, and resumes the session, the cookie remains valid. If the browser is closed for 30 minutes the cookie expires.

  2. CSRF prevention cookie (Csrf-Token)

    Like the AtmoAuthToken cookie, the CSRF prevention cookie is set at login. It is used only if the CSRF prevention feature is in use. The platform provides this cookie as an additional safeguard against CSRF attacks. Like the authorization cookie, it is stored in the browser for the duration of the user's session. It is renewed if the AtmoAuthToken cookie is renewed. The CSRF prevention cookie has the same expiration time as the AtmoAuthToken cookie. For more information, see What is the CSRF prevention feature?

A key difference between these two cookies is that the AuthToken cookie is set with the HttpOnly option, meaning that JavaScript cannot read this cookie; the CSRF token cookie does not use the HttpOnly option, because the JavaScript must be able to read this cookie when making Ajax calls from the browser.

Local browser storage

In addition, the Community Manager developer portal uses a local storage field in the browser, touch, to store the timestamp that's used to manage the inactive session timeout feature in scenarios where the user might have two browser tabs open at the same time. This is true for the following browser versions:

  • Internet Explorer version 8 and later
  • Chrome
  • Mozilla Firefox

There are other cookies that are used in different parts of the Community Manager developer portal user interface very briefly as a way to pass information from one page to another. For more information, see Does the Community Manager developer portal use any cookies other than the session and CSRF cookies? below.

Will the Community Manager developer portal work properly if cookies are disabled?

If cookies are disabled, anonymous users can still access the portal, but none of the functionality that is available only to users who are logged in will be available. This includes activities such as adding, modifying, and deleting apps and APIs, creating contracts, creating or joining groups, and commenting on discussions.

The session cookie (AtmoAuthToken) includes information on the user's roles, and the resources the user has access to, so it is necessary for the full functionality of the Community Manager developer portal.

The Site Admin can turn off the CSRF prevention feature in the security settings: More > Admin >Settings > Security. In this case, the Csrf-Token cookie is not used. However, turning off this security feature is not recommended.

What information is contained in the cookies and what is it used for?

The session cookie includes information on the roles and permissions that have been granted to the user. This includes:

  • Whether the user is a Site Admin or Business Admin.
  • Whether the user is an API Admin for one or more APIs, and if so which ones.
  • Whether the user is an app team member for one or more apps, and if so which ones.
  • Groups the user is a member of, and the membership role if applicable (Admin, Leader, or Member, for independent platform groups).
  • Resources the user is following.

The session cookie determines which resources the user can see and can modify, based on the user's role and permissions as above.

The Csrf-Token cookie is used only as an additional mechanism that can be used to help prevent a CSRF attack. When adding, changing, or deleting platform resources, the CSRF-header is needed; the CSRF-Token is used in composing the CSRF header. For more information, see What is the CSRF prevention feature? The CSRF settings can be turned off; in this case, the Csrf-Token cookie is not used.

Does the Community Manager developer portal store persistent cookies in the browser?

By default, both the cookies that the Community Manager developer portal uses are persistent cookies; the action of closing the browser does not remove them. However, both the cookies are removed when the session ends or times out.

There is a Site Admin setting you can use for added security so that the cookie is removed when the user closes the browser. For more information, see below.

You can modify the cookie behavior so that cookies are removed when the user closes the browser. To do this, update the site setting, Support Persistent Sessions, in More > Admin >Settings > Login. For more information, see How do I configure settings for login policy?

By default, the session cookie persists if the browser is closed, until either the user resumes the session and then logs out, or the cookie expires. If the Support Persistent Sessions setting is disabled, for added security, the cookie expires when the browser is closed.

There are some other factors that might affect how this setting works:

  • If the user closes the tab that's running the Community Manager developer portal, but doesn't close the browser, this action doesn't expire the cookie. The user must fully close the browser, all tabs and all instances, for the cookie to be expired.
  • When the Site Admin changes the setting, he/she must log out and log back in for the setting to take effect for his/her own session.
  • Non-persistent cookie override: If the user has the browser set to automatically open the tabs from the last session (Continue where you left off setting or similar wording), behavior might be different depending on the user's browser:
    • In Firefox and Chrome, if the user enables this setting, the browser behavior overrides the platform setting. The cookie persists when the browser is closed and re-opened (if the cookie timer doesn't expire).
    • In Internet Explorer 9 and 11, and Microsoft Edge, browser behavior doesn't override the platform setting. If the Support Persistent Sessions setting is disabled, the cookie expires when the browser is closed, as expected.
  • Persistent cookie override: in Firefox, if the user enables the "never remember history" setting, the session cookie is removed when the user closes the browser, even if the Support Persistent Sessions setting is enabled.

Does the Community Manager developer portal send cookies to other sites?

No. The Community Manager developer portal uses its own cookies, as covered in Does the Community Manager developer portal use cookies? above. It does not send cookies to other sites.

Does the Community Manager developer portal use any cookies other than the session and CSRF cookies?

The main cookies that the Community Manager developer portal uses are the session and CSRF cookies, as covered in Does the Community Manager developer portal use cookies? above.

However, the portal also uses cookies very briefly with certain features, in the following scenarios:

  1. Test Client with OAuth Policy

    If you are using Test Client with OAuth policy, there is a cookie used in the Test Client feature that is set in the main page of the user interface so that it can be read in a popup window. It is deleted as soon as it has been read in the popup window. The platform does this to work around browser-enforced security, since the OAuth provider is usually from a different URL than the Community Manager developer portal URL. This cookie is live in Test Client only for a very short time, probably a few milliseconds. The cookie name is oauthRedirectInfoCookie.

  2. Third-Party Login with Google and Facebook (not LDAP)

    If you are using a third party such as Google or Facebook for login (not LDAP login), when the user logs into the portal for the first time, the portal uses a transient cookie to exchange information between the SSO login page and the signup page, in order to complete the signup page. This cookie stays live only for a very short time, probably a few milliseconds.

Note: If the platform is configured for Google Analytics integration, there will be additional cookies that are used by Google Analytics. Google Analytics integration is configured in the database. To turn it on: in the TENANTS table, set the value of the ANALYTICSACCOUNTID column to your Google Analytics account ID. To turn it off: set this value to null. Google Analytics cookies are prefixed with __utm.