OpenID Shared Signals Framework Specification 1.0

Workgroup:
Shared Signals

Published:
29 August 2025

Authors:
A. Tulshibagwale (SGNL)
T. Cappalli (Okta)
M. Scurtescu (Coinbase)
A. Backman (Amazon)
J. Bradley (Yubico)
S. Miel (Cisco)

Abstract

この Shared Signals Framework (SSF) は、協調する相手同士の間でシグナルやイベントを共有できるようにします。これにより、Risk Incident Sharing and Coordination (RISC) や Continuous Access Evaluation Profile (CAEP) など、複数のアプリケーションを実現できます。

この仕様は、次を定義します。

Security Event Tokens のためのプロファイル
Subject principals
SSF イベントにおける Subject claims
イベント種別
イベント
Receiver が利用するための Transmitter Configuration Metadata と、そのディスカバリ方法
Event Streams のための管理 API

また、この仕様は複数の IETF Security Events 仕様を直接プロファイルします。

Security Event Token (SET)
Subject Identifiers for Security Event Tokens
Push-Based Security Event Token (SET) Delivery Using HTTP
Poll-Based Security Event Token (SET) Delivery Using HTTP

1. はじめに

1.1. 表記規約

この文書中のキーワード "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", "OPTIONAL" は、ここに示すとおり大文字で表記された場合に限り、BCP 14（RFC2119 および RFC8174）で記述されているとおりに解釈されます。

2. Subject Principals

この Shared Signals Framework 仕様は、Subject Principal を、Shared Signals Framework を用いて Transmitter がイベントを送信し、Receiver が受信できる対象となるエンティティとして定義します。

Subject Principals は、SSF の Transmitter または Receiver において管理されるエンティティです。これには、人間またはロボットの principal、デバイス、マルチテナントサービスにおける顧客テナント、テナント内の組織単位、Subject principal のグループ、あるいは Transmitter と Receiver が管理するその他のエンティティが含まれます。Subject Principal として扱える他のアクターやリソースが存在する場合もあり、イベント種別の定義では、そのイベントが対象とする principal の範囲を明記すべきです。

Subject Principals は、後述の Subject Members によって識別されます。

3. SSF Events における Subject Members

3.1. Subject Members

SSF イベントの Subject Member は、イベントの subject を記述します。イベントの主要な subject を記述するために、sub_id という名前のトップレベル claim を MUST 使用します。

3.1.1. 既存の CAEP および RISC イベント

CAEP および RISC の仕様ですでに定義されているイベント種別は、SSF イベントの events claim 内の subject フィールドを用いて、イベントの主要な Subject Principal を記述してもかまいません。SSF Transmitter は、これら既存のイベント種別であっても、トップレベルの sub_id claim を MUST 含めなければなりません。

3.1.2. 新しいイベント種別

新しいイベント種別は、トップレベルの sub_id claim を MUST 使用し、主要な Subject Principal を記述するために events claim 内の subject フィールドを MUST NOT 使用しなければなりません。

3.1.3. 追加の Subject Members

特定のイベント種別は、そのイベント種別における追加の subject（例: Transferee）を記述する必要がある場合、追加の Subject Members を定義してもかまいません。これら追加の subject フィールドは、任意のフィールド名を持ってもかまいません。

3.1.4. Subject Member の値

各 Subject Member は、ちょうど 1 つの Subject Principal を参照しなければなりません。Subject Member の値は、「simple subject」または「complex subject」であってもかまいません。

3.2. Simple Subject Members

Simple Subject Member は、claim 名と、Subject Identifiers for Security Event Tokens で定義される「Subject Identifier」である値を持ちます。以下は、SSF イベントにおける Simple Subject Member の非規範的な例です。

"sub_id": {
  "format": "email",
  "email": "foo@example.com"
}

Figure 1: Example: Simple Subject

3.3. Complex Subject Members

Complex Subject Member は、名前と、format フィールドを持ち、1 つ以上の Simple Subject Members を含む JSON オブジェクトの値を持ちます。format フィールドの名前は "format" で、その値は "complex" です。この値に含まれる各 Simple Subject Member の名前は、次のいずれかであってもかまいません。

user

OPTIONAL. ユーザーを識別する Subject Identifier。

device

OPTIONAL. デバイスを識別する Subject Identifier。

session

OPTIONAL. セッションを識別する Subject Identifier。

application

OPTIONAL. アプリケーションを識別する Subject Identifier。

tenant

OPTIONAL. テナントを識別する Subject Identifier。

org_unit

OPTIONAL. 組織単位を識別する Subject Identifier。

group

OPTIONAL. グループを識別する Subject Identifier。

Complex Subjects では、追加の Subject Member 名を使用してもかまいません。各 member 名は、Complex Subject の値の中に最大 1 回まで出現してもかまいません。

以下は、SSF イベントにおける Complex Subject claim の非規範的な例です。

"sub_id": {
  "format": "complex",
  "user": {
    "format": "email",
    "email": "bar@example.com"
  },
  "tenant": {
    "format": "iss_sub",
    "iss": "https://example.com/idp1",
    "sub": "1234"
  }
}

Figure 2: Example: Complex Subject

3.3.1. Complex Subject の解釈

Complex Subject 内のすべての member は、同一の Subject Principal の属性を表していなければなりません。Complex Subject 全体として、ちょうど 1 つの Subject Principal を参照しなければなりません。

Complex Subject 内の未指定 claim をワイルドカードとして解釈する方法の詳細は、Subject Matching のセクション（Section 8.1.3.1）を参照してください。

3.4. SSF Events における Subject Identifiers

SSF イベントにおける Subject Identifier は、次のいずれかである識別子フォーマットを持たなければなりません。

Subject Identifiers for Security Event Tokens で定義される IANA Registry に定義されているもの
後述の Additional Subject Identifier Formats（Section 3.5）で定義される識別子フォーマット、または
当事者間で合意された独自の subject identifier フォーマット。独自フォーマットを持つ subject identifier 内の member は当事者間で合意されるものであり、その合意は本仕様のスコープ外です。

3.5. Additional Subject Identifier Formats

次の新しい subject identifier フォーマットを定義します。

3.5.1. JWT ID Subject Identifier Format

"JWT ID" Subject Identifier Format は、RFC7519 で定義される JSON Web Token (JWT) の識別子を指定します。この型の Subject Identifiers は、次の member を MUST 含めなければなりません。

iss

REQUIRED. 識別対象の JWT の "iss"（issuer）claim。

jti

REQUIRED. 識別対象の JWT の "jti"（JWT token ID）claim。

"JWT ID" Subject Identifier Format は、名前 "jwt_id" によって識別されます。

以下は、"jwt_id" Subject Identifier Format の Subject Identifier の非規範的な例です。

{
  "format": "jwt_id",
  "iss": "https://idp.example.com/123456789/",
  "jti": "B70BA622-9515-4353-A866-823539EECBC8"
}

Figure 3: Example: 'jwt_id' Subject Identifier

3.5.2. SAML Assertion ID Subject Identifier Format

"SAML Assertion ID" Subject Identifier Format は、SAML 2.0（OASIS.saml-core-2.0-os）assertion の識別子を指定します。このフォーマットの Subject Identifiers は、次の member を MUST 含めなければなりません。

issuer

REQUIRED. 識別対象の SAML assertion の "Issuer" 値。

assertion_id

REQUIRED. 識別対象の SAML assertion の "ID" 値。

"SAML Assertion ID" Subject Identifier Format は、名前 "saml_assertion_id" によって識別されます。

以下は、"saml_assertion_id" Subject Identifier Format の Subject Identifier の非規範的な例です。

{
  "format": "saml_assertion_id",
  "issuer": "https://idp.example.com/123456789/",
  "assertion_id": "_8e8dc5f69a98cc4c1ff3427e5ce34606fd672f91e6"
}

Figure 4: Example: 'saml_assertion_id' Subject Identifier

3.5.3. IP Addresses Subject Identifier Format

"IP addresses" Subject Identifier Format は、Transmitter によって観測された IP アドレスの配列を指定します。このフォーマットの Subject Identifiers は、次の member を MUST 含めなければなりません。

ip-addresses

REQUIRED. Transmitter によって観測された subject の IP アドレスの配列。値は文字列の配列で MUST あり、各文字列は IP アドレスの RFC4001 文字列表現でなければなりません。

"IP addresses" Subject Identifier Format は、名前 "ip-addresses" によって識別されます。

以下は、"IP addresses" Subject Identifier Format の Subject Identifier の非規範的な例です。

{
  "format": "ip-addresses",
  "ip-addresses": ["10.29.37.75", "2001:0db8:0000:0000:0000:8a2e:0370:7334"]
}

Figure 5: Example: 'ip-addresses' Subject Identifier

3.6. Receiver における subject の処理

SSF Receiver は、SSF イベント内の Subject から得られるすべての member を処理するために最善の努力を MUST 行わなければなりません。後述の Transmitter Configuration Metadata（Section 7.1）は、Complex Subject 内の特定の member を Critical として定義してもかまいません。SSF Receiver は、処理できない Critical member を含む Subject を持つイベントを、MUST 破棄しなければなりません。

4. Events

4.1. Security Event Token Profile

Shared Signals Framework は、SET の特定の性質をこのセクションで説明するとおりに定義することで、Security Event Token (SET) 仕様（RFC8417）をプロファイルします。

4.1.1. SET の明示的な型付け

SSF イベントは、RFC8417 の Section 2.3 で定義される明示的な型付けを MUST 使用しなければなりません。

{
  "typ": "secevent+jwt",
  "alg": "HS256"
}

Figure 6: Explicitly Typed JOSE Header

目的は、RFC8417 の Section 4.5、4.6、4.7 に記述されるとおり、他の JWT との混同に対する防御です。現時点の ID Token（OpenID.Core）バリデータは "typ" ヘッダーパラメータを使用していないかもしれませんが、SSF の SET に対してこれを必須にすることで、将来のバリデータに対しても区別可能な値が保証されます。

4.1.2. SSF Event Subject

SSF イベントにおける主要な Subject Member は、「Subject Members」セクション（Section 3）で説明されます。JWT の "sub" claim は、SSF イベントを含むいかなる SET にも MUST NOT 含まれてはなりません。

4.1.3. 他種の JWT と SET を区別すること

特に懸念されるのは、SET が他種の JWT と混同される可能性です。RFC8417 の Section 4 にはこの主題に関する複数の下位セクションがあります。Shared Signals Framework は、追加の制約を要求します。

"sub" claim は、Section 4.1.2 で説明したとおり MUST NOT 含まれてはなりません。
SSF の SET は、Section 4.1.1 で説明したとおり明示的な型付けを MUST 使用しなければなりません。
"exp" claim は、Section 4.1.7 で説明したとおり MUST NOT 含まれてはなりません。

4.1.4. Signature Key Resolution

署名鍵は "jwks_uri" を通じて取得できます。Section 7 を参照してください。

4.1.5. SSF Prescriptive SETs

Shared Signals Framework は、各デプロイまたは統合がイベント処理の振る舞いを定義できるようにします。その範囲は、情報提供としての入力から、追加の処理が必要なもの、強制的な適用が必要なものまで多岐にわたります。

4.1.6. "iss" Claim

"iss" claim は、そのイベントが送信されるストリームの Stream Configuration データ内の "iss" 値と一致しなければなりません。Receiver は、この claim が Stream Configuration データ内の "iss" と一致すること、さらに Receiver が Transmitter Configuration データを要求した Issuer と一致することを MUST 検証しなければなりません。

4.1.7. "exp" Claim

"exp" claim は、SET では MUST NOT 使用してはなりません。

目的は、RFC8417 の Section 4.5 および 4.6 に記述されるとおり、他種の JWT との混同に対する多層防御（defense in depth）です。

4.1.8. "aud" Claim

"aud" claim は、単一の文字列でも文字列の配列でもかまいません。当事者間でフォーマットについて合意がある場合、Transmitter に対して Receiver を一意に識別する値を使用してもかまいません。

対応する Receiver が同一エンティティであることを Transmitter が把握している場合（例: 同一アプリケーションの web client と mobile client）、複数の値を含めてもかまいません。この場合、すべての Receiver は同一の配信方法を MUST 使用しなければなりません。

複数の Receiver がまったく同一の配信設定を持つものの、それらが同一エンティティに属するかどうかを Transmitter が把握できない場合、Transmitter は Receiver ごとに別々の SET を SHOULD 発行し、個別に配信すべきです。この場合、複数の Receiver が同一のサービスを用いて SET を処理し、そのサービスが各 Receiver に対して SET を振り分けることがありますが、複数の Receiver を含む "aud" claim は意図しないデータ開示につながります。

{
  "jti": "123456",
  "iss": "https://transmitter.example.com",
  "aud": ["receiver.example.com/web", "receiver.example.com/mobile"],
  "iat": 1493856000,
  "txn": "8675309",
  "sub_id": {
    "format": "opaque",
    "id": "72e6991badb44e08a69672960053b342"
  },
  "events": {
    "https://schemas.openid.net/secevent/ssf/event-type/verification": {
      "state": "VGhpcyBpcyBhbiBleGFtcGxlIHN0YXRlIHZhbHVlLgo="
    }
  }
}

Figure 7: Example: SET with array 'aud' claim

4.1.9. "txn" claim

Transmitter は、SET に "txn" claim 値を設定することが推奨されます。値が存在する場合、それは Transmitter が SET を生成する原因となった基底のイベントに対して一意で MUST なければなりません。ただし Transmitter は、session revoked と credential change のように、複数の SET にわたって同一の "txn" claim 値を使用してもかまいません。これは、それらの SET が同一の基底原因または理由に由来することを示すためです。

4.2. Event Properties

4.2.1. "events" claim

"events" claim は、1 つのイベントのみを含めることが推奨されます。複数の event type URI が許されるのは、それらがまったく同一のイベント種別を定義する代替 URI である場合に限られます。イベントの種別は、events claim の値におけるキーによって指定されます。このフィールドの値はイベントオブジェクトです。

4.2.2. イベント種別固有フィールド

events claim 内のイベントオブジェクトは、イベント種別によって一意に定まる 1 つ以上のフィールドを持ってもかまいません。

4.2.3. 追加フィールド

Transmitter は、SSF イベントに追加フィールドを含めてもかまいません。これらのフィールドは、SET のどこに存在してもよく、"events" claim 内のイベントオブジェクト内にあってもかまいません。Receiver は、受信した SSF イベントのうち理解できないフィールドを MUST 無視しなければなりません。

5. Shared Signals Framework に適合する SET の例

以下は、Shared Signals Framework に適合する SET の仮想的な例です。

{
  "iss": "https://idp.example.com/",
  "jti": "756E69717565206964656E746966696572",
  "iat": 1520364019,
  "txn": "8675309",
  "aud": "636C69656E745F6964",
  "sub_id": {
    "format": "email",
    "email": "foo@example.com"
  },
  "events": {
    "https://schemas.openid.net/secevent/risc/event-type/account-enabled": {}
  }
}

Figure 8: Example: SET Containing an SSF Event with a Simple Subject Member

{
  "iss": "https://idp.example.com/",
  "jti": "756E69717565206964656E746966696572",
  "iat": 1520364019,
  "txn": "8675309",
  "aud": "636C69656E745F6964",
  "sub_id": {
    "format": "phone_number",
    "phone_number": "+1 206 555 0123"
  },
  "events": {
    "https://schemas.openid.net/secevent/risc/event-type/account-disabled": {
      "reason": "hijacking"
    }
  }
}

Figure 9: Example: SET Containing a RISC Event with a Phone Number Subject

{
  "iss": "https://idp.example.com/",
  "jti": "756E69717565206964656E746966696572",
  "iat": 1520364019,
  "txn": "8675309",
  "aud": "636C69656E745F6964",
  "sub_id": {
    "format": "email",
    "email": "user@example.com"
  },
  "events": {
    "https://schemas.openid.net/secevent/caep/event-type/token-claims-change": {
      "claims": {
        "token": "some-token-value"
      }
    }
  }
}

Figure 10: Example: SET Containing a CAEP Event with Properties

{
  "iss": "https://idp.example.com/",
  "jti": "756E69717565206964656E746966696572",
  "iat": 1520364019,
  "txn": "8675309",
  "aud": "636C69656E745F6964",
  "sub_id": {
    "format": "complex",
    "user": {
      "format": "iss_sub",
      "iss": "https://idp.example.com/3957ea72-1b66-44d6-a044-d805712b9288/",
      "sub": "jane.smith@example.com"
    },
    "device": {
      "format": "iss_sub",
      "iss": "https://idp.example.com/3957ea72-1b66-44d6-a044-d805712b9288/",
      "sub": "e9297990-14d2-42ec-a4a9-4036db86509a"
    }
  },
  "events": {
    "https://schemas.openid.net/secevent/caep/event-type/session-revoked": {
      "initiating_entity": "policy",
      "reason_admin": {
        "en": "Policy Violation: C076E82F"
      },
      "reason_user": {
        "en": "Land speed violation.",
        "es": "Violacion de velocidad en tierra."
      },
      "event_timestamp": 1600975810
    }
  }
}

Figure 11: Example: SET Containing an SSF Event with a Complex Subject Member

{
  "iss": "https://sp.example2.com/",
  "jti": "756E69717565206964656E746966696572",
  "iat": 1520364019,
  "txn": "8675309",
  "aud": "636C69656E745F6964",
  "sub_id": {
    "format": "email",
    "email": "foo@example2.com"
  },
  "events": {
    "https://schemas.openid.net/secevent/caep/event-type/token-claims-change": {
      "event_timestamp": 1600975810,
      "claims": {
        "role": "ro-admin"
      }
    }
  }
}

Figure 12: Example: SET Containing an SSF Event with a Simple Subject and a Property Member

{
  "iss": "https://myservice.example3.com/",
  "jti": "756E69717565206964656E746966696534",
  "iat": 15203800012,
  "txn": "8675309",
  "aud": "636C69656E745F6324",
  "sub_id": {
    "format": "catalog_item",
    "catalog_id": "c0384/winter/2354122"
  },
  "events": {
    "https://schemas.openid.net/secevent/caep/event-type/token-claims-change": {
      "event_timestamp": 1600975810,
      "claims": {
        "role": "ro-admin"
      }
    }
  }
}

Figure 13: Example: SET Containing an SSF Event with a Proprietary Subject Identifier Format

6. Event Delivery

このセクションでは、SSF Events を配信するためにサポートされる方法を説明します。また、RFC8935 および RFC8936 仕様に対する SSF のプロファイリング仕様を提供します。

6.1. Stream Configuration Metadata

各配信方法は URI によって識別され、以下で "method" メタデータによって指定されます。

6.1.1. HTTP を用いた Push Delivery

このセクションでは、RFC8935 仕様に対する SSF のプロファイリング仕様を提供します。

method

"urn:ietf:rfc:8935"

endpoint_url

HTTP POST によってイベントが push される URL。これは Receiver によって設定されます。Receiver が 1 つの Transmitter から複数のストリームを使用し、SET を分離して保持する必要がある場合、各ストリームの URL を一意にすることが推奨されます。

authorization_header

endpoint_url が認可を要求する場合、receiver はストリームの作成または更新時にこの authorization header を提供すべきです。この値が存在する場合、Transmitter は endpoint_url へのすべての HTTP リクエストにおいて、この値を MUST 付与しなければなりません。

6.1.2. HTTP を用いた Poll Delivery

このセクションでは、RFC8936 仕様に対する SSF のプロファイリング仕様を提供します。

method

"urn:ietf:rfc:8936"

endpoint_url

イベントを取得できる URL。これは Transmitter によって指定されます。これらの URL は Receiver 間で再利用されてもかまいませんが、ある Receiver にとってはストリームごとに一意で MUST でなければなりません。

7. Transmitter Configuration Discovery

このセクションでは、Receiver が Transmitter Configuration Metadata を取得するための仕組みを定義します。

7.1. Transmitter Configuration Metadata

Transmitters は、自身の構成を説明するメタデータを持ちます。

spec_version

OPTIONAL. Transmitter が実装する implementer's draft または final specification のバージョンを識別するもの。これには、NAMINGCONVENTION 文書で説明される spec version の数値部分が含まれます。存在しない場合、Transmitter は本仕様の "1_0-ID1" バージョンに適合すると仮定されます。

以下は、Shared Signals Framework 1_0 の final specification を実装する Transmitter の非規範的な例です。

{
  "spec_version": "1_0"
}

Figure 14: Example: spec_version referring to the final 1_0 spec

issuer

REQUIRED. query または fragment を含まない https スキームの URL であり、Transmitter が自身の Issuer Identifier として主張するもの。これは、この Transmitter から発行される Security Event Tokens の iss claim 値と同一で MUST なければなりません。

jwks_uri

OPTIONAL. Transmitter の JSON Web Key Set（RFC7517）文書の URL。これは、Receiver が Transmitter からの署名を検証するために用いる署名鍵（複数可）を含みます。Transmitter が署名付き JWT の生成を意図する場合、この値は MUST 指定されなければなりません。この値が存在する場合、この URL は HTTP over TLS（RFC9110）を MUST 使用しなければなりません。

delivery_methods_supported

RECOMMENDED. サポートされる配信方法 URI のリスト。

configuration_endpoint

OPTIONAL. Configuration Endpoint の URL。この値が存在する場合、この URL は HTTP over TLS（RFC9110）を MUST 使用しなければなりません。

status_endpoint

OPTIONAL. Status Endpoint の URL。この値が存在する場合、この URL は HTTP over TLS（RFC9110）を MUST 使用しなければなりません。

add_subject_endpoint

OPTIONAL. Add Subject Endpoint の URL。この値が存在する場合、この URL は HTTP over TLS（RFC9110）を MUST 使用しなければなりません。

remove_subject_endpoint

OPTIONAL. Remove Subject Endpoint の URL。この値が存在する場合、この URL は HTTP over TLS（RFC9110）を MUST 使用しなければなりません。

verification_endpoint

OPTIONAL. Verification Endpoint の URL。この値が存在する場合、この URL は HTTP over TLS（RFC9110）を MUST 使用しなければなりません。

critical_subject_members

OPTIONAL. Complex Subject における member 名の配列。この配列が存在し、イベント内の Subject Member に含まれる場合、Receiver はそれを MUST 解釈しなければなりません。

authorization_schemes

OPTIONAL. Section 7.1.1 で定義される、サポートされる authorization scheme のプロパティを指定する JSON オブジェクト配列。構成のシームレスなディスカバリを可能にするため、サービス提供者は、適切なセキュリティ考慮のもとで、事前の認証なしに authorization_schemes 属性へアクセス可能にしておくことが推奨されます。

default_subjects

OPTIONAL. 新規に作成されるストリームのデフォルト動作を示す文字列。この値が存在する場合、値は "ALL" または "NONE" のいずれかで MUST なければなりません。提供されない場合、この点に関する Transmitter の振る舞いは規定されません。

"ALL" は、ストリームに適切なあらゆる subject がデフォルトでストリームに追加されることを意味します。Receiver は remove_subject_endpoint を通じてストリームから subject を削除してもよく、その場合それらの subject のイベントは送信されなくなります。Receiver は add_subject_endpoint を通じて、この方法で削除した subject を再追加してもよいです。
"NONE" は、デフォルトではいかなる subject も追加されないことを意味します。Receiver は add_subject_endpoint を通じてストリームへ subject を追加してもよく、その場合それらの subject のイベントのみが送信されます。Receiver は remove_subject_endpoint を通じて、この方法で追加した subject を削除してもよいです。

7.1.1. Authorization scheme

SSF は HTTP ベースのシグナル共有フレームワークであり、ストリーム構成 API を保護するために使用される認証および認可の方式には依存しません。SSF 固有の認証・認可方式は提供せず、協調する当事者同士の相互のセキュリティ考慮に依存します。

Transmitter Configuration Metadata の authorization_schemes キーは、Transmitter のストリーム管理 API に関連する認可情報を提供します。これらの authorization schemes は、Transmitter によってホストされる polling endpoint（RFC8936 の Poll-Based SET delivery で使用）を保護するためにも使用されるべきです。

spec_urn

REQUIRED. 使用されているプロトコル仕様を記述する URN。

Receiver は spec_urn に従った適切な資格情報を提示して Transmitter APIs を呼び出します。

以下は spec_urn の非規範的な例です。

{
  "spec_urn": "urn:ietf:rfc:6749"
}

Figure 15: Example: 'spec_urn' specifying the OAuth protocol for authorization

この場合、Receiver は Client Credentials Grant（RFC6749 の Section 4.4）を用いて access token を取得することができ、または Receiver と Transmitter に適した他の方法を用いてもかまいません。

7.2. Transmitter Configuration Metadata の取得

Transmitter が文書化した Issuer URL を用いて、Transmitter Configuration Metadata を取得できます。Receiver は、Issuer URL が信頼できるソースに由来し、https スキームを使用していることを確実にすべきです。

Discovery をサポートする Transmitters は、Issuer の host component と（存在する場合）path component の間に "/.well-known/ssf-configuration" という文字列を挿入して形成されるパスで JSON 文書を公開しなければなりません。".well-known" の構文と意味は RFC8615 で定義されます。"ssf-configuration" は、本仕様に適合する JSON 文書を指し、かつその文書は "application/json" content type を用いて返されなければなりません。

7.2.1. Transmitter Configuration Request

Transmitter Configuration Document は、前述のパスに対して HTTP "GET" リクエストで問い合わせなければなりません。

Issuer が path component を含まないため、Issuer "https://tr.example.com" に対して Transmitter Configuration Metadata を取得する場合、Receiver は次のリクエストを行います。

GET /.well-known/ssf-configuration HTTP/1.1
Host: tr.example.com

Figure 16: Example: Transmitter Configuration Request (without path)

Issuer 値に path component が含まれる場合、host component と path component の間に "/.well-known/ssf-configuration" を挿入する前に、末尾の "/" は MUST 削除されなければなりません。Issuer "https://tr.example.com/issuer1" に対して Transmitter Configuration Metadata を取得する場合、Receiver は次のリクエストを行います。

GET /.well-known/ssf-configuration/issuer1 HTTP/1.1
Host: tr.example.com

Figure 17: Example: Transmitter Configuration Request (with path)

path components を使うことで、ホスト 1 つにつき複数の issuer をサポートできます。これは、特定のマルチテナントホスティング構成では必要になります。この ".well-known" の使い方は、RFC8615 における使い方とは異なり、ホストに関する一般情報を提供するものではなく、ホスト 1 つにつき複数の issuer をサポートするためのものです。

7.2.2. RISC Transmitters との後方互換性

既存の RISC Transmitters は、Transmitter Configuration Metadata のパス component として "/ssf-configuration" の代わりに "/risc-configuration" を引き続き使用してもかまいません。Shared Signals Framework をサポートする新しいサービスは、この場所を Transmitter Configuration Metadata の公開に使用すべきではありません。例として、Transmitter "https://risc-tr.example.com" の Transmitter Configuration Metadata は、次のリクエストで取得してもかまいません。

GET /.well-known/risc-configuration HTTP/1.1
Host: risc-tr.example.com

Figure 18: Example: Transmitter Configuration Request for RISC Transmitters

7.2.3. Transmitter Configuration Response

レスポンスは、必要なすべての endpoint と公開鍵の場所情報を含む、Transmitter の構成に関する Claims の集合です。成功レスポンスは 200 OK HTTP status code を MUST 使用し、"application/json" content type を用いる JSON オブジェクトを返し、そのオブジェクトは Section 7.1 で定義される Metadata 値の部分集合である Claims の集合を member として含まなければなりません。その他の Claims が返されてもかまいません。

複数値を返す Claims は JSON 配列として表現されます。要素数が 0 の Claims はレスポンスから MUST 省略されなければなりません。

エラーレスポンスは、適用される HTTP status code を使用します。

以下は Transmitter Configuration Response の非規範的な例です。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "spec_version": "1_0",
  "issuer":
    "https://tr.example.com",
  "jwks_uri":
    "https://tr.example.com/jwks.json",
  "delivery_methods_supported": [
    "urn:ietf:rfc:8935",
    "urn:ietf:rfc:8936"],
  "configuration_endpoint":
    "https://tr.example.com/ssf/mgmt/stream",
  "status_endpoint":
    "https://tr.example.com/ssf/mgmt/status",
  "add_subject_endpoint":
    "https://tr.example.com/ssf/mgmt/subject:add",
  "remove_subject_endpoint":
    "https://tr.example.com/ssf/mgmt/subject:remove",
  "verification_endpoint":
    "https://tr.example.com/ssf/mgmt/verification",
  "critical_subject_members": ["tenant", "user"],
  "authorization_schemes": [
      {
        "spec_urn": "urn:ietf:rfc:6749"
      },
      {
        "spec_urn": "urn:ietf:rfc:8705"
      }
    ],
  "default_subjects": "NONE"
}

Figure 19: Example: Transmitter Configuration Response

7.2.4. Transmitter Configuration Validation

本仕様で定義される検証手順のいずれかが失敗した場合、検証に失敗した情報を必要とするあらゆる操作は MUST 中止されなければならず、検証に失敗した情報は MUST NOT 使用してはなりません。

返された "issuer" 値は、構成情報を取得するために直接使用された Issuer URL と同一で MUST なければなりません。これは、この Transmitter から発行される Security Event Tokens の "iss" Claim 値とも同一で MUST なければなりません。

8. Management API for SET Event Streams

Event Stream は、Transmitter から Receiver へイベントを伝達する方法の抽象です。Event Stream の構成は Transmitter と Receiver の共同管理であり、Transmitter からどの種別のイベントが送信されるか、そして Receiver がそのイベントをどのような仕組みで受信することを期待できるか、といった情報を保持します。Event Stream はまた、Receiver が関心を持つ Subjects を追跡し、それらの Subjects を持つイベントのみがストリーム上で送信されます。

このセクションでは、Event Transmitters が実装すべき HTTP API を定義します。これは Event Receivers が 1 つ以上の Event Streams を作成および削除するために使用できます。この API は、Event Stream の構成とステータスの問い合わせと更新、Subjects の追加と削除、ならびにそれらのストリームに対する verification のトリガーにも使用できます。

Transmitter と Receiver の間で信頼を確立する別の方法が存在しない限り、Stream Management API のすべての endpoint は RFC9110 に従って標準の HTTP 認証および認可方式を MUST 使用しなければなりません。この認可は、Receiver を 1 つ以上の stream ID と "aud" 値に関連付ける MUST があり、認可された Receiver のみが、関連付けられた Event Streams の詳細へアクセスまたは変更できるようにしなければなりません。

+------------+                +------------+
|            | Stream Config  |            |
| Event      <----------------+ Event      |
| Stream     |                | Receiver   |
| Management | Stream Status  |            |
| API        <----------------+            |
|            |                |            |
|            | Add Subject    |            |
|            <----------------+            |
|            |                |            |
|            | Remove Subject |            |
|            <----------------+            |
|            |                |            |
|            | Stream Updated |            |
|            +---------------->            |
|            |                |            |
|            | Verification   |            |
|            <----------------+            |
|            |                |            |
+------------+                +------------+

Figure 20: Event Stream Management API

Transmitters が Management API を実装することは OPTIONAL ですが、特に Stream Status を問い合わせる endpoint と Verification をトリガーする endpoint は実装することが推奨されます。

8.1. Event Stream Management

Event Receivers は、Event Stream Management API の endpoints へ HTTP リクエストを行うことで、Event Stream を介して受信するイベントの内容と、どの subjects についてイベントを受信したいかを管理します。

Transmitter と Receiver は、複数の Subject Principals に関する更新を 1 つの Event Stream で共有してもかまいません。Event Stream のステータスは、Transmitters と Receivers によって、Subject Principal ごとに独立して問い合わせ・管理されてもかまいません。

Event Stream Management API は Event Transmitter によって実装され、次の endpoints から構成されます。

Configuration Endpoint

Event Streams の作成と削除、および Event Stream の現在の構成の読み取りと更新に使用される endpoint。

Status Endpoint

Event Stream の現在のステータスの読み取りと更新に使用される endpoint。

Add Subject Endpoint

Event Stream に subjects を追加するために使用される endpoint。

Remove Subject Endpoint

Event Stream から subjects を削除するために使用される endpoint。

Verification Endpoint

Event Stream を介して Verification Event を送信するよう Event Transmitter に要求するために使用される endpoint。

Event Transmitter は、認証資格情報などから適用対象となる Event Streams の集合を特定できる仕組みを持つ限り、複数の Event Receivers に対して同じ URLs を endpoint として使用してもかまいません。そうした仕組みの定義は本仕様のスコープ外です。

8.1.1. Stream Configuration

Event Stream の構成は、Event Stream を介して送信される情報を記述する、Transmitter と Receiver の双方から提供されるデータの集合です。これは次のプロパティを持つ JSON オブジェクトとして表現されます。

stream_id

Transmitter-Supplied, REQUIRED. ストリームを一意に識別する文字列。Transmitter は、ストリーム作成時に、削除されていない各ストリームについて一意の ID を MUST 生成しなければなりません。Transmitters は、RFC3986 の Section 2.3 で説明される文字集合を用いて stream ID を生成することが推奨されます。

iss

Transmitter-Supplied, REQUIRED. query または fragment を含まない https スキームの URL であり、Transmitter が自身の Issuer Identifier として主張するもの。これは、この Transmitter から発行される Security Event Tokens の "iss" Claim 値と同一で MUST なければなりません。

aud

Transmitter-Supplied, REQUIRED. Event Receiver(s) を識別する audience claim（RFC7519 で定義される JSON Web Token (JWT)）を含む、文字列または文字列配列。このプロパティは更新できません。複数の Receivers が指定される場合、Transmitter はそれらの Receivers が同一のエンティティであることを把握しているべきです。

events_supported

Transmitter-Supplied, OPTIONAL. この Receiver に対して Transmitter がサポートするイベント集合を識別する URI の配列。省略される場合、Event Transmitters は、この集合を別の手段（例: オンラインドキュメントで公開）で Event Receiver に提供することが推奨されます。

events_requested

Receiver-Supplied, OPTIONAL. Receiver が要求したイベント集合を識別する URI の配列。Receiver は、理解でき、かつ対応できるイベントのみを要求すべきです。これは Receiver によって設定可能です。Transmitter は、理解できない配列要素を MUST 無視しなければなりません。この配列は空であるべきではありません。

events_delivered

Transmitter-Supplied, REQUIRED. Transmitter がストリームに含める MUST があるイベント集合を識別する URI の配列。これは "events_supported" と "events_requested" の共通部分の部分集合（真部分集合とは限らない）です。Receiver は、このフィールドで受け取った値をもとに、Transmitter からどのイベント種別を期待できるかを理解しなければなりません。

delivery

REQUIRED. SET 配信方法の構成パラメータを指定する name/value ペアの集合を含む JSON オブジェクト。実際の配信方法は、特別なキー "method" によって識別され、値は Section 6.1 で定義される URI です。

min_verification_interval

Transmitter-Supplied, OPTIONAL. verification リクエストの間に最低限経過しなければならない秒数を示す整数。Event Receiver がこれより高頻度で verification を要求した場合、Event Transmitter は 429 status code を返してもかまいません。Event Receiver がこの頻度を超えていない場合、Event Transmitter は 429 status code を返すべきではありません。

description

Receiver-Supplied, OPTIONAL. ストリームのプロパティを説明する文字列。複数ストリームを扱うシステムにおいて、人間がストリームを識別するために有用です。transmitter は、許容される最大長を超える部分を切り詰めてもかまいません。

inactivity_timeout

Transmitter-Supplied, OPTIONAL. ストリームの refreshable inactivity timeout（秒）。後述のとおり Receiver からの適格な活動がないまま timeout が経過した場合、Transmitter はストリームを pause、disable、または delete してもかまいません。構文は RFC6749 の Section A.14 における expires_in と同じです。

次は、適格な Receiver 活動を構成します。Transmitter がこれらの活動のいずれかを観測した場合、inactivity timeout のカウンタを MUST 再開始しなければなりません。

PUSH（RFC8935）配信方法で作成されたストリームの場合:
- Receiver が、そのストリームを参照する Event Stream Management API の任意の endpoint を呼び出すこと（Section 8）。

POLL（RFC8936）配信方法で作成されたストリームの場合:
- Receiver がストリーム内のイベントを取得するために Transmitter を poll すること。
- Receiver が、そのストリームを参照する Event Stream Management API の任意の endpoint を呼び出すこと（Section 8）。

Transmitter がストリームを pause または disable することを決定した場合、Section 8.1.2 で説明されるとおり、Receiver に Stream Updated Event を MUST 送信しなければなりません。

8.1.1.1. ストリームの作成

Transmitter から Receiver へイベントを伝達するために、Receiver はまず Event Stream を作成しなければなりません。Event Receiver は Configuration Endpoint に対して HTTP POST リクエストを行うことでストリームを作成します。有効なリクエストを受け取ると、Event Transmitter は "201 Created" レスポンスを返し、本文にストリーム構成の JSON 表現を含めます。Receiver はレスポンスを MUST 確認し、iss 値が Transmitter Configuration データを受け取った Issuer と一致することを確認しなければなりません。

ストリームがすでに存在し、かつ Transmitter が同一 Receiver に対して複数ストリームを許可する場合、Event Transmitter は新しい stream ID を MUST 返さなければなりません。Transmitter が同一 Receiver に対して複数ストリームを許可しない場合、HTTP status code "409 Conflict" を MUST 返さなければなりません。その後、Receiver は既存ストリーム構成を GET で取得し、必要であれば PATCH または PUT を用いて既存ストリーム構成を更新または置換してもかまいません。

HTTP POST リクエストには、Stream Configuration（Section 8.1.1）オブジェクトにおける Receiver-Supplied の値を含めてもかまいません。

events_requested
delivery
description

リクエストに delivery プロパティが含まれない場合、Transmitter は method が "urn:ietf:rfc:8936"（poll）であると MUST 仮定しなければなりません。Transmitter が Poll-Based Delivery をサポートする場合、レスポンスにこの method プロパティと endpoint_url プロパティを持つ delivery プロパティを MUST 含めなければなりません。Transmitter がその配信方法をサポートしない場合、HTTP Status Code "400 Bad Request" を返してもかまいません。

poll method の場合、endpoint_url 値は Transmitter によって供給されることに注意してください。

以下は Event Stream を作成するための非規範的なリクエスト例です。

POST /ssf/stream HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=

{
  "delivery": {
    "method": "urn:ietf:rfc:8935",
    "endpoint_url": "https://receiver.example.com/events"
  },
  "events_requested": [
    "urn:example:secevent:events:type_2",
    "urn:example:secevent:events:type_3",
    "urn:example:secevent:events:type_4"
  ],
  "description": "Stream for Receiver A using events type_2, type_3, type_4"
}

Figure 21: Example: Create Stream Request

以下は非規範的なレスポンス例です。

HTTP/1.1 201 Created
Content-Type: application/json

{
  "stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
  "iss": "https://tr.example.com",
  "aud": [
    "https://receiver.example.com/web",
    "https://receiver.example.com/mobile"
  ],
  "delivery": {
    "method": "urn:ietf:rfc:8935",
    "endpoint_url": "https://receiver.example.com/events"
  },
  "events_supported": [
    "urn:example:secevent:events:type_1",
    "urn:example:secevent:events:type_2",
    "urn:example:secevent:events:type_3"
  ],
  "events_requested": [
    "urn:example:secevent:events:type_2",
    "urn:example:secevent:events:type_3",
    "urn:example:secevent:events:type_4"
  ],
  "events_delivered": [
    "urn:example:secevent:events:type_2",
    "urn:example:secevent:events:type_3"
  ],
  "description": "Stream for Receiver A using events type_2, type_3, type_4"
}

Figure 22: Example: Create Stream Response

エラーは次の HTTP status codes で通知されます。

Code	Description
400	リクエストを parse できない場合
401	認可に失敗した、または欠落している場合
403	Event Receiver がストリーム作成を許可されていない場合
409	Transmitter が Receiver ごとの複数ストリームをサポートしない場合

8.1.1.1.1. Create Stream Response の検証

aud: Receiver は Create Stream Response の aud を検証すべきです。Transmitter と Receiver は audience 値について out of band に合意してもかまいません。audience 値がどのように合意されたとしても、Receiver はそれが期待どおりであることを確実にすべきです。

8.1.1.2. ストリーム構成の読み取り

Event Receiver は Configuration Endpoint に対して HTTP GET リクエストを行うことで、ストリームの現在の構成を取得します。有効なリクエストを受け取ると、Event Transmitter は "200 OK" レスポンスを返し、本文にストリーム構成の JSON 表現を含めます。Receiver はレスポンスを MUST 確認し、iss 値が Transmitter Configuration データを受け取った Issuer と一致することを確認しなければなりません。

GET リクエストには、正しい Event Stream を識別するために query parameter として "stream_id" を含めてもかまいません。"stream_id" parameter が欠落している場合、Transmitter はこの Receiver が利用可能なストリーム構成のリストを MUST 返さなければなりません。Event Streams が構成されていない場合、Transmitter は空リストを MUST 返さなければなりません。

以下は Event Stream 構成を読み取るための非規範的なリクエスト例です。

GET /ssf/stream?stream_id=f67e39a0a4d34d56b3aa1bc4cff0069f HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=

Figure 23: Example: Read Stream Configuration Request

以下は非規範的なレスポンス例です。

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
  "iss": "https://tr.example.com",
  "aud": [
    "https://receiver.example.com/web",
    "https://receiver.example.com/mobile"
  ],
  "delivery": {
    "method": "urn:ietf:rfc:8935",
    "endpoint_url": "https://receiver.example.com/events"
  },
  "events_supported": [
    "urn:example:secevent:events:type_1",
    "urn:example:secevent:events:type_2",
    "urn:example:secevent:events:type_3"
  ],
  "events_requested": [
    "urn:example:secevent:events:type_2",
    "urn:example:secevent:events:type_3",
    "urn:example:secevent:events:type_4"
  ],
  "events_delivered": [
    "urn:example:secevent:events:type_2",
    "urn:example:secevent:events:type_3"
  ],
  "description": "Stream for Receiver A using events type_2, type_3, type_4"
}

Figure 24: Example: Read Stream Configuration Response

"stream_id" を示さない、Event Stream 構成読み取りの非規範的なリクエスト例です。

GET /ssf/stream HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=

Figure 25: Example: Read Stream Configuration Request

"stream_id" がないリクエストに対する、非規範的なレスポンス例です。

[
  {
    "stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
    "iss": "https://tr.example.com",
    "aud": [
      "https://receiver.example.com/web",
      "https://receiver.example.com/mobile"
    ],
    "delivery": {
      "method": "urn:ietf:rfc:8935",
      "endpoint_url": "https://receiver.example.com/events"
    },
    "events_supported": [
      "urn:example:secevent:events:type_1",
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3"
    ],
    "events_requested": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3",
      "urn:example:secevent:events:type_4"
    ],
    "events_delivered": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3"
    ]
  },
  {
    "stream_id": "50b2d39934264897902c0581ba7c21a3",
    "iss": "https://tr.example.com",
    "aud": [
      "https://receiver.example.com/web",
      "https://receiver.example.com/mobile"
    ],
    "delivery": {
      "method": "urn:ietf:rfc:8935",
      "endpoint_url": "https://receiver.example.com/events"
    },
    "events_supported": [
      "urn:example:secevent:events:type_1",
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3"
    ],
    "events_requested": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3",
      "urn:example:secevent:events:type_4"
    ],
    "events_delivered": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3"
    ],
    "description": "Stream for Receiver A using events type_2, type_3, type_4"
  }
]

Figure 26: Example: Read Stream Configuration Response

Event Stream が 1 つだけ構成されている場合に、"stream_id" がないリクエストへ返す非規範的なレスポンス例です。

[
  {
    "stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
    "iss": "https://tr.example.com",
    "aud": [
      "https://receiver.example.com/web",
      "https://receiver.example.com/mobile"
    ],
    "delivery": {
      "method": "urn:ietf:rfc:8935",
      "endpoint_url": "https://receiver.example.com/events"
    },
    "events_supported": [
      "urn:example:secevent:events:type_1",
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3"
    ],
    "events_requested": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3",
      "urn:example:secevent:events:type_4"
    ],
    "events_delivered": [
      "urn:example:secevent:events:type_2",
      "urn:example:secevent:events:type_3"
    ]
  }
]

Figure 27: Example: Read Stream Configuration Response

Event Streams が構成されていない場合に、"stream_id" がないリクエストへ返す非規範的なレスポンス例です。

[]

Figure 28: Example: Read Stream Configuration Response

エラーは次の HTTP status codes で通知されます。

Code	Description
401	認可に失敗した、または欠落している場合
403	Event Receiver がストリーム構成の読み取りを許可されていない場合
404	この Event Receiver に対して指定された "stream_id" の Event Stream が存在しない場合

8.1.1.3. ストリーム構成の更新

Event Receiver は Configuration Endpoint に対して HTTP PATCH リクエストを行うことで、ストリームの現在の構成を更新します。PATCH の本文には、変更するストリーム構成プロパティの JSON 表現が含まれます。有効なリクエストを受け取ると、Event Transmitter は "200 OK" レスポンスを返し、本文に更新後のストリーム構成全体の JSON 表現を含めます。Receiver はレスポンスを MUST 確認し、iss 値が Transmitter Configuration データを受け取った Issuer と一致することを確認しなければなりません。

リクエストには stream_id プロパティを MUST 含めなければなりません。その他のプロパティを含めてもかまいません。リクエストに存在する Receiver-Supplied プロパティは、Transmitter によって MUST 更新されなければなりません。リクエストに存在しないプロパティは、Transmitter によって MUST NOT 変更されてはなりません。events_requested がリクエストに含まれる場合、それは空配列であるべきではありません。

stream_id 以外の Transmitter-Supplied プロパティが存在してもかまいませんが、それらは期待値と一致しなければなりません。欠落している Transmitter-Supplied プロパティは、Transmitter によって無視されなければなりません。events_delivered プロパティが存在する場合、更新が適用される前に、それは Transmitter の期待値と一致しなければなりません。

以下は Event Stream 構成を置換するための非規範的なリクエスト例です。

PATCH /ssf/stream HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=

{
  "stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
  "events_requested": [
    "urn:example:secevent:events:type_2",
    "urn:example:secevent:events:type_3",
    "urn:example:secevent:events:type_4"
  ],
  "description": "Stream for Receiver B using events type_2, type_3, type_4"
}

Figure 29: Example: Update Stream Configuration Request

以下は非規範的なレスポンス例です。

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
  "iss": "https://tr.example.com",
  "aud": [
    "https://receiver.example.com/web",
    "https://receiver.example.com/mobile"
  ],
  "delivery": {
    "method": "urn:ietf:rfc:8935",
    "endpoint_url": "https://receiver.example.com/events"
  },
  "events_supported": [
    "urn:example:secevent:events:type_1",
    "urn:example:secevent:events:type_2",
    "urn:example:secevent:events:type_3"
  ],
  "events_requested": [
    "urn:example:secevent:events:type_2",
    "urn:example:secevent:events:type_3",
    "urn:example:secevent:events:type_4"
  ],
  "events_delivered": [
    "urn:example:secevent:events:type_2",
    "urn:example:secevent:events:type_3"
  ],
  "description": "Stream for Receiver B using events type_2, type_3, type_4"
}

Figure 30: Example: Update Stream Configuration Response

保留条件またはエラーは次の HTTP status codes で通知されます。

Code	Description
202	更新リクエストは受理されたが未処理の場合。Receiver は後で同じリクエストを試して処理結果を取得してもよい。
400	リクエスト本文を parse できない、Transmitter-Supplied プロパティが不正、またはリクエストが不正な場合
401	認可に失敗した、または欠落している場合
403	Event Receiver がストリーム構成の更新を許可されていない場合
404	この Event Receiver に対して指定された "stream_id" の Event Stream が存在しない場合

8.1.1.4. ストリーム構成の置換

Event Receiver は Configuration Endpoint に対して HTTP PUT リクエストを行うことで、ストリームの現在の構成を置換します。PUT の本文には新しい構成の JSON 表現が含まれます。有効なリクエストを受け取ると、Event Transmitter は "200 OK" レスポンスを返し、本文に更新後のストリーム構成の JSON 表現を含めます。Receiver はレスポンスを MUST 確認し、iss 値が Transmitter Configuration データを受け取った Issuer と一致することを確認しなければなりません。

PUT 本文には、stream_id と Receiver-Supplied プロパティの完全な集合を MUST 含めなければならず、変更対象のみを含めるのではありません。欠落している Receiver-Supplied プロパティは削除要求として解釈されなければなりません。Event Receivers は、まず構成を読み取り、JSON 表現を修正し、その後に置換リクエストを行ってもかまいません。events_requested が含まれる場合、それは空配列であるべきではありません。

stream_id 以外の Transmitter-Supplied プロパティが存在してもかまいませんが、それらは期待値と一致しなければなりません。欠落している Transmitter-Supplied プロパティは、Transmitter によって無視されなければなりません。events_delivered プロパティが存在する場合、更新が適用される前に、それは Transmitter の期待値と一致しなければなりません。

以下は Event Stream 構成を置換するための非規範的なリクエスト例です。

PUT /ssf/stream HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=

{
  "stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
  "delivery": {
    "method": "urn:ietf:rfc:8935",
    "endpoint_url": "https://receiver.example.com/events"
  },
  "events_requested": [
    "urn:example:secevent:events:type_2",
    "urn:example:secevent:events:type_3",
    "urn:example:secevent:events:type_4"
  ],
  "description": "Stream for Receiver C"
}

Figure 31: Example: Replace Stream Configuration Request

以下は非規範的なレスポンス例です。

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
  "iss": "https://tr.example.com",
  "aud": [
    "https://receiver.example.com/web",
    "https://receiver.example.com/mobile"
  ],
  "delivery": {
    "method": "urn:ietf:rfc:8935",
    "endpoint_url": "https://receiver.example.com/events"
  },
  "events_supported": [
    "urn:example:secevent:events:type_1",
    "urn:example:secevent:events:type_2",
    "urn:example:secevent:events:type_3"
  ],
  "events_requested": [
    "urn:example:secevent:events:type_2",
    "urn:example:secevent:events:type_3",
    "urn:example:secevent:events:type_4"
  ],
  "events_delivered": [
    "urn:example:secevent:events:type_2",
    "urn:example:secevent:events:type_3"
  ],
  "description": "Stream for Receiver C"
}

Figure 32: Example: Replace Stream Configuration Response

保留条件またはエラーは次の HTTP status codes で通知されます。

Code	Description
202	置換リクエストは受理されたが未処理の場合。Receiver は後で同じリクエストを試して処理結果を取得してもよい。
400	リクエスト本文を parse できない、Transmitter-Supplied プロパティが不正、またはリクエストが不正な場合
401	認可に失敗した、または欠落している場合
403	Event Receiver がストリーム構成の置換を許可されていない場合
404	この Event Receiver に対して指定された "stream_id" の Event Stream が存在しない場合

8.1.1.5. ストリームの削除

Event Receiver は Configuration Endpoint に対して HTTP DELETE リクエストを行うことでストリームを削除します。リクエストを受け取ると、Event Transmitter は構成が正常に削除された場合、空の "204 No Content" レスポンスを返します。

DELETE リクエストは、正しい Event Stream を識別するために query parameter として "stream_id" を MUST 含めなければなりません。

以下は Event Stream を削除するための非規範的なリクエスト例です。

DELETE /ssf/stream?stream_id=f67e39a0a4d34d56b3aa1bc4cff0069f HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=

Figure 33: Example: Delete Stream Request

成功したリクエストに対する非規範的なレスポンス例です。

HTTP/1.1 204 No Content
Cache-Control: no-store

Figure 34: Example: Delete Stream Response

エラーは次の HTTP status codes で通知されます。

Code	Description
401	認可に失敗した、または欠落している場合
403	Event Receiver がストリーム削除を許可されていない場合
404	この Event Receiver に対して指定された "stream_id" の Event Stream が存在しない場合

8.1.2. Stream Status

Event Streams は独立して管理されます。Receiver は Stream Status を更新することにより（Section 8.1.2.2）、あるストリームからのイベントが中断されるよう要求してもかまいません。Transmitter が、Receiver からの更新要求とは独立に、ストリームからの更新を enable、pause、または disable することを決定した場合、Receiver に対して Stream Updated Event（Section 8.1.5）を MUST 送信しなければなりません。

8.1.2.1. ストリームステータスの読み取り

Event Receiver はストリームの Status Endpoint に対して HTTP GET リクエストを行うことで、Event Stream の現在のステータスを確認します。

Stream Status メソッドは次のパラメータを取ります。

stream_id

REQUIRED. ステータス照会対象のストリームを識別する文字列。

有効なリクエストを受け取ると、Event Transmitter は 200 OK レスポンスを返し、本文に次の属性を持つ JSON オブジェクトを含めます。

stream_id

REQUIRED. ステータス照会対象のストリームを識別する文字列。

status

REQUIRED. 値が後述のいずれかで MUST ある文字列。

reason

OPTIONAL. ストリームのステータスが現在値に設定されている理由を表すべき文字列。

許容される "status" 値は次のとおりです。

enabled

Transmitter は、ストリームに構成された配信方法に従い、ストリームを介してイベントを送信しなければなりません。

paused

Transmitter はストリームを介してイベントを送信してはなりません。Transmitter は paused の間に送信するはずだったイベントを保持し、ストリームのステータスが "enabled" になったときにそれらを送信することが推奨されます。Transmitter は、paused の間に保持されたイベントを 0 個以上破棄してもかまいません。Transmitter が同一の Subject Principal に影響する連続イベントを保持する場合、Transmitter は、それらのイベントが生成された時刻順に送信されるよう MUST 取り計らうか、または、以前のイベントが後続イベントにより取り消されている／古くなっているため Receiver が処理する必要がない場合に限り、最後のイベントのみを MUST 送信しなければなりません。

disabled

Transmitter はストリームを介してイベントを送信してはならず、後で送信するためにイベントを保持もしません。

以下は Event Stream のステータスを確認するための非規範的なリクエスト例です。

GET /ssf/status?stream_id=f67e39a0a4d34d56b3aa1bc4cff0069f HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=

Figure 35: Example: Check Stream Status Request

以下は非規範的なレスポンス例です。

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
  "status": "paused",
  "reason": "SYSTEM_DOWN_FOR_MAINTENANCE"
}

Figure 36: Example: Check Stream Status Response

エラーは次の HTTP status codes で通知されます。

Code	Description
401	認可に失敗した、または欠落している場合
403	Event Receiver がストリームステータスの読み取りを許可されていない場合
404	この Event Receiver に対して指定された "stream_id" の Event Stream が存在しない場合

Examples:

Receiver が未認可リクエストを行った場合、Transmitter は 401 エラーステータスを MUST 返さなければなりません。
Receiver が認可されたリクエストを行ったが、Transmitter のポリシーが Receiver にステータス取得を許可しない場合、Transmitter は 403 エラーステータスを返してもかまいません。
Receiver が存在しないストリームのステータスを要求した場合、Transmitter は 404 エラーステータスを MUST 返さなければなりません。

8.1.2.2. ストリームステータスの更新

Event Receiver は Status Endpoint に対して HTTP POST リクエストを行うことで、ストリームの現在のステータスを更新します。POST 本文には次のフィールドを持つ JSON オブジェクトが含まれます。

stream_id

REQUIRED. 更新対象のストリームを識別する文字列。

status

REQUIRED. Event Stream の新しいステータス。

reason

OPTIONAL. 変更理由を説明する短いテキスト。

有効なリクエストを受け取ると、Event Transmitter は "200 OK" レスポンスを返し、本文に更新後のストリームステータスの JSON 表現を含めます。フィールドはリクエストで説明されるものと同じです。

以下は Event Stream のステータスを更新するための非規範的なリクエスト例です。

POST /ssf/status HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=

{
  "stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
  "status": "paused"
}

Figure 37: Example: Update Stream Status Request Without Optional Fields

optional な reason を含む Update Stream Status リクエストの非規範的な例です。

POST /ssf/status HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=

{
  "stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
  "status": "paused",
  "reason": "Disabled by administrator action."
}

Figure 38: Example: Update Stream Status Request With Optional Reason

以下は非規範的なレスポンス例です。

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
  "status": "paused",
  "reason": "Disabled by administrator action."
}

Figure 39: Example: Update Stream Status Response

エラーは次の HTTP status codes で通知されます。

Code	Description
202	更新リクエストは受理されたが未処理の場合。Receiver は後で同じリクエストを試して処理結果を取得してもよい。
400	リクエスト本文を parse できない、またはリクエストが不正な場合
401	認可に失敗した、または欠落している場合
403	Event Receiver がストリームステータスの更新を許可されていない場合
404	この Event Receiver に対して指定された "stream_id" の Event Stream が存在しない場合

Examples:

Receiver がストリームステータスの更新リクエストを行い、Transmitter がそのリクエストを完了すべきかどうか判断できない場合、Transmitter は 202 status code を MUST 返さなければなりません。

8.1.3. Subjects

Event Receiver は、ある特定の subject についてイベントを受信したいかどうかを、Event Stream にその subject を「追加」または「削除」することで、それぞれ Event Transmitter に示すことができます。

8.1.3.1. Subject Matching

Receiver が Section 8.1.3.2 に定義されるストリームへ subject を追加した場合、Transmitter は、ストリームの status が enabled である限り、Receiver が購読した event_types を持つ、その subject に関するイベントを SHOULD 送信すべきです。Simple Subjects の場合、2 つの subject は完全に同一であれば一致します。Complex Subjects の場合、Complex Subject の各フィールド（user、group、device など）について、次のいずれかが成り立つときに一致します。

Subject 1 のフィールドが定義されていない
Subject 2 のフィールドが定義されていない
Subject 1 のフィールドが Subject 2 のフィールドと同一である

以下は、Receiver が、Transmitter が送信する subject よりも制約が緩い subject を追加した場合の、Complex Subjects における subject matching の非規範的な例です。

Receiver は次の subject を自分のストリームへ追加しています。

{
  "format": "complex",
  "tenant": {
    "format": "opaque",
    "id": "example-a38h4792-uw2"
  }
}

Transmitter は、次の subject を持つブロードキャスト対象のイベントを持っています。

{
  "format": "complex",
  "tenant": {
    "format": "opaque",
    "id": "example-a38h4792-uw2"
  },
  "user": {
    "format": "email",
    "email": "jdoe@example.com"
  }
}

上記のマッチング規則に従うと、Transmitter はそのイベントを Receiver のストリームへ SHOULD ブロードキャストすべきです。

以下は、Receiver が、Transmitter が送信する subject よりも制約が強い subject を追加した場合の、Complex Subjects における subject matching の非規範的な例です。

Receiver は次の subject を自分のストリームへ追加しています。

{
  "format": "complex",
  "user": {
    "format": "email",
    "email": "jdoe@example.com"
  },
  "device": {
    "format": "ip-addresses",
    "ip-addresses": ["10.29.37.75"]
  }
}

Transmitter は、次の subject を持つブロードキャスト対象のイベントを持っています。

{
  "format": "complex",
  "user": {
    "format": "email",
    "email": "jdoe@example.com"
  }
}

上記のマッチング規則に従うと、Transmitter はそのイベントを Receiver のストリームへ SHOULD ブロードキャストすべきです。

以下は、マッチしない 2 つの Complex Subjects の非規範的な例です。

Receiver は次の subject を自分のストリームへ追加しています。

{
  "format": "complex",
  "user": {
    "format": "email",
    "email": "jdoe@example.com"
  },
  "group": {
    "format": "did",
    "url": "did:example:123456"
  }
}

Transmitter は、次の subject を持つブロードキャスト対象のイベントを持っています。

{
  "format": "complex",
  "user": {
    "format": "email",
    "email": "jdoe@example.com"
  },
  "group": {
    "format": "did",
    "url": "did:example:9999999"
  }
}

上記のマッチング規則に従うと、Transmitter はそのイベントを Receiver のストリームへ SHOULD NOT ブロードキャストすべきです。

8.1.3.2. ストリームへの subject 追加

Event Stream に subject を追加するために、Event Receiver は Add Subject Endpoint に対して HTTP POST リクエストを行い、本文に次の claims を持つ JSON オブジェクトを含めます。

stream_id

REQUIRED. subject を追加する対象ストリームを識別する文字列。

subject

REQUIRED. 追加対象の subject を識別する Subject claim。

verified

OPTIONAL. 真偽値。true の場合は Event Receiver が Subject claim を検証したことを示し、false の場合は検証していないことを示します。省略された場合、Event Transmitters は subject が検証済みであると仮定することが推奨されます。

成功レスポンスでは、Event Transmitter は空の "200 OK" レスポンスを返します。Event Transmitter は、たとえば subject が以前に「この Event Receiver へイベントを送信しないでほしい」と Transmitter に示している場合などに、リクエストを黙って無視してもかまいません。この場合、Transmitter は空の "200 OK" レスポンス、または適切なエラーコードを返してもかまいません。Security Considerations（Section 9）を参照してください。

以下は、Email Subject Identifier により subject を識別してストリームに追加する、非規範的なリクエスト例です。

POST /ssf/subjects:add HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=

{
  "stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
  "subject": {
    "format": "email",
    "email": "example.user@example.com"
  },
  "verified": true
}

Figure 40: Example: Add Subject Request

成功したリクエストに対する非規範的なレスポンス例です。

HTTP/1.1 200 OK
Server: transmitter.example.com
Cache-Control: no-store

Figure 41: Example: Add Subject Response

エラーは次の HTTP status codes で通知されます。

Code	Description
400	リクエスト本文を parse できない、またはリクエストが不正な場合
401	認可に失敗した、または欠落している場合
403	Event Receiver がこの特定の subject の追加を許可されていない、または一般に追加を許可されていない場合
404	この Event Receiver に対して指定された "stream_id" の Event Stream が存在しない場合、または subject が Event Transmitter に認識されない場合（後者では Transmitter は黙って "200" を返すことを選んでもよい）
429	Event Receiver が一定時間内にリクエストを送りすぎた場合

8.1.3.3. subject の削除

Event Stream から subject を削除するために、Event Receiver は Remove Subject Endpoint に対して HTTP POST リクエストを行い、本文に次の claims を持つ JSON オブジェクトを含めます。

stream_id

REQUIRED. subject を削除する対象ストリームを識別する文字列。

subject

REQUIRED. 削除対象の subject を識別する Subject claim。

成功レスポンスでは、Event Transmitter は "204 No Content" レスポンスを返します。

以下は Phone Number Subject Identifier により subject を識別して削除する、非規範的なリクエスト例です。

POST /ssf/subjects:remove HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=

{
  "stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
  "subject": {
    "format": "phone",
    "phone_number": "+12065550123"
  }
}

Figure 42: Example: Remove Subject Request

成功したリクエストに対する非規範的なレスポンス例です。

HTTP/1.1 204 No Content
Server: transmitter.example.com
Cache-Control: no-store

Figure 43: Example: Remove Subject Response

エラーは次の HTTP status codes で通知されます。

Code	Description
400	リクエスト本文を parse できない、またはリクエストが不正な場合
401	認可に失敗した、または欠落している場合
403	Event Receiver がこの特定の subject の削除を許可されていない、または一般に削除を許可されていない場合
404	この Event Receiver に対して指定された "stream_id" の Event Stream が存在しない場合、または subject が Event Transmitter に認識されない場合（後者では Transmitter は黙って "204" を返すことを選んでもよい）
429	Event Receiver が一定時間内にリクエストを送りすぎた場合

8.1.4. Verification

場合によっては、Event Stream 上のイベント送信頻度が非常に低くなり、Event Receiver が、期待どおりの動作と、ストリームの誤構成によるイベント送信失敗とを区別することが難しくなります。Event Receivers は、Verification Event が Event Stream を介して送信されるよう要求でき、これにより、イベントを正常に受信できれば、ストリームが正しく構成されていることを確認できます。Verification Event の acknowledgement は、署名検証および暗号化を含む end-to-end の配信が機能していることを Event Transmitter に対しても確認させます。

Transmitter は、Event Receiver から要求されていなくても、任意のタイミングで Verification Event を送信してもかまいません。

Transmitter は、Verification Event が Stream Configuration（Section 8.1.1）の events_supported、events_requested、および / または events_delivered フィールドに存在しなくても、Verification Event の要求へ応答してもかまいません。

8.1.4.1. Verification Event

Verification Event は、イベント種別が "https://schemas.openid.net/secevent/ssf/event-type/verification" の SSF イベントです。このイベントは次の属性を含みます。

state

OPTIONAL. Verification Event がトリガーされたときに Event Receiver によって提供される opaque な値。

他の SSF イベントと同様に、Verification Event はトップレベルの sub_id claim を持ちます。

sub_id

REQUIRED. Verification Event におけるトップレベル sub_id claim の値は、常に opaque 型の simple value になるよう設定されなければなりません。値の id は、検証対象ストリームの stream_id で MUST なければなりません。

なお、ストリーム自体を識別する subject は常に暗黙にストリームへ追加されており、ストリームから削除することはできません。

Verification Event を受信すると、Event Receiver は SET を解析して claims を検証します。特に、"state" の値が期待どおりであることを確認しなければなりません。"state" の値が一致しない場合、"err" フィールドを "invalid_state" に設定したエラーレスポンスを返すことが推奨されます（RFC8935 の Section 2.4、または RFC8936 の Section 2.4.4 を参照）。

多くの場合、Event Transmitters は、Event Receiver による acknowledgement の有無に基づき、検証に成功しない Event Stream を disable または suspend してもかまいません。

8.1.4.2. Verification Event のトリガー

Verification Event が Event Stream を介して送信されるよう要求するために、Event Receiver は Verification Endpoint に対して HTTP POST リクエストを行い、本文に（もしあれば）verification リクエストのパラメータを含む JSON オブジェクトを含めます。成功リクエストでは、Event Transmitter は空の "204 No Content" レスポンスを返します。

verification リクエストは次のプロパティを持ちます。

stream_id

REQUIRED. Verification Event を要求する対象ストリームを識別する文字列。

state

OPTIONAL. 任意の文字列で、Event Transmitter は Verification Event の payload において Event Receiver へこの値を MUST そのまま返さなければなりません。Event Receivers は、この値を使って Verification Event と verification リクエストを関連付けてもかまいません。Verification Event が Transmitter により開始される場合、このパラメータは設定されてはなりません。

Verification Endpoint への POST の成功レスポンスは、Verification Event が正常に送信されたことを示すものではなく、Event Transmitter がそのイベントを送信した、または将来送信することだけを示します。Event Transmitters は非同期プロセスでイベントを送信してもかまわず、Verification Event 送信時間に関する SLA を公開することが推奨されます。Event Receivers は、Verification Event が同期的に送信されること、または現在のイベントキューに対して特定の順序で送信されることに依存してはなりません。

エラーは次の HTTP status codes で通知されます。

Code	Description
400	リクエスト本文を parse できない、またはリクエストが不正な場合
401	認可に失敗した、または欠落している場合
404	この Event Receiver に対して指定された "stream_id" の Event Stream が存在しない場合
429	Event Receiver が一定時間内にリクエストを送りすぎた場合（Section 8.1.1 の "min_verification_interval" も参照）

以下は Verification Event をトリガーするための非規範的なリクエスト例です。

POST /ssf/verify HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=
Content-Type: application/json

{
  "stream_id": "f67e39a0a4d34d56b3aa1bc4cff0069f",
  "state": "VGhpcyBpcyBhbiBleGFtcGxlIHN0YXRlIHZhbHVlLgo="
}

Figure 44: Example: Trigger Verification Request

成功したリクエストに対する非規範的なレスポンス例です。

HTTP/1.1 204 No Content
Server: transmitter.example.com
Cache-Control: no-store

Figure 45: Example: Trigger Verification Response

そして次は、上記リクエストの結果として Event Receiver に送信される Verification Event の非規範的な例です。

{
  "jti": "123456",
  "iss": "https://transmitter.example.com",
  "aud": "receiver.example.com",
  "iat": 1493856000,
  "sub_id": {
    "format": "opaque",
    "id": "f67e39a0a4d34d56b3aa1bc4cff0069f"
  },
  "events": {
    "https://schemas.openid.net/secevent/ssf/event-type/verification": {
      "state": "VGhpcyBpcyBhbiBleGFtcGxlIHN0YXRlIHZhbHVlLgo="
    }
  }
}

Figure 46: Example: Verification SET

8.1.5. Stream Updated Event

Transmitter は、Receiver からのリクエストなしにストリームの status を変更してもかまいません。Transmitter は、ストリームの status を変更したことを示すために、種別が "https://schemas.openid.net/secevent/ssf/event-type/stream-updated" のイベントを送信します。

Transmitter が Event Stream の status を "enabled" から "paused" または "disabled" のいずれかへ変更することを決定した場合、そのストリームを停止する前に、このイベントを Receiver へ MUST 送信しなければなりません。

Transmitter がストリームの status を "paused" または "disabled" から "enabled" へ変更する場合、そのストリームを再度有効化する際に、このイベントを Receiver へ MUST 送信しなければなりません。

Transmitter は、Stream Updated event が Stream Configuration（Section 8.1.1）の events_supported、events_requested、および / または events_delivered フィールドに存在しなくても、このイベントを送信してもかまいません。

"stream-updated" イベントは次の claims を含みます。

status

REQUIRED. ストリームの新しい status を定義します。

reason

OPTIONAL. Transmitter が status を更新した理由を説明する短い記述を提供します。

他の SSF イベントと同様に、このイベントはトップレベルの sub_id claim を持ちます。

sub_id

REQUIRED. トップレベルの sub_id claim は status が更新された Stream ID を指定します。sub_id の値は opaque フォーマットで MUST あり、その id 値はストリームの一意 ID で MUST なければなりません。

なお、ストリーム自体を識別する subject は常に暗黙にストリームへ追加されており、ストリームから削除することはできません。

以下は Stream Updated event の非規範的な例です。

{
  "jti": "123456",
  "iss": "https://transmitter.example.com",
  "aud": "receiver.example.com",
  "iat": 1493856000,
  "sub_id": {
    "format": "opaque",
    "id": "f67e39a0a4d34d56b3aa1bc4cff0069f"
  },
  "events": {
    "https://schemas.openid.net/secevent/ssf/event-type/stream-updated": {
      "status": "paused",
      "reason": "Internal error"
    }
  }
}

Figure 47: Example: Stream Updated SET

9. Security Considerations

9.1. Subject Probing

Event Transmitter が、subject 追加リクエストへのレスポンスを通じて subject に関する情報を漏えいする可能性があります。"404" レスポンスは、Event Receiver に対して subject が存在しないことを示す場合があり、これが意図せず subject に関する情報（例: 特定の個人がその Event Transmitter サービスを利用しているか否か）を明らかにしてしまうことがあります。

Event Transmitters は、subject 追加リクエストに対してどのような条件でエラーレスポンスを返すかを慎重に評価すべきです。Event Transmitters は、実際には subject に関連するイベントを送信しない場合でも "204" レスポンスを返してもよく、Event Receivers は、204 レスポンスが subject に関連するイベントを受信することを意味すると MUST NOT 仮定してはなりません。

9.2. Information Harvesting

SETs は、個人を特定し得る情報（PII）や、Event Transmitter、SET 内のイベントの subject、または両者の関係に関する非公開情報を含む場合があります。Event Transmitters は、Event Receivers にイベントを送信する際にどの情報を開示しているかを理解することが重要です。さもないと、Event Stream が、私的情報への不正アクセスのベクトルになり得ます。

Event Transmitters は、subject 追加リクエストを「Event Receiver がその subject に関心を持っている」という表明として解釈すべきであり、Event Receiver がストリームに追加したすべての subject に関連するイベントを送信する義務はありません。Event Transmitters は、任意の subject に関連するイベントを、いくつか、すべて、あるいはまったく送信しないことを選んでもかまいません。また、イベントを送信する前に、そのイベントに含まれる情報を Event Receiver と共有することが許可されていることを検証することが推奨されます。そのような検証がどのように行われるかの仕組みは、本仕様のスコープ外です。

9.3. Malicious Subject Removal

悪意ある当事者は、特定の subject に関連する悪意ある活動を Event Receiver が検知する能力を低下させる、subject に不便を与える、またはその他の理由のために、ストリームから特定の subject を削除することが有利だと考えるかもしれません。したがって、Event Transmitter が、subject がストリームから削除された後もしばらくの間、その subject に関連するイベントを送信し続けることは、subject の利益にかなう場合があります。

Event Transmitters は、subject がストリームから削除された後もしばらくの間、その subject に関連するイベントを送信し続けてもかまいません。Event Receivers は、ストリームから削除された subject に対するイベントを受信することを許容しなければならず、それらのイベントを Event Transmitter へエラーとして報告してはなりません。

10. Privacy Considerations

10.1. Subject Information Leakage

Event Transmitters と Receivers は、Subject Identifiers を通じて subject に関する情報が漏えいしないよう予防措置を取り、適切な Subject Identifier Types を選択すべきです。当事者は、ある Subject Identifier Type を用いることで、受信者が、受信者がすでに知っているとは限らない subject に関する異なる claims を相関できてしまう場合、その Subject Identifier Type を用いて subject を識別すべきではありません。Transmitters と Receivers は、情報漏えいの可能性を減らすために、ある当事者と通信する際には、常に同じ Subject Identifier Type と同じ claim 値を用いて、特定の subject を識別すべきです。

10.2. Previously Consented Data

SSF イベントが、Transmitter と Receiver の間で以前に交換された Subject Principals の属性について新しい値を含む場合、ユーザーから一度きりの同意を得て属性が交換されたのでない限り、SSF イベントで更新値を提供することにより新たなプライバシー考慮が導入されることはありません。

10.3. New Data

以前に Transmitter と Receiver の間で交換されていないデータ、または交換への同意が失効しているデータには、次の考慮があります。

10.3.1. Organizational Data

ユーザーが以前に Transmitter に対して、特定のデータを第三者へ提供することに同意している場合、Transmitter はユーザーの追加同意なしに、そのデータを SSF イベントに含めて送信してもかまいません。そのようなデータには、Transmitter によって生成された Subject Principal に関する organizational data が含まれてもかまいません。

10.3.2. Consentable Data

Transmitter が、以前にユーザーが提供に同意していないデータを SSF イベントに含める意図がある場合、Transmitter は、Transmitter のプライバシーポリシーに従って、そのデータ提供への同意をユーザーから MUST 得なければなりません。

11. IANA Considerations

この文書で定義される Subject Identifiers は、"Security Event Identifier Formats" レジストリに追加されます。このレジストリは、Subject Identifiers for Security Event Tokens（RFC9493）仕様で定義されます。

ssf-configuration の well-known endpoint は、RFC8615 により定義される IANA の Well-Known URIs レジストリに登録されます。

IANA は、Security Event Token レジストリにおける Security Event Token Error Codes セクションへ、エラーコード "invalid_state" を割り当てるよう求められます（RFC8935 の Section 7.1）。登録テンプレートとして次の情報が提供されます。

Error Code

invalid_state

Description

Verification event が、Receiver が期待する値と一致しない "state" claim を含んでいたことを示します。

Change Controller

OpenID - Shared Signals Working Group

12. Normative References

[CAEP]

Cappalli, T. and A. Tulshibagwale, "OpenID Continuous Access Evaluation Profile 1.0", August 2025.

[NAMINGCONVENTION]

Foundation, O., "OpenID Naming and Content of Specifications", n.d.

[OASIS.saml-core-2.0-os]

Cantor, S., Kemp, J., Philpott, R., and E. Maler, "Assertions and Protocol for the OASIS Security Assertion Markup Language (SAML) V2.0", OASIS Standard saml-core-2.0-os, March 2005.

[OpenID.Core]

Sakimura, N., Bradley, J., Jones, M. B., de Medeiros, B., and C. Mortimore, "OpenID Connect Core 1.0 - ID Token", November 2014.

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997.

[RFC3986]

Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005.

[RFC4001]

Daniele, M., Haberman, B., Routhier, S., and J. Schoenwaelder, "Textual Conventions for Internet Network Addresses", RFC 4001, DOI 10.17487/RFC4001, February 2005.

[RFC6749]

Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012.

[RFC7159]

Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2014.

[RFC7517]

Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/RFC7517, May 2015.

[RFC7519]

Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017.

[RFC8417]

Hunt, P., Ed., Jones, M., Denniss, W., and M. Ansari, "Security Event Token (SET)", RFC 8417, DOI 10.17487/RFC8417, July 2018.

[RFC8615]

Nottingham, M., "Well-Known Uniform Resource Identifiers (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019.

[RFC8935]

Backman, A., Ed., Jones, M., Ed., Scurtescu, M., Ansari, M., and A. Nadalin, "Push-Based Security Event Token (SET) Delivery Using HTTP", RFC 8935, DOI 10.17487/RFC8935, November 2020.

[RFC8936]

Backman, A., Ed., Jones, M., Ed., Scurtescu, M., Ansari, M., and A. Nadalin, "Poll-Based Security Event Token (SET) Delivery Using HTTP", RFC 8936, DOI 10.17487/RFC8936, November 2020.

[RFC9110]

Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022.

[RFC9493]

Backman, A., Ed., Scurtescu, M., and P. Jain, "Subject Identifiers for Security Event Tokens", RFC 9493, DOI 10.17487/RFC9493, December 2023.

[RISC]

Scurtescu, M., Backman, A., Hunt, P., Bradley, J., Bounev, S., and A. Tulshibagwale, "OpenID RISC Profile Specification 1.0", August 2025.

Appendix A Acknowledgements

著者は、この仕様の策定に貢献した OpenID Foundation Shared Signals Working Group のすべてのメンバーに感謝します。

Appendix B. 注意書き

OpenID Foundation (OIDF) は、あらゆる Contributor、開発者、実装者、またはその他の関係者に対し、(i) 仕様の策定、および (ii) Implementers Draft、Final Specifications、ならびに Final Specification Incorporating Errata Corrections に基づく実装を行う目的に限り、本 Implementers Draft、Final Specification、または Final Specification Incorporating Errata Corrections を複製し、派生物を作成し、配布し、実演し、表示するための、非独占、ロイヤルティフリー、全世界的な著作権ライセンスを付与します。ただし、OIDF を素材の出典として帰属表示することが条件であり、その帰属表示は OIDF による推奨を示すものではありません。

この仕様で説明される技術は、OpenID Foundation のメンバーを含むさまざまなソースからの貢献により提供されました。OpenID Foundation は、その技術が配布可能であることを確保するための措置を講じていますが、この仕様で説明される技術の実装または使用に関して主張され得る知的財産権その他の権利の有効性または範囲、ならびにそれらの権利に基づくライセンスが利用可能か否か、またはどの程度利用可能かについて、いかなる立場も取りません。また、そのような権利を特定するために独自の努力を行ったことを表明するものでもありません。OpenID Foundation と、この仕様への貢献者は、この仕様に関連して、商品性、非侵害、特定目的適合性、権原を含む（ただしこれらに限られない）あらゆる保証（明示、黙示、その他）を行わず、かつ明示的に否認します。この仕様を実装することに伴うリスクは、すべて実装者が負担します。OpenID Intellectual Property Rights policy（openid.net に掲載）は、貢献者に対し、他の貢献者および実装者に対して特定の特許請求を主張しないための特許約束を提示することを求めています。OpenID は、この仕様を実施するために必要となり得る技術をカバーする著作権、特許、特許出願、またはその他の専有権が存在する場合、あらゆる関係者がそれを OpenID に知らせることを歓迎します。

寄稿者

Steve Venema

ForgeRock

Email: steve.venema@forgerock.com

Steve は Complex Subjects の format フィールドを定義しました。

Apoorva Deshpande

Okta

Email: apoorva.deshpande@okta.com

Sean O'Dell

The Walt Disney Company

Email: sean.odentity@disney.com

Jen Schreiber

Workday

Email: jennifer.winer@workday.com

Tushar Raibhandare

Google

Email: traib@google.com

Yair Sarig

Omnissa

Email: ysarig@omnissa.com

Authors' Addresses

Atul Tulshibagwale

SGNL

Email: atul@sgnl.ai

Tim Cappalli

Okta

Email: tim.cappalli@okta.com

Marius Scurtescu

Coinbase

Email: marius.scurtescu@coinbase.com

Annabelle Backman

Amazon

Email: richanna@amazon.com

John Bradley

Yubico

Email: secevemt@ve7jtb.com

Shayne Miel

Cisco

Email: smiel@cisco.com

OpenID Shared Signals Framework Specification 1.0

Abstract

Table of Contents

1. はじめに

1.1. 表記規約

2. Subject Principals

3. SSF Events における Subject Members

3.1. Subject Members

3.1.1. 既存の CAEP および RISC イベント

3.1.2. 新しいイベント種別

3.1.3. 追加の Subject Members

3.1.4. Subject Member の値

3.2. Simple Subject Members

3.3. Complex Subject Members

3.3.1. Complex Subject の解釈

3.4. SSF Events における Subject Identifiers

3.5. Additional Subject Identifier Formats

3.5.1. JWT ID Subject Identifier Format

3.5.2. SAML Assertion ID Subject Identifier Format

3.5.3. IP Addresses Subject Identifier Format

3.6. Receiver における subject の処理

4. Events

4.1. Security Event Token Profile

4.1.1. SET の明示的な型付け

4.1.2. SSF Event Subject

4.1.3. 他種の JWT と SET を区別すること

4.1.4. Signature Key Resolution

4.1.5. SSF Prescriptive SETs

4.1.6. "iss" Claim

4.1.7. "exp" Claim

4.1.8. "aud" Claim

4.1.9. "txn" claim

4.2. Event Properties

4.2.1. "events" claim

4.2.2. イベント種別固有フィールド

4.2.3. 追加フィールド

5. Shared Signals Framework に適合する SET の例

6. Event Delivery

6.1. Stream Configuration Metadata

6.1.1. HTTP を用いた Push Delivery

6.1.2. HTTP を用いた Poll Delivery

7. Transmitter Configuration Discovery

7.1. Transmitter Configuration Metadata

7.1.1. Authorization scheme

7.2. Transmitter Configuration Metadata の取得

7.2.1. Transmitter Configuration Request

7.2.2. RISC Transmitters との後方互換性

7.2.3. Transmitter Configuration Response

7.2.4. Transmitter Configuration Validation

8. Management API for SET Event Streams

8.1. Event Stream Management

8.1.1. Stream Configuration

8.1.1.1. ストリームの作成

8.1.1.1.1. Create Stream Response の検証

8.1.1.2. ストリーム構成の読み取り

8.1.1.3. ストリーム構成の更新

8.1.1.4. ストリーム構成の置換

8.1.1.5. ストリームの削除

8.1.2. Stream Status

8.1.2.1. ストリームステータスの読み取り

8.1.2.2. ストリームステータスの更新

8.1.3. Subjects

8.1.3.1. Subject Matching

8.1.3.2. ストリームへの subject 追加

8.1.3.3. subject の削除

8.1.4. Verification

8.1.4.1. Verification Event

8.1.4.2. Verification Event のトリガー

8.1.5. Stream Updated Event

9. Security Considerations

9.1. Subject Probing

9.2. Information Harvesting

9.3. Malicious Subject Removal

10. Privacy Considerations

10.1. Subject Information Leakage

10.2. Previously Consented Data

10.3. New Data

10.3.1. Organizational Data

10.3.2. Consentable Data

11. IANA Considerations