public / DiscoJuice

/ docs / discoreadwrite.txt
andreassolberg
Adding documentation for v1.0

1 contributor

100644 41 lines (24 sloc) 2.136 kb 
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

# DiscoReadWrite Protocol

The DiscoReadWrite protocol is a simple extension to *[Identity Provider Discovery Service Protocol and Profile](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-idp-discovery.pdf)*.

The protocol is backward compatible with *Identity Provider Discovery Service Protocol and Profile*, meaning that it adds some functionality (which will be ignored by disovery services that supports this profile and not the DiscoReadWrite protocol).

The extension includes two new elements:

* allowing a provider to *write the result of preferred provider*, and
* allowing a new parameter `auth` that may distinguish saml authentication from other authentication methods.

## The Request

entityID
: REQUIRED. The unique identifier of the service provider the end user is (or will be) interacting with, following successful authentication by an identity provider.

return
: The URL in which to return the result.

policy
: Described in *Identity Provider Discovery Service Protocol and Profile*.

returnIDParam
: A parameter name used to return the unique identifier of the selected identity provider to the original requester. If this parameter is omitted, it defaults to a value of "`entityID`".

isPassive
: A boolean value of "`true`" or "`false`" that controls whether the discovery service is allowed to visibly interact with the user agent in the second step below. If a value is not provided, the default is "`false`". In DiscoJuice this value is always set to `true`.

IdPentityID
: **NEW**. If the client that sends the request already knows what provider the user has selected. The reason why the DiscoReadWrite protocol is used in this context is not to ask the server what is the preferred provider, but to tell what it is. Then the server may store that value in a central cookie, and other services may benefit from learning about this.

## The Response

entityID
: The SAML entityID of the login provider. Or unique ID if authentication protocol is not SAML.

auth
: **NEW**. The authentication protocol supported by the login provider. Default is `saml`. May be `twitter`, `facebook` or other.

Markdown Cheat Sheet

Format Text

Headers

# This is an <h1> tag
## This is an <h2> tag
###### This is an <h6> tag

Text styles

*This text will be italic*
_This will also be italic_
**This text will be bold**
__This will also be bold__

*You **can** combine them*

Lists

Unordered

* Item 1
* Item 2
  * Item 2a
  * Item 2b

Ordered

1. Item 1
2. Item 2
3. Item 3
   * Item 3a
   * Item 3b

Miscellaneous

Images

![GitHub Logo](/images/logo.png)
Format: ![Alt Text](url)

Links

http://github.com - automatic!
[GitHub](http://github.com)

Blockquotes

As Kanye West said:

> We're living the future so
> the present is our past.

Code Examples in Markdown

Syntax highlighting with GFM

```javascript
function fancyAlert(arg) {
  if(arg) {
    $.facebox({div:'#foo'})
  }
}
```

Or, indent your code 4 spaces

Here is a Python code example
without syntax highlighting:

    def foo:
      if not bar:
        return true

Inline code for comments

I think you should use an
`<addr>` element here instead.
Something went wrong with that request. Please try again. Dismiss

Looking for the GitHub logo?