SAML Requested Attributes

Requested Attributes allow you to specify the user information (attributes) that you ask Signicat to include in the SAML assertion.

You control the requested attributes by using the XML element RequestedAttribute which you can pass in your request in a few ways. The context of the RequestedAttribute element depends on the eID used.

How it works

You can define the RequestedAttribute element in a few different ways:

1. In the metadata file, by using AttributeConsumingService.
2. In the request, by using a SAML protocol extension in the AuthnRequest.
3. In the Signicat Dashboard, by configuring the attributes in the Products > eID and Wallet Hub > Advanced > eID Rules (more information will follow soon).

Below, you find more details and examples for the different mechanisms.

AttributeConsumingService

When you send an authentication request, Signicat looks up the AttributeConsumingService in the metadata file and returns the attributes corresponding to the RequestedAttribute elements, as defined in the metadata.

Example of AttributeConsumingService with index="1" in a metadata file:

<md:EntityDescriptor>
  <md:SPSSODescriptor>
    <md:AttributeConsumingService index="1">
      <md:ServiceName xml:lang="en">Example Service</md:ServiceName>
      <md:RequestedAttribute isRequired="true" Name="firstName"/>
      <md:RequestedAttribute Name="email"/>
    </md:AttributeConsumingService>
  </md:SPSSODescriptor>
</md:EntityDescriptor>

Note

The isRequired attribute is not supported and will be ignored.

To use the RequestedAttribute defined in the AttributeConsumingService of your metadata file, you either pass the AttributeConsumingServiceIndex in the AuthnRequest or configure a default service, as explained below.

AttributeConsumingServiceIndex with AuthnRequest

To use a specific service, you include the index value in the AttributeConsumingServiceIndex element in your authentication request.

<samlp:AuthnRequest AttributeConsumingServiceIndex="1"></samlp:AuthnRequest>

Using the example above, the SAML response will return the user attributes as specified in the AttributeConsumingService element with index="1" of the metadata file.

Using a default AttributeConsumingService

Alternatively, you can configure a default service in the metadata. This way, Signicat returns the attributes of the default AttributeConsumingService when no AttributeConsumingServiceIndex is passed in the AuthnRequest.

You can configure a default service in two ways:

• Include isDefault="true" in the AttributeConsumingService element of your metadata file:

  <AttributeConsumingService index="1" isDefault="true">

• Add a default service in the Advanced tab in the Signicat Dashboard. To do this:
  1. Navigate to Products > eID and Wallet Hub > SAML 2.0 and select your connection.
  2. In the Advanced tab, select + Add new next to Attribute consuming services.
  3. Configure the following fields:
  • Enter a Name for the default service.
  • Enter the Index of the service. The index must match a value in the metadata.
  • Optional. Enter a Description.
  • Toggle the Default button.
  • Add the user attributes you wish to receive by default.
  

  How to add a default attribute consuming service

RequestedAttributes in AuthnRequest

You can specify the sets of user attributes on individual requests by using the SAML 2.0 Protocol Extension for requesting attributes, as explained in the official specification.

In your AuthnRequest you can define the attributes with the RequestedAttributes element.

<samlp:AuthnRequest>
  <samlp:Extensions>
      <req-attr:RequestedAttributes>
          <md:RequestedAttribute Name="firstName" isRequired="true"/>
          <md:RequestedAttribute Name="lastName"/>
          <md:RequestedAttribute Name="role">
              <saml:AttributeValue>User</saml:AttributeValue>
              <saml:AttributeValue>Administrator</saml:AttributeValue>
          </md:RequestedAttribute>
      </req-attr:RequestedAttributes>
  </samlp:Extensions>
</samlp:AuthnRequest>

Note

The AttributeValue element in RequestedAttributes is not supported. Therefore, 'User' and 'Administrator' in the example above will be ignored.

Additional parameters

Apart from regular requested attributes, the AuthnRequest to Signicat may contain additional parameters. These allow you to specify advanced aspects of an authentication session like the language or the service to use.

You can pass additional parameters in the RequestedAttributes under the Extensions object. Here you specify the string the signicat:param:<parameter_name> as the value of the Name field in the RequestedAttribute element. If the additional parameter requires you to provide a value, you can pass the value as a string in the AttributeValue element.

Language

For example, you can specify the language by using the signicat:param:language parameter, as shown in the example below:

<saml2p:Extensions xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol">
    <req-attr:RequestedAttributes xmlns:req-attr="urn:oasis:names:tc:SAML:protocol:ext:req-attr">
        <md:RequestedAttribute xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
                                Name="signicat:param:language"
                                isRequired="true"
                                >
            <saml2:AttributeValue xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
                                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                                  xsi:type="xsd:string">fi</saml2:AttributeValue>
        </md:RequestedAttribute>
    </req-attr:RequestedAttributes>
</saml2p:Extensions>

Prefilled information

When you already know some information about the end-user and you want to display it on the authentication page, you can send the prefilled data in the RequestedAttribute.

You can pass prefilled information in your request by using the signicat:prefilled:parametername format.

Signicat supports the following attributes to prefill information in your SAML 2.0 request:

Note that an eID might support only a subset of attributes.

Example

The following example shows how to prefill information about email address (signicat:prefilled:email) and mobile number (signicat:prefilled:mobile):

<samlp:Extensions>
        <req-attr:RequestedAttributes>
            <md:RequestedAttribute isRequired="true"
                                   Name="firstName"/>
            ...
            <md:RequestedAttribute Name="signicat:prefilled:email">
                <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                     xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">subject@test.com</saml:AttributeValue>
            </md:RequestedAttribute>
            <md:RequestedAttribute isRequired="false"
                                   Name="signicat:prefilled:mobile">
                                   <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                     xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">1234567890</saml:AttributeValue>
            </md:RequestedAttribute>
        </req-attr:RequestedAttributes>
</samlp:Extensions>

Provider scoping

Certain eIDs are comprised of a network of identity providers (or issuers), such as banks, that collectively offer authentication to their customers. You may want to offer your end-users only a limited number of these providers when the end-users authenticate with a specific eID.

To learn more about this feature and see examples for SAML, see the Provider scoping documentation.

Learn more

Set up a SAML connection

Exchange metadata to set up a SAML connection

SAML examples

Take a look at some SAML examples