WSO2 Identity Server

https://github.com/wso2/product-is
Admin
WSO2 Identity Server is a powerful, modern identity and access management solution for your...
Tokens:28,236
Snippets:227
Trust Score:9.8
License:Apache-2.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### Start the conformance suite in development mode

Source: https://github.com/wso2/product-is/blob/master/oidc-conformance-tests/conformance-suite-setup-guidelines.md

Starts the conformance suite using Docker Compose in development mode.

```bash
docker-compose -f docker-compose-dev.yml up
```

--------------------------------

### Start WSO2 Server

Source: https://github.com/wso2/product-is/blob/master/README.txt

Run this command from the bin directory to start the server. In default mode, it will prompt for the master password, which by default is the password of the carbon keystore and private key.

```bash
wso2server.sh
```

--------------------------------

### Package and import statements example

Source: https://github.com/wso2/product-is/wiki/Contributing-to-Identity-Server

Example showing the package statement followed by import statements, as required in Java source files.

```java
package org.wso2.carbon.identity.casque.authenticator.authenticator;

import org.apache.commons.lang.StringUtils;
import org.apache.commons.logging.Log;
```

--------------------------------

### Block comment example

Source: https://github.com/wso2/product-is/wiki/Contributing-to-Identity-Server

Shows the format for a block comment: starts with /* and has an asterisk at the beginning of each line except the first.

```java
/*
 * Here is a block comment.
 */
```

--------------------------------

### Start and debug WSO2 Identity Server

Source: https://github.com/wso2/product-is/blob/master/docs/CONTRIBUTING.md

Starts the WSO2 Identity Server from the /bin directory after extracting the distribution. Use the -debug option to run in debug mode. The .sh scripts are for Linux/macOS and .bat for Windows.

```bash
wso2server.sh
```

```bash
wso2server.bat
```

```bash
wso2server.sh -debug
```

```bash
wso2server.bat -debug
```

--------------------------------

### Cast spacing examples

Source: https://github.com/wso2/product-is/wiki/Contributing-to-Identity-Server

Shows that casts should be followed by a blank space.

```java
myMethod((byte) aNum, (Object) x);
myFunc((int) (cp + 5), ((int) (i + 3)) + 1);
```

--------------------------------

### Run scenario tests with test.sh

Source: https://github.com/wso2/product-is/blob/master/product-scenarios/README.md

Execute the test.sh script with input-dir and output-dir arguments to run the product scenario tests. The example shows using the current working directory for both.

```bash
./test.sh --input-dir <INPUT_DIR> --output-dir <OUTPUT_DIR>
Ex: ./test.sh --input-dir $PWD --output-dir $PWD
```

--------------------------------

### Single-line comment example

Source: https://github.com/wso2/product-is/wiki/Contributing-to-Identity-Server

Example of a single-line comment indented to the level of the code that follows, preceded by a blank line.

```java
if (condition) {

     /* Handle the condition. */
      ...
}
```

--------------------------------

### End-of-line comment examples

Source: https://github.com/wso2/product-is/wiki/Contributing-to-Identity-Server

Examples of // comments: used for a complete line or partial line, and for commenting out sections of code. Note that commented-out code is removed in final code.

```java
if (foo > 1)  {
      // Do a double-flip.
       ...
}
else
       return false;               // Explain why here.


//if  (bar > 1)  {
//
//       // Do a triple-flip.
//       ...
// }
//else
//        return false;
```

--------------------------------

### Keyword followed by parenthesis spacing example

Source: https://github.com/wso2/product-is/wiki/Contributing-to-Identity-Server

Shows that a keyword followed by a parenthesis should be separated by a space, as in while (true).

```java
while (true) {
 ...
 }
```

--------------------------------

### jaxrs:server configuration for API implementations

Source: https://github.com/wso2/product-is/blob/master/modules/api-resources/README.md

Example jaxrs:server configurations for adding API implementations under the corresponding server tag or creating new jaxrs:server configurations for new resources.

```xml
    <jaxrs:server id="server" address="/server/v1">
        <jaxrs:serviceBeans>
            <bean class="org.wso2.carbon.identity.rest.api.server.challenge.v1.ChallengesApi"/>
        </jaxrs:serviceBeans>
        <jaxrs:providers>
            <bean class="com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider"/>
        </jaxrs:providers>
    </jaxrs:server>
    <jaxrs:server id="users" address="/users/v1">
        <jaxrs:serviceBeans>
            <bean class="org.wso2.carbon.identity.rest.api.user.association.v1.UsersApi"/>
            <bean class="org.wso2.carbon.identity.rest.api.user.challenge.v1.UserIdApi"/>
            <bean class="org.wso2.carbon.identity.rest.api.user.challenge.v1.MeApi"/>
        </jaxrs:serviceBeans>
        <jaxrs:providers>
            <bean class="com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider"/>
        </jaxrs:providers>
    </jaxrs:server>
```

--------------------------------

### JavaDoc comment example for method

Source: https://github.com/wso2/product-is/wiki/Contributing-to-Identity-Server

Shows the required format for a method-level documentation comment with @param and @return tags. Place the comment immediately before the method declaration.

```java
/**
     * Add String to the buffer
     *
     * @param tempBuffer the buffer to add the attribute to.
     * @param offset     offset to add the attribute.
     * @param str        the attribute value (a string).
     * @param type       the attribute type.
     * @return the offset after adding the attribute
     */
    private static int addString(byte[] tempBuffer, int offset, String str, byte type) {
```

--------------------------------

### Run test_runner.sh

Source: https://github.com/wso2/product-is/blob/master/oidc-conformance-tests/README.md

Executes the test runner script to start and configure the identity server locally and run OIDC conformance tests.

```bash
bash test_runner.sh
```

--------------------------------

### Binary and unary operator spacing examples

Source: https://github.com/wso2/product-is/wiki/Contributing-to-Identity-Server

Shows that binary operators should be surrounded by spaces, while unary operators like ++ and -- should not be separated from their operands.

```java
 a += c + d;
 a = (a + b) / (c * d);
 while (d++ = s++) {
 n++;
 }
 prints("size is " + foo + "\n");
```

--------------------------------

### Build distribution with Maven

Source: https://github.com/wso2/product-is/blob/master/docs/CONTRIBUTING.md

Builds the WSO2 Identity Server distribution from source. The first command runs all tests; the second skips unit and integration tests. Run from the product-is directory after installing JDK 11-21 and Maven 3.x.x.

```bash
mvn clean install
```

```bash
mvn clean install -Dmaven.test.skip=true
```

--------------------------------

### For statement expression spacing example

Source: https://github.com/wso2/product-is/wiki/Contributing-to-Identity-Server

Shows that expressions in a for statement should be separated by blank spaces.

```java
for (expr1; expr2; expr3)
```

--------------------------------

### Error message logging with whitespace

Source: https://github.com/wso2/product-is/wiki/Contributing-to-Identity-Server

Shows a logging example where whitespace is used to clearly identify the error message and exception.

```java
log.error("Could not get the Datagram responsePacket ", ioe);
```

--------------------------------

### JavaDoc comment example for class

Source: https://github.com/wso2/product-is/wiki/Contributing-to-Identity-Server

Shows the required format for a class-level documentation comment. Place the comment immediately before the class declaration. In IntelliJ IDEA, type /** and press Return to auto-generate the stub.

```java
/**
 * The Example class provides ...
 */
class Example { …
```

--------------------------------

### Line wrapping: breaking method calls

Source: https://github.com/wso2/product-is/wiki/Contributing-to-Identity-Server

Examples of breaking method calls: break after a comma and align the new line with the beginning of the expression at the same level. The second example shows a nested function call.

```java
function(longExpression1, longExpression2, longExpression3,
    longExpression4, longExpression5);

var = function1(longExpression1,
    function2(longExpression2,
 	    longExpression3));
```

--------------------------------

### Trailing comment example

Source: https://github.com/wso2/product-is/wiki/Contributing-to-Identity-Server

Shows very short comments on the same line as the code, shifted far enough to separate them from the statements. Multiple trailing comments should be indented to the same tab setting.

```java
if (a == 2) {
     return TRUE; 			/* special case */
} else {
     return isprime(a); 		/* works only for odd a */
}
```

--------------------------------

### Line wrapping: if statements (bad vs good indentation)

Source: https://github.com/wso2/product-is/wiki/Contributing-to-Identity-Server

Three examples for wrapping if statements. The first is bad because the indentation makes the body easy to miss. The second and third use the recommended 4-space rule.

```java
//DON’T USE THIS INDENTATION
if  ((condition1 && condition2)
      || (condition3 && condition4)
      ||!(condition5 && condition6))  {  //BAD WRAPS
      doSomethingAboutIt();              //MAKE THIS LINE EASY TO MISS
}

//USE THIS INDENTATION INSTEAD
If ((condition1 && condition2)
    || (condition3 && condition4)
    ||!(condition5 && condition6)) {
    doSomethingAboutIt();
}

//OR USE THIS
if ((condition1 && condition2) || (condition3 && condition4)
    ||!(condition5 && condition6)) {
    doSomethingAboutIt();
}
```

--------------------------------

### Line wrapping: arithmetic expression (preferred vs avoid)

Source: https://github.com/wso2/product-is/wiki/Contributing-to-Identity-Server

Two examples of breaking an arithmetic expression. The first is preferred because the break occurs outside the parenthesized expression (higher level). The second is to be avoided.

```java
longName1 = longName2 * (longName3 + longName4 - longName5)
                      + 4 * longname6; // PREFER

longName1 = longName2 * (longName3 + longName4
                      - longName5) + 4 * longname6; // AVOID
```

--------------------------------

### Deploy samples on Linux

Source: https://github.com/wso2/product-is/blob/master/product-scenarios/test-resources/README.md

Run this script on Linux to download and deploy the sample applications. Provide the IS HTTPS URL as an argument; if omitted, default configurations are used.

```bash
sh deploy-samples-linux.sh <ISHttpsURL>

ex: sh deploy-samples-linux.sh https://wso2.is.com:443
```

--------------------------------

### Sample command for running tests

Source: https://github.com/wso2/product-is/blob/master/product-scenarios/README.md

A sample command showing how to run test.sh with absolute paths for input-dir and output-dir.

```bash
./test.sh --input-dir /home/ubuntu/code/product-is/product-scenarios --output-dir /home/centos/code/product-is/product-scenarios
```

--------------------------------

### Deploy samples on MacOS

Source: https://github.com/wso2/product-is/blob/master/product-scenarios/test-resources/README.md

Run this script on MacOS to download and deploy the sample applications. Provide the IS HTTPS URL as an argument; if omitted, default configurations are used.

```bash
sh deploy-samples-mac.sh <ISHttpsURL>

ex: sh deploy-samples-mac.sh https://wso2.com:9443
```

--------------------------------

### Compile and package the conformance suite

Source: https://github.com/wso2/product-is/blob/master/oidc-conformance-tests/conformance-suite-setup-guidelines.md

Builds the conformance suite using Maven, skipping tests.

```bash
mvn clean package -Dmaven.test.skip=true
```

--------------------------------

### Build the component with Maven

Source: https://github.com/wso2/product-is/blob/master/modules/api-resources/README.md

Command to build the component after adding the API implementation.

```bash
     mvn clean install
```

--------------------------------

### Configure infrastructure.properties

Source: https://github.com/wso2/product-is/blob/master/product-scenarios/README.md

Create a file named infrastructure.properties and add the ISHttpsUrl and ISSamplesHttpUrl configurations to point to the Identity Server pack.

```properties
ISHttpsUrl=https://localhost:9443 
ISSamplesHttpUrl=http://localhost:8080
```

--------------------------------

### Clone the product-is repository

Source: https://github.com/wso2/product-is/blob/master/product-scenarios/README.md

Clone the WSO2 Identity Server product-is repository from GitHub to run scenario tests.

```bash
git clone  https://github.com/wso2/product-is.git
```

--------------------------------

### Run all integration tests

Source: https://github.com/wso2/product-is/blob/master/docs/CONTRIBUTING.md

Runs all integration tests from the tests-backend directory. Requires building the product first.

```bash
mvn clean install
```

--------------------------------

### Beginning comment template (generic)

Source: https://github.com/wso2/product-is/wiki/Contributing-to-Identity-Server

All source files should begin with a c-style comment listing the programmer(s), date, copyright notice, and a brief description of the program's purpose.

```java
/*
 * Classname
 *
 * Version info
 *
 * Copyright notice
 */
```

--------------------------------

### Clone the conformance suite repository

Source: https://github.com/wso2/product-is/blob/master/oidc-conformance-tests/conformance-suite-setup-guidelines.md

Clones the OpenID Connect Conformance Suite repository and changes into the directory.

```bash
git clone https://gitlab.com/openid/conformance-suite.git
cd conformance-suite
```

--------------------------------

### Sample server API endpoint

Source: https://github.com/wso2/product-is/blob/master/modules/api-resources/README.md

Sample endpoint for server APIs.

```text
            https://localhost:9443/api/server/v1/challenges
```

--------------------------------

### Configure Secure Vault with Default Configurations

Source: https://github.com/wso2/product-is/blob/master/README.txt

Run this command from the bin directory to configure the secure vault with default settings. It replaces sensitive elements in configuration files with alias tokens, encrypts plain text passwords defined in cipher-text.properties, and updates secret-conf.properties with default keystore and callback class.

```bash
ciphertool.sh -Dconfigure
```

--------------------------------

### Sample user API endpoint

Source: https://github.com/wso2/product-is/blob/master/modules/api-resources/README.md

Sample endpoint for user APIs.

```text
            https://localhost:9443/api/users/v1/me/challenges
```

--------------------------------

### Sample curl request for server API

Source: https://github.com/wso2/product-is/blob/master/modules/api-resources/README.md

Sample curl request to access a server API endpoint.

```bash
            curl -u admin:admin -v -X GET "https://localhost:9443/api/server/v1/challenges" -H "accept: application/json" -k
```

--------------------------------

### Sample curl request for user API

Source: https://github.com/wso2/product-is/blob/master/modules/api-resources/README.md

Sample curl request to access a user API endpoint.

```bash
            curl -u admin:admin -v -X GET "https://localhost:9443/api/users/v1/me/challenges" -H "accept: application/json" -k
```

--------------------------------

### Profile module directory structure

Source: https://github.com/wso2/product-is/blob/master/modules/api-resources/README.md

Shows the directory structure of a profile module, including the beans.xml file that must be edited to expose a new API in a specific profile.

```text
     <profile-module>
     ├── pom.xml
     ├── src
     │   └── main
     │       └── webapp
     │           ├── META-INF
     |           |   ├── webapp-classloading.xml
     │           └── WEB-INF
     │               ├── beans.xml
     │               └── web.xml
    
```

--------------------------------

### Built WAR file location

Source: https://github.com/wso2/product-is/blob/master/modules/api-resources/README.md

Shows the location of the built WAR file in the target directory of the profile module.

```text
        ── <profile-module>
           └── target
               ├── api-resources-<profile>.war
```

--------------------------------

### Docker Compose configuration with extra hosts

Source: https://github.com/wso2/product-is/blob/master/oidc-conformance-tests/conformance-suite-setup-guidelines.md

Shows the docker-compose-dev.yml configuration with extra_hosts entries for mongodb, httpd, and server services to resolve the WSO2 Identity Server hostname.

```yaml
version: '3'
services:
mongodb:
    image: mongo:4.2
    volumes:
     - ./mongo/data:/data/db
    extra_hosts:
     - "localhost:host-gateway"

httpd:
    build:
      context: ./httpd
      dockerfile: Dockerfile-static
    ports:
     - "8443:8443"
    extra_hosts:
     - "localhost:host-gateway"
    volumes:
     - ./src/main/resources/:/usr/local/apache2/htdocs/
    depends_on:
     - server
server:
    build:
      context: ./server-dev
    ports:
     - "9999:9999"
    extra_hosts:
     - "localhost:host-gateway"
```

--------------------------------

### Line wrapping: ternary expressions (three acceptable formats)

Source: https://github.com/wso2/product-is/wiki/Contributing-to-Identity-Server

Three acceptable ways to format ternary expressions, showing different line break placements.

```java
alpha = (aLongBooleanExpression) ? beta : gamma;

alpha = (aLongBooleanExpression) ? beta
 				 : gamma;

alpha = (aLongBooleanExpression)
             ? beta
             : gamma;
```

--------------------------------

### Import API CXF XML files in beans.xml

Source: https://github.com/wso2/product-is/blob/master/modules/api-resources/README.md

XML import statements to add to the beans.xml file to import the API CXF XML files for the new API.

```xml
       <import resource="classpath:META-INF/cxf/workflow-engine-server-v1-cxf.xml"/>
       <import resource="classpath:META-INF/cxf/claim-management-server-v1-cxf.xml"/>
       <import resource="classpath:META-INF/cxf/challenge-server-v1-cxf.xml"/>
       <import resource="classpath:META-INF/cxf/email-template-server-v1-cxf.xml"/>
```

--------------------------------

### Change Password with Ciphertool

Source: https://github.com/wso2/product-is/blob/master/README.txt

Run this command from the bin directory to change any password. This is used after the initial configuration to update passwords.

```bash
ciphertool -Dchange
```

--------------------------------

### Copyright comment for open-source components

Source: https://github.com/wso2/product-is/wiki/Contributing-to-Identity-Server

Standard Apache License 2.0 copyright header used for open-source components developed by WSO2.

```java
/*
 * Copyright (c) 2022, WSO2 LLC. (http://www.wso2.com).
 *
 * WSO2 LLC. licenses this file to you under the Apache License,
 * Version 2.0 (the "License"); you may not use this file except
 * in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
```

--------------------------------

### if, if-else, if-else-if-else statement formatting

Source: https://github.com/wso2/product-is/wiki/Contributing-to-Identity-Server

Shows the required brace style for if-else statements. Always use braces {} even for single statements.

```java
if (condition) {
     statements;
}

if (condition) {
statements;
} else {
statements;
}

if (condition) {
statements;
} else if (condition) {
statements;
} else if (condition) {
statements;
}
```

--------------------------------

### try-catch statement formatting

Source: https://github.com/wso2/product-is/wiki/Contributing-to-Identity-Server

Shows the required format for try-catch blocks.

```java
try {
statements;
} catch (ExceptionClass e) {
statements;
}
```

--------------------------------

### Run or debug integration tests with external debug

Source: https://github.com/wso2/product-is/blob/master/docs/CONTRIBUTING.md

Runs or debugs integration tests while debugging another repository. The first command runs the tests normally; the second runs them in debug mode.

```bash
mvn clean install
```

```bash
mvn -Dmaven.surefire.debug test
```

--------------------------------

### Update Identity Component Versions with Maven

Source: https://github.com/wso2/product-is/blob/master/release-guidelines.md

Use this Maven command to update versions of identity components, authenticators, and other specified dependencies. It disables backup POM generation and includes a list of WSO2 and Apache artifacts.

```bash
mvn versions:update-properties -DgenerateBackupPoms=false -Dincludes=org.wso2.carbon.identity.*,org.wso2.carbon.extension.identity.*,org.wso2.charon,org.apache.rampart.wso2,org.apache.ws.security.wso2,org.wso2.carbon.consent.*,org.wso2.carbon.database.utils -U
```

--------------------------------

### Run integration tests in debug mode

Source: https://github.com/wso2/product-is/blob/master/docs/CONTRIBUTING.md

Runs integration tests in debug mode using Maven Surefire debug.

```bash
mvn -Dmaven.surefire.debug test
```

--------------------------------

### Enable debug port in automation.xml

Source: https://github.com/wso2/product-is/blob/master/docs/CONTRIBUTING.md

Uncomment this line in automation.xml to enable debugging of another repository while running integration tests. The value debug 5005 sets the debug port.

```xml
<parameter name="cmdArg" value="debug 5005" />
```

--------------------------------

### Line wrapping: prefer higher-level breaks

Source: https://github.com/wso2/product-is/wiki/Contributing-to-Identity-Server

Shows the preferred way to break a long expression: break before an operator and at a higher level, aligning the new line with the beginning of the expression. If that leads to confusing code, indent 4 spaces instead.

```java
// prefer higher-level breaks
longName1 = longName2 * (longName3 + longName4 - longName5)
       + 4 * longname6;
```

--------------------------------

### Copyright comment for private components

Source: https://github.com/wso2/product-is/wiki/Contributing-to-Identity-Server

Copyright header used for components developed privately, with a proprietary notice and restrictions on dissemination.

```java
/*
 * Copyright (c) 2022, WSO2 LLC. (http://www.wso2.com). All Rights Reserved.
 *
 * This software is the property of WSO2 Inc. and its suppliers, if any.
 * Dissemination of any information or reproduction of any material contained
 * herein in any form is strictly forbidden, unless permitted by WSO2 expressly.
 * You may not alter or remove any copyright or other notice from copies of this content.
 */
```

--------------------------------

### Avoid omitting braces in if statements

Source: https://github.com/wso2/product-is/wiki/Contributing-to-Identity-Server

This form is explicitly discouraged. Always use braces {} to avoid errors.

```java
if (condition)          //AVOID! THIS OMITS THE BRACES {}!
Statement;
```
Tokens:
Raw