SAML ECP client with assertion delegation support.
npm install hana-saml-wsseSome advanced SAML use cases involve a single logical transaction that spans one or more intermediate
clients or servers. A common example includes a SAML-enabled web site acting on behalf of a logged-in
user while accessing additional SAML-enabled services, which are not directly accessible
by the user agent, e.g. a database. Generalizing this example, a number of intermediaries might be
traversed before the final point of access. Popular ways of making this happen are
__SAML impersonation__, __SAML assertion forwarding__ and __SAML IdP proxy__.
All of them suck:
* SAML impersonation forces principal to disclose credentials to an SP.
* SAML forwarding makes IdP lose track of who and when is using forwarded assertions.
* IdP proxy requires a second IdP in exotic configuration.
When a SAML assertion is used as a security token to authenticate/authorize people and software
against a mission-critical service, it is important that the identities and order of intermediaries,
if any, are expressed within the token in some fashion.
__SAML assertion delegation__ moves beyond the forwarding scenario by adding information to the
assertion that explicitly identifies the chain of parties through which a transaction flows.
Delegation assures that all requests in the chain are routed back through the identity provider at
each hop to cryptographically guarantee that each party has been authenticated and appropriate
policy enforced. This finegrained and real-time enforcement capability is a key advantage over
pure SAML forwarding and impersonation, at a price of additional back-channel operation for
each delegation hop.
[__Shibboleth Identity Provider__]() implements SAML 2.0 profile for assertion delegation (Liberty/IDWSF).
__hana-saml-wsse__ is the corresponding client. It also implements an __ECP__ client, which is handy
for testing your delegation configuration, but can be very useful in its own right, e.g.
if you are implementing impersonation or fowarding model.
The package name is historical; the client has been originally implemented for a specific use case
that involved a SAP HANA database backend. Making Shibboleth delegation work with SAP HANA requires
additional IdP configuration, which is not covered here.
This implementation is known to work with Shibboleth IdP 3.2. There is some indication that ECP
and ID-WSF profiles are supported by some other open source and commercial IdP
systems, but none of them were tested.
As it should be clear from the example below, ID-WSF requires that your IdP is configured to support
__X.509 client certificate authentication__. The same applies to all TLS middleware you might have
in front of your IdP, e.g. nginx, httpd, netscaler, etc. This is at least as complicated as it
sounds, so good luck. Good starting points are:
* Tomcat SSLValve
* X.509 Client-Side Certificate Auth with Nginx
> Things get easier if you want to use this library in ECP mode. Although ECP does support X.509 auth,
> it is optional (you can use basic HTTP auth method).
- The client signs all outgoing AuthRequests.
- The client expects incoming assertions to be both encrypted and signed.
- inResponseTo validation is supported and enabled by default.
- NotBeforeOrAfter is not validated, but is returned in assertionInfo object.
- wsa profile does not work over plain HTTP, and never will.
- ecp mode _should_ work over plain HTTP, but this is a very bad idea.
``
$ npm install hana-saml-wsse
The following configuration snippet assumes the following scenario:
- A Service Provider idendified as webserver-sp is allowed to obtain a webserver-sp
delegatable assertion using ECP at any time. Assertion is valid for 10 hours.
- By itself, a delegatable assertion in not usable by any other SP other than as its Audience restriction is limited to webserver-sp.webserver-sp
- However, for as long as delegatable assertion remains valid, can database-sp
request additional, "delegated" assertions which will be valid for ,database-sp
each valid for 60 seconds. These delegated assertions are no further delegatable,
i.e. is the final point of access.
___
> Note that, while requesting a delegated assertion, webserver-sp does not needdatabase-sp
> to present actual credentials of the user (generally, username and password), and it
> is not expected to have them - instead, it presents a delegatable assertion as the
> means of confirming that it has the authority to impersonate that user on
> or elsewhere. The communication takes place over authenticated TLS channel, i.e.
> IdP uses TLS to ensure it is actually talking to the SP to which the delegatable
> assertion was originally issued. __In essence, this is the whole idea of how
> assertion delegation works__.
___
`xml
p:inboundInterceptorFlows="security-policy/saml2-ecp"
p:allowDelegation-ref="delegation-predicate"
p:assertionLifetime="PT600M"
/>
p:inboundInterceptorFlows="security-policy/saml2-idwsf-ssos"
p:maximumTokenDelegationChainLength="1"
p:allowDelegation="false"
p:delegationPredicate-ref="delegation-predicate"
p:additionalAudiencesForAssertion="#{{ 'database-sp' }}"
p:assertionLifetime="PT1M"
/>
`
SP metadata must inform IdP that SP is ready and willing to consume delegatable assertions,
as shown below. The Location attribute of AssertionConsumerService must match consumerURL parameterhana-saml-wsse
of client configuration, but this is a formality as SP is not expected
to actually respond on that URL.
`xml
...
Location="https://my.org/Liberty/SSOS"/>
Name="urn:liberty:ssos:2006-08"
FriendlyName="assertionDelegation"
isRequired="false" />
...
`
The example below matches the IdP configuration above and:
1. Binds to your Identity Provider's ECP endpoint using TLS transport.
2. Authenticates using either user/password or X.509 certificate of the user.
3. Retrieves, verifies and decrypts a delegatable assertion.
4. Creates an ID-WSF AuthRequest using delegatable assertion as a security token.
5. Binds to the ID-WSF endpoint using TLS transport.
6. Authenticates using X.509 certificate of the SP.
7. Retrieves, verifies and decrypts a delegate assertion.
8. Tests it by using it as a security token to connect to a SAP HANA backend.
9. Optionally repeats steps 4-7 every deleg_test_repeat_ms milliseconds.
___
`javascript
// test.js
var
hdb = require('hdb'),
precise = require('precise'),
moment = require('moment'),
xmlfmt = require('xmlfmt'),
WSS = require('hana-saml-wsse')
;
var
deleg_test_repeat_ms = 3000,
idpHost = 'idphost',
idpPort = 443,
http_ua = 'hana-wss-client/1.0',
hdb_conf = {
host: 'hanahost',
port: 30015
}
;
var conf = {
user : 'tj_holowaychuk',
pass : null, // leave blank for TLS CCA (@see user_key/user_cert)
idpHost : idpHost,
idpPort : idpPort,
idpId : 'idp-id',
spId : 'webserver-sp',
url: {
ecp : '/idp/profile/SAML2/SOAP/ECP',
wsa : '/idp/profile/IDWSF/SSOS'
},
consumerURL : 'https://my.org/Liberty/SSOS',
idp_cert : './idp.pem',
// used both for signing and X.509 auth (WSA only)
sp_key : './sp_private_key.pem',
sp_cert : './sp_public_key.pem',
// optional TLS CCA authentication (ECP only)
user_key : './user.key',
user_cert : './user.crt',
sig_alg : 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',
tls_opt: {
hostname : idpHost,
port : idpPort,
method : 'POST',
headers : {
'Content-Type' : 'text/xml',
'Transfer-Encoding' : 'chunked',
'User-Agent' : http_ua
},
// die on bad IdP cert
rejectUnauthorized: true
},
log: console.log
};
var client = new WSS.client(conf);
function hdbtest(assertion, cb) {
var hdbclient = hdb.createClient(hdb_conf);
hdbclient.connect({ assertion: assertion }, (err) => {
if (err) {
console.error('[hdb] error:', err);
} else {
console.log('[hdb] i am', hdbclient.get('user'));
}
hdbclient.end();
cb && cb(err);
});
}
client.get('ecp', (err, delegatableAssertion, assertionInfo) => {
if (err)
return conf.log('[ecp] error:', err);
conf.log('[ecp] rcvd delegatable assertion, expires',
moment(assertionInfo.notOnOrAfter).fromNow());
//conf.log(xmlfmt(delegatableAssertion))
var delegator = () => {
var timer = precise().start();
client.get('wsa', (err, assertion, assertionInfo) => {
if (err)
return conf.log('[wsa] error:', err);
//conf.log(xmlfmt(assertion));
//conf.log(assertion);
conf.log('[wsa] rcvd delegated assertion in',
(timer.stop().diff()/1000000000).toFixed(2) + 's,',
'expires', moment(assertionInfo.notOnOrAfter).fromNow());
hdbtest(assertion, () => {
if(!deleg_test_repeat_ms)
process.exit(0);
});
}, delegatableAssertion);
};
if (deleg_test_repeat_ms)
setInterval(delegator, deleg_test_repeat_ms);
else
delegator();
});
//:~
`
You should get something like:
`
$ node test.js
[ecp] using tls cca with user key
[ecp] rcvd delegatable assertion, expires in 10 hours
[wsa] using tls cca with SP key
[wsa] rcvd delegated assertion in 0.22s, expires in a minute
[hdb] i am tj_holowaychuk
[wsa] using tls cca with SP key
[wsa] rcvd delegated assertion in 0.14s, expires in a minute
[hdb] i am tj_holowaychuk
[wsa] using tls cca with SP key
[wsa] rcvd delegated assertion in 0.16s, expires in a minute
[hdb] i am tj_holowaychuk
[wsa] using tls cca with SP key
[wsa] rcvd delegated assertion in 0.11s, expires in a minute
[hdb] i am tj_holowaychuk
[wsa] using tls cca with SP key
[wsa] rcvd delegated assertion in 0.14s, expires in a minute
^C
``
SAML specs are fun:
* Overview of SAML assertion delegation scenarios
* SAML V2.0 Enhanced Client or Proxy (ECP)
* WS-Security SAML Token
* SAML Metadata Specification
* IDWSF-SAML Specification
* Understanding WS-Security
* WSA SOAP binding
* urn:oasis:names:tc:SAML:2.0:cm:holder-of-key
MIT. Use at your own risk. As with all things SAML, always be sure you know what you are doing.