Change requests

Change requests

In order to request changes there there are new endpoints to create, query or rejects change requests.

Create change request

Create a change request with a POST containing path-updates similar to the merge endpoint. The structure is flattened metaData, but can also contain top-level data attributes like entityid or allowedall.

POST: /manage/api/internal/change-requests
{
  "metaDataId" : "1",
  "type" : "saml20_sp",
  "pathUpdates" : {
    "allowedall": true,
    "metaDataFields.description:en" : "New description",
    "metaDataFields.name:nl" : "Nieuwe naam"
  },
  "auditData" : {
    "user" : "jdoe"
  },
  "note": "Optional note describing the reason for this change"
}

The auditData part is required, but the value can be either urn, name, email etc. The note is optional, but recommended. If the value of a property in the pathUpdates dictionary is null then it will be removed.

Incremental changes

When updating the allowed entities it is preferable to create a change request which just adds / removes one of the entries. To achieve this you can make an incrementalChange change request. It is the same endpoint, but the change request is marked as incrementalChange and the update type (e.g. ADDITION of REMOVAL) must be specified:

POST: /manage/api/internal/change-requests
{
  "metaDataId": "1",
  "type": "saml20_sp",
  "incrementalChange": true,
  "pathUpdateType": "ADDITION",
  "pathUpdates": {
    "allowedEntities": {
      "name": "http://mock-idp"
    }
  },
  "auditData": {
    "user": "jdoe"
  },
  "note": "Optional note describing the reason for this change"
}

The change request created with an incrementalChange will add or remove the specified entity from the metadata. It can be used on all metadata collections under the main data root (e.g. allowedResourceServers, allowedEntities, stepupEntities, mfaEntities and disableConsent)

The pathUpdates value for the specified collection (e.g. allowedEntities) can also be a list of entities, which will all be added or removed.

{
  "metaDataId": "1",
  "type": "saml20_sp",
  "incrementalChange": true,
  "pathUpdateType": "ADDITION",
  "pathUpdates": {
    "allowedEntities": [
      {
        "name": "http://mock-idp"
      },
      {
        "name": "http://idp-real"
      }
    ]
  },
  "auditData": {
    "user": "jdoe"
  },
  "note": "Optional note describing the reason for this change"
}

The incremental change requests also supports ARP removals or additions:

{
  "metaDataId": "1",
  "type": "saml20_sp",
  "incrementalChange": true,
  "pathUpdateType": "ADDITION",
  "pathUpdates": {
    "arp.attributes": {
      "urn:mace:dir:attribute-def:eduPersonOrcid" : [
        {
          "value" : "*",
          "source" : "idp",
          "motivation" : ""
        }
      ]
    }
  },
  "auditData": {
    "user": "jdoe",
    "notes": "notes"
  },
  "note": "note"
}

Get all outstanding change requests

To retrieve all outstanding change requests for an entity you must specify the ID of the entity and the type of the entity as path parameters:

GET: /manage/api/internal/change-requests/saml20_sp/1
[
{
  "id" : "620f904ab451045ee60eda74",
  "metaDataId" : "1",
  "type" : "saml20_sp",
  "pathUpdates" : {
    "metaDataFields.description:en" : "New description",
    "metaDataFields.coin:application_url" : "https://nice"
  },
  "auditData" : {
    "user" : "jdoe",
    "userName" : "sp-portal",
    "apiUser" : true
  },
  "note": "Optional note describing the reason for this change"
  "created" : "2022-02-18T12:25:46.032Z",
  "metaDataSummary" : {
    "organizationName" : "Organization name en",
    "name" : "OpenConext Valid SP",
    "entityid" : "Duis ad do",
    "state" : "testaccepted"
  }
}]

The metaDataSummary is used by the Manage GUI and can be ignored.

Reject

Rejecting a change request requires the ID of the change request, the ID of the entity and the type of the entity.

PUT: /manage/api/internal/change-requests/reject
{
   "id" : "620f904ab451045ee60eda74",
   "metaDataId": "1",
   "type": "saml20_sp"
}

Accept

Accepting a change request is not possible with this API. Change requests can only be accepted in the Manage GUI.