OneLogin SDKs & Libraries: Official & Community Integrations

SDKs overview

OneLogin offers Software Development Kits (SDKs) and client libraries designed to facilitate the integration of its identity and access management services into custom applications. These SDKs abstract much of the complexity of direct API interactions, providing language-specific methods for common operations such as user authentication, managing application access, and provisioning users and groups. The availability of SDKs across various popular programming languages aims to reduce development time and potential errors by providing pre-built components for interacting with the OneLogin API endpoints.

The SDKs typically handle tasks such as constructing API requests, managing authentication tokens (e.g., OAuth 2.0 access tokens), and parsing API responses. This approach aligns with common development patterns for integrating third-party services, allowing developers to focus on their application's core logic rather than the intricacies of HTTP requests and JSON parsing. OneLogin's developer resources, including comprehensive API documentation and SDK guides, support integrators in leveraging these tools effectively for enterprise single sign-on (SSO), multi-factor authentication (MFA), and other identity-related functionalities OneLogin developer documentation.

Official SDKs by language

OneLogin provides official SDKs for several programming languages, enabling developers to integrate identity management capabilities directly into their applications. These SDKs are maintained by OneLogin and are designed to offer a consistent and reliable interface to the OneLogin API.

Each SDK is typically available through the respective language's standard package manager, simplifying the process of adding the library to a project. Developers can find detailed instructions and usage examples within the OneLogin API documentation for each specific SDK.

Installation

Installing OneLogin SDKs follows the standard practices for each programming ecosystem. Below are general installation instructions for the officially supported languages. Specific version requirements and detailed setup steps are available in the OneLogin developer guides.

Python

The Python SDK for SAML integration can be installed using pip, the standard Python package installer:

pip install python-saml

For API interaction, developers may also use general-purpose HTTP clients like requests or libraries specifically designed for OAuth 2.0, as OneLogin's API largely follows OAuth 2.0 for authentication.

Ruby

The Ruby SDK is available as a gem. Install it using the gem command:

gem install ruby-saml

Then, include it in your project's Gemfile:

gem 'ruby-saml'

Java

For Java projects, the SDK can be integrated using Maven, by adding the following dependency to your pom.xml file:

<dependency>
    <groupId>com.onelogin</groupId>
    <artifactId>java-saml</artifactId>
    <version>X.Y.Z</version> <!-- Replace with the latest version -->
</dependency>

Check the OneLogin Java SDK documentation for the latest version information.

PHP

The PHP SDK is installed via Composer, the PHP dependency manager:

composer require onelogin/php-saml

This command adds the necessary files and updates your project's composer.json and composer.lock files.

Node.js

For Node.js applications, use npm, the Node.js package manager, to install the SAML 2.0 library:

npm install saml2-js

This will add the package to your node_modules directory and update your package.json.

Go

The Go SDK can be retrieved using go get:

go get github.com/onelogin/go-saml

Once retrieved, you can import it into your Go project:

import "github.com/onelogin/go-saml/onelogin"

Quickstart example

This quickstart example demonstrates a basic flow using the Node.js SDK (saml2-js) for handling a SAML assertion from OneLogin. This assumes a Service Provider (SP) initiated flow where OneLogin acts as the Identity Provider (IdP). The example focuses on receiving and validating a SAML response.

Prerequisites:

• Node.js installed.
• saml2-js installed (npm install saml2-js).
• OneLogin application configured with SP metadata (ACS URL, Entity ID).
• IdP metadata (certificate, SSO URL) from OneLogin.

Example Code (Node.js - Express with SAML SP):

const express = require('express');
const fs = require('fs');
const saml = require('saml2-js');
const bodyParser = require('body-parser');

const app = express();
app.use(bodyParser.urlencoded({ extended: false }));

// SP settings (replace with your actual values)
const sp_options = {
  entity_id: "http://localhost:3000/metadata.xml",
  assert_endpoint: "http://localhost:3000/saml/acs",
  private_key: fs.readFileSync("./path/to/your/sp_private_key.pem").toString(),
  certificate: fs.readFileSync("./path/to/your/sp_certificate.pem").toString()
};
const sp = new saml.ServiceProvider(sp_options);

// IdP settings (replace with your actual values from OneLogin)
const idp_options = {
  sso_login_url: "https://your-onelogin-domain.onelogin.com/trust/saml2/http-post/sso/XXXXXXXX",
  sso_logout_url: "https://your-onelogin-domain.onelogin.com/trust/saml2/http-redirect/slo/XXXXXXXX",
  certificates: [fs.readFileSync("./path/to/your/onelogin_idp_certificate.pem").toString()]
};
const idp = new saml.IdentityProvider(idp_options);

// Endpoint to receive SAML assertion from OneLogin
app.post('/saml/acs', (req, res) => {
  sp.post_assert(idp, { request_body: req.body }, (err, saml_response) => {
    if (err) {
      console.error("SAML Assertion Error:", err);
      return res.status(500).send("SAML Assertion Error");
    }

    // User is authenticated, saml_response.user contains user attributes
    console.log("Authenticated user:", saml_response.user);
    res.send(`Hello, ${saml_response.user.name_id}! You are authenticated.`);
  });
});

// Optional: Endpoint to generate SP metadata
app.get('/metadata.xml', (req, res) => {
  res.type('application/xml');
  res.send(sp.create_metadata());
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`SP server listening on port ${PORT}`);
  console.log(`SP metadata available at http://localhost:${PORT}/metadata.xml`);
});

Explanation:

1. Dependencies: express for the web server, fs for reading certificate files, saml2-js for SAML processing, and body-parser to handle POST requests.
2. SP Configuration: Defines the Service Provider's (your application's) entity ID, assertion consumer service (ACS) endpoint, and its private key/certificate. These are used to sign requests and decrypt assertions if needed.
3. IdP Configuration: Defines the Identity Provider's (OneLogin's) SSO login URL and its public certificate. This certificate is crucial for validating the digital signature of the SAML assertion received from OneLogin.
4. ACS Endpoint (/saml/acs): This POST endpoint is where OneLogin sends the SAML assertion after successful user authentication. The sp.post_assert method processes the incoming SAML response, validates it against the IdP's certificate, and extracts user attributes.
5. Metadata Endpoint (/metadata.xml): While optional for this quickstart, this endpoint provides the SP's metadata XML, which you would typically upload to OneLogin during application setup. It helps OneLogin configure its IdP settings for your application.
6. User Data: Upon successful assertion, saml_response.user will contain attributes like name_id (the user's identifier) and potentially other custom attributes configured in OneLogin.

To run this example, create sp_private_key.pem, sp_certificate.pem, and onelogin_idp_certificate.pem files in the correct paths with your security credentials. Your OneLogin application must be configured to send SAML responses to http://localhost:3000/saml/acs.

Community libraries

While OneLogin provides and maintains official SDKs for core functionality, the broader developer community has also created and contributed various libraries and integrations. These community-driven projects can offer solutions for niche use cases, alternative language bindings, or deeper integrations with specific frameworks or platforms not directly covered by official SDKs.

Community libraries are often found on platforms like GitHub or through language-specific package repositories. Developers considering these options should evaluate them based on factors such as:

• Maintenance Status: How actively is the library maintained and updated?
• Documentation: Is the documentation clear, comprehensive, and up-to-date?
• Community Support: Is there an active community (e.g., GitHub issues, forums) for assistance?
• Security Audit: Has the library undergone any security reviews, especially crucial for identity-related integrations?
• License: What open-source license governs its use?

Because these are not officially supported by OneLogin, their reliability, security, and compatibility with the latest OneLogin API versions may vary. Developers should exercise due diligence when incorporating community libraries into production environments. For direct API interaction, developers can also refer to generic HTTP client libraries available in their chosen language, such as Fetch API for JavaScript or requests for Python, to build custom integrations against the OneLogin REST API.