Child pages
  • InCommon Shibboleth IdP Training - NameID Configuration

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


  • Microsoft (Office 365)
  • Google Apps
  • DocuSign

NameID Formats

  • In addition to the NameID itself, the assertion will also include a "NameID format" identifier. These are a way to tell the service provider what type of NameID is being sent in the assertion.
  • In the metadata, SPs typically (but not always) specify what "format" of NameID they prefer. Multiple formats may be specified in the SP's metadata, indicating that any of the listed formats are acceptable.

Common NameID Formats

These are what you are most likely to encounter in most single sign-on integrations with cloud vendors:


In practice, an SP typically will request a certain NameID format, either in its metadata (look for one or more <NameIdFormat> elements), or out-of-band (e.g. in a single sign-on configuration document).

Populating the NameID for a specific SP

For most cloud SSO integrations that require a custom NameID, you'll need to populate the NameID with the value of an attribute specified in attribute-resolver.xml. Here is a typical recipe. In this example, the SP entity ID is, the NameID format is urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified, and the NameID will be populated with the value of the googleAppsPrincipal attribute.


  1. In saml-nameid.xml, look for the list of SAML 2 NameID Generators (<util:list id="shibboleth.SAML2NameIDGenerators">). Inside this block, add a new <bean> that specifies the NameID format, entity ID for the target SP, and attribute that you want to use:

    Code Block
    <bean parent="shibboleth.SAML2AttributeSourcedGenerator"
          p:attributeSourceIds="#{ {'googleAppsPrincipal'} }">
          <property name="activationCondition">
              <bean parent="shibboleth.Conditions.RelyingPartyId"
                    c:candidate="" />

  2. In attribute-filter.xml, make sure that you're releasing the attribute to the SP: 

    Code Block
    <AttributeFilterPolicy id="exampleServiceProvider">
        <PolicyRequirementRule xsi:type="Requester" value="" />
        <AttributeRule attributeID="googleAppsPrincipal" permitAny="true" />


    If you release an attribute that has encoders attached to it, the attribute will also be included in the <AttributeStatement> of the assertion. Some SPs may balk at this (although, in practice, most won't care). To avoid this side effect, you can add a new attribute definition (in attribute-resolver.xml) that does not include any <AttributeEncoder> blocks.

  3. Sometimes, you'll also need to add an entry to relying-party.xml that explicitly specifies the NameID format you want to use. Typically, you'll need to do this if:
    • The SP's metadata does not have a <NameIDFormat> section that includes the desired format(s) (in these cases, absent a specific relying party configuration, the IdP will use an automatically-generated transient identifier, which usually is not what you will want).
    • The SP is requesting the urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified format (the IdP will ignore this specific format if it sees it in the metadata).

    Code Block
    <bean parent="RelyingPartyByName" c:relyingPartyIds="">
        <property name="profileConfigurations">
                <bean parent="SAML2.SSO" p:nameIDFormatPrecedence="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" />


Configure your IdP to populate the NameID field with the user's email address (value of the mail attribute) for all assertions sent to the classroom SP.


If you have problems, see the "troubleshooting" section (below), or ask one of your friendly trainers.


Custom NameID configurations require editing several configuration files, and as such, can sometimes be error-prone and tricky to troubleshoot. If the NameID isn't getting populated the way you expect for a certain SP, the first place to look is idp-process.log. For each assertion the IdP generates, a log entry will be created in this file that includes (among other useful information) the NameID that the IdP generated and used in the assertion.


If you see a long, random string of characters where you were expecting to see an identifier, that means that the IdP was unable to generate a NameID, so it fell back on using a transient identifier. That's usually due to an error in the configuration. In these cases, it can be helpful to enable debug logging. In /opt/shibboleth-idp/conf/logback.xml, change idp.loglevel.idp to DEBUG, and restart (or wait for the file to reload). This log level will include useful debugging output related to NameID generation, and you usually can identify the problem by reading through the logs.