Single sign-on with SAML 2.0 (beta)

***On-Premises only***

If you are using an on-premises deployment and would like to set up single sign-on (SAML 2,.0) follow the below instructions.

Step 1: Activate it

Whether you’re using a docker-compose or a Kubernetes deployment, introduce the following environment variable:

Name: samlEnabled
Value: 'true'

Step 2: Configure it

The provided “saml/saml.properties” file contains all the configuration keys necessary to the SAML functionality.

onelogin.saml2.sp.entityid: identifies the SP

onelogin.saml2.sp.assertion_consumer_service.url: where the response from idp is returned after an authentication request

Onelogin.saml2.sp.single_logout_service.url: where the response from idp is returned after logout request

onelogin.saml2.idp.single_sign_on_service.url: where the SP will send the Authentication Request 

onelogin.saml2.idp.single_logout_service.url: where the SP will send the logout request

onelogin.saml2.idp.x509cert: public x509 certificate of the IdP

 

Example:
onelogin.saml2.sp.entityid = apifortress

onelogin.saml2.sp.assertion_consumer_service.url = http://apif.example.com:8080/app/web/login/acs

onelogin.saml2.sp.single_logout_service.url = http://apif.example.com:8080/app/web/login/sls

onelogin.saml2.idp.entityid = https://app.onelogin.com/saml/metadata/7037e41d-4ab4-417a-b0a2-c4e2f580faf2

Onelogin.saml2.idp.single_sign_on_service.url = https://apifortress.onelogin.com/trust/saml2/http-post/sso/917654

onelogin.saml2.idp.single_logout_service.url = https://apifortress.onelogin.com/trust/saml2/http-redirect/slo/917654

onelogin.saml2.idp.x509cert = —–BEGIN CERTIFICATE—–CERTIFICATE HASH—–END CERTIFICATE—–

Further changes can be applied to the expected properties:
apifortress.firstname=FIRSTNAME

apifortress.lastname=LASTNAME

apifortress.mail=MAIL
#in IDP one of MANAGER,DEVELOPER,ANALYST

apifortress.level=LEVEL

By altering these configuration keys, you change the name of the property that’s being sent by the IDP. As a default, the required properties are:

FIRSTNAME

LASTNAME

MAIL

LEVEL represents the level of the user within API Fortress and can be one of the following values: MANAGER,DEVELOPER,ANALYST

If the field is not provided, MANAGER is assumed.

The admin status can only be set via the API Fortress configuration panel.

Note: there may be other configuration keys to be altered based on the IDP requirements.

Step 3: Mount it

Mount the provided “saml” directory to the location: /usr/local/tomcat/webapps/app/WEB-INF/saml

If Kubernetes is being used, ConfigMaps will achieve the same result.

Step 4: Restart API Fortress

Restart the API Fortress dashboard(s).

The login screen will now look like this:

 

Connectors – StatusPage

This connector allows you to connect your API Fortress instance with your StatusPage instance. When a test fails the connector will open an incident in StatusPage, the next time that same test runs and passes the connector will resolve the incident in StatusPage.

What you will need from your Status page account is the Page ID and the API key, both can be found by logging into your StatusPage account and going to the manage account page. Then click on the tab names “API”:

Next we will configure the connector in API Fortress:

Don’t forget to add the alert group the project you want the connector to work for:

Build from Axway

You can generate a test draft from an API managed in Axway.

  1. On the test interstitial page there is a “Build from Axway” button, click it
  2. Enter the Username, Password and Base URI for your Axway account (this is your base URI, not including the path eg. https://api.axway.training:PORT, please note that the http/s is required)
  3. Then choose the API Project that contains the API you would like to generate a test from
  4. Then for the API you want to generate a test from, click on the lightning bolt on the right side
  5. You now have a high level test created from the API in your Axway account. Run the test as is, or modify it to add more logic!

Click here if you would like to learn what to do from here.

Integrate with Test Modeller (Curiosity Software)

We now have an integration built out with Curiosity Software’s Test Modeller. This integration allows you to power your API Fortress tests with modeled data that was generated in TDM.

Below are the steps to integrate TDM with APIF:

API Fortress:

  1. Create an API Fortress test that will be used with TDM data.
  2. Generate Webhook for project that will use TDM data:
  1. Test Modeller:
    1. Go to Profile -> Connectors
    2. Click “Add Connection”
    3. Set up the API Fortress connector in Test Modeller

    1. Connector Type: choose API Fortress
    2. Profile Name: Give the profile a name (recommendation: this should match the API Fortress project name for organizational purposes)
    3. Url: This is your API Fortress domain up to the “/app” part (example: https://mastiff.apifortress.com/app/)
    4. Username: This is your API Fortress login username
    5. Password: This is your API Fortress login password
    6. Project Hook: This is the API Fortress hook that we created earlier in API Fortress. (use the string at the end of the url, for example https://mastiff.apifortress.com/app/api/rest/v3/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxxx

4. Save the connector

5. Now that the connector has been configured, go to the “Submit Job” tab
6. Find the API Fortress job and execute it

 

Now you have your integration between TDM and API Fortress complete, create some models and run tests with multiple input sets easily!

To watch a video on this process including how to create model and push data to APIF and run the test click here.

Connectors – PagerDuty

Here is a quick guide to setting up and using the PagerDuty connector.
Note: this connector does not come pre-loaded out of the box, and will need to be loaded separately. To learn how to load the connector into your API Fortress instance click here.

  1. Go to settings page
  2. Click on “Alert Groups”
  3. Create a new group or add a connector to an existing alert group
  4. Add a new connector
  5. Choose the PagerDuty connector
  6. Configure the connector
    1. routing_key is the integration key generate for a service in PagerDuty. The routing_key can be generated here
      1. click on the service you would like to alert, and click on the “Integrations tab”
      2. Use an existing integration or create a new one specifically for API Fortress. The integration key provided is the “routing_key”
    2. severity is the level the alert should be sent as. (critical, error, warning, and info)
    3. dedup_key is a key that will allow to you match a triggered alert with a response for that alert
    4. event_action is the action you would like the alert to take. (trigger, acknowledge, and resolve)
  7. Go into project settings for a project you would like PagerDuty alerts set up for
  8. Add the alert group that contains your PagerDuty connector to this project

Add New Connector

Here is a quick guide to load up a new connector into your API Fortress on-premises deployment.

You can find all the connectors here: https://github.com/apifortress/connectors

  1. Go to admin panel
  2. Click on connectors
  3. Add new connector
  4. Follow the README.md file for how to fill in the connector form
  5. Copy and Paste the code from the connector groovy file into the code section

Connectors – JIRA

API Fortress can absolutely integrate with your JIRA setup. However, because not all JIRA boards are created equal, if you would like a connector set up for your specific JIRA board please out to support@apifortress.com

We will then gather the appropriate information and build you a custom connector for your JIRA setup.

Connectors – Hipchat

Here is a quick guide to setting up a Hipchat integration.

First generate your Hipchat personal access token. To do so go to https://[your_company].hipchat.com/account/api

Then get the room id you would like to send the alerts to, it can be retrieved in the room details page “API ID”

Next use these values to set up the connector in API Fortress:

Finally, assign the alert group to the project for which you want alerts from:

If you are migrating to Slack, we also have a connector for that! Click here to see how to set up that integration.

Version Control

There are two primary mechanisms for version control in API Fortress. The first is the Publish Test feature, which allows for the pushing of updated test-code to a live version of the test.

The second mechanism for version control is the API Fortress-Git integration. The integration is powered by the API Fortress Post-Receive Git Hook, which can be found here. Documentation is located here.

Bamboo – Integrate API Tests & Results

Passing data from API Fortress to Atlassian Bamboo allows Bamboo users to include API Fortress test results in their CI/CD process.

Step 1: Generating a Webhook

The first step to integrating API Fortress into your CI/CD process is to grab the generated API hook for the project in question. To do so, head to the Settings panel in API Fortress. This view, seen below, can be accessed from anywhere in the application by clicking the Gear icon in the top right corner of the screen. Please note you need Manager access to generate a webhook. From Settings, click the API Hooks section and generate the hook for your project. The process can be seen in detail in the .gif below.

hook

Step 2: Select or Create a Bamboo Project

After we’ve created our webhook, calling it from within Bamboo is a fairly simple process. First, create a new project in Bamboo. You can also add to an existing project from this screen.

project

Step 3: Adding an HTTP Call

Next, we need to add an HTTP Call component and enter the webhook we generated. Depending on what you wish the call to API Fortress to trigger, you may append different routing on to the end of the webhook. The API Fortress API Documentation is located here.

httpcall

Step 4: Parsing Results

After the request is sent to the API Fortress API, we’ll need to save the JUnit data that’s returned. We do so by adding a JUnit Parser step.

junit

Once the above steps are completed and saved, the build sequence will make a call to API Fortress upon execution, receive the results of the tests, and parse the results.

summary

 

Keywords: cicd, jenkins, bamboo, microsoft tfs, team foundation server, gitlab ci/cd, travisci