SAML 2.0

Overview

JustIAM acts as a SAML 2.0 Identity Provider (IdP). Service providers (SPs) redirect users to JustIAM for authentication, which issues signed SAML assertions back to the SP.

---

Endpoints

Purpose	URL
IdP Metadata	GET /saml/{app_id}/metadata
SP-initiated SSO	GET /saml/{app_id}/sso
IdP-initiated SSO	GET /saml/{app_id}/launch
Single Logout	POST /saml/{app_id}/slo

{app_id} is the application UUID visible in the admin UI.

---

IdP Metadata

Provide this URL to the SP during setup. It contains:

• IdP Entity ID (OIDC_ISSUER/saml/{app_id}/metadata)
• SSO service endpoint (/saml/{app_id}/sso)
• SLO service endpoint (/saml/{app_id}/slo)
• IdP signing certificate (X.509)

GET /saml/{app_id}/metadata

---

SP-Initiated SSO Flow

1. User accesses SP
2. SP → redirect to GET /saml/{app_id}/sso?SAMLRequest=<encoded>
3. JustIAM checks SSO session; shows login page if needed; applies MFA
4. JustIAM → POST to ACS URL with SAMLResponse
5. SP validates response; grants access

The SAMLRequest is a deflate+base64-encoded AuthnRequest XML.

---

IdP-Initiated SSO Flow

GET /saml/{app_id}/launch

The user must already be logged in (valid idp_sid cookie). JustIAM generates an assertion immediately and POST-binds it to the ACS URL.

This endpoint is linked from the My Apps portal for SAML applications.

---

Assertions

Assertions are signed with JustIAM's RSA key (RS256/SHA-256). The assertion includes:

• Subject — <NameID> with the configured format and attribute
• Conditions — audience restriction + NotBefore/NotOnOrAfter validity window
• Authentication statement — PasswordProtectedTransport context
• Attribute statement — SAML attributes from the configured attribute mappings

---

Configuring the SP

Give the SP:

1. IdP Metadata URL: https://justiam.example.com/saml/{app_id}/metadata
   Or download the XML and upload it manually.
2. SSO URL: https://justiam.example.com/saml/{app_id}/sso
3. Entity ID: Same as the metadata URL, or just https://justiam.example.com
4. Certificate: Download from the metadata XML — the SP needs this to verify assertion signatures.

---

Configuring JustIAM

See Applications — SAML for the full configuration reference.

Quick setup summary:

PUT /api/v1/applications/{id}/saml
{
  "entity_id":      "<sp-entity-id>",
  "acs_url":        "<sp-acs-url>",
  "name_id_format": "emailAddress",
  "sign_assertions": true,
  "attribute_mappings": [
    { "name": "email",      "value": "${email}",      "format": "basic" },
    { "name": "first_name", "value": "${first_name}", "format": "basic" },
    { "name": "groups",     "value": "${groups}",     "format": "basic" }
  ]
}

---

Single Logout

Send a signed LogoutRequest to POST /saml/{app_id}/slo.

JustIAM will: 1. Validate the request signature 2. Terminate the user's idp_sid SSO session 3. Send SAML SLO requests to all other active SAML apps for the user 4. Return a signed LogoutResponse

---

Security

• Assertions are always signed (default behaviour)
• Response envelope can optionally be signed (sign_response = true)
• Assertions can optionally be encrypted using the SP's public certificate (encrypt_assertions = true)
• SP-signed AuthnRequests are verified if sp_signing_cert is provided

---

Example: AWS IAM Identity Center

PUT /api/v1/applications/{id}/saml
{
  "entity_id": "urn:amazon:webservices",
  "acs_url": "https://signin.aws.amazon.com/saml",
  "name_id_format": "persistent",
  "name_id_attribute": "email",
  "sign_assertions": true,
  "attribute_mappings": [
    {
      "name": "https://aws.amazon.com/SAML/Attributes/Role",
      "value": "${role}",
      "format": "uri"
    },
    {
      "name": "https://aws.amazon.com/SAML/Attributes/RoleSessionName",
      "value": "${email}",
      "format": "basic"
    },
    {
      "name": "https://aws.amazon.com/SAML/Attributes/SessionDuration",
      "value": "43200",
      "format": "basic"
    }
  ]
}

Then create App Mappings with the full role ARN + principal ARN value for each team:

variable_name: aws_role_arn
value: arn:aws:iam::123456789012:role/Developers,arn:aws:iam::123456789012:saml-provider/JustIAM

Assign the mapping to the appropriate groups or users.

The ${role} template emits one AttributeValue per assigned App Mapping, which is what AWS requires when a user has multiple role assignments.