

Maintaining Logins and Passwords

The following section explains how you can change your credentials, recover your password, and customize your login.

Change the super admin credentials

Follow the instructions below to change the default admin password:

1. Navigate to the <API-M_HOME>/repository/conf/deployment.toml file and change the user credentials as shown below.

   [super_admin]
   username = "your-name"
   password = "your-password"

Note

Do you have any special characters in username or passwords?

• The above credentials are applied to relevant XML configuration files such as user-mgt.xml.

  If you specify passwords inside XML files, you have to be mindful when defining special characters in the user names and passwords. Based on the XML specification (https://www.w3.org/TR/xml/#sec-cdata-sect/), some special characters can disrupt the configuration. For example, the ampersand character (&) must not appear in the literal form in XML files. It can cause a Java Null Pointer exception. You must wrap it with CDATA as shown below or remove the character:

• Do not use £ character in the admin password as it can cause a buffer overflow exception. This happens due to a limitation where a £ character has two values as its byte representation.

• The above credentials are applied to the jndi.properties file.

  • It is not possible to use the @ { } symbols in the username or password.
  • It is also not possible to use the percentage (%) sign in the password. When building the connection URL, the URL with credentials is parsed. This parsing exception happens because the percentage (%) sign acts as the escape character in URL parsing. If the percentage (%) sign in the connection string is required, use the respective encoding character for the percentage (%) sign in the connection string. For example, if you need to pass adm%in as the password, then the % symbol should be encoded with its respective URL encoding character. Therefore, you have to send it as adm%25in. For a list of possible URL parsing patterns, see URL encoding reference. Add the following configuration.

Therefore, if you have special characters, add the following configurations. If you have special characters, be mindful to wrap values with CDATA tag in super_admin configurations and to encode values in the apim.throttling.jms configurations.

[super_admin]
username = "your-name"
password = "<![CDATA[your-password]]>" 

[apim.throttling.jms]
username = "your-name"
password = "your-encoded-password"        

sample deployment.toml configs

[super_admin]
username = "foo_admin"
password = "<![CDATA[~^&*#`43d:3;]]>"

[apim.throttling.jms]
username = "foo_admin"
password = "~%5E%26*%23%6043d%3A3%3B"

Note

Note that the above password is written to the primary user store when the server starts for the first time. Thereafter, the password will be validated from the primary user store and not from the configuration file. Therefore, if you need to change the admin password stored in the user store, you cannot simply change the credentials as above. To change the super admin password, you must use the Change Password option from the management console.

To change the password from Management Console (https://localhost:9443/carbon), follow the steps in Changing a Password corresponding to API Manager.

Recover a password

Use the <API-M_HOME>/bin/chpasswd.sh script.

Note

If you encountered an error similar to ant: command not found, Please install Apache Ant before running the above script.

Setup an e-mail login

1. Follow the steps from Step 1 to Step 5 given in Email Authentication in the WSO2 IS documentation.

2. Define the complete username with the tenant domain under the API-M throttling related sections in the <API-M_HOME>/repository/conf/deployment.toml file.

   If you are in the super tenant mode, the username should have the following format:

   <email>@carbon.super

   [tenant_mgt]
   enable_email_domain= true
   
   [apim.throttling]
   username = "$ref{super_admin.username}@carbon.super"
   
   [apim.throttling.policy_deploy]
   username = "$ref{super_admin.username}@carbon.super"
   
   [apim.throttling.jms]
   username="admin!wso2.com!carbon.super"
   password = "$ref{super_admin.password}"

   3. Optionally, follow the instructions below if you have enabled regular expression to validate usernames in the step 1.

   You need to manually create a default user with a valid email username instead of the default apim_reserved_user user for each tenant.

   This user is an internal user created to handle cross tenant subscription validations. Therefore, if you have enabled cross tenant subscription validation feature you need to configure the above created username in the deployment.toml for the default_reserved_username field, instead of the apim_reserved_user default user as shown below.

   [user_store]
   type = "database_unique_id"
   username_java_regex = '^[a-zA-Z0-9.-]+@[a-zA-Z0-9.-]+.[a-zA-Z]{2,4}'
   username_java_script_regex = '^[a-zA-Z0-9.-]+@[a-zA-Z0-9.-]+.[a-zA-Z]{2,4}$'
   
   [apim.devportal]  
   enable_cross_tenant_subscriptions = true
   default_reserved_username = "apim_reserved_user"

   Element	Description
   [tenant_mgt] enable_email_domain	This property specifies whether the email authentication is activated or not.
   [apim.throttling] username	When the email login feature is enabled, the super tenant will be attached with the username. This property facilitates the latter mentioned requirement.
   [apim.throttling.policy_deploy] username	Specify the username required to deploy throttling policies.
   [apim.throttling.jms] username	Specify the username in JMS Connection URL. note The "@" character is a reserved character in the WSO2 messaging component. Therefore, when specifying the username in JMS Connection URL, under apim.throttling.jms.username section in the <API-M_HOME>/repository/conf/deployment.toml file, "@" characters should be replaced by "!" character. An example is shown below. [apim.throttling.jms] username="admin!wso2.com!carbon.super"

3. Restart the server.

sample deployment.toml configs

[tenant_mgt]
enable_email_domain= true

[super_admin]
username = "[email protected]"
password = "admin"
create_admin_account = true

[apim.throttling]
username = "[email protected]@carbon.super"

[apim.throttling.jms]
username = "admin!wso2.com!carbon.super"

[user_store]
type = "database_unique_id"
username_java_regex = '^[a-zA-Z0-9.-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,4}'
username_java_script_regex = '^[a-zA-Z0-9.-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,4}$'

[apim.devportal]  
enable_cross_tenant_subscriptions = true
default_reserved_username = "[email protected]"

Developer Portal

Setup a social media login

You can auto-provision users based on a social network login by integrating the API Manager with WSO2 Identity Server. For more information, see Log in to the API Developer Portal using Social Media.

Note

Note that auto-provision users based on a social network login are not supported in a multi-tenant environment.

Info

In a multi-tenant environment, the system cannot identify the tenant domain in the login request that comes to the API Manager's Publisher/Developer Portal. Therefore, the service provider is registered as a SaaS application within the super tenant's space. Configuring user provisioning is part of creating the service provider. In order to authenticate the user through a third-party identity provider such as social network login, you must enable identity federation. As the service provider is created in the super tenant's space, the provisioned user is also created within the super tenant's space. As a result, it is not possible to provision the user in the tenant's space.

Follow the instructions below to overcome the latter mentioned limitation:

1. Write a custom authenticator to retrieve the tenant domain of the user.

   For information on writing a custom authenticator, see Creating Custom Authenticators in the WSO2 IS documentation.

2. Write a custom login page where the user can enter the tenant domain, which is then added to the authenticator context.

   For information on writing a custom login page, see Customizing Login Pages in the WSO2 IS documentation.

3. Write a custom provisioning handler to provision the user in the tenant domain that is maintained in the context.

Top