Product Documentation

Single Sign-on Provisioning Software Development Kit (SDK)

May 11, 2015

The Single Sign-on Provisioning Software Development Kit (SDK) allows you to fully manage users' secondary credentials. Secondary credentials are application-specific credentials that Single Sign-on submits on the user's behalf after the primary domain authentication has occurred.

Credential provisioning allows you to automate many of the tasks associated with managing user credentials. Whether you are rolling out a new installation of Single Sign-on, adding new users, adding new applications, or clearing out unneeded information, credential provisioning provides you with the tools to complete these tasks quickly and efficiently.

This online help describes the high-level design of Single Sign-on's credential provisioning feature and provides a summary of API functions that you can use to define actions in the provisioning XML file.

The Provisioning Module

The Provisioning Module is part of the Single Sign-on Service and is a standard Web Service that exposes a Simple Object Access Protocol and Service Provisioning Markup Language (SOAP/SPML) interface for receiving provisioning commands. All communications between the client and the Provisioning Module occur over a Transport Layer Security (TLS) channel.

When sending provisioning commands to the queue, ensure that the data is stored securely and is not transmitted over an insecure network connection.

The Provisioning Module must have read and write access to the Single Sign-on central store to be able to queue the incoming provisioning commands until the Single Sign-on Plug-in executes the commands.

Commands sent to the Provisioning Module cannot be recalled. Once sent, commands remain queued until they are executed by the SIngle Sign-on Plug-in. If you need to remove a command from the queue, send the opposite command for each user, application, and credential object that must be removed from the queue.

Note: The Provisioning Module uses an interface that conforms to SPML 2.0. Only the core operations required for conformance are supported.

The SPML 2.0 Model

The provisioning XML file and any third party components that issue SPML requests are called requesting authorities (RA).

The Provisioning Module is a Provisioning Service Provider (PSP). This PSP supports a single Provisioning Service Target (PST) that performs per-user queuing of Single Sign-on provisioning commands.

Providing users with secondary credentials is the action that is performed when running provisioning. This means that end users and secondary credentials are the Provisioning Service Objects (PSO) of the provisioning service target. The unique identifier (PSO-ID) for each end user is a fully qualified domain name (FQDN). The unique identifier (PSO-ID) for each secondary credential is the GUID assigned to the credential when it is created. Since the secondary credentials are associated with a particular user, the user PSO acts as a container for the credential PSOs. This is represented by the containerID element in an SPML request.

Strictly speaking, Single Sign-on does not add, modify, or delete users; however, Single Sign-on does add, modify, and delete data associated with a user.

Provisioning and the Single Sign-on Plug-in

Because the Single Sign-on Plug-in is ultimately responsible for protecting a user's secondary credentials with user-specific encryption keys, the execution of provisioning operations is a two-step process. First, you must issue the provisioning command to a Provisioning Module. Then, on behalf of its current user, the Single Sign-on Plug-in applies any queued provisioning commands to the user's secondary credential store.

The Single Sign-on Plug-in detects the presence of queued provisioning operations during its regular synchronization process, which occurs at start up. The plug-in executes queued provisioning commands before resuming normal activity. This ensures that in the First-Time-Use scenario, the plug-in performs the provisioning actions first, thus minimizing the end user's First-Time-Use configuration actions.

All communications between the Single Sign-on Plug-in and Provisioning Module occur over a TLS-secured connection.

The client provisioning application must define the mapping between the applications listed as available for provisioning and the client-side representation of the application.

Provisioning Secondary Credentials

Secondary credentials are associated with a specific application definition that was created using the Single Sign-on component of AppCenter; therefore, the addRequest operation must include data that binds the user details in the request to a specific application definition. This means that the requesting authority must determine the list of applications available for provisioning on a per-user basis, and provide an ID of an application definition as part of the addRequest operation. This burdens the requesting authority with determining the association between the Single Sign-on application definitions and your external identification (such as the application name) of the applications you are provisioning.

Since the person who administers Single Sign-on and the person who performs provisioning tasks may not be the same, there is a potential for "human induced confusion." For example, a Single Sign-on administrator may define the "Microsoft Outlook" application, while a provisioning administrator creates "Microsoft Exchange" accounts. Single Sign-on allows multiple secondary credentials for a given application definition. For example, a user might have multiple MSN Hotmail accounts for which Single Sign-on has stored credentials. This ability means that it is valid for an administrator to issue multiple addRequests with identical parameters. In this case, multiple secondary credentials are created. Similarly, the administrator may want to provision multiple different credentials for the same application; however, the secrets of the credential (user ID, password, and custom fields) are encrypted by Single Sign-on Plug-in and are not recoverable by the Provisioning module to aid the requesting authority in distinguishing the credentials at a later date.

To help address these issues an optional requesting authority private data field, provision description is available in the addRequest and modifyRequest operations. This provides the requesting authority with the ability to add an ID or descriptive data to help it distinguish the credentials. This field is not modified or displayed by the Single Sign-on Plug-in or the Provisioning module. It is retained and returned to the requesting authority when a credential list is requested through a lookupRequest.

The Single Sign-on Plug-in has complete edit-access to all the secondary credentials. This includes actions such as duplicating, deleting, and modifying the credentials. This means that users can change their data so that it no longer matches the state created by provisioning operations.

Also, users can define applications at will, which means they can add credentials for applications not defined in the Single Sign-on console. This ability can lead to ownership issues such as whether or not an administrator can delete or modify a secondary credential or should these credentials be listed in a lookupResponse.This release of Single Sign-on does not support any ownership restrictions; all credentials can be modified by either the administrator or the end user.

Application Groups

Single Sign-on allows you to group applications. An attribute of this grouping is whether or not to use the same password for all credentials defined for applications in the group. Whenever a user edits a credential associated with a group, the change is applied to all credentials of all applications in the group.

This behavior persists when changes are made through the provisioning API. More specifically, if a credential is added to an application group, the new password provided as a parameter to the add command becomes the new password for each application in the group. So, the add command has the net effect of an add and several modify commands. Similarly, a modify command modifies all the applications in a group and therefore has the net effect of several modify commands.

Error Codes

Code Description
101 One or more required credential fields are missing in provisioning request
102 Invalid user name specified; user name is either missing or format is not correct
103 Specified user not found
104 Invalid application definition; either application definition is missing or has an invalid structure
105 Credential identifier is not in valid format.
106 Specified credential not found.
107 Invalid authorization security token.
108 Unauthorized access token. Specified token is not allowed to perform requested operation.
109 Storage mechanism is accessed by another process. Please try after some time.
110 Error occurred while consuming provisioning commands.
111 User is not authorized to access provision command queue.
112 Error occurred while getting provisioning secret key.
113 Unable to allocate memory for encryption.
114 Unable to allocate entropy data buffer.
115 Encryption failed.
116 Unable to allocate cipherText buffer.
117 Decryption failed.
118 Failed to format windows error code to error message.
119 Pso Id is either missing or not in proper format.
120 Referenced application could not be found.
121 User configuration for requested user could not be found.
122 "join" attribute is missing for credential in password sharing group.
123 "use-new-password" attribute is missing for credential in password sharing group.
124 Password is missing for credential in password sharing group.
125 Credential name is invalid or missing. Please specify valid credential name.
126 Invalid application id specified.
127 Credential cannot rejoin password sharing group.
128 Provisioning is not enabled for the specified user account.