npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

hana-saml-wsse

v0.3.8

Published

SAML ECP client with assertion delegation support.

Downloads

265

Readme

SAML delegation

Some 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.

Compatibility

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.

X.509 authentication

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:

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).

Security

  • 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.

Install

$ npm install hana-saml-wsse

IdP configuration

The following configuration snippet assumes the following scenario:

  • A Service Provider idendified as webserver-sp is allowed to obtain a 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 webserver-sp as its Audience restriction is limited to webserver-sp.
  • However, for as long as delegatable assertion remains valid, webserver-sp can 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. database-sp is the final point of access.

Note that, while requesting a delegated assertion, webserver-sp does not need 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 database-sp 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.


<!-- conf/relying-party.xml -->

<!-- 
     "delegation-predicate" is a reference to a bean that implements
     com.google.common.base.Predicate<ProfileRequestContext<?,?>> interface.
     It can be used to implement additional custom logic to selectively allow
     or disallow delegation. In the most basic case, you want to implement a predicate that
     always returns true.
-->

<bean parent="RelyingPartyByName" c:relyingPartyIds="#{{ 'webserver-sp' }}">
  <property name="profileConfigurations">
    <list>
      <!-- serve long-lived delegatable assertions via ECP -->
      <bean id="SAML2.ECP"
        class="net.shibboleth.idp.saml.saml2.profile.config.ECPProfileConfiguration"
        p:inboundInterceptorFlows="security-policy/saml2-ecp"
        p:allowDelegation-ref="delegation-predicate"
        p:assertionLifetime="PT600M"
      />
      <!-- serve short-lived delegated assertions via ID-WSF -->
      <bean id="Liberty.SSOS"
        class="net.shibboleth.idp.saml.idwsf.profile.config.SSOSProfileConfiguration"
        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"
      />
     </list>
  </property>
</bean>

SP configuration

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 parameter of hana-saml-wsse client configuration, but this is a formality as SP is not expected to actually respond on that URL.

...
<!-- SSOS -->
<AssertionConsumerService
  Binding="urn:oasis:names:tc:SAML:2.0:bindings:PAOS"
  Location="https://my.org/Liberty/SSOS"/>

<AttributeConsumingService>
  <RequestedAttribute
    NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
    Name="urn:liberty:ssos:2006-08"
    FriendlyName="assertionDelegation"
    isRequired="false" />
</AttributeConsumingService>
...

Usage

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.

// 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

Recommended reading

SAML specs are fun:

License

MIT. Use at your own risk. As with all things SAML, always be sure you know what you are doing.