plasmid

plasmid

Basic SAML identity provider for testing service providers.

Warning

This application is strictly meant for testing, no authentication is (nor will be) implemented on the administration endpoints exposed by the API. It MUST NOT be used as a production SAML IdP.

• Introduction
• Installation
  • From Source
  • Pre-built Binaries
• Configuration
• Usage
  • Example (SP-initiated)
  • Example (IdP-initiated)
  • Docker
  • Starting the Identity Provider
  • Interacting With a Running Instance
  • API Endpoints
• Known Limitations
• License

Introduction

Plasmid is a SAML identity provider (IdP) based on the implementation from crewjam/saml, it is meant to be used as an easy way to test SAML service providers (SP) without requiring a complicated setup. It can be configured via a YAML file or using environment variables, and has default values for most settings, allowing to quickly get it working with minimal configuration.

Installation

From Source

Simply clone the project and run go build to build it:

git clone github.com/mdeous/plasmid
cd plasmid
go build .
./plasmid -h

Pre-built Binaries

Download the latest release for your plaform from the releases page. You can also live on the edge by using the nightly release, which always contains the latest changes from the main branch.

Configuration

Plasmid can be started without any configuration, it will then automatically generate a certificate and private key and create a user in the idp (credentials: admin:Password123).

The default configuration can be overridden either with a YAML file named plasmid.yaml and located in the current directory, or from environment variables. Some values can also be set from the command-line. Environment variables take precedence over the configuration file, and command line arguments take precedence over environment variables.

All the configuration entry names can be translated from their path in the YAML file to the environment variable name by replacing . with _, converting it to upper case, and prepending IDP_ to it. For example the environment variable for the YAML entry user.username is IDP_USER_USERNAME.

An example YAML file with all the configurable values is provided in plasmid.example.yaml at the root of the project folder.

Usage

Example (SP-initiated)

If you don't care about all the reading and just want to copy paste stuff and get started, this section is for you. This example demonstrates how to setup a test environment using ngrok plasmid, and SAMLRaider.

• In a terminal, start a ngrok tunnel and copy the tunnel URL:

ngrok http 8000

• In another terminal, generate the IdP certificate and private key, and start the server:

./plasmid gencert
./plasmid serve -u <ngrok-url>

• Using the generated metadata.xml file (or the <base-url>/metadata URL), register the plasmid instance on the service provider you want to test
• In SAMLRaider, import the certificate and private key
• You can begin testing the service provider and login using admin:Password123

Example (IdP-initiated)

• Follow the steps described in the SP-initiated example above, and then log into the service provider using the SP-initiated flow in order to create a session in plasmid (this is needed as a workaround to a bug with sp-initiated flow in the underlying SAML library)
• Create a new link in plasmid for the service provider

./plasmid client login-add -n "<link-name>" -e "<sp-entity-id>"

• Start the IdP-initiated flow

./plasmid client login "<login-name>"

• A new browser window should open and the login flow should start

Docker

To run plasmid with Docker, simply start the image and pass any needed arguments to it. Optionally, you can mount a configuration file to the container's /plasmid/plasmid.yaml path, or use environment variables.

docker run mdeous/plasmid:latest serve

Starting the Identity Provider

To start the IdP with the bare minimum settings, simply run plasmid serve. The application will generate a certificate and a private key, and will create a default admin:Password123 user. By default, the application is served on http://127.0.0.1:8000.

The certificates can also be generated separately using the plasmid gencert command. The generated certificate and private key are saved in PEM format, and can then be imported into other testing tools like SAMLRaider.

It is sometimes needed to make the IdP accessible from the internet, this can be achieved using ngrok by setting the base_url configuration variable to the ngrok tunnel URL.

Interacting With a Running Instance

Multiple functions to interact in various ways with a running Plasmid instance are provided under the plasmid client command. The available commands are:

Interact with a running Plasmid instance

Usage:
  plasmid client [command]

Aliases:
  client, c

Available Commands:
  login        Start an idp initiated login flow (opens a browser)
  login-add    Create a new idp initiated login link
  login-del    Delete an idp initiated login link
  login-list   List links for idp initiated login
  session-del  Delete an active user session
  session-get  Get details about an active user session
  session-list List active user sessions
  sp-add       Register a new service provider
  sp-del       Delete a service provider
  sp-list      List service providers
  user-add     Create a new user account
  user-del     Delete an user account
  user-list    List user accounts

Flags:
  -h, --help         help for client
      --url string   plasmid instance url (default "http://127.0.0.1:8000")

Use "plasmid client [command] --help" for more information about a command.

Refer to the help for each command for more details on their usage.

Common Operations

• Adding a new user to the IdP:

./plasmid client user-add -u "<username>" -e "<email>" -p "<password>"

• Deleting an active user session:

# list active sessions ids
./plasmid client sessions
# delete the session
./plasmid client session-del "<session-id>"

• Adding a new SP to the IdP:

./plasmid client sp-add -m "<metadata_url_or_file>" -s "<service-name>"

• Creating a new IdP-initiated login link:

./plasmid client login-add -n "<link-name>" -e "<sp-entity-id>"

API Endpoints

The underlying IdP implementation exposes a number of API endpoints, this section merely exists as an inventory of those endpoints. Most of those can be easily queried using the integrated client via the plasmid client command.

For more information, please refer to the code for their handlers in crewjam/saml, which are listed here.

SSO

Service providers

Users

Sessions

Identity provider initiated flow

Identity provider initiated flow links management

Known Limitations

• Does not support signed SAML requests
• Does not support encrypted SAML requests
• IdP initiated flow currently only works with existing session, but login form is broken (waiting for crewjam/saml#463 to be merged)
• client sssion-get and client session-del commands fail when session id contains a / (waiting for crewjam/saml#462 to be merged)

License

This project is licensed under the MIT license. See the LICENSE file for more information.