How to set up single sign on (SSO) for the Shoreline platform

SSO Setup and Multi-Federation User Guide

Overview

The Shoreline Execution Platform supports multi-federation Single Sign-On (SSO) using SAML 2.0, allowing multiple organizations to authenticate users through their own identity providers (IdPs) such as Azure AD, Okta, or other SAML-compliant services.
The system uses domain-based tenant routing to automatically direct users to the correct SSO configuration.

Architecture

The SSO implementation uses:

Multi-SAML Strategy for handling multiple identity providers
Domain-based routing to select the correct configuration
Encrypted certificate storage for enhanced security

Prerequisites

Before setting up SSO, ensure the following:

You have Super Admin or SSO Management permissions.
You can access your organization’s Identity Provider (IdP) admin console.
You’ve collected the following from your IdP:
- SAML Entry Point URL (SSO URL)
- Issuer/Entity ID
- X.509 Certificate (PEM format)
- Your organization’s email domain

Setting Up a New SSO Configuration

Step 1: Gather Information from Your Identity Provider

Parameter	Example	Description
Entry Point URL (SSO URL)	`https://login.microsoftonline.com/{tenant-id}/saml2` (Azure AD) `https://{your-org}.okta.com/app/{app-id}/sso/saml` (Okta)	The URL where SAML authentication is initiated.
Issuer/Entity ID	Typically a unique identifier in your IdP	Identifies the SAML application.
X.509 Signing Certificate	PEM (base64 encoded)	Used to verify signatures in SAML responses.
Email Domain	`acmecorp.com`	Used for domain-based routing.

Step 2: Configure Your Identity Provider

Required SAML Attributes / Claims

Claim Name	Source Attribute	Required	Description
`emailaddress`	`user.email`	✅ Yes	User’s email address
`givenname`	`user.givenName`	✅ Yes	User’s first name
`surname`	`user.surname`	✅ Yes	User’s last name
`company` / `department`	`user.companyName` or `user.department`	Optional (for provisioning)	Used for company or department assignment.

Callback URL

Set the Assertion Consumer Service (ACS) or Reply URL in your IdP to:

https://{your-platform-domain}/api/login/callback

Example:
https://app.shoreline.no/api/login/callback

Supported Signature Algorithms

Algorithm	Recommended	Status
SHA-1	❌	Deprecated (legacy support only)
SHA-256	✅	Recommended
SHA-512	✅	Supported

Step 3: Create SSO Configuration via API

Endpoint:
POST /api/sso-configurations

Headers:

Authorization: Bearer {your-jwt-token}
Content-Type: application/json

Request Body:

{
  "name": "Acme Corporation SSO",
  "domain": "acmecorp.com",
  "entryPoint": "https://login.microsoftonline.com/{tenant-id}/saml2",
  "issuer": "https://sts.windows.net/{tenant-id}/",
  "certificate": "-----BEGIN CERTIFICATE-----\nMIIDdzCCAl+gAwIBAgIEAgAAu...\n-----END CERTIFICATE-----",
  "signatureAlgorithm": "sha256",
  "callbackUrl": "https://app.shoreline.no/api/login/callback",
  "disableRequestedAuthnContext": false
}

Field Descriptions

Field	Type	Required	Description
`name`	string	✅	Friendly name for configuration
`domain`	string	✅	Email domain for routing
`entryPoint`	string	✅	IdP SAML SSO URL
`issuer`	string	✅	IdP Entity ID
`certificate`	string	✅	X.509 certificate (encrypted before storage)
`signatureAlgorithm`	enum	❌	One of: `sha1`, `sha256`, `sha512`
`callbackUrl`	string	✅	ACS / Reply URL
`disableRequestedAuthnContext`	boolean	❌	Use `true` if IdP doesn’t support AuthnContext

Response:

{
  "success": true,
  "message": "SSO configuration created successfully",
  "data": {
    "id": 1,
    "name": "Acme Corporation SSO",
    "domain": "acmecorp.com",
    "entryPoint": "https://login.microsoftonline.com/{tenant-id}/saml2",
    "issuer": "https://sts.windows.net/{tenant-id}/",
    "callbackUrl": "https://app.shoreline.no/api/login/callback",
    "signatureAlgorithm": "sha256",
    "disableRequestedAuthnContext": false,
    "createdAt": "2025-11-07T09:00:00.000Z",
    "updatedAt": "2025-11-07T09:00:00.000Z"
  }
}

⚠️ Note: The certificate is encrypted and not returned in API responses.

How Multi-Federation Works

Domain-Based Routing

User enters email (john.doe@acmecorp.com)
Platform extracts domain (acmecorp.com)
Looks up corresponding SSO configuration
Redirects to the associated IdP

Authentication Flows

1. SP-Initiated Flow

User → Platform Login Page
     ↓
Platform → IdP Redirect
     ↓
IdP → User Authentication
     ↓
SAML Response → Platform Callback
     ↓
Platform → Validate + Session Creation

2. IdP-Initiated Flow

User → IdP Portal
     ↓
IdP → Sends SAML Response to Callback
     ↓
Platform → Validates + Authenticates User

Multi-Tenant Session Management

Step	Action
1	Temporary token created
2	JWT stored in server-side cache (5 min TTL)
3	Token ID returned to frontend
4	Frontend exchanges token for JWT
5	Token invalidated after retrieval

Benefits:

Prevents JWT exposure in URLs
Enables single-use tokens
Ensures automatic expiry

Managing SSO Configurations

List All

GET /api/sso-configurations

Get by ID

GET /api/sso-configurations/:id

Check Domain Availability

GET /api/sso-configurations/check-domain?domain=acmecorp.com

Example Response:

{
  "success": true,
  "data": {
    "available": false,
    "domain": "acmecorp.com",
    "message": "Domain is already in use"
  }
}

Update

PUT /api/sso-configurations/:id

Body:

{
  "entryPoint": "https://new-idp-url.com/saml2",
  "signatureAlgorithm": "sha512"
}

Delete (Soft Delete)

DELETE /api/sso-configurations/:id

Sets deletedAt timestamp instead of hard deletion.

User Provisioning

Users from unconfigured domains must be manually created before SSO login succeeds.

Security Considerations

Certificate Encryption

All SAML certificates are encrypted at rest using the platform’s encryption utility.

Signature Algorithms

Use SHA-256 or SHA-512.
⚠️ SHA-1 is deprecated — use only if legacy systems require it.

Token Storage

JWTs not exposed in URLs
Temporary tokens expire after 5 minutes
Tokens are single-use

Permission Requirements

All /api/sso-configurations endpoints require:

manageSSO permission, or
Super Admin privileges

Troubleshooting

Error	Cause	Solution
"SSO configuration not found for domain"	Missing or misspelled domain	Verify configuration and domain spelling
"SAML validation error"	Certificate or algorithm mismatch	Re-upload valid certificate, check signature algorithm
"Login failed, email error"	User not provisioned	Manually create user or match IdP email
"Token expired / invalid"	Token timeout or reuse	Re-initiate login; ensure timely exchange

API Reference Summary

Endpoint	Method	Permission	Description
`/api/sso-configurations`	GET	manageSSO	List all configurations
`/api/sso-configurations/:id`	GET	manageSSO	Get configuration by ID
`/api/sso-configurations`	POST	manageSSO	Create new configuration
`/api/sso-configurations/:id`	PUT	manageSSO	Update configuration
`/api/sso-configurations/:id`	DELETE	manageSSO	Soft delete configuration
`/api/sso-configurations/check-domain`	GET	manageSSO	Check domain availability

Example: Azure AD Multi-Tenant SSO Setup

Step 1: Azure AD Configuration

Go to Azure Active Directory → Enterprise Applications
Click New Application → Create your own application
Name: Shoreline Execution Platform
Choose Non-gallery application
Click Create

Step 2: Configure SAML

Setting	Value
Identifier (Entity ID)	`https://app.shoreline.no`
Reply URL (ACS)	`https://app.shoreline.no/api/login/callback`

User Attributes & Claims:

emailaddress → user.mail
givenname → user.givenname
surname → user.surname
company → user.companyname
department → user.department

Download Certificate (Base64) and copy:

Login URL → Entry Point
Azure AD Identifier → Issuer

Step 3: Create Configuration

curl -X POST https://app.shoreline.no/api/sso-configurations \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Azure AD - Acme Corp",
    "domain": "acmecorp.com",
    "entryPoint": "https://login.microsoftonline.com/TENANT_ID/saml2",
    "issuer": "https://sts.windows.net/TENANT_ID/",
    "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "signatureAlgorithm": "sha256",
    "callbackUrl": "https://app.shoreline.no/api/login/callback",
    "disableRequestedAuthnContext": false
  }'

Step 4: Test

Go to login page
Enter test.user@acmecorp.com
Redirect to Azure AD
Authenticate
Redirected back to platform — ✅ logged in

Best Practices

Use SHA-256 or higher
Always test in staging before production
Track certificate expiration dates
Use clear configuration names
Document SAML claims per IdP
Enable audit logging for SSO events
Coordinate with IT admins during setup
Test both SP-initiated and IdP-initiated flows

Support

If issues occur:

Check platform logs for authentication errors
Verify IdP and platform configurations
Use SAML debugging tools
Contact Shoreline Support with:
- Domain used
- Error messages
- IdP screenshots

This guide describes how the multi-federation SSO system allows the Shoreline Execution Platform to support unlimited organizations, each with their own IdP, while maintaining security, flexibility, and ease of administration.