Administration

Overview

This section explains the options available to configure the Developer Portal settings. They include:

• SMTP configuration settings
• Password policy configuration
• User account and account security settings
• Email notification templates
• Events notification to external systems using webhooks
• Developer Portal URL configuration
• License management
• Payment gateway configuration

How to configure Custom Domains?

A custom domain is a unique name that identifies your website. There are scenarios where you do not want to expose the default domain provided by Developer Portal. In such cases, you can customize the default tenant URL or domain and access the tenant using your own domain.

Use custom domains if you want to make your application accessible on your own domain. Custom domains direct requests to your own URL.

You can request for a custom domain name for your tenant. For example, if your company domain is abc.com, you can have the domain name as https://subdomain.abc.com. Contact Software AG Global Support for details on how to enable and configure the custom domain capability.

Steps to configure custom domains:

1. Determine the number of domains to be configured for your account and the list of custom domains.
   The domain names are owned by you.

2. Decide the SSL certificate required, which depends on whether you want to protect a single domain, multiple subdomains of a domain, or multiple domain names.

3. Share the number of domains to be configured for your account and the list of custom domains with Software AG.

4. Obtain the SSL certificates from a Certificate Authority (CA) and determine the number and type of domains you want to be protected by the certificates.

5. Send the SSL certificates and Certificate Key to Software AG in base64 format to configure the certificates on the custom domain load balancer.

6. Software AG sends you the CNAME in return.
   Using the CNAME, configure your DNS to point to the custom domain load balancer.

7. After the configuration is completed, start using the custom domain to access webMethods.io API Gateway.

Checks for existing assets after configuring custom domains

• External end points change after the custom domain is configured, so you have to inform your partners about the new domain.

• Verify all assets that expose end point URLs, for example, REST APIs, SOAP APIs, Services over HTTP, webhooks and so on.

• Few assets, for example, SOAP APIs and REST APIs may not work after the custom domain change as the endpoints change after the custom domain is configured, so you have to inform your customers to update the endpoints.

Allowed IP Addresses

Overview

Developer Portal connects with most third-party services easily and instantly. However, in some cases, you may have to connect to your servers from specific IP addresses, and access resources that lie behind a protective firewall. This can be achieved in Developer Portal. SoftwareAG provides a set of static IP addresses that you have to allow in your firewall. This allows Developer Portal to make connections to your servers and run the required services successfully.

Software AG Cloud products are available in several geographical regions, operated by different infrastructure providers. Go to the Software AG Cloud Regions website for information on the available products and also the underlying infrastructure provider in each region.

Currently, Developer Portal is available on Amazon Web Services (AWS) and Microsoft Azure. Based on the vendor and the associated region selected by you at the time of creating your tenant, you need to allow relevant IPs to establish the connectivity. Once you add the allowed IP addresses available on the Software AG Cloud Regions page, you should be able to connect to your resources from Developer Portal services. If not, contact Software AG Global Support with the required details.

Tenant URL and Software AG Cloud Region

The following table helps you to identify the cloud region based on a your tenant URL. Once you identify your cloud region, go to the Software AG Cloud Regions page for information on the allowed IP addresses.

How do I configure SMTP settings to send emails?

Developer Portal sends notifications over emails to its users as part of various functionalities such as user registration, application request, and so on. To enable Developer Portal to send email notifications, you have to register your SMTP server and set the sender’s email address.

This use case starts when you want to configure SMTP settings and ends when you have completed the configuration.

To configure SMTP settings

1. Click the menu options icon from the title bar and click Administration.

2. Click SMTP.

3. Provide the following details:

   Field	Description
   Host name	Host name or IP address of the SMTP server.
   Port	Port number used by the SMTP server.
   Sender address	Email address that must appear as sender address for all emails. This must be a valid email address.

4. Turn Use SSL on to enable SSL.

5. If you enable the SSL mode, perform the following:

   • Select a value from the SSL mode field that specifies the method to use for a secured connection.
     

     Options available are:
     

     • STARTTLS. Transforms a connection that was initially untrusted into an encrypted connection without requiring a specific port to secure communication.
     • SSL. Establishes a trusted connection with a dedicated port.
   
   
   • In the Connection timeout field, provide the duration, in milliseconds, after which the attempt to connect to the SMTP server is cancelled.
   
   

6. Turn Use authentication on to use authentication to the SMTP server. Provide the username and password used for authentication in the corresponding fields.

7. Click Save.
   Your changes are saved.

How do I configure password policy?

Password policy determines the conditions to be imposed on passwords specified by users.

This use case starts when you want to configure a password policy and ends when you have completed the configuration.

To configure password policy

1. Click the menu options icon from the title bar and click Administration.

2. Click Password policy from the left pane.

3. In the General tab, provide the required values in the following fields:

   If the password specified by a user does not satisfy the requirements specified in this section, the password will not be accepted.

   Fields	Description
   Minimum length	Select the minimum length of the password.
   Maximum length	Select the maximum length of the password.
   Minimum number of lowercase letters	Select the minimum number of lowercase characters that must be provided.
   Allow special characters	Select whether special characters are allowed.
   Minimum number of special characters	Select the minimum number of special characters that must be provided.
   Special characters	Provide the special characters that are allowed.
   Allow uppercase letters	Select whether uppercase characters are allowed.
   Minimum number of uppercase letters	Select the minimum number of uppercase characters that must be provided.
   Allow numbers	Select whether numbers are allowed.
   Minimum number of numbers	Select the minimum number of digits that must be provided.
   Allow commonly used password	Select whether commonly used passwords can be provided.
   Common password (s)	Provide the list of common passwords that must not be allowed.
   Allow sequential characters	Select whether sequential characters are allowed.
   Minimum sequential characters	Select the minimum number of sequential characters that must be provided.
   Allow repetitive characters	Select whether redundant characters are allowed.
   Minimum repetitive characters	Select the minimum number of repetitive characters that must be provided.
   Allow context-related password	Select whether context-related passwords are allowed.
   Minimum context-related characters	Select the minimum number of context-related characters that must be provided.

4. In the Advanced tab, enable the following based on your requirements:

   Field	Description
   Force change before first login	Turn on to enforce the password change during their first sign in.
   Force change after reset	Turn on to enforce the password change when user reset the password and new password was shared to user over email.
   Force different password	Turn on to enforce user for a different password if the user provides a password that was already in use.
   Activate reset confirmation	Turn on to send a confirmation email for password reset. If turned on, a link to reset password is sent. Else, the reset password is sent.
   Activate password expiry	Turn on to specify the number of days after which a password expires. In the Password lifetime (in days) field, specify the number of days a password is valid.

5. Click Save.
   Your configurations are saved.

The set of password rules enabled here enhances the user account security by mandating users to employ strong passwords and use them properly.

Security Settings

You can configure the following security settings:

• Account lockout settings. For more information, see How do I configure user account lockout settings?
• Multi-factor authentication settings. For more information, see How do I configure multi-factor authentication settings?
• Advanced settings. For more information, see How do I configure advanced security settings?

How do I configure user account lockout settings?

This use case explains the steps to configure the number of times that a user can attempt to sign in with an incorrect password.

Multiple attempts of users providing passwords to access their accounts would also mean that the user does not have the required authentication. Hence, to ensure safety, you can configure the number of attempts that a user can make to provide their password to log on to Developer Portal.

This use case starts when you want to configure account lockout settings and ends when you have completed the configuration.

To configure account lockout settings

1. Click the menu options icon from the title bar and click Administration.

2. Click Security.

3. In the Account lockout tab, enable Lock users after failed login attempts to specify whether a user account must be temporarily locked when there is certain number of failed logins.

4. Provide the following details:

   Field	Description
   Attempt limit	Number of failed log in attempts that are allowed before user account is locked.
   Lockout duration (in seconds)	Number of seconds for which the user account remains locked. If the Lock users after failed login attempts setting is enabled and if there are too many failed sign in attempts, then the user account is locked for the specified number of seconds.
   Lock counter duration (in seconds)	Number of seconds after which users can try to sign in after a failed sign in attempts is reset. Users must retry to sign in to Developer Portal after the duration specified in this field. For example, if you have entered 1800 in this field, users can retry to sign in after 30 minutes of their failed attempt.

5. Click Save.
   Your configurations are saved.

Next steps:

• The user accounts get locked if they exceed the number of attempts that you have configured.

How do I configure multi-factor authentication settings?

Multi-factor authentication enforces users to pass through an extra step, in addition to password entry, to sign in to their account. The additional step involves the entry of an OTP received over the registered email of users.

This use case starts when you want to configure multi-factor authentication and ends when you completed the configuration.

To configure multi-factor authentication settings

1. Click the menu options icon from the title bar and click Administration.

2. Click Security.

3. In the Multi-factor authentication tab, enable Use multi-factor authentication to specify whether multi-factor authentication is required.

4. Provide the values:

   Field	Description
   Clock skew intervals	Value based on which the validity of an OTP is calculated. An OTP is valid for the previous and current interval based on the specified value. For example, if you provide 1 in this field, the generated OTP will be valid for the 30 seconds prior to receipt of the OTP and 30 seconds from the receipt of the OTP.
   Excluded users	List of user login names, separate by commas, for whom the multi-factor authentication is not required. For example, administrator.

5. Click Save.
   Your changes are saved.

Next steps:

• An OTP is sent to the user who tries to sign in through their registered email address and they can provide the OTP to sign in to the application. This step ensures that only the authenticated users have access to the application.
• Administrators can send an OTP secret token to users by clicking the generate OTP secret token icon from the Manage users page.



If multi-factor authentication is enabled, the secret token is sent to the email of users who sign up to the application. If there are existing who onboarded when the multi-factor authentication was not enabled, you can send them the OTP secret token generator by clicking the generate OTP secret token icon.

How do I configure advanced security settings?

This use case explains the steps to enable logs related to user authentication transactions, generate user statistics, and configure OTP validity. You can view the logged events using the Events log screen or the using the Events REST API. For information on viewing from the Events log screen, see How do I view audit log events and for information on the Events REST API, see Viewing Developer Portal Audit Events.

This use case starts when you want to specify advanced security settings and ends when you have completed the configuration.

To configure advanced security settings

1. Click the menu options icon from the title bar and click Administration.

2. Click Security from the left pane and click Advanced.

3. From the following list, enable the list of data that you want to log:

   Field	Description
   Log authentication	Enables the logging of user authentication events.
   Log changes to configuration	Enables the logging of changes made to configurations.
   Log changes to licenses/privileges	Enables the logging of changes made to licenses and privileges.
   Log changes to users/user groups	Enables the logging of changes made to users and user group details.
   Generate user statistics	Generate the user statistics data.
   User statistics in backup	Includes user statistics data in the backup files. This data is included if you select the User module when you create the backup. For information on creating backup, see How do I take a backup?
   Use OTPs	Enables OTP generation as a part of user multi-factor authentication.

4. Optional. If you have enabled the Use OTPs setting, provide the number of seconds that an OTP must be valid in the OTP Lifetime field.

5. Click Save.
   Your changes are saved.

The logs enabled using the settings are used to monitor activities related to user accounts.

How do I configure user session settings?

You can configure the user session settings from the Users page of the Administration section.

This use case begins when you want to configure user session settings and ends when you have saved the configuration.

To configure user session settings

1. Click the menu options icon from the title bar and click Administration.

2. Select Users.

3. Turn Email address required on to specify that the entry of users’ email address is mandatory during sign up and sign in.

4. Turn Validate email address on to specify that the email address is entered by users must be validated.

   The email address validation is performed by sending an email to the registered email address.

5. Specify required values in the following fields:

   Field	Description
   Maximum length of login name	Provide the maximum number of characters allowed for user login name.
   Maximum image size (in bytes)	Provide the maximum size of user image that can be uploaded.
   Initial session duration (in minutes)	Provide the duration, in minutes, of the initial session of users.
   Maximum session duration (in minutes)	Provide the maximum duration of user sessions.

6. Select the Default group name from the list.

   New users are assigned to the selected group by default.

How do I configure email notification templates?

Developer Portal sends email notifications to users on various events such as email verification during sign up, OTP email to users, or application approval notification and so on. The default email templates are used for such notifications. You can edit these notification messages if required.

This use case starts when you want to edit an email template and ends when you have completed the edit.

To configure email notification templates

1. Click the menu options icon from the title bar and click Administration.

2. Click Email templates from the left pane.

3. Click the edit icon next to a template.

4. Make the required changes in the subject and body of the email notification.

5. Use predefined variables to formulate messages in a meaningful way.

   To view the available variables, type $. The list of available variables appears.

   

   Click the required option to insert it in the email template.

6. Click Save.

   Your changes are saved.

The email notification templates are used for sending email notifications.

How do I configure webhooks to notify events to an external system?

Webhooks are used by applications to provide real-time information to other applications.

You can create webhooks in Developer Portal to notify the specified events to an external application URL. For example, an API is published, or an application is shared. For the list of events that you can notify, see List of events.

This use case starts when you want to configure a webhook and ends when you have configured one.

To configure webhooks

1. Click the menu options icon from the title bar and click Administration.

2. Click Webhooks from the left pane.

3. Provide the URL of the destination system to which the notification has to be sent.

4. From the Type list, select the type of destination that you want to send notification:

   • System. To notify an external system endpoint.
   • Provider. To notify a provider endpoint.
   
   

5. Select one of the following from the Security field:

   • Basic. Select this option if the destination requires basic authentication, and provide the corresponding user name and password.
   • None. Select this option if the destination requires no authentication.
   
   

6. Select the required event type.

   You can select more than one event type.

7. Click Save.

   Your changes are saved.

The webhook is added. Notifications for the selected events are triggered and sent to the specified endpoint.

List of events

The following table lists the events for which you can create webbooks:

How do I configure webhooks to notify user sign up and application requests to an external approval system?

Webhooks can be used to send the user sign up requests or new application registration requests to an external approval systems.

This use case starts when you want to configure an external approval onboarding strategy and ends when you have completed the configuration.

To configure webhooks

1. Click the menu options icon from the title bar and click Administration.

2. Click Webhooks from the left pane.

3. Provide the external approval system endpoint URL in the field.

4. Select System from the Type list.

5. Provide the required Security preference. Available options are:

   • Basic. Indicates the basic credentials are required. Provide your user name and password.
   • None. Indicates that no authentication is required.
   
   

6. Select EXTERNAL_VERIFICATION from the Event type list.

7. Click Save.

   Your changes are saved.

The webhook is added. Notifications for the selected events are triggered and sent to the specified endpoint.

Next steps - Configuring external approval for user sign-up requests:

• When there is a user sign-up request, the user details are sent to the configured URL.
  

  Sample request
  

  	
  {
  "created" : "2022-02-09T13:37+0000",
  "documentType" : "EVENTS",
  "parameters" : {
  "details" : {
  "email" : "johnsmith@gmail.com",
  },
  "source" : "ExternalVerificationExecutor",
  "link_id" : "8688ae09-243b-4589-bea1-48cb53d9e702"
  },
  "type" : "EXTERNAL_VERIFICATION_EVENT"
  }
  

  The parameters.details section in the payload has the newly signed up user information. Approvers check this data to approve or reject a sign-up request. By default, the Sign up page displays the Email and Password fields. If you add other fields, the data entered by users is included in the parameters.details section of the payload.

How do I specify the Developer Portal URL for reference from external systems?

The Load balancer URL field allows you to provide the Developer Portal URL. The URL provided in this field is used in the emails sent from Developer Portal. Users who receive those emails can click the link to access Developer Portal.

The Load Balancer URL should be configured to receive email notifications with proper resolvable URL.

This use case starts when you want to modify the Developer Portal URL and ends when you have saved the configuration.

To specify the Developer Portal URL

1. Click the menu options icon from the title bar and click Administration.

2. Click General from the left pane.

3. In the Load balancer URL field, specify the Developer Portal URL with the corresponding system name or IP address.

4. Click Save.
   

   Your configurations are saved.

The specified URL is provided to external systems for directing from anywhere to Developer Portal.

How do I update the Developer Portal license?

This use case explains the steps to upload a license file if you are using an outdated one.

This use case starts when you want to update your existing license and end when you have successfully uploaded the same.

To update the license file

1. Click the menu options icon from the title bar and click Administration.

2. Click Licenses from the left pane.

3. Click Browse file and select the required license file.

4. Click Save.

   Your license is updated.

How do I configure the default group and community for a new user?

This use case starts when you want to specify the group and community that must be assigned to a new user by default and ends when you have completed the configuration.

To specify the default group and community

1. Click the menu options icon from the title bar and click Administration.

2. Click Onboarding strategy.

3. Select the default community from the Default community for onboarding users list.

   You can select more than one community.

4. Click Save.

   Your changes are saved.

5. Click Users

6. Select the default group from the Default group name from the list.

7. Click Save.

   Your changes are saved. New users are assigned to the default team and community.

How do I view audit log events?

The Events log screen lists:

• Audit events. Audit log events related to various assets such as APIs, applications, packages, plans, communities, and providers. It also includes topic and comment related events.

• User events. Events that Developer Portal creates based on your settings on the Advanced tab of the Security screen. For the list of log events that you can configure, see How do I configure advanced security settings?

To view audit events

1. Click the menu options icon from the title bar and click Administration.

2. Click Events log from the left pane.

   The logged events list appears. You can filter the required events by typing the required event name in the text box.

   You can also select the type of events to view, and period for which the events must be displayed.

Data Management

Data is an integral part of Developer Portal and contains all the information about your APIs, packages, and your customized themes. Hence, it is essential to manage data efficiently. To protect any accidental loss of data, you must take regular backups of your data and save in a fail-proof repository.

Developer Portal provides you an option through the UI to create backup of your data and restore any backed up data.

The following sections explain the backup and restore processes.

How do I take a backup?

This use case starts when you want to create a backup of your data and ends when you have successfully created the backup.

Before you begin:

Ensure that you have the API Administrator privilege.

To take backup:

1. Click the menu options icon from the title bar and click Administration.

2. Click Backup and restore from the left pane.

3. Select Backup.

4. Select the Modules that you want to be included in the backup.

   Available options are:

   • Collaboration. Collaboration groups, posts and discussions related data, and comments or posts related to APIs.

   • Core. Includes the meta data information of APIs and packages, access tokens of APIs, Applications, Communities, and Providers.

   • Theme. Includes the UI customization templates.

   • User. Includes details of users, user groups, and user privileges.

   • Analytics. Includes Page views, User registrations, API lifecycle events, and run-time analytics data for APIs

5. Click Backup.

   A dialog box appears to allow you save the backup file.

6. Click Save.

   The backup data, in zipped folder format, is saved to the default downloads location of your browser.

Next steps:

• To view the list of assets saved in the backup, open the core-result.pdf file from the Core folder inside the backup folder.
  

How do I restore data from a backup file?

This use case starts when you have a backup file to be restored and ends when you have successfully restored the backup data in your environment.

Before you begin:

Ensure that you have the API Administrator privilege.

To restore from a backup:

1. Click the menu options icon from the title bar and click Administration.

2. Click Backup and restore from the left pane.

3. Select Restore.

4. Click Browse file and select the backup file that has to be restored.

5. Select the Modules that must be restored.

6. Click Restore.

   The selected data is restored in your environment.

Configuring Default Language

As an administrator, you can select a default language for Developer Portal. When a guest user accesses Developer Portal, the application appears in the default language.

Users can sign in and set a language that they prefer to view; and the application appears in the language specified by users whenever they sign in.d the same.

As an administrator, you can also provide an option to select language by adding a language switcher icon. When added, this icon appears in the landing page. For more information, see How do I add the language switcher icon?.

To configure default language

1. Click the menu options icon from the title bar and click Administration.

2. Click General.

3. Select the required language from the Default system language field.

4. Click Save.

   Your license is updated.

Configuring Personal Profile Settings

Users can specify their preferred language for Developer Portal.

When launched, the application appears in the default language configured by the administrator. Once users sign in to the application, the UI switches to the language that is configured using the steps provided in this section.

To configure personal profile settings

1. Click the menu options icon from the title bar and click Administration.

2. Click Account settings.

3. Select the required language from the Default system language field.

4. Click Save.

   The selected language is saved.

Configuring Payment Gateway

Developer Portal supports direct monetization of APIs by allowing you to configure your payment gateway account.

As an administrator, you can enable the payment gateway feature in Developer Portal and add your account details. This, in turn, enables API consumers to provide the details of their credit card from which they would make the payment for plan subscriptions that they use.

Developer Portal supports Stripe payment gateway.

This section provides details about how to configure the payment gateway to collect credit card information using the Stripe payment gateway.

Pre-requisites

For information about retrieving the above values, see https://stripe.com/docs/keys.

To configure payment gateway

1. Click the menu options icon from the title bar and click Administration.

2. Click Payment gateway.

3. Turn the Enable payment gateway slider on.

4. Provide the Publishable key and Secret key in respective fields.

5. Click Test to validate the provided values. This is an optional step.

6. Click Save.

   System validates the provided values. The payment gateway feature is enabled.

Next steps

Adding Payment Details (for consumers)

You, as an API administrator, can collect the details of API consumers’ credit cards for receiving payments for the plan subscriptions that they use.

API consumers can provide the details of their credit card that they want to use for payments in Developer Portal by following the given steps.

Pre-requisites

To add payment details of consumers

1. Click the menu options icon from the title bar and click your user name or email address to edit your profile.

2. Click Payment details.

3. Provide card details.

4. Click Add.

   The provided card details are saved.

Next steps

Click Update to modify your card details, if required.

Configuring Usage report preference settings

Users can specify the frequency that they want to receive the Application usage report. This report displays the break-up of an API within an application and first five applications and first five APIs within the application.

To configure Usage report preference settings

1. Click the menu options icon from the title bar and click your user name or email address to edit your profile.

2. Click Usage report preference.

3. Select the required frequencies.

4. Click Save.