Category Archives: SAML

HOW TO: Using SAML-Tracer to Capture SAML Event(s) for Debugging Purposes

HOW TO: Using SAML-Tracer to Capture SAML Event(s) for Debugging Purposes

N.B. In our work, it’ll frequently become necessary to ask customers (or our client’s customers) to capture a SAML login or logout event, in order to assist our team in debugging the SAML workflow. This guide is therefore intended to serve as a walk-through for a potentially non-technical audience, to enable that user to install, use, and collect the log from the popular browser extension SAML-Tracer.

Step #1: Installing SAML-tracer

The SAML-Tracer add-on is available for free for Mozilla Firefox and Google Chrome from their respective web stores:

You can also leverage the Chrome version of the plugin in Chromium-based browsers, such as:

  • Microsoft Edge
  • Vivaldi
  • Brave

After you successfully install the extension, and to ensure that you have no active session, you should clear your browser’s cache and restart the browser.

PRO TIP: You can quickly access the menu for clearing your cache with the ctrl + shift + delete keyboard shortcut.

Step #2: Capturing a SAML Login or Logout

After installing the extension in your browser one simply needs to activate the extension in order for it to capture traffic. To do this, either look for the SAML-tracer icon in your browser:

Screenshot of browser toolbar with SAML-tracer icon visible and highlighted by red arrowing pointing at it.

Figure 1. Mozilla Firefox toolbar with SAML-Tracer icon.

In many browsers you’ll need to “pin” the icon to be visible by default, e.g. for Mozilla Firefox, you may find the SAML-Tracer icon hiding under the dropdown that appears when clicking on the two angle brackets to the right side of the image. Also, in a stock Google Chrome installation, for example:

Screenshot of Chrome browser toolbar with SAML-tracer icon visible within extensions dropdown.

Figure 2. Google Chrome toolbar with SAML-Tracer icon hidden in the “puzzle piece” menu.

You can see that the SAML-Tracer extension gets placed in the “Extensions” menu (denoted with a small puzzle piece). You can optionally pin the SAML-Tracer icon to the main toolbar with the “pin” button within that menu.

Once the extension is activated, you’ll see a small pop-up window like the following:

A screenshot of the initial window that opens when activating SAML-Tracer.

Figure 3. An empty SAML-Tracer window.

You’ll at this point potentially notice some lines appearing within the top-part of window. Ignore this for now. Go back to your browser, and log into the application you’re trying to capture debug information for.

At this point, you’ll see many more lines appear as your are performing your login. These lines represent all of the various URLs that are being loaded or to which data is being sent. After you login, you should notice that some of the lines will have an orange saml logo to the right, for example:

Figure 4. A screenshot of the SAML-Tracer extension showing captured SAML.

If, when you click on one of the lines with this logo, and you also click on the “SAML” tab in the lower panel, you see some XML code as shown within the screenshot, then congratulations! You’ve captured SAML!

Step #3: Sharing the Captured SAML

In order to share the capture you’ve just taken, click on the “export” button at the top of the SAML tracer window (next to “Colorize”). The window will darken, and a selection box will appear with some export options:

Figure 5. The SAML-Tracer export options screen.

WARNING: Make sure you either keep the “mask values” option checked, or select “Remove Values”. If you chose “None” in this dialog, you will capture any secret parameters that were exchanged in the process, namely plaintext passwords. You do NOT need to share a capture with a plaintext password. Removing, or masking the value with a series of ****** are the only advisable options here.

When you click “export”, a JSON file will be saved to the location of your choice. This is the file that you should share with the engineer that’s requesting the SAML trace.

If requested from the IDM Engineer, we’ll share with you a URL where you can securely upload the file, and it will be accessible only to the engineering team at IDME. Emailing this file is generally safe, though for added safety we recommend sharing the file through some means other than email.

Need help with a SAML issue? Contact us to discuss your needs. IDM Engineering is a team of dedicated, honest SSO support engineers that are standing by to help!

This entry was posted in Blog, HowTo, SAML on by .

SP Metadata for Amazon Cognito

AWS Cognito SP Metadata

SP Metadata for Amazon Cognito

Cognito is the easy-to-implement authentication service for web and mobile apps hosted in the AWS ecosystem.

Cognito provides “user pools” — or groups of user’s coming from various sources — against which an application can authenticate a user, with those further able to be extended to external sources such as social media (Google, Facebook, Amazon) or federated identity providers via SAML 2.0.

And when it comes to implementing SAML 2.0 integration with an identity provider (IDP), Amazon provides pretty good documentation.

However that documentation, and indeed the Cognito service, lacks something relatively fundamental.

Cognito admirably accounts for the fact that most Service Provider operators will recieve from their integration partners an XML metadata bundle representing the IDP, and hence provides the ability to configure the SAML connection on the Cognito side by uploading that IDP metadata document. They even allow you to supply a link to the IDP metadata, given that many IDP operators maintain URLs which serve up a signed copy of the latest metadata, in an effort to provide simpler rollover of SAML signing and encryption certificates.

However, where Cognito fails utterly (as of the writing of this document) is to provide a simple means to generate service provider (SP) metadata, leading to awkward conversations where unknowing Cognito admins are being asked by more knowledgeable IDP operators for metadata that they don’t have. Furthermore, Cognito’s documentation is really lacking in the area of how to create that metadata.

As such, this post is intended as a quick how-to for Cognito SP operators to generate valid XML metadata representing the Cognito SP.

Metadata Prerequisites

There are three core pieces of information that you are required to know in order to generate SAML SP metadata for a Cognito User Pool:

The Cognito User Pool ID: $pool_id

You can access this information from the AWS Console. From the upper left hand corner select “Services -> Security, Identity, and Governance -> Cognito” to access the Cognito control panel. Then select “Manage User Pools”. You should then select the User Pool for which you wish to obtain the Pool ID. Selecting a User Pool will take you to the “General Settings” for the Pool, which should list the “Pool ID” at the top:

At the time of writing this post Cognito is moving to a “new” interface. You can access the Pool ID in basically the same way, however Amazon conveniently lists the Pool ID on your list of User Pools:

The User Pool’s AWS Region: $region

Conveniently, you can get this straight out of the Pool ID:

as the struction of the $pool_id is $region_XXXXXXXXX. As you can see from the above example, my test User Pool is located in the “US East 2 (Ohio)” region, hence $region = us-east-2 for our metadata.

Cognito Domain Prefix: $domain_prefix (or Custom Domain)

Lastly, you will specify a domain prefix when you create the User Pool, which establishes a domain that uniquely identifies the pool to AWS. This will take the form of:

$domain_prefix.auth.$region.amazoncognito.com

Alternatively, if you have associated a custom domain to your Cognito User Pool, you will substitute that.

You’ll find the settings for the domains under “App Integration -> Domain Name” in the current Cognito User Pool Settings,

or on the “App Integration” tab in the new Cognito interface:

Integration Particulars

Additionally, you’ll want to make some decisions now about things like the SAML attributes that you require from the IDP. Each of these will be enumated within the templated metadata below, and you’ll want to know the name of the attribute, as well as it’s friendlyName.

There are many particularities to Cognito attribute mappings, and fortunately, the documentation about attribute mapping is quite robust.

The keys are the following:

  • Cognito requires an attribute as the SAML <NameID> which will be used to uniquely identify the user within Cognito. You don’t necessarily need to use this as the principal identifier within your application, but it is ideally a useful identifier for a human being to look at (i.e. not a transient: urn:oasis:names:tc:SAML:2.0:nameid-format:transient). We recommend requesting some form of “user id” as a persistent identifier (urn:oasis:names:tc:SAML:2.0:nameid-format:persistent).
  • Ensure that any attribute mappings that you define in Cognito are properly enumerated within the metadata, as this will assist the IDP deployer in facilitating their configuration of attribute release.

We furthermore strongly encourage the following best practices:

  • Don’t ask for an email address as the NameID / principal identifiers. Email addresses frequently change!
  • Request only the minimal set of attributes your application requires.
  • Be flexible! It is generally considered rude within the SAML community for a vendor to demand that an IDP releases a custom attribute specific to your organization. Instead, adapt your attribute mapping to work with what the IDP has available to send. Generic names are also good: mail, uid, sn, givenName etc.

Building the SP Metadata

Now we can construct our metadata… we will use the following elements:

  • $pool_id
  • $region
  • $domain_prefix
  • The NameID format we’ll request, in this example case: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
  • A list of attributes we’ll need, in this case we are requesting mail, givenName, and sn using standard LDAP OIDs.

You will then use the following template to substitute your values for $pool_id, $region, and $domain_prefix.

<?xml version="1.0"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="urn:amazon:cognito:sp:$pool_id">
    <md:SPSSODescriptor AuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</md:NameIDFormat>
        <md:AssertionConsumerService
Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
Location="https://$domain_prefix.auth.$region.amazoncognito.com/saml2/idpresponse"
index="1"/>
        <md:AttributeConsumingService index="1">
            <md:ServiceName xml:lang="en">Cognito Sample SP</md:ServiceName>
            <md:RequestedAttribute FriendlyName="givenName" Name="urn:oid:2.5.4.42"/>
            <md:RequestedAttribute FriendlyName="sn" Name="urn:oid:2.5.4.4"/>
            <md:RequestedAttribute FriendlyName="mail" Name="urn:oid:0.9.2342.19200300.100.1.3"/>
        </md:AttributeConsumingService>
    </md:SPSSODescriptor>
</md:EntityDescriptor>

And substitute your NameID and attribute requirements as in the above examples. Note that the <md:ServiceName> element is not optional, and you should provide a relevant name for your purposes. Many IDP systems will tolerate the absence of this element, though formally to the spec for the <AttributeConsumingService> it is required

A Note About Signing

Note that we do not include a certificate within the metadata because Cognito does not support signed <AuthnRequests>. Hopefully Amazon will overcome this limitation in the future, as some IDP partners do require signing of these requests.

Need help with AWS Cognito? Contact us to discuss your needs. IDM Engineering is a team of dedicated, honest SSO support engineers that are standing by to help!

This entry was posted in Blog, SAML on by .