SP Portal

SP portal API

SP Portal is the first READ/ WRITE internal client of the Manage API. It needed custom endpoints to optimize re-use and UI-friendly flows.

Create new SP

Posting XML metadata of a SP with the credentials - basic auth - to the endpoint /manage/api/internal/new-sp wrapped in JSON like this:

{"xml": "${XML_METATDATA}"}

will result in a new MetaData type of saml20_sp. There a three scenario:s:

1. Success and the new JSON MetaData including generated ID and version is returned
2. Validation fails with response code 400. The JSON returned contains detailed information about the validation errors are deductable by parsing the validations field:

{
	"timestamp": 1508497262513,
	"status": 400,
	"error": "org.everit.json.schema.ValidationException",
	"exception": "org.everit.json.schema.ValidationException",
	"message": "org.springframework.web.util.NestedServletException: Request processing failed; nested exception is org.everit.json.schema.ValidationException: #/metaDataFields: 3 schema violations found",
	"path": "/manage/api/internal/new-sp",
	"validations": "#/metaDataFields: required key [name:en] not found, #/metaDataFields: required key [AssertionConsumerService:0:Binding] not found, #/metaDataFields: required key [AssertionConsumerService:0:Location] not found"
}

3. The entity ID already exists for an saml20_sp MetaData instance:

{
	"timestamp": 1508497483957,
	"status": 400,
	"error": "Bad Request",
	"exception": "manage.exception.DuplicateEntityIdException",
	"message": "There already exists a MetaData entry with entityId: https://profile.test2.surfconext.nl/authentication/metadata",
	"path": "/manage/api/internal/new-sp"
}

Update existing SP

To update an existing SP one will need the internal ID and current version which are returned when a SP is created. If the user is a new session then the internal ID of the saml20_sp MetaData must be retrieved using the search API:

curl -H 'Content-Type: application/json' -u sp-portal:secret  -X POST -d '{"entityid":"${ENTITY_ID}"}' 'http://localhost:8080/manage/api/internal/search/saml20_sp'

which will return one entry (if any) containing the ID anv version of the SP.

[{
	"_id": "1bebe55c-ce15-4035-bff1-fd1eaba9fcb7",
	"version": 2,
	"data": {
		"entityid": "http://sp",
		"state": "prodaccepted",
		"metaDataFields": {
			"name:en": "OpenConext Manage",
			"name:nl": "OpenConext Manage"
		}
	}
}]

Using the ID of the MetaData the MetaData XML can be retrieved using the endpoint http://localhost:8080/manage/api/internal/sp-metadata/{id}.

To update a SP you have several options, but for the SP-portal the easiest option is to PUT the changed metadata wrapped in JSON with the element xml (analogue to the create SP call) to http://localhost:8080/manage/api/internal/update-sp/.

The 3 possible results are exactly the same as the POST to /manage/api/internal/new-sp.