Source

connect / openid-connect-session-1_0.xml

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
<?xml version="1.0" encoding="US-ASCII"?>
<?xml-stylesheet type='text/xsl' href='http://xml.resource.org/authoring/rfc2629.xslt' ?>
<!DOCTYPE rfc PUBLIC "-//IETF//DTD RFC 2629//EN"
"http://xml.resource.org/authoring/rfc2629.dtd">
<rfc category="exp" docName="openid-connect-session-1_0" ipr="trust200902">
  <?rfc toc="yes" ?>

  <?rfc tocdepth="4" ?>

  <?rfc symrefs="yes" ?>

  <?rfc sortrefs="yes"?>

  <?rfc strict="no" ?>

  <?rfc iprnotified="no" ?>

  <?rfc private="Draft" ?>

  <front>
    <title abbrev="OpenID Connect Session Management 1.0">OpenID Connect
    Session Management 1.0 - draft 08</title>

    <author fullname="Breno de Medeiros" initials="B." surname="de Medeiros">
      <organization>Google</organization>

      <address>
        <email>breno@google.com</email>
      </address>
    </author>

    <author fullname="Naveen Agarwal" initials="N." surname="Agarwal">
      <organization>Google</organization>

      <address>
        <email>naa@google.com</email>
      </address>
    </author>

    <author fullname="Nat Sakimura" initials="N." role="editor"
            surname="Sakimura">
      <organization abbrev="NRI">Nomura Research Institute,
      Ltd.</organization>

      <address>
        <email>n-sakimura@nri.co.jp</email>
      </address>
    </author>

    <author fullname="John Bradley" initials="J." surname="Bradley">
      <organization abbrev="Ping Identity">Ping Identity</organization>

      <address>
        <email>ve7jtb@ve7jtb.com</email>
      </address>
    </author>

    <author fullname="Michael B. Jones" initials="M.B." surname="Jones">
      <organization abbrev="Microsoft">Microsoft</organization>

      <address>
        <email>mbj@microsoft.com</email>
      </address>
    </author>

    <date day="22" month="June" year="2012" />

    <abstract>
      <t>NOTE: This is a first cut of a significant rewrite based on May 5,
      2012 WG meeting.</t>

      <t>OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0
      protocol. It allows Clients to verify the identity of the End-User based
      on the authentication performed by an Authorization Server, as well as
      to obtain basic profile information about the End-User in an
      interoperable and RESTful manner.</t>

      <t>This document describes how to manage sessions for OpenID
      Connect.</t>
    </abstract>
  </front>

  <middle>
    <section title="Introduction">
      <t>While OpenID Connect Messages and Standard defines the method to
      login the user to the RP based on the ID token, it does not talk about
      how to continuously monitor the user's login status at the OP so that
      the RP may logout the user once the user has logged out of the OP. This
      specification defines the method to achieve this.</t>

      <section anchor="rnc" title="Requirements Notation and Conventions">
        <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
        "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
        document are to be interpreted as described in <xref
        target="RFC2119">RFC 2119</xref>.</t>

        <t>Throughout this document, values are quoted to indicate that they
        are to be taken literally. When using these values in protocol
        messages, the quotes MUST NOT be used as part of the value.</t>
      </section>

      <section anchor="terminology" title="Terminology">
        <t>This specification uses the terms "Access Token", "Refresh Token",
        "Authorization Code", "Authorization Grant", "Authorization Server",
        "Authorization Endpoint", "Client", "Client Identifier", "Client
        Secret", "Protected Resource", "Resource Owner", "Resource Server",
        and "Token Endpoint" defined by <xref target="OAuth2.0">OAuth
        2.0</xref>, and the terms defined by <xref
        target="OpenID.Messages">OpenID Connect Messages 1.0</xref>. </t>
      </section>
    </section>

    <section title="Endpoint Discovery">
      <t>To support the OpenID Conenct session managment, the RP MUST obtain
      the session management related endpoint URLs. This can either be
      obtained out of band or through the OP configuration file as described
      in OpenID Connect Discovery.</t>

      <t>The OP endpoints defined in this specification are as follows:</t>

      <t><list style="hanging">
          <t hangText="OP iframe URL">The URL from which OP iframe is being
          loaded. This URL provides a page that accepts postMessage from the
          relevant RP iframe and postMessage back the login status of the user
          at the OP.</t>

          <t hangText="OP Logout endpoint URL">The URL that initiate the user
          logout at the OP.</t>
        </list></t>

      <t>The RP endpoints defined in this specification are as follows:</t>
    </section>

    <section title="Creating and Updating Sessions">
      <t>In OpenID Connect, the session at the RP typically starts when the RP
      verifies the user's ID Token. Refer to OpenID Connect Standard to find
      out how to obtain an ID Token and verify it. Typically, when the RP has
      enough knowledge on the user's identity, the RP sends the authentication
      request with previously obtained ID Token as the user hint with
      prompt=none. </t>

      <t>This specification defines one additional claim in id_token. </t>

      <t><list style="hanging">
          <t hangText="ops">REQUIRED if session management is supported. OP
          Session Status. A JSON string that represent the user's login state
          at the OP. It is an opaque string for the RP. </t>
        </list></t>
    </section>

    <section title="Session status change notification">
      <t>ID Token typically comes with the expiry date. The RP MAY rely on it
      to expire the RP session. However, it is entirely possible that the user
      may have logged out of the IdP before the expiry date. Therefore, it is
      highly desirable to be able to find out the login status of the user at
      the OP.</t>

      <t>To do so, it is possible to repeat the authentication request with
      prompt=none. However, this causes network traffic and this is
      problematic on the mobile devices that are increasingly becoming
      popular. Therefore, once the session is established with the
      authentication request and response, it is desirable to be able to check
      the login status at the OP without causing network traffic by polling
      the hidden OP iframe from a RP iframe with origin restricted postMessage
      as follows.</t>

      <t></t>

      <section title="OP iframe">
        <t>The RP loads typically invisible OP iframe in the page from the OP
        iframe URL with the following parameters.</t>

        <t><list style="hanging">
            <t hangText="user_hint">REQUIRED. ID Token that the RP received
            when it logged in the user. The value of the aud field, which is a
            client_id of the RP, is used to set the source origin for the
            postMessage request. Note: If the id_token was asymmetrically
            encrypted for the RP, then the RP MUST decrypt it and use the
            decrypted version of the ID Token in this field.</t>
          </list></t>

        <t>The RP MUST assign an "id" attribute to the iframe so that it can
        address it later.</t>

        <t>The OP iframe MUST accept the postMessage from the source origin
        that was registered with the client. It MUST reject the postMessage
        request from other source origin.</t>

        <t>The postMessage from the RP iframe delevers session state, the
        concatenation of the following, as the data.</t>

        <t><list style="numbers">
            <t>sha256 hash of the concatenation of the Client ID, the source
            origin URL, the OP session state, and a salt which is 128 bits or
            more.</t>

            <t>An ascii period ".", i.e., 0x2E.</t>

            <t>the salt</t>
          </list></t>

        <t>The OP iframe MUST recalculate it from the previously obtained
        Client ID, the source origin URL, the current OP session state, and
        the salt obtained from the data. If the received value and the
        calculated value does not match, then the OP iframe MUST postMessage
        the string "changed" back to the source. If it matched, then it MUST
        postMessage the string "unchanged".</t>

        <t>Following is a non-normative example pseudo code for the OP
        iframe.</t>

        <t><figure>
            <artwork><![CDATA[window.addEventListener("message",receiveMessage, false);
function receiveMessage(e){
  if ( e.origin !== "http://client.example.net" ) {
    return;
  }
  var stat;
  var opss = get_op_session_state();
  var ss = CryptoJS.SHA256(client_id + origin + opss + salt) + "." + salt;
  if (e.data == ss) {
    stat = 'unchanged';
  } else [
    stat = 'changed';
  }
  e.source.postMessage(stat, e.origin);
};]]></artwork>
          </figure></t>
      </section>

      <section title="RP iframe">
        <t>The RP also loads an invisible iframe from itself in the same page.
        This iframe MUST know the id of the OP iframe so that it can
        postMessage to the OP iframe.</t>

        <t>RP iframe polls OP iframe with postMessage with certain interval
        suitable for the RP application. With each postMessage, it sends the
        session state defined in Section 4.1. It also has to be able to
        receive the postMessage back from the OP iframe. The received data
        would either be "changed" or "unchanged". Upon receit of
        "changed", the RP MUST perform the re-authentication with 
        <spanx type="verb">prompt=none</spanx> to find the current 
        session state at the OP. </t>

        <t>Following is a non-noramtive example pseudo code for the RP
        iframe. </t>

        <t><figure>
            <artwork><![CDATA[Var stat = "unchanged";
var mes = CryptoJS.SHA256(client_id + origin + opss + salt) + "." + salt;

function check_session()
{
  var targetOrigin  = "http://server.example.com";
  var win = window.parent.document.getElementById("op").contentWindow;
  win.postMessage( mes, targetOrigin);

}
function setTimer()
{
  check_session();
  timerID = setInterval("check_session()",3*1000);
}

window.addEventListener("message", receiveMessage, false); 

function receiveMessage(e)
{
  var targetOrigin  = "http://server.example.com";
  if (e.origin !== targetOrigin ) {return;}
  stat = e.data;
}

]]></artwork>
          </figure></t>
      </section>
    </section>

    <section title="RP initiated Logout">
      <t>Sometimes, the RP may want to notify the OP that the user has logged
      out of the site, and he may want to logout of the OP as well. In this
      case, the RP, after having logged out the user, sends the user to the
      OP's logout endpoint URL that is either advertised through IdP
      configuration file or out of band knowledge.</t>

      <t>Upon receipt of such message, the OP SHOULD prompt the user whether
      he wants to logout of the OP as well. If he says yes, then the OP MUST
      log him out.</t>
    </section>

    <section anchor="IANA" title="IANA Considerations">
      <t>This document makes no requests of IANA.</t>
    </section>

    <section anchor="Security" title="Security Considerations">
      <t>TBD</t>
    </section>
  </middle>

  <back>
    <references title="Normative References">
      <?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119"?>

      <?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.2616"?>

      <?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.3339"?>

      <?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.3548"?>

      <reference anchor="OpenID.Messages">
        <front>
          <title>OpenID Connect Messages 1.0</title>

          <author fullname="Nat Sakimura" initials="N." surname="Sakimura">
            <organization abbrev="NRI">Nomura Research Institute,
            Ltd.</organization>
          </author>

          <author fullname="John Bradley" initials="J." surname="Bradley">
            <organization abbrev="Ping Identity">Ping Identity</organization>
          </author>

          <author fullname="Michael B. Jones" initials="M.B." surname="Jones">
            <organization abbrev="Microsoft">Microsoft</organization>
          </author>

          <author fullname="Breno de Medeiros" initials="B."
                  surname="de Medeiros">
            <organization abbrev="Google">Google</organization>
          </author>

          <author fullname="Chuck Mortimore" initials="C." surname="Mortimore">
            <organization abbrev="Salesforce">Salesforce</organization>
          </author>

          <author fullname="Edmund Jay" initials="E." surname="Jay">
            <organization abbrev="Illumila">Illumila</organization>
          </author>

          <date day="25" month="May" year="2012" />
        </front>

        <format target="http://openid.net/specs/openid-connect-messages-1_0.html"
                type="HTML" />
      </reference>

      <reference anchor="OAuth2.0">
        <front>
          <title>OAuth 2.0 Authorization Protocol</title>

          <author fullname="Eran Hammer" initials="E." role="editor"
                  surname="Hammer">
            <organization></organization>
          </author>

          <author fullname="David Recordon" initials="D." surname="Recordon">
            <organization abbrev="Facebook">Facebook</organization>
          </author>

          <author fullname="Dick Hardt" initials="D." surname="Hardt">
            <organization abbrev="Microsoft">Microsoft</organization>
          </author>

          <date day="1" month="May" year="2012" />
        </front>

        <format target="http://tools.ietf.org/html/draft-ietf-oauth-v2"
                type="HTML" />
      </reference>
    </references>

    <!-- <references title="Informative References"> -->

    <!-- </references> -->

    <section anchor="Acknowledgements" title="Acknowledgements">
      <t>Breno, Naveen, George, Torsten, Axel, Amanda, Justin, Tony, Edmund,
      Mike, John, Nat.</t>
    </section>

    <section title="Notices">
      <t>Copyright (c) 2012 The OpenID Foundation.</t>

      <t>The OpenID Foundation (OIDF) grants to any Contributor, developer,
      implementer, or other interested party a non-exclusive, royalty free,
      worldwide copyright license to reproduce, prepare derivative works from,
      distribute, perform and display, this Implementers Draft or Final
      Specification solely for the purposes of (i) developing specifications,
      and (ii) implementing Implementers Drafts and Final Specifications based
      on such documents, provided that attribution be made to the OIDF as the
      source of the material, but that such attribution does not indicate an
      endorsement by the OIDF.</t>

      <t>The technology described in this specification was made available
      from contributions from various sources, including members of the OpenID
      Foundation and others. Although the OpenID Foundation has taken steps to
      help ensure that the technology is available for distribution, it takes
      no position regarding the validity or scope of any intellectual property
      or other rights that might be claimed to pertain to the implementation
      or use of the technology described in this specification or the extent
      to which any license under such rights might or might not be available;
      neither does it represent that it has made any independent effort to
      identify any such rights. The OpenID Foundation and the contributors to
      this specification make no (and hereby expressly disclaim any)
      warranties (express, implied, or otherwise), including implied
      warranties of merchantability, non-infringement, fitness for a
      particular purpose, or title, related to this specification, and the
      entire risk as to implementing this specification is assumed by the
      implementer. The OpenID Intellectual Property Rights policy requires
      contributors to offer a patent promise not to assert certain patent
      claims against other contributors and against implementers. The OpenID
      Foundation invites any interested party to bring to its attention any
      copyrights, patents, patent applications, or other proprietary rights
      that may cover technology that may be required to practice this
      specification.</t>
    </section>

    <section title="Document History">
      <t>[[ To be removed from the final specification ]]</t>

      <t>-08</t>

      <t><list style="symbols">
          <t>Complete rewrite based on the May 5, 2012 WG F2F meeting at
          Microsoft.</t>
        </list></t>

      <t>-07 <list style="symbols">
          <t>Added warning about the significant revisions planned to session
          management to the abstract and introduction.</t>

          <t>Changed client.example.com to client.example.org, per issue
          #251</t>

          <t>Listed author of ISO29115 as "International Telecommunication
          Union and International Organization for Standardization", per issue
          #589</t>

          <t>Use standards track version of JSON Web Token spec
          (draft-ietf-oauth-json-web-token)</t>
        </list></t>

      <t>-06 <list style="symbols">
          <t>Updated Notices</t>

          <t>Updated References</t>
        </list></t>

      <t>-05 <list style="symbols">
          <t>Removed Check Session Endpoint</t>

          <t>Updated ID Token claims to reflect changes in Messages</t>
        </list></t>

      <t>-04 <list style="symbols">
          <t>Changes associated with renaming "Lite" to "Basic Client" and
          replacing "Core" and "Framework" with "Messages" and "Standard".</t>

          <t>Numerous cleanups, including updating references.</t>
        </list></t>

      <t>-03 <list style="symbols">
          <t>Corrected examples.</t>
        </list></t>

      <t>-02 <list style="symbols">
          <t>Correct issues raised by Johnny Bufu and discussed on the
          7-Jul-11 working group call.</t>
        </list></t>

      <t>-01 <list style="symbols">
          <t>Consistency and cleanup pass, including removing unused
          references.</t>
        </list></t>

      <t>-00 <list style="symbols">
          <t>Split from core when all optional features were removed.</t>
        </list></t>
    </section>
  </back>
</rfc>