Configuration

Set up custom color schemes, define a platform login, and upload documentation files and style sheets.

API Platform Version: 8.1 and later

Table of Contents

Custom Styles:
  1. I want to customize platform styles. What do I do?
  2. Which platform CSS file should I update?
  3. How do I customize how Markdown looks in the developer portal?
  4. What color scheme changes are supported on my platform deployment?
  5. What style sheets do I use to update the color scheme of my platform deployment?
  6. How do I download the platform CSS?
  7. How do I upload the custom.less file after I've updated it?
  8. After I update my custom.less file, how do I apply the changes to my platform deployment?
  9. How do I rebuild my color scheme styles after I have uploaded the custom.less file?
  10. What is a sprite?
  11. How do I modify sprite colors?
  12. What is less.js and what are the benefits?
  13. How do I make my style and sprite file changes visible on my platform deployment after I regenerate styles?
  14. How do I configure a custom footer?
  15. How do I configure a custom logo?
  16. What is a platform theme?
  17. How can I determine the theme name?
  18. Where do I store customization files for Hermosa theme?
Logins:
  1. How does login configuration work?
  2. Does the platform provide a default login?
  3. How do I enable and customize a platform login domain?
  4. What is a Target Host?
  5. What login page integration modes are supported?
  6. How do I disable a platform login?
  7. How do I disable the option for users to change the email address on the account?
Resources:
  1. What is a Resource?
  2. What's the difference between Resources and Content?
  3. What is the folder structure for content in Default Theme/Hermosa Theme?
  4. What is the folder structure for content in Simple Developer Theme?
  5. How do I upload content for Simple Developer theme?
  6. How do I download content or resource files?
  7. How do I upload style sheets to the platform?
  8. How do I upload sprite files to the developer portal?
  9. How do I upload content to the developer portal?
  10. How do I upload resources to the developer portal?
  11. How do I modify the landing page for the developer portal?
  12. How do I modify the favicon for the developer portal?
  13. How do I modify the default icon for apps, APIs, or other resources?
  14. How do I upload the API and Online Help content style sheet to the developer portal?
  15. How do I develop content for Simple Developer theme?
  16. Can Test Client use CORS to send the requests to the API endpoint directly without using the Forward Proxy?
  17. What are the metadata.json and widget_factory.json files, and how do I use them for customization?
  18. What is the Resource Version Key and how do I find it?
Configuration:
  1. How do I configure separate notification addresses for different platform themes?
  2. What is the CSRF prevention feature?
  3. How do I implement the CSRF prevention feature?
  4. I want CSRF prevention, but we already have a custom client. What do I do?
  5. How do I configure security challenge questions?
  6. How do I enable Markdown for Forum items?
  7. I need to monitor app security changes. What do I do?
Site Page Customization:
  1. How do I customize the left menu bar?
  2. How do I customize so that users are taken to a different page after login?
  3. How do I customize the Support page?
  4. How do I customize fonts in the developer portal?
  5. How do I customize fonts by referencing an external font?
  6. How do I customize fonts by uploading font files?
Cookies:
  1. Does the developer portal use cookies?
  2. Will the developer portal work properly if cookies are disabled?
  3. What information is contained in the cookies and what is it used for?
  4. Does the developer portal store persistent cookies in the browser?
  5. How can I set up the developer portal so that the cookies are not persistent?
  6. Does the developer portal send cookies to other sites?
  7. Does the developer portal use any cookies other than the session and CSRF cookies?
  8. Related Topics

Custom Styles:

I want to customize platform styles. What do I do?

The platform comes with a default look and feel, including styles, colors, navigation, logo, and so on. These platform default styles are stored in a stylesheet which is dynamically generated from a file named custom.less.

If you want to customize platform styles, follow the basic steps below.

For more information on what you can change, see What color scheme changes are supported on my platform deployment?

Note: When you upload new styles to the platform, you'll need to clear your browser cache and refresh the page to see the changes.

To customize platform styles:
  1. Log in as the Site Admin.
  2. Go to Administration > Config > Custom Styles.
  3. If you want to work with the template for the Simple Developer Theme (Simple Dev) rather than the full user interface (Default Theme/Hermosa Theme), choose it from the drop-down list at the top (theme names might be different depending on your implementation). Styles for all themes are managed in the same place. For more information, see What is a platform theme? and Simple Developer theme.
  4. Click Download to download the customized style sheet, custom.less.
  5. Choose a save location to save the file.
  6. Modify the styles as needed.
  7. Upload the revised file to the platform. For instructions, see How do I upload the custom.less file after I've updated it?
  8. Clear your browser cache and refresh the page to see the changes.

Note: The platform uses other stylesheets, such as style.css or supplement.css. Do not modify these stylesheets. All customizations should be stored in custom.less as explained above. For more information, see Which platform CSS file should I update? below.

Back to top

Which platform CSS file should I update?

All customizations should be stored in custom.less as explained in I want to customize platform styles. What do I do? above.

The platform uses other stylesheets, such as style.css or supplement.css. Do not modify these stylesheets. Some of the benefits of storing your customizations in custom.less:

  • All customized styles are in one place.
  • You can always revert back to the platform default if needed.
  • Your custom styles will not be overridden by the platform's CSS hierarchy
  • Your custom styles will not be overridden by platform updates

Back to top

How do I customize how Markdown looks in the developer portal?

The developer portal includes a set of default style definitions for the styles supported for Markdown. These styles are defined in the platform's custom.less style file.

To customize the Markdown styles, download the custom.less file (Administration > Config > Custom Styles) and search for Markdown. You'll see the section that defines the Markdown styles. For example:

// @markdown-preview-font-size-h1: 36px;

The above defines the style that's rendered for the h1 Markdown:

# This is a Heading 1 in Markdown

Modify the styles you want to change, remove the comment marks on any lines that you've changed (// at the beginning of the line), and then upload the revised custom.less file. The platform rebuilds the css based on the uploaded file, and the new styles are effective for both new and revised user-generated Forum entries that use Markdown.

For example, to change the default color for headings to red, find this line:

// @markdown-preview-headings-color: inherit;

and change it, as per the example below (you can also use any color values supported by standard CSS):

@markdown-preview-headings-color: red;

Then upload the modified file. See How do I upload the custom.less file after I've updated it?

To see the changes immediately, you'll need to clear cache. Active users do not see the changes immediately since the styles are cached for up to 30 minutes. After that point, everyone will see the revised styles.

For more information on modifying custom styles, see I want to customize platform styles. What do I do?

For more information on the use of Markdown for Forum items in the developer portal, see Using Markdown.

Back to top

What color scheme changes are supported on my platform deployment?

You can change the color scheme for platform elements such as:

  • Site background color
  • Left and top navigation
  • Text content area
  • Pop-up dialog elements
  • Horizontal rules
  • Text color of input fields
  • Default link colors

Color scheme updates are performed by updating the custom.less style sheet. For an overview of the process, and instructions, see I want to customize platform styles. What do I do?

Back to top

What style sheets do I use to update the color scheme of my platform deployment?

The platform offers two options for downloading the platform style sheet, which is the starting point for customization of platform styles:

  • Download the default style sheet template, custom_template.less. If you make customizations, and later want to revert, you can do so by downloading this file (Administration > Config > Custom Styles >Download Template), renaming it to custom.less, and uploading it (Administration > Config > Custom Styles > Upload).
  • Download the custom style file currently in use. If you haven't yet uploaded customizations, custom.less is the same as custom_template.less. If you've already uploaded customizations and are happy with them, but want to make further changes, you can download custom.less and build on that (but save a backup copy). In the UI: Administration > Config > Custom Styles > Download.

Some general points regarding the platform style sheet:

  • All of the variables and sprite file references in the custom_template.less file are configured with defaults that represent the look and feel of a default platform installation.
  • All custom.less style sheet variables are commented out. For site elements you want to customize, remove the comment from the element and then customize the variable.
  • Color management for icons is accomplished by modifying the Adobe Illustrator file that includes the sprite icons. Download a ZIP containing the Adobe Illustrator files.

Back to top

How do I download the platform CSS?

The platform CSS rules are documented in a file called custom.less. To customize platform css, first download the custom.less file, then customize the file, and then upload the revised file.

When you upload the custom.less file, the platform automatically rebuilds the styles and uses the new rules.

To download the latest version of the style customization file for the platform (custom.less file)
  1. Log in as the Site Admin.
  2. Go to Administration > Config > Custom Styles.
  3. From the Theme drop-down list, choose the theme. For more information, see What is a platform theme? and Platform user interface "theme".
  4. Click Download to download the customized style sheet, custom.less.
  5. Choose a save location to save the file.

Note: It's a good idea to keep a backup copy of the original file and any customization versions that you implement, as a manual version control. If you're not happy with the results when you upload the new customizations, you can revert to the previous version before troubleshooting.

Back to top

How do I upload the custom.less file after I've updated it?

The Administration > Config > Custom Styles section includes an Upload button that allows you to upload the custom.less file after you've customized it.

To upload the modified custom.less file:
  1. Log in as the Site Admin.
  2. Go to Administration > Config > Custom Styles.
  3. From the Theme drop-down list, choose the theme.
  4. In the bottom right section, click Upload.
  5. Navigate to the location of the modified file and upload it. When you upload the file, the platform styles are automatically rebuilt using the new file. When regeneration is complete a confirmation message is displayed. The custom.less file is stored in the \resources\less directory.
  6. Clear the browser cache and refresh the page to review the changes.

Back to top

After I update my custom.less file, how do I apply the changes to my platform deployment?

After you update your custom.less file, you can apply the changes to the platform deployment by uploading the modified file. When you upload the file, the site automatically rebuilds the site style sheets and the changes are reflected on the site. See How do I upload the custom.less file after I've updated it? for more information.

If the style sheet and sprite file changes are not visible immediately after the style sheet rebuild process is complete, clear the browser cache and then refresh.

Note: If you want to go back to the default styles at any point, you can always go back to the custom_template.less file. See To customize platform styles for the first time.

Back to top

How do I rebuild my color scheme styles after I have uploaded the custom.less file?

The platform includes a Rebuild Styles option that allows you to Initiate a rebuild of the platform style sheets. This is primarily used when a platform update is installed that includes style sheet changes. This option is primarily used when a site update is performed where style sheet changes were made.

For example, if an update was applied to the site and the update included new additions to the UI that required style sheet changes; this would mean that the style sheets were not active immediately after the update was completed. In this case, the Rebuild Styles option would complete update process by regenerating the style sheets.

To rebuild site style sheets:
  1. Log in as the Site Admin.
  2. Go to Administration > Config > Custom Styles.
  3. If you want to work with the template for the Simple Developer Theme (Simple Dev) rather than the full user interface (Default Theme/Hermosa Theme), choose it from the drop-down list at the top (theme names might be different depending on your implementation). Styles for all themes are managed in the same place. For more information, see What is a platform theme? and Simple Developer theme.
  4. In the Styles Customization section, click Rebuild Styles. The rebuild process takes approximately one minute. After style sheets have been rebuilt, the "Platform style sheets have been successfully regenerated using custom.less" confirmation message displays.
  5. After the style sheets are regenerated, clear the browser cache and refresh the page to view the changes.

Back to top

What is a sprite?

A sprite is a two-dimensional image used by the developer portal CSS to control the colors in platform default icons and images.

The platform UI includes a series of standard icons that are used for standard components of the UI such as quick filters, help, menu navigation names, and window titles. Although the icons and images cannot themselves be changed, the colors can be changed, as part of UI customization.

In Default Theme, you can customize by changing the colors of the sprite files.

Hermosa Theme uses a different approach to customization, Font Awesome (see http://fontawesome.io; external link).

When developing your UI customization design, in addition to deciding what colors you want to use on your site, you must also decide what icons and "contrasts" you want, before moving forward with the customization tasks. This task should be part of your site UI design process.

The platform provides a set of sprite files for Default Theme. You can view how the sprite files are specified, in the custom_template.less file. Each one is commented with " // path to the image file" and lists a URL that represents the path of the file.

Sprite files should always be uploaded after you have uploaded and regenerated your style sheets. For instructions, see How do I upload sprite files to the developer portal?

Back to top

How do I modify sprite colors?

During the UI design phase of your platform deployment your brand standards and colors are selected. The site includes a series of icons. The icon design is fixed and part of the site design, but the icon color and contrast can be changed by modifying the sprite files used by the platform icons. The general process for modifying icon colors involves the following steps:

  • To change icon color and contrast, you'll need to update one or more of a series of sprite files that define the color contrast for platform icons, by modifying the applicable Adobe Illustrator file provided by Akana. Download a ZIP containing the Adobe Illustrator files.
  • The process involves selecting the Artboard that includes the icon you want to modify, changing the icon color, and saving the Artboard to a PNG file. The PNG file must then be uploaded to the /resources/theme/{theme_name}/styles/images folder via Administration > Config > Resources to be updated in your platform UI.
  • For detailed instructions on how to modify sprite files, see Modifying Sprite Colors (separate PDF file).
  • If you save a sprite file to a filename that is not referenced in the custom_template.less file, edit the custom_template.less file and update the path to reflect the new filename. For example, if a particular icon was gray and you wanted it changed to orange, you might save your artwork to a new filename that reflected the color change or you could develop a naming convention using numbers, etc. The following example is an excerpt from a custom_template.less file that illustrates a sprite file URL reference:
    // path to the image file of 18px sprites of leftnav navigation items that reflect the current section of "subject" details
    // @leftnav-active-icons: @icon-active-18px: url("images/sprites_18_color.png");
    
  • If you updated a style sheet, use the Rebuild Styles option to regenerate the styles before uploading any new sprite files. Note that this function rebuilds all the folders in the /resources/theme/{theme_name}/styles directory. Because of this, new sprite files must be uploaded after the site styles are regenerated.
  • If you add a new Artboard to the Adobe illustrator file, or save an existing Artboard with a different name, you must upload the updated sprite files to the platform via Administration > Config > Resources, and save them in the /resources/theme/{theme_name}/style/images folder. Perform this step after rebuilding styles (Rebuild Styles option).
  • After styles are regenerated and sprite files are uploaded, clear the browser cache and refresh the page to view the changes.
  • For information on uploading sprite files to the platform, see How do I upload sprite files to the developer portal?

Back to top

What is less.js and what are the benefits?

The custom.less style sheet is implemented with LESS, a dynamic stylesheet language that extends the static CSS by adding a dynamic behavior in the CSS.

  • LESS.JS is a CSS pre-processor that allows you to write your own styles using the LESS pre-processor language and save them in a .LESS file.
  • LESS.JS will compile the file into pure CSS. LESS variables are defined with an @ sign and Variable assignment is done with a colon (:). After you update the custom.less style sheet and rebuild, the values of the variables are inserted into the output CSS document.
  • LESS helps reduce the size of the CSS and allows you to quickly and easily make changes to the platform color scheme and sprite files by updating one custom.less file and then rebuilding the complete set of site stylesheets.

Back to top

How do I make my style and sprite file changes visible on my platform deployment after I regenerate styles?

In most cases, after you regenerate styles and upload your sprite files you must clear the browser cache and refresh the page to view the changes.

Back to top

How do I configure a custom footer?

The footer customization process includes the following steps:

  1. Footer customization is done with an HTML file that acts as a template. The HTML file is uploaded to the /resources/templates/footer with the name footer.htm.
  2. Links in the footer.htm file can have a class attribute with values "ext" or "dialog." When a link has a class "ext," clicking on the link will open a popup window. When the link has a class "dialog," clicking on the link will open the href in a dialog window.
  3. A footer can be uploaded using the File Manager in the Site Administration > Config > Resources > Resources section. An uploaded footer becomes effective within five minutes if the page is refreshed after five minutes.
  4. If the footer.htm file requires additional styles, you can add them to custom.less.

Back to top

How do I configure a custom logo?

The process of adding a custom logo to the platform includes configuring your logo to comply with the logo file requirements (listed below), specifying the logo filename in the template (see To specify your logo filename in the template below) and uploading it to the platform (see To upload your logo file below).

Logo File Requirements

Your logo must comply with the following requirements:

  • Width should be no more than 295px.
  • Height should be 46px.
  • Background must be transparent.
  • File format should be PNG.
  • Specify the logo filename in the custom.less style sheet.
To specify your logo filename in the template:
  1. Log in as the Site Admin.
  2. Go to Administration > Config > Custom Styles.
  3. If you want to work with the template for the Simple Developer Theme (Simple Dev) rather than the full user interface (Default Theme/Hermosa Theme), choose it from the drop-down list at the top (theme names might be different depending on your implementation). Styles for all themes are managed in the same place. For more information, see What is a platform theme? and Simple Developer theme.
  4. Click Download to download a new custom_template.less file and rename it to custom.less.
  5. Load the custom .less file into an HTML editor and change the filename for this entry: @logo-img: url("images/{image_name}.png"); to the new logo filename.
  6. In the Custom Styles section, click Upload to upload the updated custom.less file. Note that the upload process automatically executes the Rebuild Styles function, which rebuilds the style sheets.
To upload your logo file:
  1. Log in as the Site Admin.
  2. Go to Administration > Config > Custom Styles.
  3. If you want to work with the template for the Simple Developer Theme (Simple Dev) rather than the full user interface (Default Theme/Hermosa Theme), choose it from the drop-down list at the top (theme names might be different depending on your implementation). Styles for all themes are managed in the same place. For more information, see What is a platform theme? and Simple Developer theme.
  4. Click Rebuild Styles to ensure that all the proper style folders are generated. Note: If you specified a custom logo name in custom.less and already uploaded the style sheet, the rebuild step is not required.
  5. Go to Config > Resources > Resources > File Manager and navigate to the theme/default/style folder:

  6. Click New Directory and name it images.

  7. Click into the /images folder and upload your logo file. Note that the logo must comply with the stated logo requirements.
  8. If for some reason the new logo does not display, try refreshing your browser cache and/or go to Administration > Config > Custom Styles, choose the theme if needed, and click Rebuild Styles.

Back to top

What is a platform theme?

One theme is one instance of the portal. During installation, the Site Admin has the option to configure more than one theme for the implementation. This is configured as part of running the jython scripts which are part of installation. Each theme has a separate URL.

When running the jython platform installation script, two parameters, theme and themeimpl, work together to establish the codebase that's installed.

If values are provided for both theme and themeImpl parameters: themeImpl is a unique code name for a specific theme which cannot be changed. It indicates the code base used for the implementation. Valid values: default or simpledev.

This introduces the possibility of cloning a specific theme with two or more user-defined sets of customizations. One set of customizations is independent of another. Definitions of the two parameters are given below.

theme

The theme parameter plays a different role as determined by whether the themeImpl parameter is also present:

  • If values are provided for both theme and themeImpl parameters: theme is a user-defined value. The customer can define multiple theme values, and each can later be customized via a unique custom.less file for each theme.
  • If the themeImpl parameter is not provided (backwards compatibility scenario): theme takes the definition of the themeImpl parameter (see themeImpl below). Valid values: default or simpledev.

themeImpl

If values are provided for both theme and themeImpl parameters: themeImpl is a unique code name for a specific theme which cannot be changed. It indicates the code base used for the implementation. Valid values: default or simpledev.

The new parameter takes the definitions previously applicable to the theme parameter. There are two valid values:

  • default (used in most cases)
  • simpledev

The theme parameter now takes a customer-defined value, naming a theme that the customer can then customize via the custom.less file. The customer can define multiple values for the theme parameter; each name must be unique for the tenant.
For backwards compatibility, if the themeImpl parameter is not present in the installation jython script, the value provided for the theme parameter in the installation script must be one of the valid core values of default or simpledev.

By using these two parameters together, customers can define multiple access points into the platform, each of which can have its own set of customizations applied. Some sample scenarios:

  • Multiple customizations of look and feel: Tenant ACMEPayments Corp has 10 partners; each partner has a different API on the platform, and each has an API admin who accesses the platform and exports metric information for the API.

    When installing version 7.2, the site admin defines the themeImpl parameter as default and creates 10 themes, each named for one of the 10 partners, and each with a different URL that includes the tenant name and partner name.

    After installation, the site admin customizes each version by uploading a custom.less file for each partner with the partner’s company colors and logo.

    When each API admin logs in via the URL for his company, he sees the colors and logo for his company.

  • Two theme implementations, additional theme customizations: Tenant ACMEPaymentDev Inc. has two audiences, a developer audience and an API Admin audience.

    In previous versions, this scenario was supported in only one customer case by supporting two completely different themes (one of which was a completely customer-specific customization). Although this solution allowed us to support two themes, it was not extensible.

    Now, the same solution can be accomplished for any customer by supporting two themes, default and simpledev. But each theme could also be cloned, defining values for the theme property of default and simpledev and then also providing values for the theme property, allowing additional customization to be supported.

    When creating the tenant, we just create a single theme. You can create additional theme later via Administration > Site. See How do I add a theme?

    Two-theme example: when installing version 7.2, the site admin defines the themeImpl parameter as default and then again as simpledev, and creates two themes:

    • developer uses the simpledev theme
    • apiadmin uses the default theme

    He does not bother with a custom.less file since having a different look and feel is not significant at the moment, but this can easily be added later at any point.

    Developers see the simpler user interface presented by the simpledev theme, while API Admins have access to the API management functionality offered only in Default Theme/Hermosa Theme.

Back to top

How can I determine the theme name?

For some customization tasks, where you're creating custom files and uploading them to the platform, you'll need to know the theme name for the version of the developer portal you're using.

The theme name is determined when the platform is created, so you might not know what it is.

If you're not sure, follow the steps below to check the theme name for your installation.

To determine the theme name for your installation
  1. Log in to the developer portal as the Site Admin.
  2. Go to Administration > Config > Custom Styles.
  3. In the Theme drop-down at the top, click to see what options are available to you. Check the theme name on the list. Unless the names are customized, the theme names are:

Use the applicable value, exactly as it's represented on the list, in your customization tasks.

Back to top

Where do I store customization files for Hermosa theme?

In general, any customization that you put in place for Default Theme is also applied to Hermosa theme. You don't need to take any extra steps, or do anything twice.

There are two possible scenarios where you might want to set up different rules:

  • You have customization in place in Default Theme that you do not want to apply to your Hermosa theme.
  • You want to apply customization to your Hermosa theme but don't want your Default Theme to be affected.

If you do not want the same customization to apply to both themes, all you need to do is create customization files for the Hermosa theme. The rules are:

  • If the platform finds customization files for Default Theme only, it applies the customization to both themes.
  • If the platform finds customization files for Hermosa, it applies that customization only to Hermosa.

The location for customization files for Hermosa theme is parallel to the location for Default Theme, but with a different folder structure as defined by the theme name:

  • theme/{default}/
  • theme/{hermosa}/

For example, for Default Theme:

  • /resources/theme/{theme_name}/locales/custom_en-us.json (for custom code that affects page behavior)
  • /resources/theme/{theme_name}/styles (for custom styles)
  • /resources/theme/{theme_name}/styles/images (for custom images such as a favicon)

and for Hermosa:

  • /resources/theme/hermosa/locales/custom_en-us.json (for custom code that affects page behavior)
  • /resources/theme/hermosa/styles (for custom styles)
  • /resources/theme/hermosa/styles/images (for custom images such as a favicon)

Back to top

Logins:

How does login configuration work?

As part of the initial platform setup, a Site Administrator sets up a series of domains that represent an enterprise's login requirements for the platform. Supported domain types for the platform login include:

  • Platform Login
  • Google® Connector
  • Facebook® Connector
  • LDAP
  • CA SiteMinder®
  • OAuth Provider
  • OpenID Connect Relying Party

In versions prior to 7.1.0, the platform installation also included a default platform domain that is automatically enabled when a new user account is created. In 7.1.0 and later, the default platform login domain is still there but it is not enabled by default. The Site Admin must manually enable the platform login domain as part of configuration.

After any desired login domains are installed, the Site Admin must enable them before they will be available to users. Additional configuration steps are also available, including:

  • Target Host (virtual hostname)
  • Logo (the button that's displayed on the login page for this login domain. If not specified, defaults to the first letter of the domain name)
  • External login page display mode (popup window or main window)

For instructions on configuring login domains, see How do I enable a domain for login?

Back to top

Does the platform provide a default login?

No. In versions prior to 7.1.0, the platform installation supported certain security domains that allow login with email address and password to be automatically enabled for use once the security domain was created.

As of version 7.1.0, this default has been removed. The platform does not allow the default platform login page to fall back to security domains supporting email/password-based login.

If your platform already had logins configured prior to upgrading to the version 7.1.0 release, the default option and configuration will remain in place after upgrading. However, if you install 7.1.0 and then configure, you'll need to add the login domains and then enable them, in two separate steps.

For more information, including instructions for restoring the default by running a database query, see How do I enable and customize a platform login domain? below.

Back to top

How do I enable and customize a platform login domain?

There are two steps to setting up a login domain on the platform:

  • Create the domain. In some cases, this requires some setup in Policy Manager. For instructions on setting up the specific type of login domain you want, see Domains.
  • Complete the configuration by enabling and customizing the login domain. See below for instructions.

Note: In versions prior to the 7.1.0 release, certain security domains that allow login with email address and password were automatically enabled once the security domain was created in Administration / Domains. The default has now been changed so that the default platform login page does not fall back to security domains supporting email/password-based login. Instead, you must explicitly enable the login domain after adding it. If you have already configured the platform prior to upgrading to the version 7.1.0 release, your default option and configuration will be unchanged after upgrading. However, if you install any version 7.1.0 or later, and then configure, you'll need to add the login domains and then enable them, in two separate steps.

To enable a domain for login:
  1. Log in as the Site Admin and click the Administration quick filter (wrench icon).
  2. Click Config > Logins.
  3. Check the Enable check box.
  4. If you would like to configure a virtual host for the domain, enter it in the "Target Host" text box. For more information, see What is a Target Host? below.
  5. In the Logo/Avatar column, click Upload and select the logo you would like to display for the Login button. for more information, see How do I upload and crop icons? You can upload your own custom button or refer to information from the provider, if available. For example:
  6. In the Mode column, click the applicable button to indicate whether you want the login domain to be a popup or to display in the main window. For more information, see What login page integration modes are supported?
  7. Click Save.

Once the login domain is enabled, it is available to anyone logging in to the platform.

Note: For new installations, if you want to restore the old setting so that platform login falls back to security domains supporting email/password login, run the following query on the database (line break added for display purposes only, query should not include line break):

update LOGIN_RULES set AUTO_LOGIN_EXT_DOMAIN='com.soa.feature.enabled' where BUSINESSID in 
(select BUSINESSID from TENANTS where FEDMEMBERID='{tenantid}';

If you have additional questions, contact Akana technical support.

Back to top

What is a Target Host?

The Site Administrator can specify one or more specific URLs that are valid logging into the platform. This could be used to provide a different login based on role (Business Admin, API Admin, Developer, and so forth), or for a backdoor login if one of the domain configurations is down. This is accomplished by specifying a Target Host address (virtual host address) for each login domain; for example, {role}.{company}.com.

It is best to develop a login plan for each role that covers different types of login scenarios. For example, if your site uses CA SiteMinder exclusively for logins, and the CA SiteMinder login is down for some reason, you will need a backdoor login to investigate the problem. To provide a resolution for this scenario, here are two possible approaches:

  • Configure the platform default login Target Host so that only the Site Administrator can log in using email and password credentials.
  • Configure an alternate Facebook domain (using the Facebook Connector domain) or Google login domain (using the OpenID Connect domain) and specify a Target Host for backdoor logins. Only users from that specific target host will be able to log in using that domain.

Back to top

What login page integration modes are supported?

The platform allows you to select how the login page associated with a login domain is displayed to the user when logging in. The integration method is selected via the Mode option on the Site Administration > Config > Logins page for a specific domain. Two options are available:

  • Popup—Displays the external login page as a popup window.
  • Main—Displays the external login page in the platform home page instead of as a popup.

Note: Mode options are not configurable for the default login page.

Back to top

How do I disable a platform login?

To disable a platform login:
  1. Log in as the Site Admin.
  2. Go to Administration > Config > Logins. The Configure page displays a listing of domains that have been added to the platform.
  3. To disable the domain, clear the Enable check box.
  4. Click Save.

Back to top

How do I disable the option for users to change the email address on the account?

For security reasons, you might want to disable the ability for users to change the email address associated with local accounts set up on the platform.

Currently, you cannot change this setting via the user interface, but you can do it in the database, as follows:

  • Table: BUSINESS_SECURITY_SETTINGS
  • Column name: USER_MODIFY_EMAIL

The default value for this column is: com.soa.feature.enabled. To disable the ability for users to change email address, set this value to: com.soa.feature.disabled.

Back to top

Resources:

What is a Resource?

In the context of the Administration > Config > Resources section available to the Site Admin, a Resource is any type of publishing artifact used in the construction of the platform UI presentation. This includes:

  • css style sheets
  • Images
  • Sprite files
  • Site copy
  • The site legal agreement
  • API documentation, legal agreements, and downloadable files
  • Online help documentation

Back to top

What's the difference between Resources and Content?

When you log in as the Site Admin and go to the Administration > Config > Resources section, you'll see two buttons to access File Manager:

  • Resources

    The Resources button takes you to the /resources folder for your implementation. From here, you can upload files and create folders. Use this location for assets that do not require indexing, such as images and sprite files.

    Note: For site styles, use the Config > Custom Styles option; see I want to customize platform styles. What do I do?

  • Content

    The Content button takes you to the /content folder for your implementation. Here, you can upload customized content files for the platform help and the platform legal agreement. You can also upload API documentation and API legal agreements, for any APIs already created on the platform. If you're uploading API documentation, you'll need to know the APIID so that you choose the correct folder.

    Files uploaded to this location are indexed periodically, automatically, so that content is available for your site users when they use the Search feature to look for content.

For more information on the file and folder structure for your implementation, as it relates to files you might want to upload or customize, see What is the folder structure for content in Default Theme/Hermosa Theme? and What is the folder structure for content in Simple Developer Theme? below.

Back to top

What is the folder structure for content in Default Theme/Hermosa Theme?

If you're uploading content to the platform, via Administration > Config > Resources > Content, you'll need to make sure you place files in the correct folders.

Clicking the Content button takes you to File Manager where you can create folders, navigate up and down the folder structure, and upload single files or ZIP files. When you're uploading files, it's important to make sure you're in the right folder. You cannot move files.

The Content button takes you to the top level of the folder structure, the /content folder. From there, the folder structure is as follows:

  • /api: top folder for any API documentation. When an API is added on the platform, a documentation folder is created. Click through to a specific API to upload API documentation.
  • /home: top folder for site content. From here there are additional subfolders:
    • /landing for the site landing page and legal agreement (ideally HTML and PDF, but only one agreement)
    • /learnmore where the site content files are located.
    • /signup/confirm for the signup page.
    • /support for the support page.

For example, let's say you want to customize the Support page. The URL for the page is: {hostname}/#/home/support. You would go to Administration > Config > Resources > Content, to access the Content folder, navigate down to the home/support folder, and upload the new file. See To customize the Support page for the developer portal.

If needed, you can save out the existing HTML; choose to view the file in the browser, click View Source, and then copy the HTML. Or you can export the fileset, which will include referenced assets.

Back to top

What is the folder structure for content in Simple Developer Theme?

The Simple Developer theme shares the same file and folder structure as Default Theme/Hermosa Theme (see What is the folder structure for content in Default Theme/Hermosa Theme? above), but uses different folders for content.

Simple Developer theme, by default, includes the following three content files/folders:

  • Documentation page: documentation/index.htm. In the user interface, this is accessed via the Documentation link at the center of the top menu bar.
  • Help page: documentation/index.htm. In the user interface, this is accessed via the Help link, right of top menu bar.
  • Welcome page: documentation/index.htm. In the user interface, this is accessed by clicking on the logo at the top left.

In the file system, these are represented by a structure of three subfolders in the main /content/ folder:

  • content/documentation/index.htm
  • content/help/index.htm
  • content/welcome/index.htm

For more detailed information about content development and management for the Simple Developer theme, see Content Development Guidelines for Simple Developer Theme.

Back to top

How do I upload content for Simple Developer theme?

The Simple Developer theme shares the same file and folder structure as Default Theme/Hermosa Theme, but uses different folders for content. If you want to replace existing content, you must mirror the existing folder structure, as given in What is the folder structure for content in Simple Developer Theme? above.

When you navigate to the content folder in File Explorer, you won't see these subfolders and files. However, to update the content, you must use identical folder and file names. Create the folder, click into the folder, and then upload the revised file, as explained below.

To update a Simple Developer default page
  1. Log in to the platform (Default Theme/Hermosa Theme) as a Site Administrator.
  2. Go to Administration > Config > Resources.
  3. In the Content section, click File Manager to access the Content folder.
  4. Click New Directory, and create a folder with the exact name of the folder in which you want to update the content: for example, help.
  5. Click the new folder to go into it in File Explorer.
  6. Click Upload a File.
  7. Navigate to the location of the updated file and upload it. You can also upload a ZIP archive if you want to add multiple files or assets.
    Note: If you are uploading a ZIP file, make sure you're in the correct folder before uploading. The files are automatically unzipped as part of the upload process.
  8. Click Upload. The file is uploaded.
  9. Test by viewing in Simple Developer theme.

    Note: to see the update immediately, you will need to clear cache and refresh the page. Cache is updated automatically every hour, so there is a delay before developers see the new page.

For more detailed information about content development and management for the Simple Developer theme, see Content Development Guidelines for Simple Developer Theme.

Back to top

How do I download content or resource files?

In File Explorer, you can download a ZIP file of the current directory including all files in the directory and all subfolders and their contents. You can download a ZIP of any content or resources that you are authorized to view and edit. Follow the instructions below.

To download content or resource files:
  1. Log in to the platform (Default Theme/Hermosa Theme) as a Site Admin.
  2. Go to Administration > Config > Resources.
  3. Under either Resources or Content, click the File Manager button.
  4. Navigate to the directory you want to download (or stay in the current directory).
  5. Click Download Directory.
  6. Choose to open or save the file.

Back to top

How do I upload style sheets to the developer portal?

When you upload a new custom.less file in the Custom Styles section, the /resources/theme/{theme_name}/style directory is automatically created and includes the site default style sheets. Some points to note:

  • These style sheets cannot be updated using the upload process used for static content because the styles are regenerated each time a new custom.less style sheet is uploaded.
  • If you want to add new styles to the platform, you must first download the template, custom_template.less, then rename it to custom.less, add the new styles to the custom.less file, and upload the modified file. When you upload the revised file in the Config section of the user interface, the new styles are added to the site as part of the rebuild process. For more information and detailed instructions, see To customize platform styles for the first time.
  • Only a Site Administrator can update the platform style sheet.

Back to top

How do I upload sprite files to the developer portal?

If you've updated one or more sprite files, you can create an /images folder in the /resources/theme/{theme_name}/style directory and upload them. Sprite files must be uploaded AFTER you have uploaded your custom.less file and have rebuilt the site styles (either automatically as part of the custom.less upload process, or manually by executing the Rebuild function).

To upload sprite files to the developer portal:
  1. Log in as the Site Admin.
  2. Go to Administration > Config > Resources.
  3. In the Resources section, click File Manager. Navigate to the /resources/theme/{theme_name}/style directory. You will see the following default styles which were auto-generated as part of the custom.less upload process.

  4. Click New Directory and assign the name "images."
  5. Navigate to the /images directory.
  6. Click Upload. The File Upload dialog box displays. Select the sprite file you would like to upload and click Open.
  7. Click Upload to upload the file to the selected directory. Repeat this process until all the sprite files are uploaded.

Back to top

How do I upload content to the developer portal?

Platform content typically consists of HTML files, images that are referenced in the content, any custom styles sheets that support the content, and reference material, such as PDF files or diagrams, that are linked in the content.

Content that you can add or customize includes:

  • API Documentation Content—The /content/api directory includes a folder for each API that is added to the platform. When you initially add your API using the Add a New API function this folder is automatically generated and an id name is automatically assigned as the folder name; for example, api100.cm. API content is uploaded to this folder.
  • Online Help Content—You can use the /content/home/learnmore directory for any html and supporting graphic files you might want to add or modify for the platform Online Help.
  • Landing Page Content—The /content/home/landing directory includes HTML and supporting files that comprise the platform home page, including images, content, css styles sheets, and JavaScript files.
  • Developer Agreement—Upload the platform developer legal agreement to the /content/system/agreements directory, as shown below. You might have to create the path.

    Agreements folder

  • Support—The /content/home/support directory includes the default Support page, index.html. Use this folder for any html and supporting graphic files that comprise the Support section of the platform.
To upload a content file to the developer portal:
  1. Log in as the Site Admin.
  2. Go to Administration > Config > Resources.
  3. In the Content section, click File Manager.
  4. Select the directory for the content area you would like to update.

  5. Click Upload. The File Upload dialog box displays. Navigate to the file you want to upload and click Open.
  6. To upload the file to the selected directory, click Upload.

Back to top

How do I upload resources to the developer portal?

You can upload platform resources, such as avatars and other images, stylesheets, and custom pages, in the same way that you upload platform content. There is a different button to access the file structure for platform resources.

To upload resources to the platform:
  1. Log in as the Site Admin.
  2. Go to Administration > Config > Resources.
  3. In the Content section, click File Manager.
  4. Navigate to the folder to which you want to upload resources. If you are modifying default platform files for the first time, you'll need to create the folder structure. Follow the instructions for the type of custom content you're uploading, making sure you follow the exact naming for the folder structure. Use the buttons at the top of File Explorer to go up or down a level in the folder structure, and to upload a file or a ZIP archive.

    Note: You might get a message that the file exists, even though you just created the folder. This is expected if you are replacing a default platform file. Click OK.

Back to top

How do I modify the landing page for the developer portal?

To modify the landing page, you must download it, modify it offline, and then upload it to the same location.

To modify the landing page:
  1. Log in as the Site Admin.
  2. Go to Administration > Config > Resources.
  3. In the Content section, click File Manager.
  4. Click into the content/home/landing directory.
  5. Locate the index.htm file and download it.
  6. Modify the file offline, and then upload the modified file using File Manager.

Back to top

How do I modify the favicon for the developer portal?

The favicon is the small icon displayed on the browser tab and possibly in other parts of the browser. You can customize the icon that displays for your installation of the developer platform.

To modify the favicon for the developer portal:
  1. Log in as the Site Admin.
  2. Go to Administration > Config > Resources.
  3. In the Resources section, click File Manager to access the /resources folder.
  4. Navigate down to resources/theme/{theme_name}/style/images. If the folder structure doesn't exist, click New Directory to create a new subfolder, name it, and then click the new folder name to change directories down one level into the new one. Then create the next one until the folder structure exists and you are in the images folder. If you click into the resources folder and the theme folder doesn't exist, you'll have to create four levels of subfolder.

    Note: Make sure the folder naming, including sequence and capitalization, is exactly as above.

  5. From the images folder, click Upload a File.
  6. Navigate to the location of the favicon image and upload it. It should be an image file, 15 x 15 pixels in size, saved in the Windows favicon format with the name favicon.ico.
  7. To update the browser, clear cache and refresh the page. You might even need to close the browser and re-open to see the new favicon on the browser tab.

Back to top

How do I modify the default icon for apps, APIs, or other resources?

The platform includes default icons for apps, APIs, and other resources. You can specify new defaults by uploading new icons of the same filename, size, and type to the folder where the default files are stored.

The folder structure is not visible unless custom assets have already been created. If you have to create the folder structure, make sure you use the exact naming and spelling given below. Essentially you are creating the following files, two sizes for each resource for which you want to customize the icon.

Resource Main Icon (console/style/images/) Small Icons (console/style/images/)
API avatar_api_75x75.png avatar_api_25x25.png
API version avatar_app_version_75x75.png avatar_api_version_25x25.png
App avatar_app_75x75.png avatar_app_25x25.png
App version avatar_app_version_75x75.png avatar_app_version_25x25.png
Alert avatar_alert_75x75.png avatar_alert_25x25.png
API Access Request avatar_api_access_req_75x75.png avatar_api_access_req_25x25.png
Group avatar_group_75x75.png avatar_group_25x25.png
Discussion avatar_discussion_75x75.png avatar_discussion_25x25.png
Ticket avatar_ticket_75x75.png avatar_ticket_25x25.png
To modify the default icon for apps, APIs, or other resources on the developer platform:
  1. Log in as the Site Admin.
  2. Go to Administration > Config > Resources.
  3. In the Resources section, click File Manager to access the /resources folder.
  4. Navigate down to resources/console/style/images. If the folder structure doesn't exist, click New Directory to create a new subfolder, name it, and then click the new folder name to change directories down one level into the new one. Then create the next one until the folder structure exists and you are in the images folder. If you click into the resources folder and the console folder doesn't exist, you'll have to create three levels of subfolder.

    Note: Make sure the folder naming, including sequence and capitalization, is exactly as above.

  5. From the images folder, click Upload a File.
  6. Navigate to the location of the new image or images and upload. You'll need to make sure your new default icons have the following properties:
    • File type: PNG graphics format.
    • Dimensions: 75 x 75 pixels for the larger icon and 25 x 25 pixels for the smaller one.
    • Filenames: Refer to the table above for the filenames for each type of resource.
  7. To update the browser, clear cache and refresh the page. You might even need to close the browser and re-open to see the new default images.

Back to top

How do I upload the API and Online Help content style sheet to the developer portal?

The document.css style sheet contains all the custom styles for both API and Online Help documentation. It is located in the /content/style directory. If you make changes to the document.css file, you can upload it directly to the /content/style directory.

Note: This style sheet is not affected by the custom.less style sheet regeneration process and will not be changed or overwritten when a new custom.less file is uploaded.

To upload a document.css style sheet to the platform:
  1. Log in as the Site Admin.
  2. Go to Administration > Config > Resources.
  3. In the Content section, click File Manager. Navigate to /content/style. You will see a directory similar to the following:

  4. Click Upload. The File Upload dialog box displays. Select the document.css file and click Open.
  5. To upload the file to the selected directory, click Upload. If you receive an overwrite message click OK.

Back to top

How do I develop content for the Simple Developer theme?

Content development for the Simple Developer theme is managed in the same way as content development for Default Theme/Hermosa Theme. The files share the same main folder structure, but there are unique subfolders for Simple Developer content.

In addition, you can develop and upload custom pages for Simple Dev.

For detailed information on working with Simple Developer content pages, including working with styles, linking, supported file formats, managing assets, and other information, refer to Content Development Guidelines for Simple Developer Theme.

For information about uploading the files, see How do I upload content for Simple Developer theme?

Back to top

Can Test Client use CORS to send the requests to the API endpoint directly without using the Forward Proxy?

Yes. You can configure the platform to enable or disable the CORS policy for the purposes of apps testing APIs in the Test Client testing tool.

Regardless of whether the CORS policy is attached to a specific API, this policy is always turned off for the purposes of testing with the Test Client tool.

If you want to turn the CORS policy on as a default in Test Client, you will need to create a file named init.js with some custom lines of code, as given below; if you already have a custom init.js file, you'll need to add the lines of code to the existing file.

To override the default setting for Same Origin Policy (CORS Policy) in Test Client:

Step 1: Check whether you have an existing init.js file

  1. Log in as the Site Admin.
  2. Go to Administration > Config > Resources.
  3. In the Resources section, click File Manager to access the /resources folder.
  4. Navigate down to resources/theme/{themename}/SOA/Dev/extensions. If the folder structure doesn't exist, click New Directory to create a new subfolder, name it, and then click the new folder name to change directories down one level into the new one. Then create the next one until the folder structure exists and you are in the extensions folder.

    Note: Make sure the folder naming, including sequence and capitalization, is exactly as above.

  5. If the folder structure already exists, and there is an init.js file in the extensions folder, download the file so you can modify it offline.

Step 2: Create or update the init.js file

  1. Do either of the following:
    • If there is an existing init.js file: Modify the file you downloaded above, adding the lines of code given in Modifying the custom init.js file below.
    • If there is no existing init.js file: Create the file and add the code as below.
  2. Customize the init.js file to the required settings. For instructions, review the comments in the code.

Step 3: Upload the customized init.js file

  1. From the extensions folder, click Upload a File. Navigate to the location of your custom init.js file and upload the file. If you kept the theme name that is the default, it will look like this:
    • resources/theme/simpledev/SOA/Dev/extensions/init.js
  2. To update the browser, clear the cache and refresh the page. You might even need to close the browser and re-open to see the update.

The default setting for the CORS policy, and the default behavior of Test Client with regard to whether the message is sent to the proxy or directly to the API endpoint, changes according to the value you specified in the init.js file. The file itself includes inline documentation.

Modifying the custom init.js file

If no customizations were already added in your installation, this file will not exist in your file structure. In that case, you can create the file using the contents below. If the file already exists, you'll need to add the lines of code given below, and then customize as needed.

The code for the default CORS settings for Test Client is shown below. Inline documentation explains the settings you can change. There are two settings:

  • allowOverride: true by default. If you change it to false, Test Client will not display the security settings dialog relating to the same origin policy, and therefore developers will not be able to change the setting.
  • defaultOption: cmForwardProxy by default, indicating that the message is sent by Test Client to the proxy and then forwarded to the API endpoint. If you change this setting to cors, indicating that the API is expected to support cross-origin resource sharing, the message is sent directly to the API endpoint; the forward proxy is not used.
SOA.Framework.Common.Map.config({
  "testClientSettings" : {
    "policySettings" : {
      "sameOriginPolicy" : {
        // possible values true, false
        // true - will display dialog
        // false - will not display dialog
        // By default this is set to true
        "allowOverride" : true,
        "cors" : {
          // possible values "cors" and "cmForwardProxy"
          // cors - directly access endpoint
          // cmForwardProxy - proxy through Forward Proxy
          // By default this is set to "cmForwardProxy"
          "defaultOption" : "cmForwardProxy"
        }
      }
    }
  }
});

Back to top

What are the metadata.json and widget_factory.json files, and how do I use them for customization?

If you're performing UI customization tasks, you'll need to modify these files:

  • metadata.json: a file that describes the layout of the pages and the corresponding URL for each page. If there is no customization in place yet, metadata.json contains only a single pair of brackets: {}. For an example of customization, see metadata.json.
  • widget_factory.json: A JSON file that describes the CanJS view corresponding to each widget in metadata.json. If there is no customization in place yet, widget_factory.json contains only a single pair of brackets: {}. For an example of customization, see widget_factory.json.

First create the files, and them upload them to the location shown below:

  • /resources/theme/{theme_name}/SOA/CM/extensions/metadata.json
  • /resources/theme/{theme_name}/SOA/CM/extensions/widget_factory.json
To upload the metadata.json and widget_factory.json files to the developer portal:
  1. Log in as the Site Admin.
  2. Go to Administration > Config > Resources.
  3. In the Resources section, click File Manager.
  4. Navigate to the /resources/theme/{theme_name}/SOA/CM/extensions directory. If the folder structure isn't there, create each folder in turn, go into it, and then create the next one until you have the structure. Make sure you get the capitalization exactly correct as shown here.
  5. In the /resources/theme/{theme_name}/SOA/CM/extensions folder, upload metadata.json and widget_factory.json.
  6. Exit out of File Manager.

Back to top

What is the Resource Version Key and how do I find it?

UI resource files include all code-related components such as JavaScript files, templates, and stylesheets.

These types of files are cached for a long time, to improve performance, since generally the files do not change. The cache setting is one month.

For all resource files, the URL includes a dynamically-constructed unique ID, called a Resource Version Key.

If a new version of the platform resource files is uploaded, there is a new Resource Version Key. Because the URL is different, the next time the file is retrieved, the latest version replaces the older version. Therefore, a CDN, browser cache, forward proxy, etc. will need to make a new call to get the latest version. The change in the URL triggers the new call, and the updated resource is served.

The key is dynamically constructed every 10 minutes. This means that if you update a file, you won't see the change immediately. To see the update you'll need to do two things:

  1. Wait for 10 minutes to be sure the content is updated.
  2. Refresh the page so you'll see the change.

If you need to set up your platform version so that file updates are immediate, you'll need to:

  • Make sure you are not using any other components between the browser and the server, that might cache the file, such as a CDN, forward proxy, or reverse proxy.
  • Clear the browser cache and refresh the page.

The resource version key is used to construct the URL, but is not used when the request comes in. The server will always serve the latest file, independent of the version key specified in the URL. A request referencing an old version key will still get the new version in response.

Back to top

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; Default Theme/Hermosa Theme both include additional functionality, such as API and business management and Site Admin functions. Because of this, notifications for roles more applicable to Default Theme/Hermosa Theme are always sent out from the Default Theme/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}';

Back to top

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.

Back to top

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.

Back to top

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?

Back to top

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.

Site Admin management of this feature is not currently available via the user interface. You can do this in two ways:

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.

Back to top

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 the Site Admin and click the Administration quick filter (wrench icon).
  2. On the left menu, click 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.

Back to top

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.

Back to top

Site Page Customization:

How do I customize the left menu bar?

The left menu bar for all default pages in the API Platform user interface is controlled by the left_nav.json file.

This file includes definitions for all the left navigation menus in the Akana API platform user interface. Below are the top-level navigation pages:

  • home
  • api
  • apiversion
  • app
  • group
  • board (for Forum)
  • system
  • license
  • user

You can customize any of the left menus to add, change, or delete entries.

Note: once you have a customized file in place, the platform always refers to your custom file. If you upgrade to a new version of the platform that itself includes new left menu items, or includes any other changes, you won't get the benefit of the updates. In order to keep up with the latest version, you'd need to get the updated left_nav.json file from the new version, merge your changes, and upload again.

Remember that once you customize a user interface component, you have to manually manage those changes from release to release.

To customize a specific left menu bar:
  1. Download the left_nav.json file for the current version (left_nav.json for version 8.1).
  2. Identify which section of the file to edit, depending on which left menu bar you want to customize.
  3. Edit the file, making sure that you preserve the JSON structure.
  4. Upload the modified file (Administration > Config > Resources > Resources file manager > create path and upload file.
  5. Test.
Path for the file

The path for the file, which you'll probably need to create in Step 3 above, is as follows:

/resources/theme/{theme name}/SOA/CM/extensions

Note: In most cases, the value for {theme name} is default. This is the default value, generally accepted except in scenarios where there are several developer portal themes. If you're not sure of the theme name for your installation, you can easily check: in the UI go to Administration > Config and check the Theme drop-down at the top left.

An example of the correct File Manager location, with the file uploaded, is shown below.

file location for custom left nav

Default file content

A portion of the default content of the left_nav.json file for version 8.1 of the API platform is shown below. Note that this is just one small piece of the file as an example. This portion has two sections:

  • The initial example is a template showing how the file is put together.
  • The API section, which changed significantly in version 8.1.

You can also download the entire file (version 8.1).

{
  "example":[
    {
      "displayNameKey":"abc.def.ghi",
      "viewName":"used_by_parser"
    },
    {
      "displayNameKey":"abc.def.ghi",
      "viewName":"used_by_parser",
      "children":[
        {
          "displayNameKey":"abc.def.ghi",
          "viewName":"used_by_parser"
        },
        {
          "displayNameKey":"abc.def.ghi",
          "viewName":"used_by_parser"
        }
      ]
    },
    {
      "displayNameKey":"abc.def.ghi",
      "view":{
        "objectType":"this will override the parser",
        "viewName":"view name"
      }
    }
  ],
  "api":[
    {
      "displayNameKey":"resource.menu.api.details.overview",
      "viewName":"details"
    },
    {
      "displayNameKey":"resource.menu.api.details.details",
      "viewName":"specifics",
      "roleNames":[
        "Admin",
        "SiteAdmin"
      ]
    },
    {
      "displayNameKey":"resource.menu.api.implementations",
      "viewName":"implementations",
      "roleNames":[
        "Admin",
        "SiteAdmin"
      ]
    },
    {
      "displayNameKey":"resource.menu.api.board",
      "viewName":"board",
      "widgetRef":"DashboardItemsFilter"
    },
    {
      "displayNameKey":"resource.menu.api.details.monitor",
      "viewName":"monitor",
      "roleNames":[
        "Admin"
      ],
      "children":[
        {
          "displayNameKey":"resource.menu.api.details.monitor.overview",
          "viewName":"monitor"
        },
        {
          "displayNameKey":"resource.menu.api.details.monitor.charts",
          "viewName":"charts"
        },
        {
          "displayNameKey":"resource.menu.api.details.monitor.logs",
          "viewName":"logs"
        },
        {
          "displayNameKey":"resource.menu.api.details.monitor.licenses",
          "viewName":"licenses"
        }
      ]
    },
    {
      "displayNameKey":"resource.menu.api.details.documents",
      "viewName":"documents",
      "widgetRef":"DocTOC"
    },
    {
      "displayNameKey":"resource.menu.api.testclient",
      "viewName":"testclient"
    },
    {
      "displayNameKey":"resource.menu.api.details.legals",
      "viewName":"legal"
    },
    {
      "displayNameKey":"resource.menu.api.visibility",
      "viewName":"apilicense",
      "roleNames":[
        "Admin",
        "SiteAdmin"
      ],
      "postRenderer":"postRendererForAPIMenuVisibilityTab",
      "children":[
        {
          "displayNameKey":"resource.menu.api.groupaccess",
          "viewName":"groupaccess"
        }
      ]
    },
    {
      "displayNameKey":"resource.menu.api.admins",
      "viewName":"admins",
      "roleNames":[
        "Admin",
        "SiteAdmin"
      ]
    },
    {
      "displayNameKey":"resource.menu.api.connections",
      "viewName":"connections",
      "roleNames":[
        "Admin"
      ]
    },
    {
      "displayNameKey":"resource.menu.api.followers",
      "viewName":"followers",
      "roleNames":[
        "Admin"
      ]
    }
  ]
}
Customization example

Let's say that on the API menu you wanted to extend the Analytics menu item to include an additional sub-item; in addition to Overview, Charts, Logs, and Licenses, you want to add a link to AlertSite.

Step 1: find applicable section in default file

First, in the left_nav.json file, find the api section and look for the Monitor section (the name in the code for the Analytics menu), shown below.

"displayNameKey": "resource.menu.api.details.monitor",
"viewName": "monitor,
"roleNames": ["Admin"],
"children": [
  {
    "displayNameKey": "resource.menu.api.details.monitor.overview",
    "viewName": "monitor"
  }, {
    "displayNameKey": "resource.menu.api.details.monitor.charts",
    "viewName": "charts"
  }, {
    "displayNameKey": "resource.menu.api.details.monitor.logs",
    "viewName": "logs"
  }, {
    "displayNameKey": "resource.menu.api.details.monitor.licenses",
    "viewName": "licenses"
  }
]

Step 2: customize

Now, add the new section. It might look something like the below (last subsection is new):

"displayNameKey": "resource.menu.api.details.monitor",
"viewName": "monitor,
"roleNames": ["Admin"],
"children": [
  {
    "displayNameKey": "resource.menu.api.details.monitor.overview",
    "viewName": "monitor"
  }, {
    "displayNameKey": "resource.menu.api.details.monitor.charts",
    "viewName": "charts"
  }, {
    "displayNameKey": "resource.menu.api.details.monitor.logs",
    "viewName": "logs"
  }, {
    "displayNameKey": "resource.menu.api.details.monitor.licenses",
    "viewName": "licenses"
  }, {
    "displayNameKey": "resource.menu.api.details.monitor.alertsite",
    "viewName": "alertsite"
  }
]

Back to top

How do I customize the Support page?

In the developer portal user interface, the help link to the right of the top navigation bar leads to the Support page. Here, you can add content that's specific to your version of the developer portal. You can also include a link to the main help page to the developer portal (http://docs.akana.com/cm/learning.html).

The URL for the Support page is:

{hostname}/#/{tenantid}/home/support
To customize the Support page for the developer portal
  1. Outside the platform, prepare an HTML file for the Support page, and name it index.htm.
  2. Log in as the Site Admin.
  3. Go to Administration > Config > Resources.
  4. In the Content section, click File Manager. The File Manager window opens at the content folder.
  5. Click into the home directory and then the support directory. You'll see the existing index.htm file in the folder.
  6. Optional: If you want to, you can rename the existing file so that you'd be able to restore it if needed. Click the Rename icon and change the name of the file, as shown below.

    Renaming a file in File Explorer

  7. Click Upload a File, navigate to the location of your new file, and upload it.
  8. Click outside the File Manager.
  9. Test:
    • Navigate to the Support page.
    • If you don't immediately see the new page, clear the cache and refresh the page.
    • Verify that the page looks as expected and that any links work.

Back to top

How do I customize fonts in the developer portal?

You can customize any of the fonts used in the developer portal user interface. You'll need to complete the high-level steps below.

To customize fonts in the developer portal: high-level steps
  1. Identify the specific CSS rules you want to customize, using developer tools in the user interface.
  2. Determine the fonts you want to use and whether you want to reference or upload the fonts.
  3. Download the platform style file. See How do I download the platform CSS?
  4. Update the custom.less file to use the new fonts, in one of two ways:
  5. Import the revised CSS. See How do I upload the custom.less file after I've updated it?
  6. Refresh your browser and review the results.

The steps are essentially the same for Default Theme/Hermosa Theme and Simple Developer theme, with the exception of the file locations for uploading the revised files. For information on the file locations for customization of Hermosa theme, see Where do I store customization files for Hermosa theme?

Back to top

How do I customize fonts by referencing an external font?

Note: this topic only covers the steps for referencing the external font in the custom.less file. For the full high-level font customization procedure, see How do I customize fonts in the developer portal? above.

When you reference an external font, you have to add code in the downloaded custom.less file to do two things:

  1. Reference the external font file using an @import statement.
  2. Indicate which styles will use the new font.

Note: It's a good idea to keep a backup copy of the original file and any customization versions that you implement, as a manual version control. If you're not happy with the results when you upload the new customizations, you can revert to the previous version before troubleshooting.

Reference the external font file using an @import statement

Locate your custom.less file and reference the custom font by providing the import URL, as shown below. This example references one of Google's cloud-hosted fonts, "Nixie One." Add this statement at the top of the file:

@import url(https://fonts.googleapis.com/css?family=Nixie+One);
Indicate which styles will use the new font

Modify the CSS rules in the custom.less file to use the new font. The examples below illustrate modifying the font in two different ways:

  1. Replacing all platform styles with the new font.
  2. Using the new font on specific elements.

Example 1: Replacing all platform styles with the new font, including headings, menus, error messages, and all other copy elements in the developer portal.

@main-font: "Nixie One", Arial, Helvetica, sans-serif;

Example 2: Using the new font on all Header elements and left navigation links.

.headerPanel {
  font-family: 'Nixie One', cursive;
}
.soa-ui-cm-leftnav-item {
  font-family: 'Nixie One', cursive;
}

When you've modified the file, the next step is to upload the revised file and review the results. For the full high-level font customization procedure, see To customize fonts in the developer portal: high-level steps above.

Back to top

How do I customize fonts by uploading font files?

Note: this topic only covers the steps for uploading the fonts and referencing the uploaded fonts in the custom.less file. For the full high-level font customization procedure, see How do I customize fonts in the developer portal? above.

When you customize fonts by uploading font files, you have to do three things:

  1. Upload the font files to the correct location.
  2. Update the custom.less file to reference the new fonts in the location you uploaded them to, using @font-face.
  3. Add or modify CSS rules to use the new font.
Upload the font files to the correct location

The platform looks for the font files in a location relative to the supplement.css or style.css files, which are stored in the /resources/theme/{theme_name}/style folder.

It's important to upload the files in the right place, and then use the correct relative path when referencing the font files in the custom.less file. The examples below use a font named advent-pro-v4-latin, and the fonts are stored in a /fonts/advent-pro-v4-latin subfolder. To do this you'd need to complete these steps:

  1. Prepare the font ZIP file externally. See Prepare the fonts ZIP file below.
  2. In the platform, go to Administration > Config > Resources > Resources File Manager.
  3. In the File Manager, click down to the /theme/{theme_name}/style folder.
  4. Create a fonts folder and navigate down into the folder.
  5. Choose Upload a ZIP Archive to upload the fonts.zip file that you prepared in Step 1. The fonts are uploaded and are immediately available.
  6. Next, update the custom.less file to use the new fonts. See Update the custom.less file to reference the new fonts in the location you uploaded them to, using @font-face below.
Prepare the fonts ZIP file

You can create folders and upload files individually, but you can also upload everything in one ZIP file, which is quicker.

For the example above, let's say that you are using one custom font, advent-pro-v4-latin, which includes five individual files for variations of the font.

On your local drive, create a folder that uses the font name, advent-pro-v4-latin, and download the files inside it.

Then, create a ZIP file named fonts.zip and copy the advent-pro-v4-latin folder and its contents into it. Then, you can upload the fonts.zip file in step 5 above.

Update the custom.less file to reference the new fonts in the location you uploaded them to, using @font-face

The next step is to use the css attribute of @font-face to use the new font. Use the example below as a guide.

In this example, you can see that the paths reference the /fonts/advent-pro-v4-latin font files that you uploaded in the previous step. Whatever fonts you are using, make sure the paths are correct for the name and location of your own font files.

Font locations should always be loaded, and referenced, as relative to the /resources/theme/{theme_name}/style folder.

@font-face {
  font-family: 'Advent Pro';
  font-style: normal;
  font-weight: 400;
  src: url('./fonts/advent-pro-v4-latin-regular.eot'); /* IE9 Compat Modes */
  src: local('Advent Pro Regular'), local('AdventPro-Regular'),
  url('./fonts/advent-pro-v4-latin/advent-pro-v4-latin-regular.eot?#iefix') format('embedded-opentype'), /* IE6-IE8 */
  url('./fonts/advent-pro-v4-latin/advent-pro-v4-latin-regular.woff2') format('woff2'), /* Super Modern Browsers */
  url('./fonts/advent-pro-v4-latin/advent-pro-v4-latin-regular.woff') format('woff'), /* Modern Browsers */
  url('./fonts/advent-pro-v4-latin/advent-pro-v4-latin-regular.ttf') format('truetype'), /* Safari, Android, iOS */
  url('./fonts/advent-pro-v4-latin/advent-pro-v4-latin-regular.svg#AdventPro') format('svg'); /* Legacy iOS */
}
Add or modify CSS rules to use the new font

The final preparation step is to update the custom.less file so that specific CSS rules use the new font.

Tip: If you're not sure which rules to change, use the browser developer tools to inspect the elements so you can identify the CSS rule names. There are also comments in the custom.less file to indicate how the various elements are used.

The example below uses the new font on all Header elements and left navigation links.

.headerPanel{
  font-family: 'Advent Pro', sans-serif;
}
.soa-ui-cm-leftnav-item{
  font-family: 'Advent Pro', sans-serif;
}

The next step is to upload the revised file to the developer portal and see the results: see How do I upload the custom.less file after I've updated it?

Custom fonts: Additional information

Many fonts are available, free or for purchase, online. Below are a couple of suggestions for free fonts:

Back to top

How do I customize so that users are taken to a different page after login?

You can customize the API Platform user interface so that after logging in, rather than being taken to the Dashboard which is the usual behavior, users are taken to a different page that you specify.

To set this up, you'll need to perform these high-level tasks (see procedures below):

  1. Determine the page you want users to be taken to
  2. Set up a custom_en-us.json file
  3. Upload the custom_en-us.json file to the developer portal
  4. Test

1: Determine the page you want users to be taken to

You might decide that you want users to be taken to the My Apps page, or the My APIs page, or the Support page.

Decide which page you want users to be taken to, and note the URL.

The example below takes users to the My Apps page after login.

2: Set up a custom_en-us.json file

You'll need to create a custom_en-us.json file; if this file exists, it overrides platform defaults.

In this file, you can set up some custom code so that users are taken to a different page after login, rather than the default /home/landing page.

As an example, let's say you want users to be directed to the My Apps page. The example below modifies the platform to direct users to this page after login.

{
"errors": {},
"labels":
{ "customLoginPage": "/home/myapps" }

,
"messages": {},
"validator": {
"errors": {}
}
}

Save the file, which you'll upload to the platform in Step 3.

Platform location for this file: /resources/theme/{theme_name}/locales/custom_en-us.json.

Additional examples

Some other examples of how the login page entry could look are shown below.

//"labels": { },    -> No custom login
//"labels": {"customLoginPage": "/home/customdashboard" }, ->  Login takes user to a custom page (required adding new page)
//"labels": {"customLoginPage": "/home/landing" }, ->  Login takes user to landing page
//"labels": {"customLoginPage": "/home/apis" }, ->  Login takes user to My APIs

3: Upload the custom_en-us.json file to the developer portal

In the developer portal, go to Administration > Config > Resources > Resources File Manager.

Make sure you know the name of the theme you're customizing. If your platform version doesn't have customized theme names, the main developer portal theme name is default. If you're not sure of the theme name, see How can I determine the theme name?

Upload the custom_en-us.json file to /resources/theme/{theme_name}/locales.

Note: If you haven't customized before, you'll have to create the theme folder, change to that folder, create the default (or other theme name) folder, change to that folder, create the locales folder, change to that folder, and then upload the custom_en-us.json file.

4: Test

Once you've uploaded the files, it's time to test.

To test the custom login
  1. Log out.
  2. Clear the browser cache.
  3. Refresh the browser page.
  4. Log in. Upon login, you are taken to the new page.

Back to top

Cookies:

Does the developer portal use cookies?

Yes. The 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 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 developer portal user interface very briefly as a way to pass information from one page to another. For more information, see Does the developer portal use any cookies other than the session and CSRF cookies? below.

Back to top

Will the 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 developer portal.

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

Back to top

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.

Back to top

Does the developer portal store persistent cookies in the browser?

By default, both the cookies that the 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.

Back to top

How can I set up the developer portal so that the cookies are not persistent?

If you want to modify the cookie behavior so that cookies are removed when the user closes the browser, you can modify a setting to do that. The setting, Support Persistent Sessions, is in Administration > Settings > Login; 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 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.

Back to top

Does the developer portal send cookies to other sites?

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

Back to top

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

The main cookies that the developer portal uses are the session and CSRF cookies, as covered in Does the 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 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.

Back to top