Once the service is running and the policy is established, you are ready to create a web part. In order to use the Microsoft SSO service in a web part, you must first set a reference to the SingleSignOn assembly in Visual Studio. After starting a new web part project, set a reference to the Microsoft.SharePoint.Portal.SingleSignon.dll assembly. Once this reference is set, you can import the library into your code by using one of the following formats for C# or VB.NET.
//C# using Microsoft.SharePoint.Portal.SingleSignon; 'VB.NET Imports Microsoft.SharePoint.Portal.SingleSignon
The Microsoft.SharePoint.Portal.SingleSignon namespace provides several classes that provide complete access to all of the administration functions of SSO. You can use these classes not only to access enterprise systems, but also to create your own separate administration interface. You can even go so far as to build a web part that allows portal users to perform self-service on their own credentials. Table 6-2 summarizes the classes available in the SingleSignon namespace.
CLASS | DESCRIPTION |
---|---|
Application | Retrieves, adds, and deletes application definitions |
Credentials | Retrieves, adds, and deletes application credentials |
SSOReturnCodes | Enumerates the results of a SingleSignonException |
SingleSignonException | Thrown when an SSO error occurs |
Access to the entire set of stored credentials managed by SSO is accomplished through the Credentials class. Using this class, you can store, retrieve, and delete credentials for any application stored in the configuration database. Table 6-3 lists the members of the Credentials class.
MEMBER | DESCRIPTION |
---|---|
DeleteAllUserCredentials(String Account) | Deletes all the credentials for a user or group Account for every application definition. |
DeleteUserCredentials(String Application, String Account) | Deletes the credentials for a user or group Account for a specific Application definition. |
GetCredentials(UInt32 Flag, String Application, String[ ] Credentials) | Returns a reference to an array of Credentials given an Application name . If the Flag is set to 0, then the cache is checked for the credentials before the database is accessed directly. If the Flag is set to 1, then the cache is not checked. |
GetCredentialsUsingTicket(UInt32 Flag, String Application, String Ticket, String[ ] Credentials) | Returns a reference to an array of Credentials given an Application name and an access Ticket . If the Flag is set to 0, then the ADO.NET data cache is checked for the credentials before the database is accessed directly. If the Flag is set to 1, then the cache is not checked. |
ReserveCredentialTicket(SingleSignOnTicketType.Default, String Ticket) | Returns an access Ticket that may be used by a member of the SSO administrator account to access credentials. |
SetCredentials(UInt32 Flag, String Application, String [ ] Credentials) | Sets the Credentials for a specific Application for the current user. |
SetGroupCredentials(String Application, String Group, String[ ] Credentials) | Sets the Credentials for a specific Application for the specified Group . |
SetUserCredentials(String Application, String Account, String[ ] Credentials) | Sets the Credentials for a specific Application for the specified Account . |
When a web part needs to access an external system, it calls the GetCredentials method. Any user is allowed to call GetCredentials ; however, the active security policy determines the level of access allowed. If the credentials exist in the data store, then they are returned as an array of Strings . The order of the data returned in the array is the same as the order in which the application fields were defined by the administrator. The following code shows the basic technique using VB.NET.
Dim Username As String Dim Password As String Dim strCredentials() As String Dim uintFlag As New UInt32 Credentials.GetCredentials(UInt32.Parse("1"), "AppName", strCredentials) Username = strCredentials(0) Password = strCredentials(1)
If the web part attempts to retrieve credentials and fails, then the GetCredentials method throws a SingleSignonException . The exact reason for the failure is subsequently determined by examining the LastErrorCode property of the SingleSignonException object. Table 6-4 lists the possible return values for the LastErrorCode property.
NAME | DESCRIPTION |
---|---|
SSO_E_ACCESSDENIED | Access is denied to the SSO resource. |
SSO_E_ALREADY_SS | The computer is already set up as a secret server. |
SSO_E_APPLICATION_ALREADY_EXISTS | The Enterprise Application Definition already exists. |
SSO_E_APPLICATION_CANNOT_OVERWRITE | The operation is unable to overwrite the Enterprise Application Definition. |
SSO_E_APPLICATION_CREATION_ DISPOSITION_UNKNOWN | Disposition is unknown. |
SSO_E_APPLICATION_NOT_FOUND | The Enterprise Application Definition cannot be found. |
SSO_E_APPLICATION_TYPE_UNKNOWN | The Enterprise Application Definition type is unknown. |
SSO_E_CREDS_NOT_FOUND | The credentials could not be found. |
SSO_E_DB_ALREADY_EXISTS | The database specified already exists. |
SSO_E_EXCEPTION | This is a general SSO exception. |
SSO_E_GET_CREDS_FLAG_UNKNOWN | The GetCredentials flag is unknown. |
SSO_E_INVALID_AUDIT_PURGE_DAYS | The purge audit days specified are invalid. |
SSO_E_INVALID_NUMBER_OF_CRED_FIELDS | The number of credential fields specified is invalid. |
SSO_E_INVALID_NUMBER_OF_CREDS | The number of credentials is invalid. |
SSO_E_INVALID_TICKET_TIMEOUT | The access token time-out specified is invalid. |
SSO_E_MASTER_SECRET_NOT_EXIST | The encryption key does not exist. |
SSO_E_REENCRYPTING | SSO is reencrypting the SSO database. |
SSO_E_SECRET_ALREADY_EXISTS | The base system key already exists. |
SSO_E_SET_CREDS_FLAG_UNKNOWN | The SetCredentials flag is unknown. |
SSO_E_SHAREPOINT_VROOT_CANNOT_ BE_FOUND | The virtual root for SPS could not be found. |
SSO_E_SSO_DB_NOT_INSTALLED | The SSO database does not exist. |
SSO_E_SSO_NOT_CONFIGURED | SSO is not configured. |
SSO_E_SSO_NOT_INSTALLED | The SSO service is not installed. |
SSO_E_SSO_WRONG_VERSION | The wrong SSO database version is being used. |
SSO_E_TICKET_TYPE_UNKNOWN | The access token type is unknown. |
SSO_E_WRONG_SS | This is the wrong secret server. |
Your web part should treat the SSO resource exactly as it would any protected resource limited by code access security policies. This means that you should always implement error handling when attempting to access the data store. In most cases, you will be attempting to retrieve credentials and should be concerned that the credentials do not exist. This situation can happen frequently with application definitions that contain an individual log-in. In fact, it is almost guaranteed to happen the first time a user invokes a web part that accesses a new application definition.
Because an administrator will not know individual credentials, your web part should expect to handle SSO_E_CREDS_NOT_FOUND the first time any user accesses your web part. In response, you must help the user enter the correct credentials into the data store for future use. SSO supports the user by providing a web page where the user can enter their credentials if they are not found.
Users access the logon form provided by the SSO by clicking a hyperlink that you build in code. The hyperlink is generated by the SingleSignonLocator class. This class supports the GetCredentialEntryUrl method, which takes the application name as an argument. The following code shows how to build a simple hyperlink in the RenderWebPart method to redirect users to the logon form.
Try Catch x As SingleSignonException 'If we cannot get the credentials, then show a link to log in If x.LastErrorCode = SSOReturnCodes.SSO_E_CREDS_NOT_FOUND Then 'Get the URL to save SSO credentials Dim strURL As String strURL = SingleSignonLocator.GetCredentialEntryUrl("MyApp") 'Display a link output.Write("<a href=""" + strURL + """>Please log in</a>") End If End Try
CAUTION | The GetCredentialEntryUrl method will fail if the current user has no credentials in the SSO database. Talk about a catch-22! The workaround is to first define dummy credentials for each user and then delete them. This will associate the user with an application definition while ensuring that the SSO_E_CREDS_NOT_FOUND exception occurs when the web part is first accessed. |
The SingleSignonLocator class belongs to the Microsoft.SharePoint.Portal namespace. Therefore, you will have to set a reference to the Microsoft.SharePoint. Portal.dll assembly before you can use the class. Additionally, you will want to import the namespace into your code using one of the following examples.
//C# using Microsoft.SharePoint.Portal; 'VB.NET Imports Microsoft.SharePoint.Portal