27
28
/*! \page cred_acq Managed credential acquisition
29
Credential providers and the identity provider must participate in
30
Credential providers and identity providers must participate in
30
31
managed credential acquisition in order to respond to the user's
31
requests to obtain new credentials for an identity or to obtain
32
new credentials for an existing identity.
32
requests to obtain new credentials for an identity or to renew
33
credentials for an existing identity.
34
35
There are two major processes that result in managed credential
35
acuqisition. One is the acquisition of initial credentials, while
36
the other is the acquisition of new crednetials. Both processes
37
acquire new credentials (or replace existing credentials with new
38
ones). The difference between the two processes lie in the way the
39
new credentials are obtained. Initial credentials are obtained
40
using user supplied username and password while new credentials
41
are obtained using other existing credentials.
36
acuqisition. One is the acquisition of credentials, while the
37
other is credential renewal. During a renewal, existing
38
credentials are used to obtain new credentials which expire later
39
than the existing credential. Typically, the identity provider
40
performs the task of obtaining renewed initial credentials while
41
the other credential providers obtain new credentials based on
42
these initial credentials.
43
\section cred_acq_init Initial Credentials
44
\section cred_acq_new New Credentials
45
46
When a user initiates the process of initial credential
46
acquisition, NetIDMgr broadcasts a
47
<::KMSG_CRED,::KMSG_CRED_INITIAL_CREDS> message. Credential
48
providers which need to participate in the initial credential
49
acquisition should respond to this message as detailed in
52
\section cred_acq_new New Credentials
54
When a user initiates the process of obtaining new credentials
55
based on existing credentials, NetIDMgr broadcasts a
47
acquisition, Network Identity Manager broadcasts a
56
48
<::KMSG_CRED,::KMSG_CRED_NEW_CREDS> message. Credential providers
57
which need to participate in the initial credential acquisition
58
should respond to this message as detailed in \ref cred_acq_handle.
49
which need to participate in the credential acquisition should
50
respond to this message as detailed in \ref cred_acq_handle.
52
\section cred_acq_renew Renew Credentials
54
Network Identity Manager broadcasts a
55
<::KMSG_CRED,::KMSG_CRED_RENEW_CREDS> message to initiate the
56
process of renewing credentials. This may be triggered
57
automatically or by a user action. Credential providers which
58
need to participate in the renewal should respond to this message
59
as detailed in \ref cred_acq_handle.
60
61
The following pages provide detailed information:
95
92
are done through ::KHUI_WM_NC_NOTIFY messages to the dialog
98
- Once the dialog completes, NetIDMgr sends
99
<::KMSG_CRED,::KMSG_CRED_DIALOG_END> message to all the
100
credentials providers. The UI portion ends here. The
101
individual dialog controls are destroyed as a result of the main
102
credentials acquisition window being destroyed.
104
- NetIDMgr posts <::KMSG_CRED,::KMSG_CRED_DIALOG_PROCESS> message
105
to all the credentials providers. Each provider should check if
106
the user cancelled the dialog or indicated that the new
107
credentials should be obtained and act accordingly. The
108
credentials provider is responsible for removing the
109
::khui_new_creds_by_type structre from the ::khui_new_creds
110
structure and freeing up any resources it allocated earlier in
111
preparation for obtaining new credentials.
95
- Once the dialog processing is done, a ::WMNC_DIALOG_PREPROCESS
96
message is sent to the dialog procedure.
98
- Network Identity Manager posts
99
<::KMSG_CRED,::KMSG_CRED_DIALOG_PROCESS> message to all the
100
credentials providers. Each provider should check if the user
101
cancelled the dialog or indicated that the new credentials
102
should be obtained and act accordingly. The \c result field of
103
the ::khui_new_creds structure will be set to either
104
::KHUI_NC_RESULT_PROCESS or ::KHUI_NC_RESULT_CANCEL to indicate
105
whether the user wishes to acquire credentials or cancel the
108
- Once all the plug-ins have processed the <::KMSG_CRED,
109
::KMSG_CRED_DIALOG_PROCESS> message, the application checks
110
whether the new credentials dialog should continue processing,
111
or whether the dialog should be closed. If the dialog should
112
continue processing, then the dialog returns to the state it was
113
in prior to the ::WMNC_DIALOG_PREPROCESS message was sent. If
114
the dialog should be closed, then a <::KMSG_CRED,
115
::KMSG_CRED_END> message is sent.
117
- A <::KMSG_CRED, ::KMSG_CRED_END> message signals the end of the
118
credentials acquisition process. Each credentials provider is
119
responsible for removing the ::khui_new_creds_by_type structre
120
from the ::khui_new_creds structure and freeing up any resources
121
it allocated earlier in preparation for obtaining new
113
124
\section cred_acq_handle Responding to credential acquisition messages
126
\subsection cred_acq_handle_init <::KMSG_CRED,::KMSG_CRED_NEW_CREDS> and <::KMSG_CRED,::KMSG_CRED_RENEW_CREDS> Messages
115
128
The credential acquisition messages are
116
<::KMSG_CRED,::KMSG_CRED_INITIAL_CREDS> and <::KMSG_CRED,
117
::KMSG_CRED_NEW_CREDS>. They are structured as follows :
129
<::KMSG_CRED,::KMSG_CRED_NEW_CREDS> and <::KMSG_CRED,
130
::KMSG_CRED_RENEW_CREDS>. They are structured as follows:
119
132
- \b type : ::KMSG_CRED
120
- \b subtype: ::KMSG_CRED_INITIAL_CREDS or ::KMSG_CRED_NEW_CREDS
133
- \b subtype: ::KMSG_CRED_NEW_CREDS or ::KMSG_CRED_RENEW_CREDS
121
134
- \b uparam : 0 (unused)
122
135
- \b vparam : a pointer to a ::khui_new_creds structure.
124
137
The \a vparam parameter of the message, as shown above, is a
125
138
pointer to a ::khui_new_creds structure. You can use the \a
126
subtype field of this structure to determine whether this is an
127
initial credentials acquisition or a new credentials acquisition
139
subtype field of this structure to determine whether this is a new
140
credentials acquisition or a renewal.
130
142
In response to this message, a credentials provider is expected to
131
143
provide a configuration panel which the user can use to customize
132
144
how the credentials of this type are to be obtained. The panel is
133
described by the ::khui_new_cred_panel structure.
145
described by the ::khui_new_creds_by_type structure.
135
\subsection cred_acq_panel_spec Specifying the credentials type panel
147
\subsubsection cred_acq_panel_spec Specifying the credentials type panel
137
149
The credentials type panel is used by the user to customize how
138
150
credentials of the specified type are to be obtained. The
139
::khui_new_cred_panel structure that describes the panel can be
151
::khui_new_creds_by_type structure that describes the panel can be
140
152
used to specify a number of parameters that guide how the panel is
141
153
to be displayed in the new credentials acquisition dialog.
143
155
The \a name field defines a localized string that will be
144
displayed in the tab control that houses the panel. Optionally,
156
displayed in the tab control that houses the panel. If it is \a
157
NULL, then the name of the credentials type is used. Optionally,
145
158
an icon can be specified in the \a icon field which will appear
146
159
alongside the name. A tooltip may be provided in the \a tooltip
147
160
field which will be displayed when the user hovers the mouse over
155
168
name). Then the panels without a positive ordianl are arranged
156
169
behind these in increasing order of \a name.
158
The \a hwnd_panel field is used to specify the handle to the
159
dialog or window of the panel. The parent of this window should
160
be set to the \a hwnd parameter of the ::khui_new_creds structure
161
which is passed in to the message handler.
171
Currently, the credentials provider must specify a dialog template
172
that will be used to create the embedded dialog for configuring
173
new credentials for the type. This is done by setting the
174
khui_new_creds_by_type::h_module, khui_new_creds_by_type::dlg_proc
175
and khui_new_creds_by_type::dlg_template fields.
163
Following is a code snippet which suggests how this could be done:
177
Following is example code which suggests how this could be done:
166
180
// Message handling code for KMSG_CRED_NEW_CREDS or
205
218
/*! \page cred_acq_dlgproc Writing the dialog procedure for a cred type panel
220
Once each credentials provider has had a chance to add a
221
credentials type panel for the new credentials dialog, the
222
application will attempt to create all the dialog panels. It will
223
use the dialog template and the dialog procedure specified in the
224
\c dlg_proc and \c dlg_template members of the
225
::khui_new_creds_by_type structure.
227
The credentials type panel will be an ordinary dialog that is
228
created as a child of the new credentials window. Therefore, the
229
dialog template should have the WS_CHILD style and the
230
WS_EX_CONTROLPARENT extended style set so that the main dialog
231
procedure can correctly navigate the child dialog.
233
\section cred_acq_dlgmsg Handling Messages
235
\subsection cred_acq_dlg_WM_INITDIALOG WM_INITDIALOG
237
When the application creates a credentials type panel dialog, it
238
passes a pointer to the ::khui_new_creds structure as the \c
239
LPARAM parameter. This can be used to query for the credentials
240
type panel for the plug-in, as follows:
244
// Handler for WM_INITDIALOG:
245
// HWND hwnd, WPARAM wParam and LPARAM lParam
247
khui_new_creds * nc = NULL;
248
khui_new_creds_by_type * nct = NULL;
250
// We can define and use a structure like the following to
251
// maintain the data that will be used to drive the dialog user
252
// interface and to store credentials type settings:
253
struct nc_dialog_data * d = NULL;
255
nc = (khui_new_creds *) lParam;
257
// Now we can use nc to query for our credentials type structure
258
khui_cw_find_type(nc, credtype_id, &nct);
262
// The dialog data structure should live until we receive
264
d = malloc(sizeof(*d));
265
ZeroMemory(d, sizeof(*d));
270
// Store it as our user data for the dialog.
271
SetWindowLongPtr(hwnd, DWLP_USER, (LPARAM) d);
273
// The aux member of the khui_new_creds_by_type structure is
274
// reserved for use by the credentials provider. We can use it to
275
// store our dialog data. This way, the dialog procedure and the
276
// plug-in thread can both access it and use it to store
277
// credential options for use when obtaining credentials. The
278
// dialog and the dialog data exist until KMSG_CRED_END is sent.
279
nct->aux = (LPARAM) d;
281
// We should return FALSE here to indicate that we don't want to
282
// set keyboard focus to this dialog yet. The application will
283
// attempt to create all the credentials type panels as well as
284
// the other child dialogs used for the new credentials opeartion.
289
\subsection cred_acq_dlg_WM_NC_NOTIFY WM_NC_NOTIFY
291
::WM_NC_NOTIFY is a special window message that Network Identity
292
Manager uses to communicate with credentials type panels. The
293
messages are listed in the ::khui_wm_nc_notifications enumeration.
294
The format of the message is as follows:
296
- uMsg : KHUI_WM_NC_NOTIFY
297
- HIWORD(wParam) : one of ::khui_wm_nc_notifications
298
- LPARAM : pointer to the ::khui_new_creds structure (except where noted)
300
The ::WM_NC_NOTIFY notifications that a credentials provider is
301
expected to handle are the following:
303
- ::WMNC_IDENTITY_CHANGE
305
\copydoc WMNC_IDENTITY_CHANGE
309
\copydoc WMNC_DIALOG_MOVE
311
- ::WMNC_UPDATE_CREDTEXT
313
\copydoc WMNC_UPDATE_CREDTEXT
315
- ::WMNC_CREDTEXT_LINK
317
\copydoc WMNC_CREDTEXT_LINK
319
- ::WMNC_DIALOG_PREPROCESS
321
\copydoc WMNC_DIALOG_PREPROCESS
323
\section cred_acq_other Other notes
added
removed
src/windows/identity/doc/cred_aquisition.h
