Using SSO in a Web Part


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.

Table 6-2: Classes 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.

Table 6-3: 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.

Table 6-4: Single Sign-On Return Codes

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 



Microsoft SharePoint[c] Building Office 2003 Solutions
Microsoft SharePoint[c] Building Office 2003 Solutions
ISBN: 1590593383
EAN: N/A
Year: 2006
Pages: 92

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net