0.1-draft1+r607
Copyright © 1999, 2007 SWsoft, Inc
Table of Contents
Single Sign-on is a specialized form of user authentication that enables automatic user authentication by multiple software applications (SSO-participating applications) once a user is successfully authenticated by one of them.
Single Sign-on implementation as a part of the SWsoft's Open Fusion initiative.
A set of binary executables providing the OF SSO functionality.
The part of SSOd that serves SOAP calls to SSO API. Usually represented by the /usr/sbin/sso_soap binary executable (the FastCGI application executed under sw-cp-server).
The part of SSOd that serves HTTP calls to SSO. Usually represented by the /usr/sbin/sso_relay binary executable (the FastCGI application executed under sw-cp-server).
User Agent. Usually represented by a Web browser application.
Section 1 is the introduction to the Single Sign-on Protocol API reference. Section 2 explains SSO Relay and discusses why it was developed and how it works. Section 3 briefly describes API command groups. Section 4 provides technical background and implementation details of the API calling protocols and procedures such as underlying transport and user authentication and presents the list of common errors. Section 5 provides complete list of the API functions accompanied by usage examples.
Please visit out mailing list page: https://lists.swsoft.com/mailman/listinfo/apppack.
SSO Relay is the endpoint for all authenticated user's session cookies originated by SSO. SSO requires that all session cookies have the same endpoint, because it cannot access cookies with different endpoints. Becuase SSO-participating applications usually reside on different domains, cookies originated by the applications cannot be accessed by SSO. The SSO Relay interface has been designed to enable setting user cookies originated by different SSO-participating applications on a single dedicated domain. Since SSO Relay and SSO SOAP work with the same database, the data are always consistent between them.
By default, SSO Relay binds to http://<sso_host>:1180/relay. Actual SSO Relay URL may be retrieved using the getSettings command of the SSO SOAP API. SSO Relay serves HTTP requests from UA. If correct GET parameters are provided in the request, SSO Relay redirects UA with HTTP headers that contain the returned parameters by using the HTTP GET method. HTTP is used to redirect UA to SSO Relay and then back to the application once the data requested from SSO Relay are received by the UA. All data exchange between UA and SSO Relay and between UA and the application is done through HTTP.
Parameter symbols in the redirecting URL must be URL encoded. For example, all non-alphanumeric characters must be represented by their hexadecimal code preceeded by the percent sign as dictated by RFC 1738, 2.2 (for example, '/' => '%2F', ':' => '%3A', etc).
Every redirect to SSO Relay should contain an
url parameter where UA will be redirected to after
the command is processed. Two commands are available - set global cookie
and get global session cookie. Application must redirect UA to SSO Relay
after successful SOAP authenticate call. The GET
parameter token must be set to the value of
relayToken in the authenticate
result. When SSO-authenticated UA is attempting to access an
application's page that requires authorization, SSO Relay must be asked
for already started global session for the user. If the global session
exists, the application will receive the Local session ID. The
application then attempts to verify the user with the verify
SOAP command. The application receives the user identifier
(userId), which confirms that the user has already been authenticated by
another SSO-aprticipating application. Otherwise, if the
ssosid parameter is returned with the
none value, the application will start the user
authentication procedure by itself (usually, display the user login
form).
url - URL to redirect UA to (after the
UA request processing).
token - unique secure identifier for a
global session start
The global session cookie set for the SSO Relay host.
UA is redirected to the callback URL
> GET http://sso.plesk.com:1180/relay?token=15f0b079fd831ea1ac638b885a7fd0ad&url=https://cp.plesk.com:8443
< Status: 302 Found
< Date: Wed, 28-Feb-2007 08:29:16 GMT
< Set-Cookie: sid=15f0b079fd831ea1ac638b885a7fd0ad; expires=+1Y; domain=sso.plesk.com
< Location: https://cp.plesk.com:8443
url - URL to redirect UA to (after
the UA request processing).
token - unique secure identifier for
a global session start
UA is redirected to the callback URL with the
ssosid parameter attached to the URL.
ssosid=none if global session failed to
start.
> GET http://sso.plesk.com:1180/relay?url=https://cp.plesk.com:8443
< Status: 302 Found
< Date: Wed, 28-Feb-2007 08:30:10 GMT
< Location: https://cp.plesk.com:8443?ssosid=https%3A%2F%2Fcp.plesk.com%3A8443%2F3d97a51d987975796db55b172
Note: Values shown in Bold in the example parameters should be in the URL encoded form, for example, https://cp.plesk.com:8443 => https%3A%2F%2Fcp.plesk.com%3A8443
Applications management includes registration/unregistration, update, and information functions. Each application participating in a single sign-on environment must first register itself with the SSOd. To leave the environment, the application needs to unregister itself by wiping its data from the SSO's centralized data storage. Application can submit requests to the SSOd for information about other applications registered in the environment. This is the complete list of available commands for application management:
registerApplication
updateApplication
listApplications
getApplications
unregisterApplication
Users management has more features than the applications management. In addition to the CRUD commands, there are some that are specific for the users management, for example, duplicateUser - to create a clone of a user with new a new identifier and same password, transferOwnership - to grant ownership of a user to another application, or getChangePasswordUrl/getRestorePasswordUrl - to get an URL for changing/restoring a user's password. Only the application that owns a user may delete, change login and password for, duplicate or transfer ownership of the user. This is complete list of commands available for users management:
createUser
deleteUser
getUser
getUserId
listUsers
changeLogin
duplicateUser
changePassword
getChangePasswordUrl
getRestorePasswordUrl
transferOwnership
Once application has a user registered in SSO, it can authenticate the user. To authenticate a user, application verifies the user-supplied login name and password and receives a new session identifier (SID), if the provided login credentials are valid. It is possible to verify any session by its identifier or terminate a session with closeSession command. Session operations can be performed by any application, even by an application acting as guest.
This is the complete list of available commands for session management:
authenticate
verifySession
closeSession
SSO service uses SOAP 1.1/1.2 over HTTP as the data transfer protocol. HTTP is layered atop of SSL sockets. All examples use SOAP 1.2 namespaces, although the SSO engine will also accept SOAP 1.1.
An application needs to be authenticated by SSO to be able to perform API calls to SSO. This is done by SSO's issuing a client SSL certficate to the application during the SSL handshake.
Client certificates issued by SSOd. (See registerApplication)
Application that wants to be authenticated must provide a client SSL certificate to establish an SSL connection. SSOd checks the validity of the certificate (excluding the expiration time) and whether this certificate is assigned to the application.
Guest is a special role existing in SSOd. If no client certificate is provided by an application during SSL connection, the session is associated with guest. The only operations available in this mode are registerApplication, listApplications, getApplication, authenticate, verifySession, closeSession, getSettings.
Application may request a new certificate any time by calling updateApplication. The old certificate will be accepted after this operation only until a connection that uses the newly issued certificate is established. Once a connection using the new certificate is established for the first time, the old certificate is disabled and the application will no longer be able to authenticate using the old certificate.
This operation creates a new application account in the SSO engine. A new identifier (unique ID number) for application is returned if the registration is successful.
Name is a short common name of application,
for example 'plesk' for 'Plesk for Unix 8.2'.
displayName is more special name of
application, without version information.
version is exact version of
application.
capabilities parameter inform SSO about
it's capabilities in the scope of Open Fusion features.
url is a URL of application's entry point.
URL MUST contain a scheme, a host name and a port number, as
specified by RFC 1738,
3.1. URL must not contain url-paths, query-strings, or
fragments. (optional)
restorePasswordUrl is an URL in
application, which will allow user (which is owned by the
application) to restore forgotten password. This is the URL where
user will be redirected from applications which are not user owners.
Application should be ready to accept
callback-url parameter in this URL in order to
redirect UA back after successful password restore. (optional)
changePasswordUrl is an URL in application,
which will allow user (which is owned by the application) to change
his password. This is the URL where user will be redirected from
applications which are not user owners. Application should be ready
to accept callback-url parameter in this URL in
order to redirect UA back after successful password change. (optional)
A new certificate and the corresponding private key, signed by the SSO's authority, will also be issued by the SSO service and returned to the application.
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:registerApplication xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:name>plesk</sso:name>
<sso:displayName>Plesk for Unix</sso:displayName>
<sso:version>8.2</sso:version>
<sso:capabilities></sso:capabilities>
<sso:url>https://plesk.example.com:8443/</sso:url>
<sso:restorePasswordUrl>https://plesk.example.com:8443/plesk/$uid/restore_password/</sso:restorePasswordUrl>
<sso:changePasswordUrl>https://plesk.example.com:8443/plesk/$uid/change_password/</sso:changePasswordUrl>
</sso:registerApplication>
</env:Body>
</env:Envelope><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:registerApplicationResponse xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:applicationId>b0c1127f-bea4-4327-a032-3e8a79afcc6a</sso:applicationId>
<sso:certificate>-----BEGIN PRIVATE KEY-----
...
-----END CERTIFICATE-----</sso:certificate>
</sso:registerApplicationResponse>
</env:Body>
</env:Envelope>One or more of the passed parameters do not validate against schema.
This operation updates an application account in SSOd. An application may only update itself. Only fields submitted for update are changed.
Empty value for sso:certificate will result in issuing and returning a new certificate as described for registerApplication.
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:updateApplication xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:applicationId>b0c1127f-bea4-4327-a032-3e8a79afcc6a</sso:applicationId>
<sso:version>8.2.1</sso:version>
<sso:capabilities>ui-integration</sso:capabilities>
<sso:certificate/>
</sso:updateApplication>
</env:Body>
</env:Envelope><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:updateApplicationResponse xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:certificate>-----BEGIN PRIVATE KEY-----
...
-----END CERTIFICATE-----</sso:certificate>
</sso:updateApplicationResponse>
</env:Body>
</env:Envelope>One or more of the passed parameters do not validate against schema.
Passed applicationId is not registered.
Application attempts to update another application, not itself.
This operation retrieves identifiers of applications registered in SSOd.
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:listApplications xmlns:sso="http://swsoft.com/schemas/sso/1"/>
</env:Body>
</env:Envelope><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:listApplicationsResponse xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:applicationsList>
<!-- Single element name does not matter when serializing arrays, sso:a is just the sample here -->
<sso:a>71f612fb-c435-4108-8ef5-1eea2123b158</sso:a>
<sso:a>b75a1d5d-3304-4486-ac5a-8d091e55c5bc</sso:a>
<sso:a>b0c1127f-bea4-4327-a032-3e8a79afcc6a</sso:a>
</sso:applicationsList>
</sso:listApplicationsResponse>
</env:Body>
</env:Envelope>none
This operation retrieves all information related to the specified application. It cannot obtain certificate.
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:getApplication xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:applicationId>b0c1127f-bea4-4327-a032-3e8a79afcc6a</sso:applicationId>
</sso:getApplication>
</env:Body>
</env:Envelope><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:getApplicationResponse xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:name>plesk</sso:name>
<sso:displayName>Plesk for Unix</sso:displayName>
<sso:version>8.2</sso:version>
<sso:capabilities></sso:capabilities>
<sso:url>https://plesk.example.com:8443/</sso:url>
<sso:changePasswordUrl>https://plesk.example.com:8443/plesk/$uid/change_password/</sso:changePasswordUrl>
<sso:restorePasswordUrl>https://plesk.example.com:8443/plesk/$uid/restore_password/</sso:restorePasswordUrl>
</sso:getApplicationResponse>
</env:Body>
</env:Envelope>The submitted applicationId is not registered.
This operation may be performed by an application only on itself. This operation permanently deletes all information about an application and its registered users from SSOd.
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:unregisterApplication xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:applicationId>b0c1127f-bea4-4327-a032-3e8a79afcc6a</sso:applicationId>
</sso:unregisterApplication>
</env:Body>
</env:Envelope><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:unregisterApplicationResponse xmlns:sso="http://swsoft.com/schemas/sso/1"/>
</env:Body>
</env:Envelope>The submitted applicationId is not registered.
Application attempts to unregister another application, not itself.
Creates a new application user. Application that creates a user becomes the owner of the user. Both plaintext and hashed user passwords are acceptable. The plaintext password type is specified by lack of the sso:passwordHashType element, and the hashed password type is specified by the sso:passwordHashType. List of supported hashes is returned by getSettings operation.
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:createUser xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:login>user@example.com</sso:login>
<sso:password>79859a2f73f6be908324090fa36f038ce59567d6</sso:password>
<sso:passwordHashType>sha1</sso:passwordHashType>
</sso:createUser>
</env:Body>
</env:Envelope><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:createUserResponse xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:userId>68847ced-57b4-4a50-a648-57f60b316900</sso:userId>
</sso:createUserResponse>
</env:Body>
</env:Envelope>The submitted login name is already registered.
Application attempts to act as guest.
Deletes specified user. An application may delete only the users that it owns.
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:deleteUser xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:userId>68847ced-57b4-4a50-a648-57f60b316900</sso:userId>
</sso:deleteUser>
</env:Body>
</env:Envelope><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:deleteUserResponse xmlns:sso="http://swsoft.com/schemas/sso/1"/>
</env:Body>
</env:Envelope>The submitted userId is not registered.
Application attempts to delete a user owned by another application.
Retrieves information about a user.
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:getUser xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:userId>68847ced-57b4-4a50-a648-57f60b316900</sso:userId>
</sso:getUser>
</env:Body>
</env:Envelope><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:getUserResponse xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:login>user@example.com</sso:login>
<sso:applicationId>b0c1127f-bea4-4327-a032-3e8a79afcc6a</sso:applicationId>
</sso:getUserResponse>
</env:Body>
</env:Envelope>The submitted user login name is not registered.
Retrieves userId for a user login name.
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:getUserId xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:login>user@example.com</sso:login>
</sso:getUserId>
</env:Body>
</env:Envelope><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:getUserIdResponse xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:userId>68847ced-57b4-4a50-a648-57f60b316900</sso:userId>
</sso:getUserIdResponse>
</env:Body>
</env:Envelope>The submitted user login name is not registered.
This operation retrieves user identifiers of users owned by the application.
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:listUsers xmlns:sso="http://swsoft.com/schemas/sso/1"/>
</env:Body>
</env:Envelope><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:listUsersResponse xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:usersList>
<!-- Single element name does not matter when serializing arrays, sso:a is just the sample here -->
<sso:a>117df1bd-09cd-4694-bdb4-4f277299410c</sso:a>
<sso:a>bd8075f6-ac38-4f61-aaff-6fa471e75c23</sso:a>
<sso:a>ae83f417-0061-4fb0-a44d-76a395861a23</sso:a>
</sso:usersList>
</sso:listUsersResponse>
</env:Body>
</env:Envelope>none
Changes the login name of a specified user. Only the application that owns the user user may change the user login name.
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:changeLogin xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:userId>68847ced-57b4-4a50-a648-57f60b316900</sso:userId>
<sso:login>user1</sso:login>
</sso:changeLogin>
</env:Body>
</env:Envelope><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:changeLoginResponse xmlns:sso="http://swsoft.com/schemas/sso/1"/>
</env:Body>
</env:Envelope>The submitted userId is not registered.
The submitted user login name is already registered.
The application attempts to change login name of a user owned by another application.
Creates a copy of a specified user with a new userId and the same login name. Only the application that owns the user may duplicate the user. Returns a new userId.
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:duplicateUser xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:userId>68847ced-57b4-4a50-a648-57f60b316900</sso:userId>
<sso:login>clone_user@example.com</sso:login>
</sso:duplicateUser>
</env:Body>
</env:Envelope><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:duplicateUserResponse xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:userId>fd82b455-4e2f-440a-a385-9ade799b0e3a</sso:userId>
</sso:duplicateUserResponse>
</env:Body>
</env:Envelope>The submitted userId is not registered.
The submitted login already registered.
Application attempts to duplicate a user owned by another application.
Changes password of a specified user. Only application that owns the user may change the user's password. The oldPassword field is optional. However, if provided, it will be checked against the old password. If they do not match, the password will not be changed and the sso:invalidCredentials fault will be returned. The optional sso:newPasswordHashType element may be specified after sso:newPassword and has the same semantics as the sso:passwordHashType element in the createUser operation.
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:changePassword xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:userId>68847ced-57b4-4a50-a648-57f60b316900</sso:userId>
<sso:oldPassword>abcdef</sso:oldPassword>
<sso:newPassword>79859a2f73f6be908324090fa36f038ce59567d6</sso:newPassword>
<sso:newPasswordHashType>sha1</sso:newPasswordHashType>
</sso:changePassword>
</env:Body>
</env:Envelope><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:changePasswordResponse xmlns:sso="http://swsoft.com/schemas/sso/1"/>
</env:Body>
</env:Envelope>Application attempted to change password of a user that it does not own.
The submitted userId is not registered.
The oldPassword parameter is specified, and either the submitted userId or the old password is invalid.
By using the userId, retrieves the URL for the the password changing form. The URL is the changePasswordUrl parameter of the application that owns the user, with the '$uid' placeholder substituted by the user identifier.
If no changePasswordUrl is specified for application, no URL is returned.
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:getChangePasswordUrl xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:userId>68847ced-57b4-4a50-a648-57f60b316900</sso:userId>
</sso:getChangePasswordUrl>
</env:Body>
</env:Envelope><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:getChangePasswordUrlResponse xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:url>https://plesk.example.com:8443/plesk/68847ced-57b4-4a50-a648-57f60b316900/change_password/</url>
</sso:getChangePasswordUrlResponse>
</env:Body>
</env:Envelope>The user with the submitted userId does not exist.
By using the user login name, retrieves the URL for the application user password retrieval form. This URL is the restorePasswordUrl parameter of the application that owns the user, with the '$uid' placeholder substituted by the user identifier.
An userId may be used instead of a login name to support legacy login name schemes in applications. To use the feature, pass userId as the sso:userId parameter instead of sso:login.
If no restorePasswordUrl is specified for an application, no url is returned.
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:getRestorePasswordUrl xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:login>user@example.com</sso:login>
[<sso:userId>68847ced-57b4-4a50-a648-57f60b316900</sso:userId>]
</sso:getRestorePasswordUrl>
</env:Body>
</env:Envelope><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:getRestorePasswordUrlResponse xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:url>https://plesk.example.com:8443/plesk/68847ced-57b4-4a50-a648-57f60b316900/restore_password/</url>
</sso:getRestorePasswordUrlResponse>
</env:Body>
</env:Envelope>The user with the submitted login name or userId does not exist.
Both login name and userId have been submitted to the operation.
No login name or userId have been submitted to operation.
Transfer ownership. Transfers the ownership of a specified user to a specified application. Only the application that owns the user may transfer the ownership of the user to another application.
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:transferOwnership xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:userId>68847ced-57b4-4a50-a648-57f60b316900</sso:userId>
<sso:applicationId>71f612fb-c435-4108-8ef5-1eea2123b158</sso:applicationId>
</sso:transferOwnership>
</env:Body>
</env:Envelope><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:transferOwnershipResponse xmlns:sso="http://swsoft.com/schemas/sso/1"/>
</env:Body>
</env:Envelope>The submitted userId is not registered.
The submitted applicationId is not registered.
An application attempts to transfer ownership of a user owned by another application.
Authenticates a user in SSO by using the user login name and password. Returns relayToken and SID if authentication is successful. For details, see the SSO Relay section. After passing a relayToken to SSO Relay, the application must no longer keep the relayToken information.
A Base URL is required for authentication to create a SID. If A base URL is omitted, no SID will be returned, but user verification will still be performed. Ommiting a base URL may be useful for user authentication by non-Web-based applications such as IMAP or FTP servers. A base URL MUST contain a scheme, a host name and a port number, as specified by RFC 1738, 3.1. Base URLs must not contain url-paths, query-strings, or fragments.
UserID may be used instead of a user login name to support legacy login name schemes in applications. To use the feature, pass userId as the sso:userId parameter instead of sso:login
Application that owns the user may omit the user password from request to create a session for the user. This does not compromise system security in any way as the application may always delete the user and create another one with any password.
If schema, host name, port number, and password are omitted from request altogether, no valuable information will be returned to application.
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:authenticate xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:login>user@example.com</sso:login>
[<sso:userId>68847ced-57b4-4a50-a648-57f60b316900</sso:userId>]
<sso:password>l2345</sso:password>
<sso:baseUrl>https://plesk.example.com:8443/</sso:baseUrl>
</sso:authenticate>
</env:Body>
</env:Envelope><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:authenticateResponse xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:relayToken>BD0319B8D9944F1D8</sso:relayToken>
<sso:sessionId>https://plesk.example.com:8443/FE00000001A734BB</sso:sessionId>
<sso:userId>68847ced-57b4-4a50-a648-57f60b316900</sso:userId>
</sso:authenticateResponse>
</env:Body>
</env:Envelope>The submitted baseUrl is not a valid URL.
Both login name and userId have been submitted to the operation.
No user login name or userId have been submitted to operation.
The user with the submitted login name or userId is not registered.
Application attempted to authenticate a user that it does not own and did not provide the user password.
Checks that the passed token denotes a valid session. If the session is expired or does not exist, an error is returned. If the session is valid, it is renewed and the session owner identifier (userId) is returned.
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:verifySession xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:sessionId>https://plesk.example.com:8443/FE00000001A734BB</sso:sessionId>
</sso:verifySession>
</env:Body>
</env:Envelope><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:verifySessionResponse xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:userId>68847ced-57b4-4a50-a648-57f60b316900</sso:userId>
</sso:verifySessionResponse>
</env:Body>
</env:Envelope>The passed sessionId is invalid or expired.
Unconditionally closes the session. If the passed sessionId is invalid or expired, no error is reported.
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:closeSession xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:sessionId>https://plesk.example.com:8443/FE00000001A734BB</sso:sessionId>
</sso:closeSession>
</env:Body>
</env:Envelope><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:closeSessionResponse xmlns:sso="http://swsoft.com/schemas/sso/1"/>
</env:Body>
</env:Envelope>none
Returns global SSO service settings: users sessions timeouts (in seconds), Single Sign-On Relay URL endpoint, and supported password hash types.
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:getSettings xmlns:sso="http://swsoft.com/schemas/sso/1"/>
</env:Body>
</env:Envelope><env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header/>
<env:Body>
<sso:getSettingsResposne xmlns:sso="http://swsoft.com/schemas/sso/1">
<sso:usersSessionsTimeout>6000</sso:usersSessionsTimeout>
<sso:relayEndpointUrl>http://sso.example.com:1180/relay</sso:relayEndpointUrl>
<sso:passwordHash>sha1</sso:passwordHash>
<sso:passwordHash>md5</sso:passwordHash>
<sso:passwordHash>sha256</sso:passwordHash>
</sso:getSettingsResponse>
</env:Body>
</env:Envelope>none
All SOAP faults that can occur while executing the protocol are described here.
This table provides the complete list of SOAP 1.2 and SOAP 1.1 fault codes and the fault descriptions. SOAP 1.1 fault codes correspond to the SOAP 1.2 fault subcodes.
Table 1. SOAP 1.2 Fault Codes and Descriptions
| env:Code | env:Subcode | Description |
|---|---|---|
| env:Sender | sso:FailedAuthentication | SSL certificate does not match any registered application. |
| env:Sender | sso:permissionDenied | Application does not have permission to execute the requested action. |
| env:Sender | sso:noSuchApplication | Passed applicationId is not registered. |
| env:Sender | sso:noSuchUser | Passed userId is not registered. |
| env:Sender | sso:noSuchSession | Passed sessionId is invalid (session does not exist, or has expired). |
| env:Sender | sso:invalidCredentials | Provided userId and user password do not match any registered user. |
| env:Sender | sso:duplicateLogin | Provided user login name is already registered. |
| env:Sender | sso:invalidParameter | Ill-formed parameter passed. |
| env:Receiver | sso:internalError | Internal error occured in the SSO engine. |