wicked.haufe.io SAML SDK
This library helps implementing Authorization Servers for federating SAML identites (SSO identities) into a wicked.haufe.io OAuth2.0 Implicit Grant Flow API implementation. It assumes your SAML IdP supports the HTTP-POST Binding and encrypted SAML Assertions.
It does the heavy lifting regarding implementing a SAML SP (Service Provider) which talks to the IdP.
You can find more information on wicked.haufe.io here:
To install the SDK into your node.js application, run
$ npm install wicked-saml --save --save-exact
Please note that you will also need to inject the
wicked-sdk when initializing the
wicked-saml SDK; check out the
wicked-sdk NPM package for more information: npmjs.com/packages/wicked-sdk.
The SDK will be kept downwards-compatible for as long as possible; it will be tried hard to make earlier versions of the SDK compatible with a later release of wicked.haufe.io, so using the
--save-exact is a safe bet.
wicked-saml package is intended for use with ExpressJS 4.x and wicked.haufe.io. It is not intended for other types of usage.
You SAML IdP needs to support the HTTP-POST-Binding and Encrypted Assertions. In some cases (like OpenAM), assertion encryption has to be explicitly turned on and cannot be part of the
metadata.xml. If you receive errors static that
EncryptedAssertion lengths is zero but was expected to be one, this may be the mistake.
var wicked = ;var wickedSaml =var async = ; // another requirement for this sampleasync;
The single most interesting point is the string
'your-server-id' in the above example. It relies on an an Authorization Server being registered in your wicked configuration. The
wicked-saml will do the following thing:
- Retrieve the
/auth-server/your-server-idinformation from the API (that's what the
wicked-sdkis needed for)
- Read out the information in the
samlproperties and use that to initialize the implementation of the SAML Service Provider with that
More information can be found in the wicked documentation under Authorization Servers.
your-server-id.json file could look like this:
The options which can be used can be found in the documentation of
saml2-js, which is the library which is used "under the hood" of the
wicked-saml package: npmjs.com/package/saml2-js.
The example properties above (when correctly filled) will work with e.g. OpenAM.
The following functions are exported by
wickedSaml.initialize(wicked, serverId, callback)
Initialize the SAML library; calls the wicked API to retrieve information on the Authorization Server registration of the wicked configuration (see above). The
serverId has to match the
auth-server definition ID.
wicked-sdk instance to the library here;
wicked-saml will use its
function(err) -- Does not return anything but an error, or
null if successful.
Returns a function which can be used directly as the
metadata.xml end point, when using express.
Create a request identifier and login URL for redirecting to the SAML IdP.
// Assume /auth-server/:apiId?client_id=3498wzio4e57648576348756345app;
Note that there is a bunch of validity checking and security measures missing in the above code.
function(err, loginInfo), whereas
loginInfo =loginUrl: ''requestId: '7hf5irutzerwiutzhw384765h8w47658w4f'
loginUrl to redirect to the IdP and store the
requestId in your session for checking when you get called back in
wickedSaml.assert(req, requestId, callback)
Use this function to decrypt a SAML assertion. Call this from the
/assert end point you specified in your configuration (
function(err, userInfo, samlResponse)
userInfo looks as follows:
userInfo =authenticated_userid: "some-id-we-found"
wickedSaml.assert will try to extract these two values (as needed for
getRedirectUriWithAccessToken), but cannot guarantee it will work out. Additionally, if you have multiple fields in your SAML response which ends with
id, any one will be picked. So it's recommended that you explicitly set those values manually using the
samlResponse and the
getAttributeValue() function (see below).
Lists all attribute names of the
user tag of the given SAML response (
samlRespose). Takes the SAML response from
assert() as an argument and returns a string array.
Note: The attribute names will be converted to lower case.
Retrieve the value of an attribute in the
wantedAttribute parameter is not case-sensitive. If the attribute cannot be found,
null is returned.
Returns the configuration object the SAML SDK retrieved from the wicked API (e.g., the
auth-saml.json settings from the
auth-servers configuration of your API portal).
wickedSaml.getLogoutResponseUrl(inResponseTo, relayState, callback)
To be written.