Search Query

[Tom Jones]

When requesting data entity data from a federation it may be possible to included a search parament with the request. The search parameter will be of the form “s={encoded search terms. The default shall just be whatever terms the user enters to be decoded by the local machine search engine. It may be possible to include a json structured query that is base64url encoded which may also be jose encoded for signing or encryption. The default json term will be take from the distinguirshed name parament set, for example “co=us.wa” or any json terms that are used by the federation. If both forms of query are acceptable, the request should not begin with the letters “Ey”/

Note that the entity data to be included in the response must only include the name of the entity, but would likely include other data that would be displayed to a human user to help in the selection of the appropriate entity, for example the country or the assurance level of the entity statement.

Note that the federation may restrict access to users that are already logged into one of the members of the federation. It may wrll happen that this is in the form of a 3rd party cookie which could be restricted in future browsers which could be solved by having the local federation member proxy requests from its own members to the federation authority.

‌

‌

[Giuseppe De Marco]

I could be wrong, is this proposal to be considered implementable in the 'Entity Listing endpoint of in OIDC federation 1.0?here: https://openid.net/specs/openid-connect-federation-1_0.html#rfc.section.7.3

if so and if I understand correctly, it would make sense to me. It would make life easier for all developers who need a smart API for data navigation, to be adopted in the components within the discovery pages (where users select the IDP / OP).

if this were the case, a pagination feature and a filter on the type (RP, OP) would also be useful. I am working on a proposal to extend this endpoint, this issue is interesting to me.

[Tom Jones]

The point was to get federation support to users looking for appropriate OP or RP. I agreed to create a use case doc for this soon.

[Roland Hedberg]

Having though a bit about this I don’t support adding a search term to the fetch operation.

As it stands right now in the specification each entity that has subordinates only need to know two things about the subordinate: the entity_id and the entity’s public federation key.

Adding a search term forces the superior to know a lot more about its subordinate.

There for I’d like to keep the fetch operation as it is and instead would like us to look at adding another operation - search.

At this time I think we also would do well to perhaps split the federation API endpoint into four separate endpoints: fetch, resolve_metadata, list, search.

This would allow an entity to publish which of these it supports, something which is not possible today.

I think the search operation is needed but I’d like to keep it separate from ‘fetch’.

[Giuseppe De Marco]

+1 @Roland Hedberg

Indeed, an intermediary or trust anchor does not have with them all the claims and values of one of their descendants, as contained in each respective statement published at the respective resources of . well-known/openid-federation

what I know to date, considering me a student for life is very clear, is that the entity statements published at the intermediaries and the anchor trusts related to their descendants always contain specific information about the "role" of their descendant within the federation (as seen with the type paramenter in “Trust Negotiation Request”)

"metadata": {
"federation_entity": {

or

"metadata": {
"openid_provider": {

or

"metadata_policy": {
"openid_relying_party": {

and this information would allow us to apply a sort of filter on the type of entity for which to obtain a result as federation_api "listing" (instead of is_leaf only).

However, the one that pushes me rather to give up this functionality is set out below:

1. I would much rather get 3 or 4 specialized endpoints and named according to their specific functions, namely remove the endpoint "federation_api" to get 4 endpoints to compose the resources of the federation API scheme.
2. inflate too much, with disparate functionalities, the only endpoint of federation_api would force the intermediaries/trust anchors to renounce to a strategy of staticization of the contents. Strategy that I consider vital for a better efficiency and resilience of the infrastructure of federation

Having said that, I wonder what might be a good semantics to name these endpoints, their purposes and their peculiar characteristics. On the track proposed by Roland I share my mental exercise below:

1. federation_statement (FETCH), performs the current federation_api fetch function, it’s required only for intermediaries and trust anchors and its result can be cached or served as a static content. My proposal would like to get even more than a single statement at this endpoint, with an appropriate pagination. Exactly as it is in SAML2 with MDQ, if specified the subject would get the single statement otherwise a list of paginated statements.
2. federation_list, performs the current federation_api listing and I believe that can be improved. it’s not required in the specs but with appropriate improvements could become an authentic razor blade for federations, I believe. I reserve the opportunity to describe my proposal for improvement for this feature in this post.
3. federation_search, performs searches (also full text or regexp) upon the entity id of its descendants. It can be dangerous because it requires a continuous update of the resources published by third parties, therefore it can require caching mechanisms that on the one hand would improve research but on the other would compromise the freshness of the data. It requires a proper study and implementation strategy. I would consider this endpoint as entirely optional.
4. federation_trust_negotiation, performs the current federation_api resolve_metadata operation.

Having "exploded" in 4 specialized endpoints the original federation_api we can consider the parameter "operation" now deprecated.

7.3 federation_list (OPTIONAL)

An entity MAY query another entity for a list of all the entities immediately subordinate to that entity and about which that entity is prepared to issue statements about.

7.3.1. Entity Listings Request

The request MUST be an HTTP request using the GET method and the https scheme to a resolved federation API endpoint with the following query string parameters:

entity_type
OPTIONAL. If left out, the result should include both leaf entities and intermediate nodes. If set to "openid_relying_party", the response MUST contain only leaf entities as relying parties. If set to “openid_provider”, the response MUST contain only leaf entities as openid providers. If set to “oauth_authorization_server”, the response MUST contain only leaf entities as OAuth2 Authorization Server. If set to "federation_entity", the response MUST contain only intermediary nodes.

page
OPTIONAL. Integer, indicates the page number. If absent the response will contains the first page

per_page
OPTIONAL. Integer, indicates how many entities will be carried in a page. If omitted, by default the value is 100.

trust_mark
OPTIONAL. A list of url encoded strings separated by space related to trust marks references to be filtered on the available entities. eg: trust_mark=https%3A%2F%2Fspid.gov.it%2Ftrust_marks%2Fprofessional_use%2FID1%20https%3A%2F%2Fspid.gov.it%2Ftrust_marks%2Fprofessional_use%2FID2

The following is a non-normative example of an entity listing request:

GET /federation_listing
Host: openid.sunet.se

7.3.2. Entity Listing Response

The response is a signed JWT with the claim called “entities” that contains a JSON list with the known entity identifiers, it MUST have a descendant ordering based on the iat claim, that it must be present, at least the iat claim, any other is intended to be OPTIONAL.

The following is a non-normative example of a response:

{
  "alg": "RS256",
  "kid": "WU52Y3MxX0VTYWs0b1pwbXAxcVkzd1Y5YnY3OWJHeUZXczgtRl9Lc3VDTQ",
  “typ”: “oidc-federation-listing+jwt”
}
.
{
 "iss": "https://openid.sunet.se",
 "iat": 1620050972,
 "exp": 1620072515,
 "entities": {
   "https://ntnu.andreas.labs.uninett.no/": {
        "iat": 1588455866,
   },
   "https://blackboard.ntnu.no/openid/callback": {
        "iat": 1588455856,
   },
  "https://serviceprovider.say.no/": {
        "iat": 1588355866,
    }
  },
"page": 1,
"per_page": 3,
"total_pages": 2,
"next_page_path": "/federation_listing?page=2&per_page=3",
"prev_page_path": ""
}

As for federation_statement (fetch) consider in the absence of the sub parameter to get a response similar to that described for federation_listing, . In the presence of the sub parameter the response would be equal to that already specified in draft 17.

I beg you to forgive the prolixity of this post

‌

[Roland Hedberg]

When it comes to the search operation having a search term that is undefined when it comes to syntax might be OK. I for one would like to have one search term syntax that is well defined and required to be implemented by anyone that implements the search endpoint. Something like JSONPath for instance.

[Michael Jones]

There was consensus on the 16-Dec-21 call to close this issue since code can implement custom searches using the features already specified. Adding search features would likely reduce interoperation - not help it.

[Tom Jones]

that's fine with me - i only entered this because i was asked to. The one thing that would have been helpful would be to specify the query parameter "S=" for search.