https://github.com/mdeous/plasmid
SAML IdP for SP security testing.
https://github.com/mdeous/plasmid
identity-provider saml saml-idp security sso
Last synced: 3 months ago
JSON representation
SAML IdP for SP security testing.
- Host: GitHub
- URL: https://github.com/mdeous/plasmid
- Owner: mdeous
- License: mit
- Created: 2022-09-23T17:14:09.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2026-04-19T21:52:53.000Z (3 months ago)
- Last Synced: 2026-04-19T23:36:09.510Z (3 months ago)
- Topics: identity-provider, saml, saml-idp, security, sso
- Language: Go
- Homepage:
- Size: 533 KB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# plasmid
[](https://github.com/mdeous/plasmid/actions/workflows/build.yml)
[](https://github.com/mdeous/plasmid/actions/workflows/docker.yml)
[](https://github.com/mdeous/plasmid/blob/main/LICENSE)
Minimal-configuration SAML identity provider for security testing of service provider implementations.
> :warning: **Warning**
>
> This application is strictly meant for testing SAML service providers, no authentication is (nor will be) implemented
> on the administration API endpoints it exposes. It MUST NOT be used as a production SAML IdP.
---
- [Introduction](#introduction)
- [Features](#features)
- [Installation](#installation)
- [From Source](#from-source)
- [Pre-built Binaries](#pre-built-binaries)
- [Configuration](#configuration)
- [Usage](#usage)
- [SP-initiated Flow](#sp-initiated-flow)
- [IdP-initiated Flow](#idp-initiated-flow)
- [Docker](#docker)
- [Interacting With a Running Instance](#interacting-with-a-running-instance)
- [Common Operations](#common-operations)
- [Web Dashboard](#web-dashboard)
- [API Endpoints](#api-endpoints)
- [SSO](#sso)
- [Service providers](#service-providers)
- [Users](#users)
- [Sessions](#sessions)
- [Identity provider initiated flow](#identity-provider-initiated-flow)
- [Identity provider initiated flow links management](#identity-provider-initiated-flow-links-management)
- [Known Limitations](#known-limitations)
- [License](#license)
---
## Introduction
Plasmid is a SAML identity provider (IdP) based on the implementation from [`crewjam/saml`](https://github.com/crewjam/saml).
It is meant to run with minimal configuration and provide an easy way to test SAML service provider (SP) implementations.
## Features
- SP-initiated and IdP-initiated SAML SSO flows
- Web dashboard for managing users, services, sessions, and shortcuts
- SAML inspector for capturing and examining request/response exchanges
- Assertion tampering for modifying SAML assertions on the fly:
- Signature manipulation (removal, empty SignatureValue, corrupt DigestValue)
- XML Signature Wrapping attacks (8 variants)
- XXE injection (local file read, SSRF, out-of-band exfiltration, custom DOCTYPE)
- XML comment injection in NameID values
- Override NameID, NameID format, Issuer, Audience, and RelayState
- Dynamic attribute injection and modification
- SAML response replay from the inspector
- CLI client for interacting with a running instance
## Installation
### From Source
Simply clone the project and use the provided `Makefile` to build it:
```bash
git clone github.com/mdeous/plasmid
cd plasmid
make
./plasmid -h
```
### Pre-built Binaries
Download the latest release for your plaform from the [releases](https://github.com/mdeous/plasmid/releases/latest)
page. You can also live on the edge by using the [nightly](https://github.com/mdeous/plasmid/releases/tag/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 options and their default values is provided in
[`plasmid.example.yaml`](https://github.com/mdeous/plasmid/blob/69bc87be8ab5da2af2adb2af94efa692b7fae3b2/plasmid.example.yml)
at the root of the project folder.
## Usage
### SP-initiated Flow
This example demonstrates how to setup a test environment using [`ngrok`](https://ngrok.com/)
`plasmid` and [`SAMLRaider`](https://github.com/portswigger/saml-raider).
- In a terminal, start a ngrok tunnel and copy the tunnel URL:
```bash
ngrok http 8000
```
- In another terminal, generate the IdP certificate and private key, and start the server:
```bash
./plasmid serve -u
```
- Using the generated `idp-metadata.xml` file (or the `/metadata` URL), register the plasmid
instance on the service provider you want to test
- In [`SAMLRaider`](https://github.com/portswigger/saml-raider), import the certificate and private key
- You can begin testing the service provider and login using `admin:Password123`
### IdP-initiated Flow
- Follow the steps described in the [SP-initiated example](#sp-initiated-flow) above to register the
plasmid instance on the service provider
- Create a new link in plasmid for the service provider using the `client` command:
```bash
./plasmid client login-add -n "" -e ""
```
- Start the IdP-initiated flow:
```bash
./plasmid client login ""
```
- A new browser window should open and prompt you for credentials (or directly redirect you to the SP if
you already have an active session)
### 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.
```bash
docker run ghcr.io/mdeous/plasmid:latest serve
```
### Interacting With a Running Instance
The `plasmid client` command provides a number of subcommands that can be used to interact with
a plasmid instance:
```text
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-get Get details about a 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.
```
Each subcommand can also be called using shorthand commands (e.g. `sg` instead of `session-get`),
please refer to the help of each of those to know more about their usage and the available shorthands.
#### Common Operations
- Adding a new user to the IdP:
```bash
./plasmid client user-add -u "" -e "" -p ""
```
- Deleting an active user session:
```bash
# list active sessions ids
./plasmid client session-list
# delete the session
./plasmid client session-del ""
```
- Adding a new SP to the IdP:
```bash
./plasmid client sp-add -m "" -s ""
```
- Creating a new IdP-initiated login link:
```bash
./plasmid client login-add -n "" -e ""
```
### Web Dashboard
Plasmid includes a web dashboard accessible at `/ui/`. It provides pages for:
- **Dashboard** — overview and stats
- **Users** — manage IdP user accounts
- **Services** — manage registered service providers
- **Sessions** — view and manage active sessions
- **Shortcuts** — manage IdP-initiated login links
- **Inspector** — view captured SAML request/response exchanges in real time
- **Tamper** — assertion tampering settings
- **Settings** — view IdP certificate details
### 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](#interacting-with-a-running-instance) via the `plasmid client` command.
For more information, please refer to the code of their handlers in [`crewjam/saml`](https://github.com/crewjam/saml),
which are listed [in this file](https://github.com/crewjam/saml/blob/main/samlidp/samlidp.go#L86-L125).
#### SSO
| **Method** | **Path** | **Description** |
| ------------ | ----------- | ---------------------------------- |
| `GET` | `/metadata` | get the identity provider metadata |
| `GET`/`POST` | `/sso` | generate SAML assertions |
#### Service providers
| **Method** | **Path** | **Description** |
| ------------ | ---------------- | -------------------------------- |
| `GET` | `/services/` | list service providers |
| `GET` | `/services/` | get service provider metadata |
| `PUT`/`POST` | `/services/` | add or update a service provider |
| `DELETE` | `/services/` | delete a service provider |
#### Users
| **Method** | **Path** | **Description** |
| ---------- | ------------------- | ---------------------------------- |
| `GET` | `/users/` | list user accounts |
| `GET` | `/users/` | get information on an user account |
| `PUT` | `/users/` | add or update an user account |
| `DELETE` | `/users/` | delete an user account |
#### Sessions
| **Method** | **Path** | **Description** |
| ---------- | ---------------- | ------------------------------------ |
| `GET` | `/sessions/` | list active sessions |
| `GET` | `/sessions/` | get information on an active session |
| `DELETE` | `/sessions/` | delete a session |
#### Identity provider initiated flow
| **Method** | **Path** | **Description** |
| ------------ | ---------------------------------- | -------------------------- |
| `GET`/`POST` | `/login` | login handler |
| `GET` | `/login/` | begin flow |
| `GET` | `/login//` | begin flow with RelayState |
#### Identity provider initiated flow links management
| **Method** | **Path** | **Description** |
| ---------- | ------------------------ | ---------------------------------------------------- |
| `GET` | `/shortcuts/` | list login links |
| `GET` | `/shortcuts/` | get information on a login link |
| `PUT` | `/shortcuts/` | create or update a login link for a service provider |
| `DELETE` | `/shortcuts/` | delete a login link |
## Known Limitations
- Does not support signed SAML requests
- Does not support encrypted SAML requests
## License
This project is licensed under the MIT license. See the [LICENSE](https://github.com/mdeous/plasmid/blob/main/LICENSE) file for more information.