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 possible responses:

1. Success (e.g. 200) 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; the validation errors are deductible 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.example.org/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 and 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.

Delete existing SP

To delete an Existing SP the following endpoint can be used:

curl -u sp-portal:secret -X DELETE "http://localhost:8080/manage/api/internal/metadata/saml20_sp/{id}"

The path variable id must be a valid GUI id fetched priorly by the search API.