Applications — SAML 2.0¶

Overview¶

JustIAM can act as a SAML 2.0 Identity Provider (IdP) for any service provider (SP) that supports the SAML standard. Create an application with type = "saml" and then configure the SAML-specific settings.

Creating a SAML application¶

Step 1: Create a base application (same as OIDC):

POST /api/v1/applications
{
  "name": "AWS SSO",
  "friendly_name": "Amazon Web Services",
  "type": "saml",
  "access_restricted": true
}

friendly_name is optional. When set, the UI displays it instead of name.

Step 2: Configure SAML settings:

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,
  "sign_response": false,
  "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" }
  ]
}

Importing SP metadata¶

You can auto-populate entity_id and acs_url by providing the SP's metadata:

POST /api/v1/applications/{id}/saml/parse-metadata
{
  "metadata_url": "https://sp.example.com/saml/metadata"
}

Or upload the XML directly in the same endpoint as metadata_xml.

SAML configuration fields¶

Field	Default	Description
`entity_id`	—	SP entity ID (must be unique)
`acs_url`	—	Assertion Consumer Service URL
`slo_url`	—	SP Single Logout endpoint
`name_id_format`	`emailAddress`	NameID format sent in assertions
`name_id_attribute`	`email`	User attribute used as NameID value
`assertion_lifetime_secs`	`300`	Assertion validity window
`session_lifetime_secs`	`28800`	SSO session lifetime (8 hours)
`sign_assertions`	`true`	Sign individual assertions
`sign_response`	`false`	Sign the outer SAML response envelope
`encrypt_assertions`	`false`	Encrypt assertions using the SP's public cert
`sp_signing_cert`	—	PEM cert to verify SP-signed AuthnRequests
`sp_encryption_cert`	—	PEM cert used to encrypt assertions

NameID formats¶

Value	Description
`emailAddress`	`urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`
`persistent`	`urn:oasis:names:tc:SAML:2.0:nameid-format:persistent`
`transient`	`urn:oasis:names:tc:SAML:2.0:nameid-format:transient`
`unspecified`	`urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified`
`x509SubjectName`	`urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName`

Attribute mappings¶

Attribute mappings define which SAML attributes are included in assertions. Each mapping has:

Field	Description
`name`	SAML attribute name (URI or friendly name)
`value`	Template value (see below)
`format`	`basic`, `uri`, or `unspecified`

Template variables¶

Variable	Resolves to
`${email}`	User's email address
`${username}`	User's username
`${first_name}`	First name
`${last_name}`	Last name
`${name}`	Full name (`first last`)
`${id}`	User UUID
`${groups}`	All group names, space/comma separated
`${roles}`	All app role values, space/comma separated
`${group}`	Emits one `AttributeValue` per group (multi-value)
`${role}`	Emits one `AttributeValue` per app role (multi-value)
`${variable_name}`	Value from an App Mapping assigned to this user/group
(literal)	Static string included as-is

The ${role} variable is useful for AWS SAML SSO where each IAM role needs to be a separate AttributeValue.

IdP metadata¶

The IdP SAML metadata (entity descriptor, SSO endpoints, certificate) is available at:

GET /saml/{app_id}/metadata

Provide this URL to the SP during setup.

SSO flows¶

Flow	Entry point
SP-initiated	SP redirects to `GET /saml/{app_id}/sso?SAMLRequest=...`
IdP-initiated	User clicks app in portal → `GET /saml/{app_id}/launch`

Single Logout (SLO)¶

JustIAM supports SP-initiated and IdP-initiated SLO. On logout, JustIAM also sends SAML SLO requests to all other active SAML applications for the user.

SLO endpoint: POST /saml/{app_id}/slo

MFA policy¶

Same per-application MFA override as OIDC apps. See the OIDC apps page.

Assertion simulator¶

The assertion simulator lets you preview the exact SAML assertion attributes a user would receive — including attribute mappings and attribute script patches — without triggering a real SSO flow.

To open it, click the flask icon (🧪) in the Applications table row for any SAML app.

What it simulates¶

Attribute mappings configured on the SAML application (including per-group, per-role, and app-mapping-based values)
Output from the attribute script (if configured), applied on top of the base attributes

The response attributes mirror the XML assertion structure: each entry represents one <Attribute> element and values lists each <AttributeValue> child.

API¶

POST /api/v1/applications/{id}/simulate
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "user_id": "<user-uuid>"
}

Response:

{
  "type": "saml",
  "has_access": true,
  "name_id": "alice@example.com",
  "name_id_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "attributes": [
    { "name": "email",  "values": ["alice@example.com"] },
    { "name": "groups", "values": ["engineering", "admins"] }
  ],
  "script_error": "<only present if the attribute script fails>"
}

has_access is false when the application has Access restricted enabled and the user is not in any allowed group or has no explicit grant.