Installing and Configuring WSO2 Identity Server

In this section:

How to:

This section describes how to install and configure WSO2 Identity Server.
Top of page
x
Procedure: How to Install WSO2 Identity Server
  1. Download the WSO2 Identity Server binary distribution from the following website:

    http://wso2.com/products/identity-server

    The WSO2 Identity Server binary is packaged as a .zip file (wso2is-4.1.0.zip).

  2. Unzip the wso2is-4.1.0.zip file to a directory on your file system.
  3. To run WSO2 Identity Server, navigate to the <WSO2_Home>\bin directory and run the wso2server.bat file.

    Note: By default, WSO2 Identity Server uses port 9999 for the JMXServerManager. This conflicts with the default console port that is used by the iSM base configuration. For a quick workaround, you can start iSM before WSO2 Identity Server, which will start the WSO2 Identity Server without JMX. For a more permanent solution, change the console port of the iSM base configuration or can change the RMIRegistryPort setting in the carbon.xml file, which is located in the <WSO2_Home>\repository\conf directory. For example:

    <RMIRegistryPort>9999</RMIRegistryPort>
  4. To stop WSO2 Identity Server, type Control-C in the command prompt window and press Enter.
  5. To open the WSO2 Identity Server console, enter the following URL in your browser: 
    https://localhost:9443/carbon/

    Note: The browser will generate a message, which indicates that the certificate is not valid. You can ignore this message and continue. In addition, the menu might not appear correctly if you are using a Microsoft Internet Explorer Version 10 browser. However, it looks better using a Google Chrome browser.

  6. Enter admin for the user name and password to log on as the default administrator account.
Top of page
x
Procedure: How to Extract and Import the SSL Certificate for WSO2 Identity Server

The Secure Sockets Layer (SSL) certificate of WSO2 Identity Server is stored in the KeyStore defined by the <KeyStore> entry in the carbon.xml file, which is located in the <WSO2_Home>\repository\conf directory. For example:

<KeyStore>
   <Location>${carbon.home}/repository/resources/security/wso2carbon.jks
   </Location>
   <Type>JKS</Type>
   <Password>wso2carbon</Password>
   <KeyAlias>wso2carbon</KeyAlias>
   <KeyPassword>wso2carbon</KeyPassword>
</KeyStore>

The default WSO2 SSL certificate is self-signed. Since there is no Certificate Authority (CA), you need that certificate itself in your TrustStore to validate it. This explains the warning message generated in the browser when accessing the console because the self-signed certificate is not in the browser trust store.

For a quick test, you can use the wso2carbon.jks KeyStore itself as a TrustStore. However, a better approach would be to extract the certificate by using the following command:

keytool -exportcert -alias wso2carbon -file wso2carbon.cert -keystore wso2carbon.jks -storetype JKS -storepass wso2carbon

Then import the certificate within an empty KeyStore or an existing TrustStore by using the following command:

keytool -importcert -trustcacerts -alias wso2carbon -file wso2carbon.cert -keystore wso2ts.jks -storetype JKS -storepass wso2password

This is the technique that was used to produce the wso2ts.jks KeyStore. For example:

iwcore/test/data/providers/keystores/wso2ts.jks

The best solution is to create a real SSL server certificate for WSO2 Identify Server and configure it in the carbon.xml file. Then you would put the CA of that certificate in our TrustStore. This is only required for production environments.
Top of page
x
Procedure: How to View WSDL Files of Web Services Implemented in WSO2 Identity Server

To view the WSDL files of web services implemented in WSO2 Identity Server, you must first instruct the server to unhide these files.

  1. Edit the carbon.xml file, which is located in the <WSO2_Home>\repository\conf directory.
  2. Change the HideAdminServiceWSDLs setting to false. For example: 
    <HideAdminServiceWSDLs>false</HideAdminServiceWSDLs>

    The description of the web services called by iSM can be viewed using the following URLs:

    https://localhost:9443/services/RemoteUserStoreManagerService?wsdl
    https://localhost:9443/services/EntitlementService?wsdl
Top of page
x
Procedure: How to Debug WSO2 Identity Server

To debug WSO2 Identity Server, you must enable log4j debugging by using one of the following options:

  1. Edit the log4j.properties file, which is located in the <WSO2_Home>\repository\conf directory.
  2. In the WSO2 Identity Server console, click Configure, select Logging, and change any required loggers to the TRACE level.

Note: Modifying these logging settings using the WSO2 Identity Server console saves the settings in the repository, but not in the log4j.properties file. The repository overrides what is defined in the log4j.properties file.
Top of page
x
Configuring WSO2 Users and Roles

If you use WSO2 Identify Server only to authorize access with XACML, then there is no need to create users and roles. You can proceed directly to Configuring XACML Policies.
x
Procedure: How to Create a New User
  1. Click Configure in the left pane, followed by Users and Roles, Users, and then Add New User.
  2. Enter a user name and password for the new user.
  3. Click Next, select the existing roles you want to assign to the new user and then click Finish.
x
Procedure: How to Create a New Role
  1. Click Configure in the left pane, followed by Users and Roles, Roles, and then Add New Role.
  2. Enter a name for the new role and then click Next.
  3. Since the WSO2 permissions are not relevant to iSM users, click Next.
  4. Enter a regular expression to display a list of users.
  5. Select which existing users belong to that role and then click Finish.
Top of page
x
Configuring XACML Policies

If you use WSO2 Identify Server only to authenticate users, then there is no need to create XACML policies.

To create an XACML policy from scratch, use the simple editor or the advanced editor.
x
Procedure: How to Create XACML Policies
  1. Click Main, followed by Administration, and then Add New Entitlement Policy.
  2. You can import an XACML policy by clicking Main, followed by Administration, and then Import New Entitlement Policy.
  3. Choose File System.
  4. Click Choose File to open the dialog that allows you to select the file.
  5. Click Upload.

    There are two policy files that can be imported for testing:

    components\iwcore\test\data\providers\xacml\policy1.txt
    components\iwcore\test\data\providers\xacml\policy2.txt
  6. Once imported, click Promote to PDP next to each policy.

    WSO2 Identity Server Version 4.1.0 accepts the XACML Version 3 schema. You will receive an error if you try to import a policy written for the XACML Version 2 schema. Ensure that you have the correct version if you experiment with a sample policy you found on the web.

    The XACML engine inside WSO2 Identity Server is called Balana.
x
Procedure: How to Debug XACML Policies

To debug an XACML policy, you must enable log4j debugging by using one of the following options:

  1. Edit the log4j.properties file, which is located in the <WSO2_Home>\repository\conf directory.
  2. In the WSO2 Identity Server console, click Configure in the left pane, select Logging.

    You want to turn on TRACE level for loggers with the word entitlement and/or the word balana in the name.

iWay Software