Kloudless API Guide

# Developer Portal

# First Visit

When first visiting the developer portal, you will need to create an account by signing up with your email address. The appliance does not currently send confirmation emails to verify the address.

Once the account information is provided, you will be presented with the application creation screen. From here, you will be able to enter the name and description of your first app.

After the application is created successfully, you will be brought to a short walkthrough to get started using the Kloudless API. It walks you through the process of how to include the authenticator that is used to connect accounts to your appliance and how to start making API requests.

You can then proceed to the Docs for detailed information about the API as well as try the Interactive Docs, which allows you to make API requests directly from your browser.

# Transitioning from kloudless.com

An application connecting to Kloudless’s public cloud at kloudless.com will not need to alter its implementation significantly to use a private deployment:

  • Any code that connects to https://api.kloudless.com/ should be modified to connect to the new API server location at http://your_appliance/, or https://your_appliance/ if SSL is configured.
  • Since the instance is entirely separate from the Kloudless cloud, a new application ID and API Key would have to be configured. This can be obtained from the appliance’s developer portal at http://your_appliance:8080/, or https://your_appliance:8443/ if SSL is configured.
  • UI Tools such as the Authenticator and File Picker can also be included from the new server as documented in the UI Tools section.

# Switching to SAML authentication

By default, developers can sign up and log in to the developer portal using password authentication. It is possible to use SAML Single Sign-On ("SAML auth") instead, where the appliance’s developer portal is the service provider ("SP").

These steps are required to turn on SAML auth:

  1. Create an application in the SAML Identity Provider's ("IdP") dashboard. For example, the IdP could be Okta, OneLogin, or a similar service. Input these values into the IdP's configuration fields (use https://your_appliance:8443 if SSL is configured for the Kloudless appliance’s developer portal):

    • Audience: http://your_appliance:8080/account/saml/metadata/
    • Recipient: http://your_appliance:8080/complete/saml/
    • ACS (Consumer) URL: http://your_appliance:8080/complete/saml/
    • Leave "Single Logout Url" empty because the logout process is done by ending the developer portal session, rather than interacting with the IdP.

    Assign permissions to the newly created app to appropriate users in the IdP account. Each user must exist both in the Kloudless developer portal as well as in the IdP, using the same email address.

  2. Generate a private/public key pair for your Service Provider certificate. You can generate a new self-signed key pair using the following command:

    openssl req -new -x509 -days 3652 -nodes -out saml.crt -keyout saml.key

    The contents of saml.crt should then be used as the value of sp_public_cert below. The contents of saml.key should be used as the value of sp_private_key. In both cases you can omit the first and last lines of the files, which aren’t required. The SP certificate is used if encryption or signing is turned on in the security_config settings below.

  3. In the Kloudless YAML configuration, add or modify the auth section to include a section similar to below, where OneLogin is used as an example:

     auth:
     saml:
         enabled: true
         force_authn: true
         sp_entity_id: 'https://your_appliance/account/saml/metadata/'
         sp_public_cert: '...'
         sp_private_key: '...'
         org_info:
             en-US:
                 name: Your Org
                 displayname: Your Org, Inc.
                 url: 'https://your_domain'
         technical_contact:
             givenName: Your Tech Contact
             emailAddress: tech_support@your_domain
         support_contact:
             givenName: Your Support
             emailAddress: support@your_domain
         sp_extra:
         security_config:
             wantAttributeStatement: false
         idp_name: main_idp
         enabled_idps:
             # value from idp_name must be used here:
             main_idp:
                 entity_id: "https://app.onelogin.com/saml/metadata/<uid>"
                 url: "https://<subdomain>.onelogin.com/trust/saml2/http-post/sso/<uid>"
                 x509cert: "<base-64 cert>"
                 attr_user_permanent_id: "name_id"
                 attr_email: "name_id"

    Alter the YAML configuration to include appropriate values for each key.

  4. Either run ke_update_configuration if modifying the YAML file at /data/kloudless.yml, or restart the Docker containers with this configuration in place instead.

← Administrative Tasks →