Version history

Version Date Notes

0.1 2025-Q1 First pilot draft

0.2

2026-02-05

Explicit target handling added
Introduced target_value to explicitly define the value sent via target_parameter. If either field is present, both are now required.

Support for relative target paths
target_value now supports absolute URIs as well as absolute-path references starting with /, optionally including query and fragment.

Improved validation of link map login URLs
In link_mapping, login URLs are now strictly required to be HTTPS, while IdP entityID keys may be any non-empty string (e.g. HTTPS URIs or URNs), due to legacy SAML entityID requirements.

Summary

The profile enables organizations to describe Service Providers (SPs) and their supported SSO mechanisms in a machine-readable format, using JSON. It supports two main SSO link types:

EntityID-based login: Relies on the identity provider’s entityID and parameters such as idp_parameter, target_parameter, and an SP-initiated login URL.
Link map-based login: Uses explicit mappings between known IdP entityIDs and proprietary login URLs.

Each metadata entry includes descriptive and branding information about the organization and its services, including display names, logos, and landing pages, facilitating consistent presentation in discovery services and login portals.

Metadata requirements

Organization Information (`organization_info`)

This section contains metadata about the organization offering the SSO services.

description REQUIRED (str)
- A short description of the organization and its services.
- Example: "An example description of the service provider organization".
display_name REQUIRED (str)
- A user-friendly name for the organization.
- Example: "Example Service Provider".
logotype REQUIRED (str, URL)
- The URL of the organization’s logo.
- Example: "https://example.com/logo.svg".
name REQUIRED (str)
- The official legal name of the organization.
- Example: "Example Service Provider AB".
url REQUIRED (str, URL)
- The official website of the organization.
- Example: "https://example.com".

List of SSO Links (`sso_links`)

This section contains a list of services that support SSO authentication.

Elements in each SSO link

description REQUIRED (str)
- A short description of the service.
- Example: "Example Digital Math Service is the number one digital math companion in Schengen".
disabled OPTIONAL (bool)
- Indicates whether the SSO link is disabled. If omitted, the value is presumed to be false.
- Possible values:
  - true → The service is disabled and not available to users.
  - false → The service is active and can be used.
- Example: false (the service is active).
display_name REQUIRED (str)
- The name of the service displayed to users.
- Example: "Math Rocket".
entity_id REQUIRED (str, URL)
- The entity ID of the service in the SAML federation.
- Example: "https://example.com/math".
logo REQUIRED (str, URL)
- The URL of the service’s logo.
- Example: "https://example.com/math/logo.svg".
sso_type REQUIRED (str)
- The type of SSO configuration used for the service.
- Possible values:
  - "entity_id" → Standard SAML SSO using an entity ID.
  - "link_map" → Direct mapping between Identity Providers (IdPs) and specific login URLs.
- Example: "entity_id" for traditional SAML SSO.
target_parameter OPTIONAL (str)
- The parameter used to pass a target address after authentication.
- Example: "Target".
target_value OPTIONAL (str)
- The value used to pass a target address after authentication.
- Example: "https://example.com/math/resource".

If either target_parameter or target_value is present, the other MUST also be present. target_value MAY be an absolute URI or an absolute-path reference starting with / optionally including query and fragment (relative to the service’s own origin).

If `sso_type` is `"entity_id"`

These fields are required for a standard SAML SSO setup using the entity ID as parameter for identifying the IdP.

idp_parameter REQUIRED (str)
- The parameter used to pass the IdP’s entity ID in the SSO request.
- Example: "entityID".
sp_init REQUIRED (str, URL)
- The URL for SP-initiated authentication.
- Example: "https://example.com/math/Shibboleth.sso/Login?".

If `sso_type` is `"link_map"`

Fields used when the service uses direct mapping between IdPs and specific login URLs

link_mapping REQUIRED (object)

A mapping where each IdP’s entity ID is used as a key, and the value is the specific login URL for that IdP.

Example:

"link_mapping": {
	"https://idp.example1.com": "https://example.com/bjj/login?idp=example1-idp",
	"https://idp.example2.com": "https://example.com/bjj/login?idp=example2-idp",
	"https://idp.example3.com": "https://example.com/bjj/login?idp=example3-idp"
},

Example metadata

[
  {
    "organization_info": {
      "description": "An example description of the service provider organization",
      "display_name": "Example Service Provider",
      "logotype": "https://example.com/logo.svg",
      "name": "Example Service Provider AB",
      "url": "https://example.com"
    },
    "sso_links": [
      {
        "description": "Example Digital Math Service is the number one digital math companion in Schengen",
        "disabled": false,
        "display_name": "Math Rocket",
        "entity_id": "https://example.com/math",
        "idp_parameter": "entityID",
        "logo": "https://example.com/math/logo.svg",
        "sp_init": "https://example.com/math/Shibboleth.sso/Login?",
        "sso_type": "entity_id",
        "target_parameter": "Target",
        "target_value": "https://example.com/math/resource"
      },
      {
        "description": "Example Digital Brazilian Jiu-Jitsu Service is the number one digital BJJ teacher in Schengen",
        "disabled": false,
        "display_name": "Example Digital Brazilian Jiu-Jitsu Service",
        "entity_id": "https://example.com/bjj",
        "link_mapping": {
          "https://idp.example1.com": "https://example.com/bjj/login?idp=example1-idp",
          "https://idp.example2.com": "https://example.com/bjj/login?idp=example2-idp",
          "https://idp.example3.com": "https://example.com/bjj/login?idp=example3-idp"
        },
        "logo": "https://example.com/bjj/logo.png",
        "sso_type": "link_map"
      }
    ]
  }
]

JSON schema

JSON schema for validating metadata:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "organization_info": {
        "type": "object",
        "properties": {
          "description": { "type": "string" },
          "display_name": { "type": "string" },
          "logotype": { "type": "string", "format": "uri" },
          "name": { "type": "string" },
          "url": { "type": "string", "format": "uri" }
        },
        "required": ["description", "display_name", "logotype", "name", "url"],
        "additionalProperties": false
      },
      "sso_links": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "description": { "type": "string" },
            "disabled": { "type": "boolean" },
            "display_name": { "type": "string" },
            "entity_id": { "type": "string", "format": "uri" },
            "idp_parameter": { "type": "string" },
            "logo": { "type": "string", "format": "uri" },
            "sp_init": { "type": "string", "format": "uri" },
            "sso_type": { "type": "string", "enum": ["entity_id", "link_map"] },
            "target_parameter": { "type": "string" },
            "target_value": { "$ref": "#/definitions/uriOrRelativePath" },
            "link_mapping": {
              "type": "object",
              "minProperties": 1,
              "patternProperties": {
                ".*": { "type": "string", "format": "uri", "pattern": "^https://" }
              },
              "additionalProperties": false,
              "propertyNames": { "type": "string", "minLength": 1 }
            }
          },
          "required": ["description", "display_name", "entity_id", "logo", "sso_type"],
          "anyOf": [
            {
              "properties": { "sso_type": { "const": "entity_id" } },
              "required": ["idp_parameter", "sp_init"]
            },
            {
              "properties": { "sso_type": { "const": "link_map" } },
              "required": ["link_mapping"]
            }
          ],
          "allOf": [
            {
              "if": { "required": ["target_parameter"] },
              "then": { "required": ["target_value"] }
            },
            {
              "if": { "required": ["target_value"] },
              "then": { "required": ["target_parameter"] }
            }
          ],
          "additionalProperties": false
        }
      }
    },
    "required": ["organization_info", "sso_links"],
    "additionalProperties": false
  },
  "definitions": {
    "uriOrRelativePath": {
      "anyOf": [
        { "type": "string", "format": "uri" },
        { "type": "string", "pattern": "^/(?!/)[^\\s]*$" }
      ]
    }
  }
}