Skip to content
Swiss federal authorities

Using External Authorization Services

Overview🔗

General

The sedex authorization service for external users is provided by the sedex system as a SOAP web service over the HTTPS protocol. The operation checks whether the delivery of a specific message type from a specific sender to a specific recipient in sedex is authorized.

Semantics

"Is the delivery of a sedex message of type [messageTypeId] from sender [logicalSender] using the client [sender] to recipient [recipient] permitted?"

Formal

Result checkAuthorisation(int messageTypeId,
                          ParticipantIdentifierType logicalSender, // Optional
                          ParticipantIdentifierType sender, 
                          ParticipantIdentifierType recipient,
                          Boolean requestSenderSedexId  // Optional
                          );

Input Parameters🔗

Name Type Description
messageTypeId int Identifier of the sedex message type.
logicalSender participantSedexId Optional parameter:
Identifier of the logical sedex sender (sedex ID).
sender participantX509Certificate Identifier of the sedex sender certificate (base64 encoded).
recipient participantSedexId Identifier of the webservice (sedex ID).
requestSenderSedexId boolean Optional parameter:
true request a response field senderSedexId
false do not reqeust a response field senderSedexId
Can be used to determine the sedex ID for a sender's certificate.

Authorisation Result🔗

Name Type Description
isAuthorised boolean true: authorized
false: not authorized or invalid input
resultErrorCode int 0: OK (Authorization completed)
Not 0: NOT OK (Details see Error Codes)
resultErrorMessage String Technical error message
senderSedexId String Identifier (sedex ID) of the sedex sender

Error Handling

The web service avoids the use of SOAP faults for error display as much as possible. Instead, errors are displayed in the form of defined error codes in the result.

Extract Credentials🔗

Extracting the TLS Certificate🔗

The caller's certificate corresponds to the sedex participant certificate of the sedex-Client. This represents the physical caller of the web service. If the call is made by a logical participant configured on the sedex-Client, it will differ from the physical caller's certificate.

  • The participant's TLS certificate must be read from the TLS session. If a preceding load balancer performs the TLS termination, it should write the certificate into an HTTP header field, so that it can be used for external authorization further downstream.
  • External Authorization supports the certificate either in binary DER or base64 encoded PEM format.

The certificate can then be used in the request as sender.participantX509Certificate.

Extracting the Logical Caller sedex ID🔗

The logical caller of webservice call is provided in the HTTP header Field X-Auth-SedexId.

That HTTP header can be read, and its value can be included in the request as described in Use of Logical Participants.

Error Codes🔗

Error Code Name Description
0 OK Operation completed successfully.
Message Type Errors
10 messageType invalid The ID does not refer to an existing MessageType.
Sender Errors
20 missing sender identification Neither a sedex ID nor a certificate for participant identification was provided.
21 sender sedex ID invalid The ID does not refer to an existing participant.
22 sender certificate invalid The certificate does not identify an existing participant.
23 sender certificate format error The certificate does not match the expected format.
Recipient Errors
30 missing recipient identification Neither a sedex ID nor a certificate for participant identification was provided.
31 recipient sedex ID invalid The ID does not refer to an existing participant.
32 recipient certificate invalid The certificate does not identify an existing participant.
33 recipient certificate format error The certificate does not match the expected format.
Other Errors
99 internal sedex error An internal processing error occurred within the sedex system.

Accessing the External Authorization Service🔗

The External Authorization Service can be accessed via the sedex Web Service Proxy. This service is implemented as a SOAP web service. If the default port 8443 has been configured, the service is available at the following URL:
https://localhost:8443/wsproxy/services/sedexExternalAuthorisationService

The Web Services Description Language (WSDL) file, which provides a machine-readable description of how the service can be called, what parameters it expects, and what data structures it returns, can also be obtained through the sedex Web Service Proxy. The WSDL is available at:
https://localhost:8443/wsproxy/services/sedexExternalAuthorisationService?wsdl

To ensure that the External Authorization Service is functioning correctly, you can use the Soap-UI program. Soap-UI is a popular tool for testing SOAP and REST web services. It allows you to create and execute automated functional, regression, and load tests. By using Soap-UI, you can simulate requests to the service and verify that it responds as expected.