Registering Custom Web Authentication Sign-In Assistants in OneNote 2010

Summary   Learn about customizing the Microsoft OneNote 2010 sign-in and authentication experience.

Applies to: Office 2010 | OneNote 2010

In this article
Custom Authentication for OneNote 2010
Registering a Custom Sign-in Assistant Component
Defining the Office Authentication API
Conclusion
Additional Resources

Published:   September 2011

Provided by:   Microsoft Corporation

Content

• Custom Authentication for OneNote 2010

• Registering a Custom Sign-in Assistant Component

• Defining the Office Authentication API

• Conclusion

• Additional Resources

Custom Authentication for OneNote 2010

This article is targeted at developers wishing to install solutions that customize the Microsoft OneNote 2010 sign in and authentication experience to a Web Provider. OneNote 2010 allows creating and storing notebooks on the Web. The default Web Provider for OneNote 2010 is Microsoft OneDrive, but this can be replaced by a different Web Provider. You can find more information on this in the article Extending OneNote 2010 to Use Different Web Providers for Creating or Sharing Notebooks.

In order to authenticate to a Web Provider other than OneDrive, it is recommended to use Forms Based Authentication as specified in the article [MS-OFBA]: Office Forms Based Authentication Protocol Specification.

To authenticate with a Web Provider, OneNote 2010 will prefer a Sign-in Assistant component, if one is installed on the system. By default, OneNote 2010 will look for the Windows Live Sign-in Assistant as shown in Figure 1. A custom Sign-in Assistant can be registered instead, as long as it supports the Office Authentication API – which is the focus of this article.

Figure 1. OneNote authentication process

Registering a Custom Sign-in Assistant Component

To register a sign-in assistant COM component with OneNote 2010, add the following string value to the registry key:

HKEY_CURRENT_USER\Software\Microsoft\Office\14.0\Common\Internet

The string value can be no larger than 260 characters.

Add the sign-in assistant string to the Windows registry

Registry String Value	Description
AuthenticationProvider (optional)	A string value specifying the path to the Authentication Component DLL.

The Microsoft Sign-in Assistant will delay-load the DLL specified at this path and its use, if the LogonIdentityExSSO method is present in the DLL.

Defining the Office Authentication API

The Office Authentication API uses the standard Windows COM data types, as specified in Windows Data Types and Component Development. It also uses the following data types.

Data Types

OPTION

A structure that specifies options for initializing the Sign-in Assistant.

Syntax

typedef struct
{
   DWORD dwId;
   BYTE * pValue;
   size_t cbValue;
} OPTION, * LP_OPTION;

Fields

• dwId
  A DWORD that specifies a Sign-in Assistant Option. OneNote 2010 passes in a value of 0x00000040.

• pValue
  A BYTE that specifies a pointer to the value of the option. OneNote 2010 passes in a byte pointer to a Unicode string production.

• cbValue
  The length of the data.

RSTParams

A data structure that specifies the request security token parameters.

Syntax

typedef struct
{
   DWORD cbSize;
   LPCWSTR wzServiceTarget;
   LPCWSTR wzServicePolicy;
   DWORD dwReserved;
   DWORD dwReserved2;
}  RSTParams, *PCRSTParams;

Fields

• cbSize
  A DWORD that specifies the size of the structure.

• wzServiceTarget
  An LPCWSTR that specifies the name of the target service. OneNote 2010 passes in a value of L"docs.live.net";.

• wzServicePolicy
  An LPCWSTR that specifies the service authentication policy for issuing the ticket. OneNote 2010 passes in a value of L”mbi”;.

• dwReserved
  Reserved. Must be zero.

• dwReserved2
  Reserved. Must be zero.

EnumIdentitiesHandle

A data structure that specifies a handle to the enumeration of cached user sign-in identities (cached credentials).

Syntax

typedef struct _tagPEIH {} *EnumIdentitiesHandle;

Value	Description
INVALID_IDENTITYHANDLE (0)	A EnumIdentitiesHandle value that specifies an invalid handle.

IdentityHandle

A data structure that specifies a handle to a user identity.

Syntax

typedef struct _tagPIH {} * IdentityHandle;

SSO_FLAGS

An enumeration that specifies the sign-in behavior.

Syntax

typedef enum
{
   SSO_DEFAULT              = 0x00000000,
   SSO_NO_UI                = 0x00000001,
   SSO_NO_AUTO_SIGNIN       = 0x00000002,
} SSO_FLAGS;

Value	Description
SSO_DEFAULT	Default behavior. Sign-in the user automatically if the user has already been signed in during the current application session or if the credentials are already cached for this user. If automatic sign-in is not possible, bring up a prompt to collect the credentials from the user. Return an error if the credential prompt is cancelled or if the user fails to provide valid credentials after several tries.
SSO_NO_UI	Attempt to sign in the user automatically, without displaying any credential prompts. If a credential prompt is needed, return an error.
SSO_NO_AUTO_SIGNIN	Do not attempt automatic sign-in, and bring up user interface (UI) to prompt the user for credentials, even if the user is already signed in or if credentials are cached.

UIParam

Specifies UI options.

Syntax

struct UIParam
{
     DWORD cbsize;
     DWORD dwReserved;
     HWND hwndParent;
     UINT_PTR pReserved;
     LPCWSTR wszServiceName;
     BYTE rgbReserved[16]; 
     UINT_PTR rghReserved[45];
} UIParam, * PCUIParam;

Fields

• cbSize
  A DWORD that specifies the size of the structure.

• dwReserved
  Reserved. Must be zero.

• hwndParent
  A HWND that specifies the handle to the parent window. Any UI dialogs should be parented to this window.

• pReserved
  Reserved. Must be zero.

• wszServiceName
  An LPCWSTR that specifies the name of the service or application to be displayed in the sign-in dialog.

• rgbReserved
  Reserved. Must be zero.

• rghReserved
  Reserved. Must be zero.

STATUS_CURRENT

A structure that specifies the authentication status information.

Syntax

typedef struct
{
    HRESULT hrAuthState;
    HRESULT hrReserved;
    HRESULT hrReserved2;
    HRESULT hrreserved3;
    LPCWSTR wzReserved;
} STATUS_CURRENT;

Fields

• hrAuthState
  An HRESULT that specifies the current authentication status of the identity. This value can indicate either that the identity is unauthenticated or the means by which the identity was authenticated. See the HRESULT Values section for a list of possible values for this field.

• hrReserved
  A reserved HRESULT.

• hrReserved2
  A reserved HRESULT.

• hrReserved3
  A reserved HRESULT.

• wszReserved
  A reserved LPCWSTR.

Methods

The sign-in API also uses the following methods.

InitializeEx

InitializeEx is called at the beginning of the session to initialize the Sign-in Assistant.

If other methods are called before calling this method, they should return 0x80048008 to indicate that the library has not been initialized prior to the call. Before the calling application exits, it calls Uninitialize.

Syntax

HRESULT InitializeEx(
       IN REFGUID GuidClientApplication,
       IN LONG lPPCRLVersion,
       IN DWORD dwFlags,
       IN LP_OPTION pOptions,
       IN DWORD dwOptions
       );

Parameters

• GuidClientApplication
  A REFGUID that uniquely identifies the hosting application. OneNote 2010 passes in {9317BCB6-314B-442f-A5DA-9BC2BEBC271D}.

• lPPCRLVersion
  A LONG that specifies the version of the API. OneNote 2010 passes in a value of 1.

• dwFlags
  A DWORD that specifies the Sign-in Assistant behavior for checking the connection. A value of 0 specifies the default behavior: if no connection to the server is available, the Sign-in Assistant should return an error. OneNote 2010 passes in 0.

• pOptions
  A pointer to an array of OPTION structures that specifies initialization options. OneNote 2010 passes in one option with a pointer to the string L”production”, specifying that it is connecting to the production version of the web service.

• dwOptions
  A DWORD that specifies the number of elements in the pOptions array.

Return Values

The following table describes the return values for this method:

HRESULT Value	Meaning
0x8004886f	The flag supplied is not valid.
0x00048044	The Sign-in Assistant has already been successfully initialized and is ready to be used.
S_OK	The Sign-in Assistant was successfully initialized and is ready to be used. It has detected a connection to the Internet and was able to successfully update its local configuration information from the Web Provider servers, if necessary.

Uninitialize

Uninitialize is called by the application before exiting, to clean up and exit the Sign-in Assistant.

Syntax

HRESULT Uninitialize(void);

Return Values

The following table describes the return values for this method:

HRESULT Value	Meaning
0x80048045	Uninitialization is skipped because of another initialization in the same process.
S_OK	The Sign-in Assistant was successfully uninitialized.

EnumIdentitiesWithCachedCredentials

EnumIdentitiesWithCachedCredentials retrieves an enumeration that contains the sign-in names of the identities for which a credential has been cached. A cached credential itself cannot be retrieved. The enumeration that is returned by this method is a snapshot of the cached credentials at the time of the call. If credentials are cached between the time the method is called and the time the enumeration is used, the newly cached credentials are not included in the enumeration.

The enumerated identities can be retrieved using the NextIdentity method. The enumeration is closed using the CloseEnumIdentitiesHandle method.

Syntax

HRESULT EnumIdentitiesWithCachedCredentials (
       IN OPTIONAL LPCWSTR szCachedCredType,
       OUT EnumIdentitiesHandle *peihEnumHandle
       );

Parameters

• szCachedCredType
  Optional. An LPCWSTR that specifies the type of credential that will be included in the returned enumeration. Can be one of the following values, or null:

Value	Meaning
ps:password	Return credentials where both the sign-in name and password are persisted.

• peihEnumHandle
  A EnumIdentitiesHandle to the location of the sign-in names of the identities for which credentials are cached.

Return Values

The following table describes the return values for this method:

HRESULT Value	Meaning
S_OK	The cached credential enumeration was successfully retrieved.
E_INVALIDARG	The peihEnumHandle parameter is null.

NextIdentity

NextIdentity returns the next identity in the enumeration of sign-in names for identities that have cached credentials. The enumeration is generated by calling the EnumIdentitiesWithCachedCredentials method.

The sign-in names returned by this method are to be freed by using the FreeMemory method.

Syntax

HRESULT NextIdentity(
       IN EnumIdentitiesHandle hEnumHandle,
       OUT LPWSTR * szMemberName
       );

Parameters

• hEnumHandle
  A EnumIdentitiesHandle specifying the enumeration of the sign-in names of the identities for which the credentials are cached.

• wszMemberName
  An LPCWSTR that specifies the sign-in name of the retrieved identity.

Return Values

The following table describes the return values for this method:

HRESULT Value	Meaning
S_OK	The sign-in name was successfully retrieved.
E_POINTER	The wszMemberName parameter is NULL.

CloseEnumIdentitiesHandle

CloseEnumIdentitiesHandle closes an enumeration of sign-in names for identities with cached credentials. After the enumeration has been closed, it cannot be used by any of the other methods. For information about generating this enumeration, see EnumIdentitiesWithCachedCredentials method which was discussed previously in this article.

Syntax

HRESULT CloseEnumIdentitiesHandle (
       IN EnumIdentitiesHandle EnumHandle
       );

Parameters

• EnumHandle
  A EnumIdentitiesHandle specifying the sign-in names of the identities for which credentials are cached.

Return Values

The following table describes the return values for this method:

HRESULT Value	Meaning
S_OK	The enumeration was successfully closed.

FreeMemory

FreeMemory frees buffers allocated and returned by the Sign-in Assistant.

Syntax

HRESULT FreeMemory(
       IN void * pMemoryToFree
       );

Parameters

• pMemoryToFree
  A pointer to the allocated memory.

Return Values

HRESULT Value	Meaning
S_OK	The memory was successfully freed.
0x8004801e	The pointer in the request does not point to a memory block that is allocated by the Sign-in Assistant. This code may also be returned if the same memory block is freed more than once.

CreateIdentityHandleEx

CreateIdentityHandleEx creates a new identity handle. This handle can be passed as a parameter to several Sing-In Assistant methods. The IdentityHandle object is used to represent a user account, including the sign-in name of the account and any authentication or service tickets that are associated with the account.

If the user account has a persistence type specifying that the Sign-in Assistant should remember the account password and the account has previously had a successful sign-in, any persisted service tickets and certificates that the Sign-in Assistant deems to be valid and unexpired should be retrieved from the credential store and populated into the identity handle automatically.

The CloseIdentityHandle method will be called when the identity handle is no longer needed and the memory for it can be freed.

Syntax

HRESULT CreateIdentityHandle (
       IN OPTIONAL LPCWSTR wszMemberName,
       IN DWORD dwflags,
       IN DWORD dwSsoGroup,
       OUT IdentityHandle *pihIdentity
       );

Parameters

• wszMemberName
  Optional. An LPCWSTR that specifies the sign-in name of the identity that is created. May be NULL initially if a new user needs to sign in.

• dwflags
  Reserved. Must be zero.

• dwSsoGroup
  A DWORD that specifies the group of services among which an actively signed-in user can be signed in automatically. OneNote 2010 passes in a value of zero specifying that the Sign-in Assistant should not automatically pick up any active signed in user from other services.

• pihIdentity
  An IdentityHandle that specifies the identity.

Return Values

The following table describes the return values for this method:

HRESULT Value	Meaning
S_OK	The identity handle was successfully created. A previously persisted password, service tickets, and certificates, will be loaded if the specified member name is found among cached credentials or if there is already one active signed in user.
E_POINTER	The supplied identity handle pointer is NULL.

CloseIdentityHandle

CloseIdentityHandle closes an identity handle previously opened with CreateIdentityHandleEx freeing any resources associated with the identity.

The Sign-in Assistant should maintain an internal reference count for identity handles. If multiple identity handles are created for the same user, the identity handles will all point to the same internal object. If some identity handles are closed, the other identity handles will still be valid.

If the identity associated with the identity handle being closed has a persisted password, the identity's service tickets (except legacy tickets) and certificates, including short-lived certificates, should also persist. If the identity does not have a persisted password, the identity's service tickets and certificates should be removed from memory.

Syntax

HRESULT CloseIdentityHandle(
        IN IdentityHandle hIdentity);

Parameters

• hIdentity
  An IdentityHandle that specifies the identity to be closed.

Return Values

The following table describes the return values for this method:

HRESULT Value	Meaning
S_OK	The identity handle was successfully closed.

LogonIdentityExSSO

LogonIdentityExSSO is called whenever the calling application may need authentication to the server of the specified identity handle, which may represent a known or unknown sign-in name.

When the Sign-in Assistant attempts to authenticate to the target URL on the server, it can bring up UI to prompt the user for credentials, if needed, and handle any resulting errors. The value of dwSSOFlags specifies whether this UI is to be suppressed. Even if the UI is not suppressed, the Sign-in Assistant should avoid bringing up any credential prompt UI if there is a way to authenticate without it. For example, if the user on previous interactions with the same UI has requested to store credentials on this computer, the Sign-in Assistant should retrieve them from the credential store without UI prompts and silently obtain the service tokens for the handle. Or if the user has already provided credentials for the target server and URL earlier in this application session, they should be reused without UI prompts. The Sign-in Assistant should provide in for such capabilities in the credential prompt UI and in the internal state that it stores during the session. A credential should be persisted to the credential store only of the user requests that in the UI and if at least one successful authentication has been completed.

If the authentication is successful, service tokens should be generated and the specified identity handle should have the appropriate authentication state. The service tokens will be put in a cache and the AuthIdentityToService method with the SERVICE_TOKEN_FROM_CACHE flag can be used to retrieve them.

If the authentication is not successful because the user cancelled the UI, because the UI was suppressed but needed, or for other reasons, the method returns a failure HRESULT that specifies the error condition.

By default, this method is executed synchronously. For asynchronous authentication, a callback method can be set by using the SetIdentityCallback method.

Syntax

HRESULT LogonIdentityExSSO(
       IN IdentityHandle hExternalIdentity,
       IN LPCWSTR wszReserved,
       IN DWORD dwAuthFlagsIn,
       IN DWORD dwSSOFlags,
       IN PCUIParam pcUIParam,
       IN PCRSTParams pcRSTParams,
       IN DWORD dwRSTParamsCount
);

Parameters

• hExternalIdentity
  A IdentityHandle that specifies the identity handle to be authenticated.

• wszReserved
  Reserved. Must be NULL.

• dwAuthFlagsIn
  A DWORD specifying a value of the type of authentication to be used. OneNote 2010 passes in a value of 0 specifying the default method.

• dwSSOFlags
  A DWORD value from the SSO_FLAGS enumeration that specifies the sign-in behavior.

• pcUIParam
  An optional pointer to a UIParam structure that specifies any customization parameters for the user interface used to collect user credentials, if any user interface needs to be shown. May be NULL.

• pcRSTParams
  An array of RSTParams structures that contain parameters for the service targets and batched ticketing behavior. OneNote 2010 passes in only one request at a time, so batched ticketing is not needed.

• dwRSTParamsCount
  A DWORD that specifies the number of requests in the array of RSTParams structures.

Return Values

The following table describes the return values for this method:

HRESULT Value	Meaning
0x80048869	A connection with the web provider service could not be established.
0x8004886c	No sign-in name has been set for the identity.
0x8004882d	The identity sign-in name is not of format xxxx@yyyy.
0x8004882e	The password was not found for the identity.
0x80048848	A network connection could not be established.
0x80048852	The correct domain authority could not be found.
0x8018	The authentication request could not be initialized or built.
0x00048847	In synchronous requests, a thread is waiting for a ticket from the server.
S_OK	The authentication call was completed successfully.

SetIdentityCallback

SetIdentityCallback associates a callback method with an identity. This method sets the identity to use asynchronous authentication. Calls to the AuthIdentityToService and LogonIdentityExSSO methods call the callback method when the updated authentication state of the supplied identity is returned from the participating service.

Syntax

HRESULT SetIdentityCallback(
       IN IdentityHandle hIdentity,
       IN IdentityChangedCallback pfCallbackNotification,
       IN OPTIONAL void * pvCallbackData
       );

Parameters

• hIdentity
  A IdentityHandle that specifies the identity handle for which the callback is set.

• pfCallbackNotification
  An IdentityChangedCallback that specifies the callback method that the Sign-in Assistant will call when the authentication state of the identity is updated. A NULL value specifies that the request for the service ticket after the authentication should be performed synchronously.

• pvCallbackData
  A pointer to the proprietary application data that is passed in to the callback method when the identity's authentication state changes.

Return Values

The following table describes the return values for this method:

HRESULT Value	Meaning
S_OK	The callback was set successfully.

IdentityChangedCallback

The calling application implements this method to be used as a callback to take actions based on the identity authentication state. The Sign-in Assistant should call this method when an authentication state change occurs for an identity that is configured to use asynchronous authentication. An identity is set to use asynchronous authentication by calling the SetIdentityCallback method. After the callback has been associated with an identity, it is called by the Sign-in Assistant in response to calls to the AuthIdentityToService and LogonIdentityExSSO methods. The method may be called by multiple threads at the same time.

Syntax

HRESULT IdentityChangedCallback (
       IN IdentityHandle hIdentity,
       IN void * pvVoid,
       IN bool bCanContinue
);

Parameters

• hIdentity
  A IdentityHandle that specifies the identity for which the authentication state has changed.

• pvVoid
  A pointer to proprietary application data that is associated with the identity. The contents of this parameter are set by means of a call to the SetIdentityCallback method.

• pCanContinue
  Reserved. Do not use.

Return Values

The Sign-in Assistant ignores the return values for this method.

AuthIdentityToService

AuthIdentityToService retrieves a service ticket for an authenticated identity. The type of service ticket that is returned by this method is determined by the service and the policy for which the ticket is being requested.

Syntax

HRESULT AuthIdentityToService(
       IN IdentityHandle hIdentity,
       IN LPCWSTR szServiceTarget,
       IN OPTIONAL LPCWSTR szServicePolicy,
       IN DWORD dwTokenRequestFlags,
       OUT OPTIONAL LPWSTR *szToken,
       DWORD * pdwReserved,
       BYTE ** prgbReserved,
       DWORD * pdwReserved2
       );

Parameters

• hIdentity
  A IdentityHandle that specifies the identity handle for which a service ticket is being requested.

• szServiceTarget
  An LPCWSTR that specifies the service name for which the ticket is being requested. OneNote 2010 passes in a pointer to L”docs.live.net”.

• szServicePolicy
  An optional LPCWSTR that specifies the service policy. OneNote 2010 passes a value of L”mbi” specifying that a Secure Sockets Layer (SSL) is required during authentication.

• dwTokenRequestFlags
  A DWORD that specifies whether the request parameters. OneNote 2010 passes in a value of 0x00010000 that specifies that the service tickets and certificates should be retrieved from a cache.

• szToken
  An optional LPCWSTR that specifies the returned service ticket.

• pdwReserved
  Reserved. Must be NULL.

• prgbReserved
  Reserved. Must be NULL.

• pdwReserved2
  Reserved. Must be NULL.

Return Values

On failure, must return a failure HRESULT.

AuthIdentityToServiceEx

AuthIdentityToServicEx requests authentication tickets from the authentication service and stores the tickets in a local cache. To use individual tickets after they have been retrieved, the AuthIdentityToService method should be used, specifying the applicable service name and using the flag 0x00010000.

Syntax

HRESULT AuthIdentityToServiceEx(
       IN IdentityHandle hIdentity,
       IN DWORD dwRequestFlags,
       IN PCRSTParams pcRSTParams,
       IN DWORD dwRSTParamsCount
);

Parameters

• hIdentity
  A IdentityHandle that specifies the identity handle for which a service ticket is being requested.

• dwRequestFlags
  Must be 0.

• pcRSTParams
  A pointer to an array of RSTParams structures that specify the parameters of the ticket requests.

• dwRSTParamsCount
  A DWORD that specifies the number of items in the array of RSTParams.

Return Values

The return values are ignored.

GetAuthenticationStatus

GetAuthenticationStatus gets the current sign-in state of the specified identity and also the identity's current position in the authentication process. If the identity is not authenticated, the ppStatus return parameter will contain the information about why the identity is not authenticated.

Syntax

HRESULT GetAuthenticationStatus(
       IN  IdentityHandle hIdentity,
       IN  LPCWSTR wzServiceTarget,        
       IN  DWORD dwVersion,
       OUT PVOID *ppStatus
       );

Parameters

• hIdentity
  A IdentityHandle that specifies the identity for which authentication state information is being requested.

• wzServiceTarget
  An LPCWSTR that specifies the name of the target service.

• dwVersion
  A DWORD that specifies the version of the API. Must be 1.

• ppStatus
  A STATUS_CURRENT structure that specifies the status of the request.

Return Values

The following table describes the return values for this method:

HRESULT Value	Meaning
S_OK	The authentication state of the identity was retrieved successfully.

Conclusion

You can customize the OneNote 2010 sign in and authentication experience to provide a different web provider other than the default provider. OneNote 2010 will do that with a Sign-in Assistant component, if one is installed on the system. You can instead use a custom Sign-in Assistant as long as it supports the Office Authentication API.

Additional Resources

For more information, see the following resources:

• Extending OneNote 2010 to use Different Web Providers for Creating or Sharing Notebooks for Developers

• Extending the Save to Web Functionality in the Office 2010 Backstage View

• Registering Custom Web Authentication Sign-In Assistants in OneNote 2010

• HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)

• File Synchronization via SOAP over HTTP Protocol Specification