Registering SP in IdP

Registration procedure is performed in two modes. The Short mode is used when an SP is registered by a third-party agent. The Putback mode is used in other cases (when SP is online and can respond to IdP queries). Mode is chosen by registration parameter reg_mode.

The registration of an SP in IdP is performed according to the following schema:

1. The SP requests IdP to register itself.

   It sends HTTP request (Content-type: application/x-www-form-urlencoded) POST IDP_API_BASE_URL/sp with the following parameters:

   • api_id. Version of API supported by the SP. Allowed values: sw:sso:sp:1_0.
   • api_url. Endpoint URL of SP interfaces (URL to which service messages from IdP to the SP are directed). All SP interfaces related to IdP must reside relatively to this URL. Later this URL will be referred to as SP_API_BASE_URL.

   Note: If the SP is registered in multiple IdPs, it is recommended to specify different SP_API_BASE_URL for each IdP.

   • idp_id. An IdP ID generated by the SP. Can be any combination of characters.
   • sp_name. Human-readable SP name.
   • root_url. Base application URL that encloses all resources that belong to this SP and require authentication by IdP.
   • name_mapping_url (optional). Endpoint URL of name mapping service that is used to resolve local account IDs to login names. For details, refer to the Local Account ID Mapping Interface section.
   • reg_mode. Registration mode. If the parameter is omitted, the default value is used. Allowed values: short, putback (default).
     
2. If IdP cannot register the SP, it responds with an HTTP error code from range 4xx or 5xx depending on the error cause and terminates the registration procedure. Else, it saves provided registration information.
   
3. IdP returns a new SP identifier, SP certificate/private key pair and its own public key.
   1. (This step is skipped if the short mode is chosen) IdP sends HTTP request PUT SP_API_BASE_URL/idp/idp_id/props. The props web resource should contain the following data:
      • sp_id. Unique identifier of the SP. This parameter is defined by IdP.
      • api_id. Version of API that is supported by IdP. Allowed values: sw:sso:idp:1_0.
      • idp_id. IdP unique identifier (defined by SP at step 1).
      • api_url. URL to which service messages from the SP to IdP are directed (endpoint URL of IdP interfaces). This URL should match one returned in Location header to the SP. This URL is referred as IDP_API_BASE_URL.
      • idp_cert (base64-encoded). Public key certificate that should be used to authenticate the SP at IdP or encrypt messages to it.
      • sp_cert (base64-encoded). Public key certificate that is used to authenticate the SP at IdP and to encrypt messages to the SP from IdP.
      • sp_pkey (base64-encoded). Private key that is required to use the certificate.

   For details on format of the props web resource, refer to the Appendix.

   1. IdP responds with code 201 "Created" and Location header pointing to location of SP web resource IDP_API_BASE_URL/sp/sp_id/props. If the short mode is chosen, the response body contains the SP properties in the same format as the props format.

4. The SP stores the registration data retrieved from IdP. In further interactions, messages from the SP can be marked with this SP identifier and messages can be signed or encrypted in either direction.