mod_auth_mellon/SOURCES/mellon_user_guide.html

7033 lines
1.0 MiB
HTML
Raw Permalink Normal View History

2019-05-07 04:08:43 +00:00
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 1.5.6.1">
<meta name="author" content="John Dennis">
<title>mod_auth_mellon User Guide</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
<style>
/* Asciidoctor default stylesheet | MIT License | http://asciidoctor.org */
/* Remove comment around @import statement below when using as a custom stylesheet */
/*@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700";*/
article,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section,summary{display:block}
audio,canvas,video{display:inline-block}
audio:not([controls]){display:none;height:0}
[hidden],template{display:none}
script{display:none!important}
html{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%}
a{background:transparent}
a:focus{outline:thin dotted}
a:active,a:hover{outline:0}
h1{font-size:2em;margin:.67em 0}
abbr[title]{border-bottom:1px dotted}
b,strong{font-weight:bold}
dfn{font-style:italic}
hr{-moz-box-sizing:content-box;box-sizing:content-box;height:0}
mark{background:#ff0;color:#000}
code,kbd,pre,samp{font-family:monospace;font-size:1em}
pre{white-space:pre-wrap}
q{quotes:"\201C" "\201D" "\2018" "\2019"}
small{font-size:80%}
sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
sup{top:-.5em}
sub{bottom:-.25em}
img{border:0}
svg:not(:root){overflow:hidden}
figure{margin:0}
fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
legend{border:0;padding:0}
button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
button,input{line-height:normal}
button,select{text-transform:none}
button,html input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer}
button[disabled],html input[disabled]{cursor:default}
input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0}
input[type="search"]{-webkit-appearance:textfield;-moz-box-sizing:content-box;-webkit-box-sizing:content-box;box-sizing:content-box}
input[type="search"]::-webkit-search-cancel-button,input[type="search"]::-webkit-search-decoration{-webkit-appearance:none}
button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
textarea{overflow:auto;vertical-align:top}
table{border-collapse:collapse;border-spacing:0}
*,*:before,*:after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}
html,body{font-size:100%}
body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;font-weight:400;font-style:normal;line-height:1;position:relative;cursor:auto;tab-size:4;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}
a:hover{cursor:pointer}
img,object,embed{max-width:100%;height:auto}
object,embed{height:100%}
img{-ms-interpolation-mode:bicubic}
.left{float:left!important}
.right{float:right!important}
.text-left{text-align:left!important}
.text-right{text-align:right!important}
.text-center{text-align:center!important}
.text-justify{text-align:justify!important}
.hide{display:none}
img,object,svg{display:inline-block;vertical-align:middle}
textarea{height:auto;min-height:50px}
select{width:100%}
.center{margin-left:auto;margin-right:auto}
.spread{width:100%}
p.lead,.paragraph.lead>p,#preamble>.sectionbody>.paragraph:first-of-type p{font-size:1.21875em;line-height:1.6}
.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}
div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0;direction:ltr}
a{color:#2156a5;text-decoration:underline;line-height:inherit}
a:hover,a:focus{color:#1d4b8f}
a img{border:none}
p{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
p aside{font-size:.875em;line-height:1.35;font-style:italic}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
h1{font-size:2.125em}
h2{font-size:1.6875em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
h4,h5{font-size:1.125em}
h6{font-size:1em}
hr{border:solid #ddddd8;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0}
em,i{font-style:italic;line-height:inherit}
strong,b{font-weight:bold;line-height:inherit}
small{font-size:60%;line-height:inherit}
code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
ul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
ul,ol{margin-left:1.5em}
ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em}
ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit}
ul.square{list-style-type:square}
ul.circle{list-style-type:circle}
ul.disc{list-style-type:disc}
ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
dl dt{margin-bottom:.3125em;font-weight:bold}
dl dd{margin-bottom:1.25em}
abbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help}
abbr{text-transform:none}
blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
blockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)}
blockquote cite:before{content:"\2014 \0020"}
blockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)}
blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
@media only screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
h1{font-size:2.75em}
h2{font-size:2.3125em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
h4{font-size:1.4375em}}
table{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede}
table thead,table tfoot{background:#f7f8f7;font-weight:bold}
table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
table tr.even,table tr.alt,table tr:nth-of-type(even){background:#f8f8f7}
table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{display:table-cell;line-height:1.6}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
.clearfix:before,.clearfix:after,.float-group:before,.float-group:after{content:" ";display:table}
.clearfix:after,.float-group:after{clear:both}
*:not(pre)>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background-color:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed;word-wrap:break-word}
*:not(pre)>code.nobreak{word-wrap:normal}
*:not(pre)>code.nowrap{white-space:nowrap}
pre,pre>code{line-height:1.45;color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;text-rendering:optimizeSpeed}
em em{font-style:normal}
strong strong{font-weight:400}
.keyseq{color:rgba(51,51,51,.8)}
kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background-color:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}
.keyseq kbd:first-child{margin-left:0}
.keyseq kbd:last-child{margin-right:0}
.menuseq,.menuref{color:#000}
.menuseq b:not(.caret),.menuref{font-weight:inherit}
.menuseq{word-spacing:-.02em}
.menuseq b.caret{font-size:1.25em;line-height:.8}
.menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
b.button:before,b.button:after{position:relative;top:-1px;font-weight:400}
b.button:before{content:"[";padding:0 3px 0 2px}
b.button:after{content:"]";padding:0 2px 0 3px}
p a>code:hover{color:rgba(0,0,0,.9)}
#header,#content,#footnotes,#footer{width:100%;margin-left:auto;margin-right:auto;margin-top:0;margin-bottom:0;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
#header:before,#header:after,#content:before,#content:after,#footnotes:before,#footnotes:after,#footer:before,#footer:after{content:" ";display:table}
#header:after,#content:after,#footnotes:after,#footer:after{clear:both}
#content{margin-top:1.25em}
#content:before{content:none}
#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #ddddd8}
#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #ddddd8;padding-bottom:8px}
#header .details{border-bottom:1px solid #ddddd8;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:-ms-flexbox;display:-webkit-flex;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap}
#header .details span:first-child{margin-left:-.125em}
#header .details span.email a{color:rgba(0,0,0,.85)}
#header .details br{display:none}
#header .details br+span:before{content:"\00a0\2013\00a0"}
#header .details br+span.author:before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
#header .details br+span#revremark:before{content:"\00a0|\00a0"}
#header #revnumber{text-transform:capitalize}
#header #revnumber:after{content:"\00a0"}
#content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #ddddd8;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
#toc{border-bottom:1px solid #efefed;padding-bottom:.5em}
#toc>ul{margin-left:.125em}
#toc ul.sectlevel0>li>a{font-style:italic}
#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
#toc li{line-height:1.3334;margin-top:.3334em}
#toc a{text-decoration:none}
#toc a:active{text-decoration:underline}
#toctitle{color:#7a2518;font-size:1.2em}
@media only screen and (min-width:768px){#toctitle{font-size:1.375em}
body.toc2{padding-left:15em;padding-right:0}
#toc.toc2{margin-top:0!important;background-color:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #efefed;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
#toc.toc2>ul{font-size:.9em;margin-bottom:0}
#toc.toc2 ul ul{margin-left:0;padding-left:1em}
#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
body.toc2.toc-right{padding-left:0;padding-right:15em}
body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #efefed;left:auto;right:0}}
@media only screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
#toc.toc2{width:20em}
#toc.toc2 #toctitle{font-size:1.375em}
#toc.toc2>ul{font-size:.95em}
#toc.toc2 ul ul{padding-left:1.25em}
body.toc2.toc-right{padding-left:0;padding-right:20em}}
#content #toc{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}
#content #toc>:first-child{margin-top:0}
#content #toc>:last-child{margin-bottom:0}
#footer{max-width:100%;background-color:rgba(0,0,0,.8);padding:1.25em}
#footer-text{color:rgba(255,255,255,.8);line-height:1.44}
.sect1{padding-bottom:.625em}
@media only screen and (min-width:768px){.sect1{padding-bottom:1.25em}}
.sect1+.sect1{border-top:1px solid #efefed}
#content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
#content h1>a.anchor:before,h2>a.anchor:before,h3>a.anchor:before,#toctitle>a.anchor:before,.sidebarblock>.content>.title>a.anchor:before,h4>a.anchor:before,h5>a.anchor:before,h6>a.anchor:before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
#content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
#content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}
#content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
table.tableblock>caption.title{white-space:nowrap;overflow:visible;max-width:0}
.paragraph.lead>p,#preamble>.sectionbody>.paragraph:first-of-type p{color:rgba(0,0,0,.85)}
table.tableblock #preamble>.sectionbody>.paragraph:first-of-type p{font-size:inherit}
.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
.admonitionblock>table td.icon{text-align:center;width:80px}
.admonitionblock>table td.icon img{max-width:initial}
.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #ddddd8;color:rgba(0,0,0,.6)}
.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
.exampleblock>.content{border-style:solid;border-width:1px;border-color:#e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;-webkit-border-radius:4px;border-radius:4px}
.exampleblock>.content>:first-child{margin-top:0}
.exampleblock>.content>:last-child{margin-bottom:0}
.sidebarblock{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}
.sidebarblock>:first-child{margin-top:0}
.sidebarblock>:last-child{margin-bottom:0}
.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
.literalblock pre,.listingblock pre:not(.highlight),.listingblock pre[class="highlight"],.listingblock pre[class^="highlight "],.listingblock pre.CodeRay,.listingblock pre.prettyprint{background:#f7f7f8}
.sidebarblock .literalblock pre,.sidebarblock .listingblock pre:not(.highlight),.sidebarblock .listingblock pre[class="highlight"],.sidebarblock .listingblock pre[class^="highlight "],.sidebarblock .listingblock pre.CodeRay,.sidebarblock .listingblock pre.prettyprint{background:#f2f1f1}
.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{-webkit-border-radius:4px;border-radius:4px;word-wrap:break-word;padding:1em;font-size:.8125em}
.literalblock pre.nowrap,.literalblock pre[class].nowrap,.listingblock pre.nowrap,.listingblock pre[class].nowrap{overflow-x:auto;white-space:pre;word-wrap:normal}
@media only screen and (min-width:768px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:.90625em}}
@media only screen and (min-width:1280px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:1em}}
.literalblock.output pre{color:#f7f7f8;background-color:rgba(0,0,0,.9)}
.listingblock pre.highlightjs{padding:0}
.listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px}
.listingblock pre.prettyprint{border-width:0}
.listingblock>.content{position:relative}
.listingblock code[data-lang]:before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:#999}
.listingblock:hover code[data-lang]:before{display:block}
.listingblock.terminal pre .command:before{content:attr(data-prompt);padding-right:.5em;color:#999}
.listingblock.terminal pre .command:not([data-prompt]):before{content:"$"}
table.pyhltable{border-collapse:separate;border:0;margin-bottom:0;background:none}
table.pyhltable td{vertical-align:top;padding-top:0;padding-bottom:0;line-height:1.45}
table.pyhltable td.code{padding-left:.75em;padding-right:0}
pre.pygments .lineno,table.pyhltable td:not(.code){color:#999;padding-left:0;padding-right:.5em;border-right:1px solid #ddddd8}
pre.pygments .lineno{display:inline-block;margin-right:.25em}
table.pyhltable .linenodiv{background:none!important;padding-right:0!important}
.quoteblock{margin:0 1em 1.25em 1.5em;display:table}
.quoteblock>.title{margin-left:-1.5em;margin-bottom:.75em}
.quoteblock blockquote,.quoteblock blockquote p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
.quoteblock blockquote{margin:0;padding:0;border:0}
.quoteblock blockquote:before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
.quoteblock .attribution{margin-top:.5em;margin-right:.5ex;text-align:right}
.quoteblock .quoteblock{margin-left:0;margin-right:0;padding:.5em 0;border-left:3px solid rgba(0,0,0,.6)}
.quoteblock .quoteblock blockquote{padding:0 0 0 .75em}
.quoteblock .quoteblock blockquote:before{display:none}
.verseblock{margin:0 1em 1.25em 1em}
.verseblock pre{font-family:"Open Sans","DejaVu Sans",sans;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
.verseblock pre strong{font-weight:400}
.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
.quoteblock .attribution br,.verseblock .attribution br{display:none}
.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
.quoteblock.abstract{margin:0 0 1.25em 0;display:block}
.quoteblock.abstract blockquote,.quoteblock.abstract blockquote p{text-align:left;word-spacing:0}
.quoteblock.abstract blockquote:before,.quoteblock.abstract blockquote p:first-of-type:before{display:none}
table.tableblock{max-width:100%;border-collapse:separate}
table.tableblock td>.paragraph:last-child p>p:last-child,table.tableblock th>p:last-child,table.tableblock td>p:last-child{margin-bottom:0}
table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
table.grid-all>thead>tr>.tableblock,table.grid-all>tbody>tr>.tableblock{border-width:0 1px 1px 0}
table.grid-all>tfoot>tr>.tableblock{border-width:1px 1px 0 0}
table.grid-cols>*>tr>.tableblock{border-width:0 1px 0 0}
table.grid-rows>thead>tr>.tableblock,table.grid-rows>tbody>tr>.tableblock{border-width:0 0 1px 0}
table.grid-rows>tfoot>tr>.tableblock{border-width:1px 0 0 0}
table.grid-all>*>tr>.tableblock:last-child,table.grid-cols>*>tr>.tableblock:last-child{border-right-width:0}
table.grid-all>tbody>tr:last-child>.tableblock,table.grid-all>thead:last-child>tr>.tableblock,table.grid-rows>tbody>tr:last-child>.tableblock,table.grid-rows>thead:last-child>tr>.tableblock{border-bottom-width:0}
table.frame-all{border-width:1px}
table.frame-sides{border-width:0 1px}
table.frame-topbot{border-width:1px 0}
th.halign-left,td.halign-left{text-align:left}
th.halign-right,td.halign-right{text-align:right}
th.halign-center,td.halign-center{text-align:center}
th.valign-top,td.valign-top{vertical-align:top}
th.valign-bottom,td.valign-bottom{vertical-align:bottom}
th.valign-middle,td.valign-middle{vertical-align:middle}
table thead th,table tfoot th{font-weight:bold}
tbody tr th{display:table-cell;line-height:1.6;background:#f7f8f7}
tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
p.tableblock>code:only-child{background:none;padding:0}
p.tableblock{font-size:1em}
td>div.verse{white-space:pre}
ol{margin-left:1.75em}
ul li ol{margin-left:1.5em}
dl dd{margin-left:1.125em}
dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
ul.unstyled,ol.unstyled{margin-left:0}
ul.checklist{margin-left:.625em}
ul.checklist li>p:first-child>.fa-square-o:first-child,ul.checklist li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}
ul.checklist li>p:first-child>input[type="checkbox"]:first-child{margin-right:.25em}
ul.inline{margin:0 auto .625em auto;margin-left:-1.375em;margin-right:0;padding:0;list-style:none;overflow:hidden}
ul.inline>li{list-style:none;float:left;margin-left:1.375em;display:block}
ul.inline>li>*{display:block}
.unstyled dl dt{font-weight:400;font-style:normal}
ol.arabic{list-style-type:decimal}
ol.decimal{list-style-type:decimal-leading-zero}
ol.loweralpha{list-style-type:lower-alpha}
ol.upperalpha{list-style-type:upper-alpha}
ol.lowerroman{list-style-type:lower-roman}
ol.upperroman{list-style-type:upper-roman}
ol.lowergreek{list-style-type:lower-greek}
.hdlist>table,.colist>table{border:0;background:none}
.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
td.hdlist1{font-weight:bold;padding-bottom:1.25em}
.literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
.colist>table tr>td:first-of-type{padding:.4em .75em 0 .75em;line-height:1;vertical-align:top}
.colist>table tr>td:first-of-type img{max-width:initial}
.colist>table tr>td:last-of-type{padding:.25em 0}
.thumb,.th{line-height:0;display:inline-block;border:solid 4px #fff;-webkit-box-shadow:0 0 0 1px #ddd;box-shadow:0 0 0 1px #ddd}
.imageblock.left,.imageblock[style*="float: left"]{margin:.25em .625em 1.25em 0}
.imageblock.right,.imageblock[style*="float: right"]{margin:.25em 0 1.25em .625em}
.imageblock>.title{margin-bottom:0}
.imageblock.thumb,.imageblock.th{border-width:6px}
.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
.image.left{margin-right:.625em}
.image.right{margin-left:.625em}
a.image{text-decoration:none;display:inline-block}
a.image object{pointer-events:none}
sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
sup.footnote a,sup.footnoteref a{text-decoration:none}
sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline}
#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em 0;border-width:1px 0 0 0}
#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;text-indent:-1.05em;margin-bottom:.2em}
#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none}
#footnotes .footnote:last-of-type{margin-bottom:0}
#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
.gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0}
.gist .file-data>table td.line-data{width:99%}
div.unbreakable{page-break-inside:avoid}
.big{font-size:larger}
.small{font-size:smaller}
.underline{text-decoration:underline}
.overline{text-decoration:overline}
.line-through{text-decoration:line-through}
.aqua{color:#00bfbf}
.aqua-background{background-color:#00fafa}
.black{color:#000}
.black-background{background-color:#000}
.blue{color:#0000bf}
.blue-background{background-color:#0000fa}
.fuchsia{color:#bf00bf}
.fuchsia-background{background-color:#fa00fa}
.gray{color:#606060}
.gray-background{background-color:#7d7d7d}
.green{color:#006000}
.green-background{background-color:#007d00}
.lime{color:#00bf00}
.lime-background{background-color:#00fa00}
.maroon{color:#600000}
.maroon-background{background-color:#7d0000}
.navy{color:#000060}
.navy-background{background-color:#00007d}
.olive{color:#606000}
.olive-background{background-color:#7d7d00}
.purple{color:#600060}
.purple-background{background-color:#7d007d}
.red{color:#bf0000}
.red-background{background-color:#fa0000}
.silver{color:#909090}
.silver-background{background-color:#bcbcbc}
.teal{color:#006060}
.teal-background{background-color:#007d7d}
.white{color:#bfbfbf}
.white-background{background-color:#fafafa}
.yellow{color:#bfbf00}
.yellow-background{background-color:#fafa00}
span.icon>.fa{cursor:default}
a span.icon>.fa{cursor:inherit}
.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
.admonitionblock td.icon .icon-note:before{content:"\f05a";color:#19407c}
.admonitionblock td.icon .icon-tip:before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
.admonitionblock td.icon .icon-warning:before{content:"\f071";color:#bf6900}
.admonitionblock td.icon .icon-caution:before{content:"\f06d";color:#bf3400}
.admonitionblock td.icon .icon-important:before{content:"\f06a";color:#bf0000}
.conum[data-value]{display:inline-block;color:#fff!important;background-color:rgba(0,0,0,.8);-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
.conum[data-value] *{color:#fff!important}
.conum[data-value]+b{display:none}
.conum[data-value]:after{content:attr(data-value)}
pre .conum[data-value]{position:relative;top:-.125em}
b.conum *{color:inherit!important}
.conum:not([data-value]):empty{display:none}
dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
h1,h2,p,td.content,span.alt{letter-spacing:-.01em}
p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
p,blockquote,dt,td.content,span.alt{font-size:1.0625rem}
p{margin-bottom:1.25rem}
.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
.exampleblock>.content{background-color:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc}
.print-only{display:none!important}
@media print{@page{margin:1.25cm .75cm}
*{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important}
a{color:inherit!important;text-decoration:underline!important}
a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
a[href^="http:"]:not(.bare):after,a[href^="https:"]:not(.bare):after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
abbr[title]:after{content:" (" attr(title) ")"}
pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
thead{display:table-header-group}
svg{max-width:100%}
p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
#toc,.sidebarblock,.exampleblock>.content{background:none!important}
#toc{border-bottom:1px solid #ddddd8!important;padding-bottom:0!important}
.sect1{padding-bottom:0!important}
.sect1+.sect1{border:0!important}
#header>h1:first-child{margin-top:1.25rem}
body.book #header{text-align:center}
body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em 0}
body.book #header .details{border:0!important;display:block;padding:0!important}
body.book #header .details span:first-child{margin-left:0!important}
body.book #header .details br{display:block}
body.book #header .details br+span:before{content:none!important}
body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
.listingblock code[data-lang]:before{display:block}
#footer{background:none!important;padding:0 .9375em}
#footer-text{color:rgba(0,0,0,.6)!important;font-size:.9em}
.hide-on-print{display:none!important}
.print-only{display:block!important}
.hide-for-print{display:none!important}
.show-for-print{display:inherit!important}}
</style>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css">
</head>
<body class="article toc2 toc-left">
<div id="header">
<h1>mod_auth_mellon User Guide</h1>
<div class="details">
<span id="author" class="author">John Dennis</span><br>
<span id="email" class="email"><a href="mailto:jdennis@redhat.com">jdennis@redhat.com</a></span><br>
<span id="revnumber">version 1.3,</span>
<span id="revdate">2018-02-22</span>
</div>
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="#_colophon">1. Colophon</a></li>
<li><a href="#_document_conventions">2. Document Conventions</a></li>
<li><a href="#_introduction">3. Introduction</a></li>
<li><a href="#_saml_overview">4. SAML Overview</a>
<ul class="sectlevel2">
<li><a href="#saml_roles">4.1. SAML Roles</a></li>
<li><a href="#saml_profiles">4.2. SAML Profiles</a></li>
<li><a href="#saml_bindings">4.3. SAML Bindings</a></li>
<li><a href="#_saml_messages">4.4. SAML Messages</a></li>
<li><a href="#web_sso_flow">4.5. SAML Web-SSO flow</a>
<ul class="sectlevel3">
<li><a href="#saml_sessions">4.5.1. Sessions</a></li>
</ul>
</li>
<li><a href="#http_post">4.6. HTTP Post and Self-Posting</a></li>
<li><a href="#entityID">4.7. entityID</a></li>
<li><a href="#name_id">4.8. Username, userid, SAML NameID</a>
<ul class="sectlevel3">
<li><a href="#_userid_vs_identity_or_why_userid_is_so_last_millennium">4.8.1. Userid vs. Identity (or why userid is so last millennium)</a></li>
<li><a href="#saml_nameid">4.8.2. How SAML identifies a subject</a></li>
<li><a href="#nameid_interpretation">4.8.3. Burden of interpreting NameID falls to the relying party</a></li>
<li><a href="#_how_mellon_handles_the_nameid">4.8.4. How Mellon handles the NameID</a></li>
<li><a href="#specify_mellon_nameid">4.8.5. How do you specify the NameID format in SAML?</a></li>
</ul>
</li>
<li><a href="#authentication_request">4.9. &lt;AuthnRequest&gt; Example</a></li>
<li><a href="#assertion_response">4.10. &lt;Assertion&gt; Example</a></li>
<li><a href="#endpoints">4.11. SAML Endpoints</a></li>
<li><a href="#relaystate">4.12. Relay State (How you return to the original URL)</a></li>
<li><a href="#metadata">4.13. The Role of Metadata</a>
<ul class="sectlevel3">
<li><a href="#metadata_keys">4.13.1. Certs and Keys Inside Metadata</a></li>
<li><a href="#sp_metadata">4.13.2. Service Provider Metadata</a></li>
<li><a href="#idp_metadata">4.13.3. Identity Provider Metadata</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#_installing_configuring_mellon">5. Installing &amp; Configuring Mellon</a>
<ul class="sectlevel2">
<li><a href="#_installing_mellon">5.1. Installing Mellon</a></li>
<li><a href="#mellon_config">5.2. Mellon Configuration</a>
<ul class="sectlevel3">
<li><a href="#load_mod_auth_mellon">5.2.1. Load mod_auth_mellon</a></li>
<li><a href="#mellon_config_files">5.2.2. Mellon Configuration Files</a></li>
</ul>
</li>
<li><a href="#_mellon_configuration_directives">5.3. Mellon Configuration Directives</a></li>
<li><a href="#mellon_config_file">5.4. Mellon Configuration File</a>
<ul class="sectlevel3">
<li><a href="#load_sp_metadata_into_idp">5.4.1. Load Your SP metadata into the IdP</a></li>
<li><a href="#obtain_idp_metadata">5.4.2. Obtaining IdP Metadata</a></li>
</ul>
</li>
<li><a href="#mellon_modes">5.5. Mellon Modes</a></li>
<li><a href="#metadata_creation">5.6. How is Mellon metadata created?</a>
<ul class="sectlevel3">
<li><a href="#using_mellon_create_metadata_sh">5.6.1. Using <code>mellon_create_metadata.sh</code></a></li>
<li><a href="#using_mellon_to_create_metadata">5.6.2. Using Mellon to generate its own metadata</a></li>
<li><a href="#_where_do_the_keys_and_certs_come_from">5.6.3. Where do the keys and certs come from?</a></li>
<li><a href="#sign_metadata">5.6.4. Signing metadata</a></li>
</ul>
</li>
<li><a href="#mellon_endpoint_path">5.7. MellonEndpointPath</a></li>
<li><a href="#mellon_endpoints">5.8. Mellon Endpoints</a></li>
<li><a href="#mellon_session">5.9. Mellon Session</a></li>
<li><a href="#mellon_cookie">5.10. Mellon Cookie</a></li>
</ul>
</li>
<li><a href="#_working_with_saml_attributes_and_exporting_values_to_web_apps">6. Working with SAML attributes and exporting values to web apps</a>
<ul class="sectlevel2">
<li><a href="#multiple_attribute_values">6.1. Handling multiple attribute values</a></li>
<li><a href="#map_assertion_attr_name">6.2. Map assertion attribute name to different Apache environment variable name</a></li>
<li><a href="#assertion_constraints">6.3. Using Mellon to apply constraints</a></li>
<li><a href="#set_remote_user">6.4. How to set REMOTE_USER</a></li>
</ul>
</li>
<li><a href="#deployment_considerations">7. Deployment Considerations</a>
<ul class="sectlevel2">
<li><a href="#apache_servername">7.1. Apache Servername</a></li>
<li><a href="#load_balancer">7.2. Load Balancer Issues</a>
<ul class="sectlevel3">
<li><a href="#_server_name">7.2.1. Server Name</a></li>
<li><a href="#load_balancer_persistence">7.2.2. Load balancer proxy persistence</a></li>
</ul>
</li>
<li><a href="#forwarded_http_headers">7.3. Forwarded HTTP Headers</a></li>
</ul>
</li>
<li><a href="#error_response">8. When a SAML party responds with an error</a>
<ul class="sectlevel2">
<li><a href="#_top_level_status_codes">8.1. Top-level status codes</a></li>
<li><a href="#_second_level_status_codes">8.2. Second-level status codes</a></li>
<li><a href="#_status_code_examples">8.3. Status code examples</a></li>
<li><a href="#find_status_code">8.4. Finding the <code>StatusCode</code></a></li>
</ul>
</li>
<li><a href="#gather_runtime_info">9. Gathering run-time information</a>
<ul class="sectlevel2">
<li><a href="#_apache_log_files">9.1. Apache log files</a></li>
<li><a href="#trace_saml_flow">9.2. Trace SAML flow</a></li>
<li><a href="#inspect_saml_messages">9.3. Inspect SAML messages</a>
<ul class="sectlevel3">
<li><a href="#saml_tracer">9.3.1. Firefox SAML Tracer</a></li>
<li><a href="#_chrome_saml_chrome_panel">9.3.2. Chrome, SAML Chrome Panel</a></li>
<li><a href="#encrypted_response">9.3.3. If the IdP response is encrypted</a></li>
</ul>
</li>
<li><a href="#inspect_mellon_env">9.4. Inspecting Mellon environment variables</a>
<ul class="sectlevel3">
<li><a href="#_python_wsgi_environment_dump">9.4.1. Python WSGI Environment Dump</a></li>
<li><a href="#_php_environment_dump">9.4.2. PHP Environment Dump</a></li>
</ul>
</li>
<li><a href="#mellon_diagnostics">9.5. Mellon Diagnostics</a>
<ul class="sectlevel3">
<li><a href="#using_mellon_diagnostics">9.5.1. Using Mellon Diagnostics</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#_potential_problems">10. Potential Problems</a>
<ul class="sectlevel2">
<li><a href="#_it_s_the_metadata">10.1. It&#8217;s the metadata</a></li>
<li><a href="#_behavior_does_not_change_after_modifying_any_saml_file">10.2. Behavior does not change after modifying any SAML file</a></li>
<li><a href="#_are_the_mellon_configuration_directives_syntactically_correct">10.3. Are the Mellon configuration directives syntactically correct?</a></li>
<li><a href="#_no_authnrequest_sent_to_idp">10.4. No AuthnRequest sent to IdP</a></li>
<li><a href="#incorrect_mellon_endpoint_path">10.5. Incorrect MellonEndpointPath</a></li>
<li><a href="#invalid_destination">10.6. HTTP_BAD_REQUEST - Invalid Destination on Response</a></li>
<li><a href="#_mellon_metadata_out_of_sync_with_mellon_configuration">10.7. Mellon metadata out of sync with Mellon configuration</a></li>
<li><a href="#_microsoft_adfs_issues">10.8. Microsoft ADFS issues</a>
<ul class="sectlevel3">
<li><a href="#adfs_sig_alg">10.8.1. ADFS Signature Algorithm</a></li>
<li><a href="#adfs_nameid_policy">10.8.2. ADFS NameIDPolicy</a></li>
</ul>
</li>
<li><a href="#_time_sync">10.9. Time Sync</a></li>
</ul>
</li>
<li><a href="#_glossary">11. Glossary</a></li>
<li><a href="#_appendix">Appendix A: Appendix</a>
<ul class="sectlevel2">
<li><a href="#authentication_request_wire">A.1. Example On-The-Wire AuthnRequest</a></li>
<li><a href="#assertion_response_wire">A.2. Example On-the-Wire &lt;Assertion&gt; response</a></li>
<li><a href="#mellon_diagnostics_example">A.3. Example Mellon Diagnostics</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div id="content">
<div class="sect1">
<h2 id="_colophon">1. Colophon</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Author: John Dennis <a href="mailto:jdennis@redhat.com">jdennis@redhat.com</a></p>
</div>
<div class="paragraph">
<p>Version: 1.3</p>
</div>
<div class="paragraph">
<p>Date: 2018-02-22</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_document_conventions">2. Document Conventions</h2>
<div class="sectionbody">
<div class="sidebarblock">
<div class="content">
<div class="title">Example Data used in this document</div>
<div class="paragraph">
<p>This document contains many examples of SAML data. For consistency we
will use the following:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The SP is hosted on the node <code>mellon.example.com</code>.</p>
</li>
<li>
<p>The SP <code>MellonEndpointPath</code> is <code>/mellon</code></p>
</li>
<li>
<p>The SP <code>entityID</code> is <code><a href="https://mellon.example.com/mellon/metadata" class="bare">https://mellon.example.com/mellon/metadata</a></code></p>
</li>
<li>
<p>Mellon is protecting the URL location <code>/private</code> and everything
under it.</p>
</li>
<li>
<p>The protected resource is <code>/private/info.html</code> and hence the URL of
the protected resource is <code><a href="https://mellon.example.com/private/info.html" class="bare">https://mellon.example.com/private/info.html</a></code>.</p>
</li>
<li>
<p>The IdP is hosted on the node <code>rhsso.example.com</code></p>
</li>
<li>
<p>The IdP <code>entityID</code> is <code><a href="https://rhsso.example.com:8443/auth/realms/test" class="bare">https://rhsso.example.com:8443/auth/realms/test</a></code></p>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_introduction">3. Introduction</h2>
<div class="sectionbody">
<div class="paragraph">
<p>mod_auth_mellon is an Apache (httpd) authentication module
providing authentication and authorization services via SAML. Mellon
plays the role of a <em>Service Provider</em> (SP) in SAML.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_saml_overview">4. SAML Overview</h2>
<div class="sectionbody">
<div class="paragraph">
<p>SAML (<em>Security Assertion Markup Language</em>) is a framework for exchanging
security information between providers. The nonprofit
<a href="https://www.oasis-open.org/">OASIS</a> consortium is responsible for
defining and publishing the various SAML specifications. OASIS is an
acronym for <em>Organization for the Advancement of Structured
Information Standards</em>. All SAML specifications and errata can be
found at this location:</p>
</div>
<div class="paragraph">
<p><a href="https://docs.oasis-open.org/security/saml/v2.0/" class="bare">https://docs.oasis-open.org/security/saml/v2.0/</a></p>
</div>
<div class="paragraph">
<p>The SAML technical committee has published the
<a href="https://www.oasis-open.org/committees/download.php/27819/sstc-saml-tech-overview-2.0-cd-02.pdf">Security
Assertion Markup Language (SAML) V2.0 Technical Overview</a>. This is an
excellent high-level overview of SAML and worth reading to familiarize
yourself with general SAML operation and terminology.</p>
</div>
<div class="paragraph">
<p>SAML is a large complex standard that currently comprises 10 individual
specifications whose total content is hundreds of pages of printed
material. SAML is much too large to cover in this overview. Instead we
will focus on the most common use of SAML, Web Single Sign-On
(Web-SSO). This is the target focus of mod_auth_mellon, although
Mellon does support other profiles as well.</p>
</div>
<div class="paragraph">
<p>SAML organizes itself into <a href="#saml_profiles">Profiles</a> and
<a href="#saml_binding">Bindings</a>. A cursory overview of these two concepts
will help you understand SAML better and is especially important if
you have to refer to any SAML specifications.</p>
</div>
<div class="sect2">
<h3 id="saml_roles">4.1. SAML Roles</h3>
<div class="paragraph">
<p>Participants in SAML play different roles. An entity may be capable of
playing more than one role, however we typically only consider a single role when
discussing entity behavior. The defined SAML roles are:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Identity Provider (IdP)</p>
</li>
<li>
<p>Service Provider (SP)</p>
</li>
<li>
<p>Affiliation</p>
</li>
<li>
<p>Attribute Authority</p>
</li>
<li>
<p>Attribute Consumer</p>
</li>
<li>
<p>Policy Decision Point</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Of these we are only interested in Service Providers (SP) and Identity
Providers (IdP). Mellon is a Service Provider because it provides a
service to clients. Authentication and user information is provided by
an Identity Provider. The SP relies on the IdP for its authentication
needs. In SAML literature you will often see the term <em>attesting
party</em> or <em>asserting party</em>, which in most contexts means an IdP
because the IdP attests to or asserts certain claims in its role as
an <em>authority</em>. On the other hand a Service Provider is often referred
to as a <em>relying party</em> because it <em>relies</em> on the <em>assertions</em>
provided by an <em>authority</em>.</p>
</div>
</div>
<div class="sect2">
<h3 id="saml_profiles">4.2. SAML Profiles</h3>
<div class="paragraph">
<p>A SAML profile defines how SAML data is conveyed using
<a href="#saml_bindings">SAML Bindings</a> on a transport to accomplish a specific task. The
<em>Web Browser SSO Profile</em> is the best known and the one Mellon focuses
on. Other profiles include <em>Single Logout</em>, <em>Enhanced Client or Proxy
(ECP)</em>, <em>Identity Provider Discovery</em>, etc.</p>
</div>
<div class="paragraph">
<p>SAML profiles are defined in the <a href="https://docs.oasis-open.org/security/saml/v2.0/saml-profiles-2.0-os.pdf">Profiles
for the OASIS Security Assertion Markup Language (SAML) V2.0</a> specification.</p>
</div>
</div>
<div class="sect2">
<h3 id="saml_bindings">4.3. SAML Bindings</h3>
<div class="paragraph">
<p>SAML bindings define how SAML messages are mapped onto standard
messaging or communication protocols. The best way to think of a SAML
binding is as a transport mechanism. A key concept is that a given
SAML profile may permit the same SAML message to be conveyed using
variety of SAML bindings. Or by the same token a SAML profile may
prohibit the use of certain SAML bindings.</p>
</div>
<div class="paragraph">
<p>SAML bindings are defined in the
<a href="https://docs.oasis-open.org/security/saml/v2.0/saml-bindings-2.0-os.pdf">Bindings
for the OASIS Security Assertion Markup Language (SAML) V2.0</a>
specification.</p>
</div>
</div>
<div class="sect2">
<h3 id="_saml_messages">4.4. SAML Messages</h3>
<div class="paragraph">
<p>All SAML messages are conveyed as XML documents. A SAML XML message
may be transported in a variety of mechanisms known as a
<a href="#saml_bindings">SAML binding</a>. Examples of SAML bindings include:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>query parameters of an HTTP URL.</p>
</li>
<li>
<p>parameters of an HTML form.</p>
</li>
<li>
<p>wrapped in a SOAP message.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The exact way a SAML interchange operates and the SAML bindings which
are utilized in each step define what is called a SAML
<a href="#saml_profiles">SAML profile</a>. For example web-sso is defined by the
<em>Web Browser SSO Profile</em>.</p>
</div>
<div class="paragraph">
<p>SAML data, and its XML schema are defined in the <a href="https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf">Assertions and Protocols for the OASIS
Security Assertion Markup Language
(SAML) V2.0</a> <em>core</em> specification.</p>
</div>
</div>
<div class="sect2">
<h3 id="web_sso_flow">4.5. SAML Web-SSO flow</h3>
<div class="paragraph">
<p>The <em>Web Browser SSO Profile</em> is the best known <a href="#saml_profiles">SAML
profile</a> and the one Mellon focuses on. Your ability to configure
Mellon and diagnose Mellon deployment issues will be greatly enhanced
if you understand this flow and the two SAML messages conveyed in the
flow, <em>SAML AuthnRequest</em> and <em>SAML Assertion Response</em>.</p>
</div>
<div class="imageblock">
<div class="content">
<img src="data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9Im5vIj8+CjwhLS0gQ3JlYXRlZCB3aXRoIElua3NjYXBlIChodHRwOi8vd3d3Lmlua3NjYXBlLm9yZy8pIC0tPgoKPHN2ZwogICB4bWxuczpkYz0iaHR0cDovL3B1cmwub3JnL2RjL2VsZW1lbnRzLzEuMS8iCiAgIHhtbG5zOmNjPSJodHRwOi8vY3JlYXRpdmVjb21tb25zLm9yZy9ucyMiCiAgIHhtbG5zOnJkZj0iaHR0cDovL3d3dy53My5vcmcvMTk5OS8wMi8yMi1yZGYtc3ludGF4LW5zIyIKICAgeG1sbnM6c3ZnPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIKICAgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIgogICB4bWxuczpzb2RpcG9kaT0iaHR0cDovL3NvZGlwb2RpLnNvdXJjZWZvcmdlLm5ldC9EVEQvc29kaXBvZGktMC5kdGQiCiAgIHhtbG5zOmlua3NjYXBlPSJodHRwOi8vd3d3Lmlua3NjYXBlLm9yZy9uYW1lc3BhY2VzL2lua3NjYXBlIgogICB3aWR0aD0iNi43NzY1NDZpbiIKICAgaGVpZ2h0PSI1Ljk2ODgxMWluIgogICB2aWV3Qm94PSIwIDAgMTcyLjEyNDI3IDE1MS42MDc4IgogICB2ZXJzaW9uPSIxLjEiCiAgIGlkPSJzdmc4IgogICBpbmtzY2FwZTp2ZXJzaW9uPSIwLjkyK2RldmVsIHVua25vd24iCiAgIHNvZGlwb2RpOmRvY25hbWU9InNhbWwtd2ViLXNzby5zdmciPgogIDxkZWZzCiAgICAgaWQ9ImRlZnMyIj4KICAgIDxtYXJrZXIKICAgICAgIGlua3NjYXBlOnN0b2NraWQ9IkFycm93MkxlbmQiCiAgICAgICBvcmllbnQ9ImF1dG8iCiAgICAgICByZWZZPSIwIgogICAgICAgcmVmWD0iMCIKICAgICAgIGlkPSJtYXJrZXIxMzU0MiIKICAgICAgIHN0eWxlPSJvdmVyZmxvdzp2aXNpYmxlIgogICAgICAgaW5rc2NhcGU6aXNzdG9jaz0idHJ1ZSI+CiAgICAgIDxwYXRoCiAgICAgICAgIGlua3NjYXBlOmNvbm5lY3Rvci1jdXJ2YXR1cmU9IjAiCiAgICAgICAgIGlkPSJwYXRoMTM1NDAiCiAgICAgICAgIHN0eWxlPSJmaWxsOiMwMDAwMDA7ZmlsbC1vcGFjaXR5OjE7ZmlsbC1ydWxlOmV2ZW5vZGQ7c3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLXdpZHRoOjAuNjI1O3N0cm9rZS1saW5lam9pbjpyb3VuZDtzdHJva2Utb3BhY2l0eToxIgogICAgICAgICBkPSJNIDguNzE4NTg3OCw0LjAzMzczNTIgLTIuMjA3Mjg5NSwwLjAxNjAxMzI2IDguNzE4NTg4NCwtNC4wMDE3MDc4IGMgLTEuNzQ1NDk4NCwyLjM3MjA2MDkgLTEuNzM1NDQwOCw1LjYxNzQ1MTkgLTZlLTcsOC4wMzU0NDMgeiIKICAgICAgICAgdHJhbnNmb3JtPSJtYXRyaXgoLTEuMSwwLDAsLTEuMSwtMS4xLDApIiAvPgogICAgPC9tYXJrZXI+CiAgICA8bWFya2VyCiAgICAgICBpbmtzY2FwZTppc3N0b2NrPSJ0cnVlIgogICAgICAgc3R5bGU9Im92ZXJmbG93OnZpc2libGUiCiAgICAgICBpZD0ibWFya2VyMTIxOTQiCiAgICAgICByZWZYPSIwIgogICAgICAgcmVmWT0iMCIKICAgICAgIG9yaWVudD0iYXV0byIKICAgICAgIGlua3NjYXBlOnN0b2NraWQ9IkFycm93MkxlbmQiPgogICAgICA8cGF0aAogICAgICAgICB0cmFuc2Zvcm09Im1hdHJpeCgtMS4xLDAsMCwtMS4xLC0xLjEsMCkiCiAgICAgICAgIGQ9Ik0gOC43MTg1ODc4LDQuMDMzNzM1MiAtMi4yMDcyODk1LDAuMDE2MDEzMjYgOC43MTg1ODg0LC00LjAwMTcwNzggYyAtMS43NDU0OTg0LDIuMzcyMDYwOSAtMS43MzU0NDA4LDUuNjE3NDUxOSAtNmUtNyw4LjAzNTQ0MyB6IgogICAgICAgICBzdHlsZT0iZmlsbDojMDAwMDAwO2ZpbGwtb3BhY2l0eToxO2ZpbGwtcnVsZTpldmVub2RkO3N0cm9rZTojMDAwMDAwO3N0cm9rZS13aWR0aDowLjYyNTtzdHJva2UtbGluZWpvaW46cm91bmQ7c3Ryb2tlLW9wYWNpdHk6MSIKICAgICAgICAgaWQ9InBhdGgxMjE5MiIKICAgICAgICAgaW5rc2NhcGU6Y29ubmVjdG9yLWN1cnZhdHVyZT0iMCIgLz4KICAgIDwvbWFya2VyPgogICAgPG1hcmtlcgogICAgICAgaW5rc2NhcGU6aXNzdG9jaz0idHJ1ZSIKICAgICAgIHN0eWxlPSJvdmVyZmxvdzp2aXNpYmxlIgogICAgICAgaWQ9Im1hcmtlcjEyMDA4IgogICAgICAgcmVmWD0iMCIKICAgICAgIHJlZlk9IjAiCiAgICAgICBvcmllbnQ9ImF1dG8iCiAgICAgICBpbmtzY2FwZTpzdG9ja2lkPSJBcnJvdzJMZW5kIgogICAgICAgaW5rc2NhcGU6Y29sbGVjdD0iYWx3YXlzIj4KICAgICAgPHBhdGgKICAgICAgICAgdHJhbnNmb3JtPSJtYXRyaXgoLTEuMSwwLDAsLTEuMSwtMS4xLDApIgogICAgICAgICBkPSJNIDguNzE4NTg3OCw0LjAzMzczNTIgLTIuMjA3Mjg5NSwwLjAxNjAxMzI2IDguNzE4NTg4NCwtNC4wMDE3MDc4IGMgLTEuNzQ1NDk4NCwyLjM3MjA2MDkgLTEuNzM1NDQwOCw1LjYxNzQ1MTkgLTZlLTcsOC4wMzU0NDMgeiIKICAgICAgICAgc3R5bGU9ImZpbGw6IzAwMDAwMDtmaWxsLW9wYWNpdHk6MTtmaWxsLXJ1bGU6ZXZlbm9kZDtzdHJva2U6IzAwMDAwMDtzdHJva2Utd2lkdGg6MC42MjU7c3Ryb2tlLWxpbmVqb2luOnJvdW5kO3N0cm9rZS1vcGFjaXR5OjEiCiAgICAgICAgIGlkPSJwYXRoMTIwMDYiCiAgICAgICAgIGlua3NjYXBlOmNvbm5lY3Rvci1jdXJ2YXR1cmU9IjAiIC8+CiAgICA8L21hcmtlcj4KICAgIDxtYXJrZXIKICAgICAgIGlua3NjYXBlOmlzc3RvY2s9InRydWUiCiAgICAgICBzdHlsZT0ib3ZlcmZsb3c6dmlzaWJsZSIKICAgICAgIGlkPSJtYXJrZXIxMTEyMSIKICAgICAgIHJlZlg9IjAiCiAgICAgICByZWZZPSIwIgogICAgICAgb3JpZW50PSJhdXRvIgogICAgICAgaW5rc2NhcGU6c3RvY2tpZD0iQXJyb3cyTGVuZCI+CiAgICAgIDxwYXRoCiAgICAgICAgIHRyYW5zZm9ybT0ibWF0cml4KC0xLjEsMCwwLC0xLjEsLTEuMSwwKSIKICAgICAgICAgZD0iTSA4LjcxODU4NzgsNC4wMzM3MzUyIC0yLjIwNzI4OTUsMC4wMTYwMTMyNiA4LjcxODU4ODQsLTQuMDAxNzA3OCBjIC0xLjc0NTQ5ODQsMi4zNzIwNjA5IC0xLjczNTQ0MDgsNS42MTc0NTE5IC02ZS03LDguMDM1NDQzIHoiCiAgICAgICAgIHN0eWxlPSJmaWxsOiMwMDAwMDA7ZmlsbC1vcGFjaXR5OjE7ZmlsbC1ydWxlOmV2ZW5vZGQ7c3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLXdpZHR
</div>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">(1) HTTP Request to Service Provider</dt>
<dd>
<p>A user agent (e.g browser)
makes a request on behalf of a user for a protected resource hosted by
the Service Provider (e.g. Mellon). The SP asks if there is an
existing <a href="#saml_sessions">session</a> for the user. A session is
established by a prior successful SAML authentication. If a valid
session exists the SP immediately grants access to the protected
resource. A user session is communicated via a HTTP cookie (see
<a href="#mellon_cookie">Mellon Cookie</a>). If a valid session does not exist the SP begins
the authentication process.</p>
</dd>
<dt class="hdlist1">(2) &lt;AuthnRequest&gt; issued by Service Provider to Identity Provider</dt>
<dd>
<p>To authenticate the user the SP must send a <code>&lt;AuthnRequest&gt;</code> to an
IdP. In the <em>Web Browser SSO Profile</em> the SP determines the IdP. The
SP uses the <em>HTTP Redirect Binding</em> to convey the <code>&lt;AuthnRequest&gt;</code> to
the IdP. This binding embeds the <code>&lt;AuthnRequest&gt;</code> in the URL query
parameters of a HTTP redirect. The browser performs a redirect to the
IdP which decodes the <code>&lt;AuthnRequest&gt;</code> embedded in the URL query
parameters. The IdP also maintains <a href="#saml_sessions">session</a>
information for the user. If there is an existing valid session for
the user at the IdP it immediately responds with a <code>&lt;Assertion&gt;</code>
response unless the <code>&lt;AuthnRequest&gt;</code> has enabled <code>ForceAuthn</code> which
requires the user to be re-authenticated. See the
<a href="#authentication_request">AuthnRequest example</a> to better understand
its contents and how it appears as HTTP data. Part of the data
communicated along with the <code>&lt;AuthnRequest&gt;</code> is an item known as the
<a href="#relaystate">RelayState</a>. The <code>RelayState</code> is the mechanism which
permits the flow to return to the original requested resource.</p>
</dd>
<dt class="hdlist1">(3) Identity Provider identifies Principal</dt>
<dd>
<p>If necessary the IdP
authenticates the user. How the authentication is performed is <strong>not</strong>
defined by SAML. Typically the IdP responds with a login page where
the user enters their username and password. After successful
authentication the IdP establishes a session for the user.</p>
</dd>
<dt class="hdlist1">(4) Identity Provider issues a SAML &lt;Response&gt; to the Service Provider</dt>
<dd>
<p>Assuming a valid session now exists on the IdP for the user
it responds to the user&#8217;s browser with an <code>&lt;Assertion&gt;</code> using the <em>HTTP
Post Binding</em>. The HTTP Post binding is a bit magical, you may want to
review how this works in <a href="#http_post">HTTP Post and Self-Posting</a>. If a valid session could not
be established for the user a failed status response is issued instead.
See the <a href="#assertion_response">Assertion example</a> to better understand
the contents of an <code>&lt;Assertion&gt;</code>.</p>
</dd>
<dt class="hdlist1">(5) SP grants or denies access to the principal</dt>
<dd>
<p>If the response does not contain a successful <code>&lt;Assertion&gt;</code> response
the SP denies access by returning a 403 HTTP_FORBIDDEN status
response. Otherwise the SP processes the <code>&lt;Assertion&gt;</code>. The SP may
apply additional constraints on access to the protected resource (see
<a href="#assertion_constraints">Mellon constraints</a> for how Mellon can
apply additional authorization constraints). If the constraint check
passes then the SP establishes a session for the user. Mellon
associates the session information with a session ID returned in a
cookie (see <a href="#mellon_cookie">Mellon Cookie</a>).</p>
</dd>
<dt class="hdlist1">(6) SP redirects to original resource</dt>
<dd>
<p>The SP uses the <a href="#relaystate">RelayState</a> which identities the
original requested resource and responds with a redirect to that URL.</p>
</dd>
<dt class="hdlist1">(7) Browser accesses resource again</dt>
<dd>
<p>The browser upon receiving the redirect to the original resource URL
once again tries to access the resource. This time however there is a
valid session established for the user as communicated in the session
cookie. The SP validates the session ID which should immediately
succeed. At this point Mellon informs Apache that the authentication
and authorization check has succeeded for the URL.</p>
</dd>
<dt class="hdlist1">(8) SP responds with resource</dt>
<dd>
<p>Since the authentication and authorization checks in Apache have now
passed the contents of the resource are returned to the user&#8217;s browser.</p>
</dd>
</dl>
</div>
<div class="sect3">
<h4 id="saml_sessions">4.5.1. Sessions</h4>
<div class="paragraph">
<p>Sessions are maintained at both the SP and the IdP.</p>
</div>
<div class="paragraph">
<p>After an IdP successfully authenticates a user it creates a session
for the user. The IdP keeps a list of every SP the user is logged
into. When the user logs out the IdP sends a logout request to the
<em>SingleLogoutService</em> endpoint of each SP. When an IdP receives a
<code>&lt;AuthnRequest&gt;</code> from a SP it checks to see if it has an existing
valid session for that user, if so it can skip authenticating the user
again and instead just issue an <code>&lt;Assertion&gt;</code> based on the existing
session. However the SP can force the IdP to always re-authenticate if
it passes a <code>ForceAuthn</code> value of <code>True</code> in the <code>&lt;AuthnRequest&gt;</code>. The
IdP may further be restricted from interacting with the SP if the
request contains a <code>isPassive</code> value of <code>True</code>.</p>
</div>
<div class="paragraph">
<p>The IdP can inform the SP how long it wishes a SP session to be valid
by passing the <code>SessionNotOnOrAfter</code> attribute in a
<code>&lt;AuthnStatement&gt;</code>. Mellon respects the <code>SessionNotOnOrAfter</code>
attribute and will limit its session duration based on it.</p>
</div>
<div class="paragraph">
<p>The SP also maintains a session for the user. The SP session is
communicated between the browser and the SP using a cookie containing
the session ID. If the SP verifies the user has an existing valid
session when it receives a request it can immediately make an access
decision based on the cached session information for the user.</p>
</div>
<div class="paragraph">
<p>See <a href="#mellon_session">Mellon Sessions</a> for more information on the
particulars of how Mellon manages it sessions.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="http_post">4.6. HTTP Post and Self-Posting</h3>
<div class="paragraph">
<p>The <em>HTTP Post Binding</em> is used to convey an assertion back to a
SP. Assertions are usually too big to embed in a URL so some other
mechanism is needed to transport the <code>&lt;Assertion&gt;</code> response data. The
data is url-form-encoded as HTTP Form. The form&#8217;s action attribute
specifies the destination URL of the form data.</p>
</div>
<div class="paragraph">
<p>Where does the destination URL come from? The IdP will have loaded the
SP&#8217;s <a href="#metadata">metadata</a> which defines among other things the
various provider URL <a href="#endpoints">endpoints</a> where SAML communication
occurs. The <code>&lt;Assertion&gt;</code> needs to be sent to one of the SP&#8217;s
<em>AssertionConsumerService</em> endpoints, specifically the
<em>AssertionConsumerService</em> endpoint URL supporting the <em>HTTP-POST</em>
binding. The SP&#8217;s <em>AssertionConsumerService</em> URL as read from its
metadata is set to the action attribute of the HTTP form. <em>The action
URL is <strong>not</strong> read from any data in the &lt;AuthnRequest&gt;</em>, this is one
safeguard to prevent SAML messages from being sent to a unintended
nefarious party. Note that many SAML bindings define a <code>Destination</code>
attribute that is embedded in the SAML message. A further check
compares the <code>Destination</code> attribute to the URL the message was
received at, see <a href="#invalid_destination">HTTP_BAD_REQUEST - Invalid Destination on Response</a> for a common deployment
problem.</p>
</div>
<div class="paragraph">
<p>But how does the POST data as received by the user&#8217;s browser get back
to the <em>AssertionConsumerService</em> endpoint of the SP? The form will
<em>self-post</em> due to this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-html" data-lang="html">&lt;body onload="document.forms[0].submit()"&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>As long as the user&#8217;s browser has not disabled scripts it will
immediately post the form data to the <em>AssertionConsumerService</em> URL
in the forms action attribute. If scripts have been disabled the HTML
will instruct the user to click the <code>Submit</code> button to post the form
data.</p>
</div>
</div>
<div class="sect2">
<h3 id="entityID">4.7. entityID</h3>
<div class="paragraph">
<p>Each SAML provider (e.g. a SP or IdP) is identified by its
<code>entityID</code>. You should think of the <code>entityID</code> as the globally unique
name of the provider. The <code>entityID</code> appears in most SAML messages and
in the provider&#8217;s metadata. This is the mechanism by which a SAML
message consumer associates the SAML message with the message
producers configuration properties. When a SAML provider receives a
message it extracts the <code>entityID</code> from the message and then looks up
the metadata belonging to that provider. The information in the
provider&#8217;s metadata is essential in order to operate on the SAML
message.</p>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
Any mismatch between the <code>entityID</code> the producer is emitting
and the consumer has loaded via the producer&#8217;s metadata will cause
failures. A common mistake is to modify a producer&#8217;s metadata
(e.g. update Mellon) but fail to reload Mellon&#8217;s metadata in the IdP.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>SAML places two requirements on the <code>entityID</code>:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>It <strong>must</strong> be an URI</p>
</li>
<li>
<p>It <strong>must</strong> be unique within the federation</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>A wise administrator will also seek to fulfill this additional
requirement when choosing an <code>entityID</code>:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>It should identify the organization instead of a specific node
within the organization.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>When migration time arrives it is far easier to move resources around
when those resources are not tied to a specific node. Thus choosing an
<code>entityID</code> comprised of the organization&#8217;s domain name and a generic
identifier such as <code>saml</code> would be one good approach, for example
<code><a href="https://bigcorp.com/saml" class="bare">https://bigcorp.com/saml</a></code>.</p>
</div>
<div class="paragraph">
<p>A common practice and one that recommended in the
<a href="https://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf">Metadata
for the OASIS Security Assertion Markup Language (SAML)</a> specification
in section 4, <em>Metadata Publication and Resolution</em> is to use the
<code>entityID</code> as a <em>well-known-location</em> for retrieving the provider&#8217;s
metadata. In other words the <code>entityID</code> is the URL which returns the
provider&#8217;s XML metadata document when a HTTP GET is performed on that
URL. <em>It is not a requirement the <code>entityID</code> be the URL for metadata
download</em> rather it is one common convention. As discussed in the SAML
metadata specification other mechanisms can be established for
metadata publication.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
SAML requires metadata publication to be integrity
protected. A provider&#8217;s metadata is literally the <em>keys to the
provider&#8217;s kingdom</em> as it contains the cryptographic keys used during
SAML authentication as well as other vital SAML properties. <em>It is
essential to establish trust and validate the metadata.</em> Metadata can
be signed but the easiest way to assure metadata integrity and the
most common is to make sure metadata is only exchanged via a secure
and trusted channel. TLS provides such a mechanism. Therefore if you
publish metadata (and Mellon always does regardless of whether Mellon&#8217;s
metadata endpoint matches Mellon&#8217;s <code>entityID</code>) it <strong><em>MUST</em></strong> occur
<em>only</em> over the <code>https</code> TLS scheme. Make sure your Apache
configuration redirects any <code>http</code> for Mellon to <code>https</code> and that your
https certificate is signed by a trusted CA such that others can
properly validate your https cert. <em>Do not use self-signed certs for
your https!</em> If you do and you&#8217;re on a public network, you&#8217;re
opening yourself up to a serious security vulnerability. Note, the
certs used <em>inside</em> the metadata can be self-signed, see
<a href="#metadata_keys">Certs and Keys Inside Metadata</a> for an explanation of why. The key concept here to take
away is that <em>a provider&#8217;s metadata provides the trust and is the validation
mechanism used by SAML</em>. Thus the integrity of the metadata is of
paramount importance.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Mellon&#8217;s metadata is <em>always</em> published at the URL location
<code>/$MellonEndpointPath/metadata</code>. See the description of
<a href="#mellon_endpoint_path">MellonEndpointPath</a> for more details on the
use of MellonEndpointPath. This is why most of the tools surrounding
Mellon generate an <code>entityID</code> as the concatenation of the https
scheme, the hostname, the MellonEndpointPath and "metadata". Thus for
example if the <code>MellonEndpointPath</code> for <code>bigcorp.com</code> was set to
<code>saml</code>, the <code>entityID</code> (the URL location for downloading its
metadata) would be <code><a href="https://bigcorp.com/saml/metadata" class="bare">https://bigcorp.com/saml/metadata</a></code>. The only reason
why "metadata" appears in the <code>entityID</code> is because that is Mellon&#8217;s
URL endpoint for metadata publication.</p>
</div>
</div>
<div class="sect2">
<h3 id="name_id">4.8. Username, userid, SAML NameID</h3>
<div class="sect3">
<h4 id="_userid_vs_identity_or_why_userid_is_so_last_millennium">4.8.1. Userid vs. Identity (or why userid is so last millennium)</h4>
<div class="paragraph">
<p>Many people struggle with the notion of <em>userid</em> when working with
SAML (or any other federated identity system). That&#8217;s because
historically <em>userid</em> has been used to describe <em>identity</em>. The two
are not the same. <em>Identity</em> identifies who or what something is for
the purpose of authentication and authorization as well as binding
attributes to that identity. In most of the literature the terms
<em>subject</em> and <em>principal</em> are used interchangeably to encapsulate the
concept of who or what is being identified. Although a
subject is often a person it need not be, it might also be an
inanimate object. A good example of a non-human subject would be a
computer service needing to be authenticated in order to perform
an operation.</p>
</div>
<div class="paragraph">
<p>Userids grew out of the early days of computing when all computing
was local and users were given accounts on a local system. The userid
was how operating systems tracked who a user was, in most cases it was
an integer. Clearly the integer userid only had meaning in the context
of the local system. As systems became networked integer userids
would be shared between systems but fundamentally nothing had changed,
the userid was still meaningful only among a group of cooperating
computers. Tools such as Yellow Pages, NIS, LDAP and Active Directory
were developed to provide a centralized repository of userids that
could be shared between cooperating networked computers. Along the way
the integer userid morphed into a string often partitioned into a
local part and a domain part. The domain part is used to identify the
realm. Realms are nothing other than collections of <em>unique</em> userids
often serving the needs of a organizational unit (e.g. company or
institution).</p>
</div>
<div class="paragraph">
<p>A key concept is that whoever is providing the userid, whether it be local
accounts created by the host operating system or a network provider of
userids such as NIS or LDAP, is an <strong>identity provider</strong> (IdP) with the
<em>userid</em> being the <strong>key</strong> used by <em>that</em> specific
<strong>identity provider</strong> to look up the <strong>identity</strong>. Hence <em>userids are only
meaningful in the context of a specific IdP!</em></p>
</div>
<div class="paragraph">
<p>By definition <em>federated identity</em> is the amalgamation of diverse
unrelated identity providers, each of which utilizes its own userid as
a key to look up an identity. Therefore while deploying federated
identity if you cling to the concept of a single userid you are likely to
be frustrated because you are abusing the concept.</p>
</div>
</div>