Identity Assurance Hub Service Profile - SAML Attributes v1.2a

IDAP/HubService/Profiles/Saml/Attributes 07/08/2015 © Crown Copyright of 12

1

Identity Assurance Hub Service Profile – 2

SAML Attributes v1.2a 3

Identity Assurance Programme, 7 August 2015 4

Document identifier: 5 IDAP/HubService/Profiles/SAML/Attributes 6

Editors: 7 Mike Pegman, Department for Work and Pensions 8 Adam Cooper, Government Digital Service 9 Stephen Dunn, Government Digital Service 10 11

Previous Contributors: 12 Paul Toal, Oracle UK Ltd 13 Brandon Murdoch, Microsoft UK Ltd 14 Additional review and contributions were made by CESG. 15

Abstract: 16

This specification defines a profile for the use of SAML assertions and request-response 17 messages to be used between participants in the Identity Assurance federation architecture. 18

19


Table of Contents 20

1 Introduction .......................................................................................................................................... 3 21

1.1 Notation ......................................................................................................................................... 3 22

2 SAML Attributes .................................................................................................................................. 4 23

2.1 Required Information ..................................................................................................................... 4 24

2.2 SAML Attribute Naming .................................................................................................................. 4 25

2.2.1 Attribute Name Comparison ....................................................................................................... 4 26

2.3 Profile-‐Specific XML Attributes ....................................................................................................... 4 27

2.4 SAML Attribute Values ................................................................................................................... 4 28

2.5 Matching Dataset Attribute Definitions ......................................................................................... 9 29

2.5.1 Firstname ..................................................................................................................................... 9 30

2.5.2 Surname ...................................................................................................................................... 9 31

2.5.3 Middle Name(s) ........................................................................................................................... 9 32

2.5.4 Date of Birth .............................................................................................................................. 10 33

2.5.5 Gender ....................................................................................................................................... 10 34

2.5.6 Current Address ........................................................................................................................ 10 35

2.5.7 Previous Address ....................................................................................................................... 11 36

2.6 Authentication Event Assertion Attribute Definitions .................................................................. 11 37

2.6.1 IPAddress ................................................................................................................................... 11 38

2.7 Fraud Event Contextual Information Assertion Attribute Definitions .......................................... 12 39

2.7.1 GPG45Status .............................................................................................................................. 12 40

2.7.2 IDPFraudEventID ....................................................................................................................... 12 41

42


1 Introduction 43 The Identity Assurance Hub Service SAML v2.0 Profile describes how service providers offering online 44 government services can use any number of Hub Services for the brokering of a citizen authentication 45 and enrichment of citizen attributes. 46

This document describes the SAML Attributes to be used in conjunction with the Hub Service SAML 2.0 47 Profile. 48

1.1 Notation 49 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD 50 NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as 51 described in IETF RFC 2119 [RFC 2119]. 52

53 Schema listings appear like this.

54 Example code listings appear like this.

55 56


2 SAML Attributes 57 This section details the Matching Dataset attributes and mandatory attributes supported by this profile for 58 the expressing of data related to the SAML assertion subject. 59

2.1 Required Information 60

Identification: http://www.cabinetoffice.gov.uk/resource-library/ida/attributes (this corresponds to the 61 target namespace specified in the schema in section 2.4) 62

2.2 SAML Attribute Naming 63

The NameFormat XML attribute in <Attribute> elements MUST be 64 urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified unless otherwise specified in 65 the schema. 66

The XML attribute Name value MUST be one of the descriptors defined in section 2.4. 67

The optional XML attribute FriendlyName value, if present, MUST be one of the friendly descriptors 68 associated with the Name descriptor. Examples are included later in this document for clarity. 69

2.2.1 Attribute Name Comparison 70

<Attribute> elements refer to the same SAML attribute if and only if the Name XML attribute values are 71 equal. 72

2.3 Profile-Specific XML Attributes 73

This following profile-specific XML attributes MAY be specified for an <AttributeValue> element as 74 specified in the schema in section 2.4: 75

• From, a date constructed in accordance with the W3C Date and Time Formats Specification at 76 http://www.w3.org/TR/NOTE-datetime. 77

• To, a date constructed in accordance with the W3C Date and Time Formats Specification at 78 http://www.w3.org/TR/NOTE-datetime 79

• Language, represents natural language identifiers as defined by [RFC 3066] with a default of 80 “en-GB”. 81

• Order, represents the order in which an <AttributeValue> element MUST be processed 82 when multiple attribute values exist for and <Attribute>. Starting at 1 with increments of 1. 83

• Verified, denotes an <AttributeValue> as being verified or not in accordance with GPG45. 84

2.4 SAML Attribute Values 85

The schema type of the contents of the <AttributeValue> element MUST be drawn from one of the 86 types specified below. The xsi:type attribute MUST be present and be given the appropriate value. 87

88 The following schema defines the XML attributes and complex types supported by this profile: 89 90

91 <xs:schema 92 xmlns:xs="http://www.w3.org/2001/XMLSchema" 93 xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" 94 xmlns="http://www.cabinetoffice.gov.uk/resource-95 library/ida/attributes" 96 elementFormDefault="qualified" 97 attributeFormDefault="qualified" 98 blockDefault="substitution" 99 targetNamespace="http://www.cabinetoffice.gov.uk/resource-100 library/ida/attributes"> 101


<xs:annotation> 102 <xs:documentation> 103 </xs:documentation> 104 </xs:annotation> 105 106 <xs:attribute name="From" type="FormattedDateType"/> 107 <xs:attribute name="To" type="FormattedDateType"/> 108 <xs:attribute name="Language" type="xs:language" default="en-GB"/> 109 <xs:attribute name="Order" type="xs:integer"/> 110 <xs:attribute name="Verified" type="xs:boolean" default="false"/> 111 112 <xs:complexType name="AddressType"> 113 <xs:annotation> 114 <xs:documentation>A FormattedAddressType 115 </xs:documentation> 116 </xs:annotation> 117 <xs:complexContent> 118 <xs:extension base="FormattedAddressType"> 119 <xs:attribute ref="Language"/> 120 <xs:attribute ref="From"/> 121 <xs:attribute ref="To"/> 122 <xs:attribute ref="Verified"/> 123 </xs:extension> 124 </xs:complexContent> 125 </xs:complexType> 126 127 <xs:complexType name="FormattedAddressType" mixed="true"> 128 <xs:sequence> 129 <xs:element name="Line" type="AddressLineType" minOccurs="1" 130 maxOccurs="5"/> 131 <xs:element name="PostCode" type="PostCodeType" 132 minOccurs="0"/> 133 <xs:element name="InternationalPostCode" 134 type="InternationalPostCodeType" 135 minOccurs="0"/> 136 <xs:element name="UPRN" type="UPRNType" minOccurs="0"/> 137 </xs:sequence> 138 </xs:complexType> 139 140 <xs:simpleType name="AddressLineType"> 141 <xs:annotation> 142 <xs:documentation>A FormattedStringType restricted in length 143 </xs:documentation> 144 </xs:annotation> 145 <xs:restriction base="FormattedStringType"> 146 <xs:minLength value="1"/> 147 <xs:maxLength value="100"/> 148 </xs:restriction> 149 </xs:simpleType> 150 151 <xs:simpleType name="DateTimeType"> 152 <xs:annotation> 153 <xs:documentation>A date and time constructed in accordance 154 with the 155 W3C Date and Time Formats Specification at 156 http://www.w3.org/TR/NOTE-datetime. 157 </xs:documentation> 158 </xs:annotation> 159


<xs:restriction base="xs:string"> 160 <xs:pattern value="(\d\d\d\d)(-(\d\d)(-161 (\d\d)(T(\d\d):(\d\d)(:(\d\d)(\.\d+)?)?Z)?)?)?"/> 162 </xs:restriction> 163 </xs:simpleType> 164 165 <xs:simpleType name="FormattedDateType"> 166 <xs:annotation> 167 <xs:documentation>A date constructed in accordance with the 168 W3C Date and Time Formats Specification at 169 http://www.w3.org/TR/NOTE-datetime. 170 </xs:documentation> 171 </xs:annotation> 172 <xs:restriction base="xs:string"> 173 <xs:pattern value="(\d\d\d\d)(-(\d\d)(-(\d\d))?)?"/> 174 </xs:restriction> 175 </xs:simpleType> 176 177 <xs:complexType name="DateType"> 178 <xs:annotation> 179 <xs:documentation>A FormattedDateType e.g. DoB 180 </xs:documentation> 181 </xs:annotation> 182 <xs:simpleContent> 183 <xs:extension base="FormattedDateType"> 184 <xs:attribute ref="From"/> 185 <xs:attribute ref="To"/> 186 <xs:attribute ref="Verified"/> 187 </xs:extension> 188 </xs:simpleContent> 189 </xs:complexType> 190 191 <xs:simpleType name="EmailAddressType"> 192 <xs:annotation> 193 <xs:documentation>Base email address type 194 </xs:documentation> 195 </xs:annotation> 196 <xs:restriction base="xs:string"> 197 <xs:minLength value="3"/> 198 <xs:maxLength value="254"/> 199 </xs:restriction> 200 </xs:simpleType> 201 202 <xs:simpleType name="FormattedStringType"> 203 <xs:annotation> 204 <xs:documentation>Base type for string use 205 </xs:documentation> 206 </xs:annotation> 207 <xs:restriction base="xs:string"> 208 <xs:minLength value="0"/> 209 <xs:maxLength value="512"/> 210 </xs:restriction> 211 </xs:simpleType> 212 213 <xs:simpleType name="SimpleGenderType"> 214 <xs:restriction base="xs:string"> 215 <xs:enumeration value="Male"/> 216 <xs:enumeration value="Female"/> 217


<xs:enumeration value="Not Specified"/> 218 </xs:restriction> 219 </xs:simpleType> 220 221 <xs:complexType name="GenderType"> 222 <xs:annotation> 223 <xs:documentation>A SimpleGenderType 224 </xs:documentation> 225 </xs:annotation> 226 <xs:simpleContent> 227 <xs:extension base="SimpleGenderType"> 228 <xs:attribute ref="From"/> 229 <xs:attribute ref="To"/> 230 <xs:attribute ref="Verified"/> 231 </xs:extension> 232 </xs:simpleContent> 233 </xs:complexType> 234 235 <xs:simpleType name="PostCodeType"> 236 <xs:annotation> 237 <xs:documentation>Type derived from xs:string with a pattern 238 restriction to UK Post Codes 239 </xs:documentation> 240 </xs:annotation> 241 <xs:restriction base="xs:string"> 242 <xs:pattern 243 value="[A-Z]{1,2}[0-9R][0-9A-Z]? [0-9][A-Z-244 [CIKMOV]]{2}"/> 245 </xs:restriction> 246 </xs:simpleType> 247 248 <xs:simpleType name="InternationalPostCodeType"> 249 <xs:annotation> 250 <xs:documentation>Type derived from xs:string representing an 251 international postal code 252 </xs:documentation> 253 </xs:annotation> 254 <xs:restriction base="xs:string"> 255 <xs:minLength value="1"/> 256 <xs:maxLength value="20"/> 257 </xs:restriction> 258 </xs:simpleType> 259 260 <xs:simpleType name="UPRNType"> 261 <xs:annotation> 262 <xs:documentation>Type derived from xs:string representing a 263 UPRN 264 </xs:documentation> 265 </xs:annotation> 266 <xs:restriction base="xs:string"> 267 <xs:minLength value="1"/> 268 <xs:maxLength value="12"/> 269 </xs:restriction> 270 </xs:simpleType> 271 272 <xs:simpleType name="IPAddressType"> 273 <xs:annotation> 274 <xs:documentation>Simple IP Address type 275


</xs:documentation> 276 </xs:annotation> 277 <xs:restriction base="xs:string"> 278 <xs:minLength value="7"/> 279 <xs:maxLength value="128"/> 280 </xs:restriction> 281 </xs:simpleType> 282 283 <xs:simpleType name="GPG45StatusType"> 284 <xs:annotation> 285 <xs:documentation>GPG45 Status code, see latest version of 286 GPG45 and the operations manual for required values 287 </xs:documentation> 288 </xs:annotation> 289 <xs:restriction base="xs:string"> 290 <xs:minLength value="4"/> 291 <xs:maxLength value="8"/> 292 </xs:restriction> 293 </xs:simpleType> 294 295 <xs:simpleType name="IDPFraudEventIDType"> 296 <xs:annotation> 297 <xs:documentation>Unique fraud event ID 298 </xs:documentation> 299 </xs:annotation> 300 <xs:restriction base="xs:string"> 301 <xs:minLength value="12"/> 302 <xs:maxLength value="100"/> 303 </xs:restriction> 304 </xs:simpleType> 305 306 <xs:complexType name="PersonNameType"> 307 <xs:annotation> 308 <xs:documentation>A FormattedStringType restricted in length 309 </xs:documentation> 310 </xs:annotation> 311 <xs:simpleContent> 312 <xs:extension base="FormattedStringType100"> 313 <xs:attribute ref="Language"/> 314 <xs:attribute ref="From"/> 315 <xs:attribute ref="To"/> 316 <xs:attribute ref="Order"/> 317 <xs:attribute ref="Verified"/> 318 </xs:extension> 319 </xs:simpleContent> 320 </xs:complexType> 321 322 <xs:simpleType name="FormattedStringType100"> 323 <xs:restriction base="FormattedStringType"> 324 <xs:minLength value="1"/> 325 <xs:maxLength value="100"/> 326 </xs:restriction> 327 </xs:simpleType> 328 329 </xs:schema> 330

331


2.5 Matching Dataset Attribute Definitions 332

2.5.1 Firstname 333

This value represents the SAML assertion subject’s first name and any historic values for the subject’s 334 first name as known to the asserting entity. 335

Name: MDS_firstname 336

One or more <AttributeValue> elements each containing a PersonNameType as specified in the 337 profile-specific schema in section 2.4. 338 339

<saml:Attribute FriendlyName="Firstname" Name="MDS_firstname" 340 NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> 341 <saml:AttributeValue ida:Language="en-GB" 342 xsi:type="ida:PersonNameType">John</saml:AttributeValue> 343 </saml:Attribute> 344

Fig, 2.5.1.1 Firstname provided without attribute history 345 346 Attribute values describing history of Firstname should be identified by the inclusion of the profile specific 347 From and To attributes as can be seen in the following example. 348 349

<saml:Attribute FriendlyName="Firstname" Name="MDS_firstname" 350 NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> 351 <saml:AttributeValue ida:Language="en-GB" 352 xsi:type="ida:PersonNameType">John</saml:AttributeValue> 353 <saml:AttributeValue ida:Language="en-GB" 354 ida:From="1969-01-11" ida:To="2000-01-11" 355 xsi:type="ida:PersonNameType">Johnathan</saml:AttributeValue> 356 </saml:Attribute> 357

Fig. 2.5.1.2 Firstname and history of Firstname 358

2.5.2 Surname 359

This value represents the SAML assertion subject’s surname and any historic values for the subject’s 360 surname as known to the asserting entity. 361

Name: MDS_surname 362

One or more <AttributeValue> elements each containing a PersonNameType as specified in the 363 profile-specific schema in section 2.4. 364 Attribute values describing history of Surname should be identified by the inclusion of the profile specific 365 From and To attributes. 366 367

<saml:Attribute FriendlyName="Surname" Name="MDS_surname" 368 NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> 369 <saml:AttributeValue ida:Language="en-GB" 370 xsi:type="ida:PersonNameType">Doe</saml:AttributeValue> 371 </saml:Attribute> 372

373

2.5.3 Middle Name(s) 374

This value represents the SAML assertion subject’s middle name(s) and any historic values for the 375 subject’s middle name(s) as known to the asserting entity. 376

Name: MDS_middlename 377

One or more <AttributeValue> elements each containing a PersonNameType as specified in the 378 profile-specific schema in section 2.4. Where there are multiple middle names for the individual these 379 should be separated by a space as shown in the example below. 380


381 <saml:Attribute FriendlyName="Middlename(s)" Name="MDS_middlename" 382 NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> 383 <saml:AttributeValue ida:Language="en-GB" 384 xsi:type="ida:PersonNameType">Mark David</saml:AttributeValue> 385 </saml:Attribute> 386

387 Attribute values describing history of Middle Name(s) should be identified by the inclusion of the profile 388 specific From and To attributes. 389

2.5.4 Date of Birth 390

This value represents the SAML assertion subject’s date of birth and any historic values for the subject’s 391 date of birth as known to the asserting entity. 392

Name: MDS_dateofbirth 393

One or more <AttributeValue> elements each containing a DateType as specified in the profile-394 specific schema in section 2.4. 395 396

<saml:Attribute FriendlyName="Date of Birth" Name="MDS_dateofbirth" 397 NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> 398 <saml:AttributeValue xsi:type="ida:DateType">1994-11-399 05</saml:AttributeValue> 400

</saml:Attribute> 401 402 Attribute values describing history of date of birth should be identified by the inclusion of the profile 403 specific From and To attributes. 404

2.5.5 Gender 405

This value represents the SAML assertion subject’s gender. 406

Name: MDS_gender 407

A single <AttributeValue> element containing a GenderType as specified in the profile-specific 408 schema in section 2.41. 409 410

<saml:Attribute FriendlyName="Gender" Name="MDS_gender" 411 NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> 412 <saml:AttributeValue xsi:type="ida:GenderType"> 413 Male 414 </saml:AttributeValue> 415

</saml:Attribute> 416 417

2.5.6 Current Address 418

This value represents the SAML assertion subject’s current address. 419

Name: MDS_currentaddress 420

One or more <AttributeValue> elements each containing an AddressType as specified in the 421 profile-specific schema in section 2.4. 422 423

<saml:Attribute FriendlyName="Current Address" Name="MDS_currentaddress" 424 NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> 425 <saml:AttributeValue ida:From="1969-01-11" ida:Language="en-426 GB" xsi:type="ida:AddressType"> 427 <ida:Line>1 Cherry Cottage</ida:Line> 428

1 In version 1.2 of the profile history of gender MUST NOT be sent by an asserting entity


<ida:Line>Wurpel Lane</ida:Line> 429 <ida:Line>Reading</ida:Line> 430 <ida:PostCode>RG99 1YY</ida:PostCode> 431 </saml:AttributeValue> 432

</saml:Attribute> 433 434 Optionally the UPRN (Unique Property Reference Number) may also be included in the subject’s address 435 details to uniquely identify the address and therefore aid matching where a local data set also includes 436 UPRN. UPRNs are integers that can be up to 12 digits in length; they can therefore be less than 12 digits 437 long and do not require leading zeros. 438 439 If a non-UK address is represented the <InternationalPostCode> element MUST be used instead of 440 the UK-centric <PostCode> element. 441 442

2.5.7 Previous Address 443

This value represents the SAML assertion subject’s previous address or addresses as known to the 444 asserting entity. 445

Name: MDS_previousaddress 446

One or more <AttributeValue> elements each containing an AddressType as specified in the 447 profile-specific schema in section 2.4. 448 449

<saml:Attribute FriendlyName="Previous Address" Name="MDS_previousaddress" 450 NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> 451 <saml:AttributeValue ida:From="1969-01-11" ida:To="2000-01-11" 452 ida:Language="en-GB" xsi:type="ida:AddressType"> 453 <ida:Line>1 Cherry Cottage</ida:Line> 454 <ida:Line>Wurpel Lane</ida:Line> 455 <ida:Line>Reading</ida:Line> 456 <ida:PostCode>RG99 1YY</ida:PostCode> 457 </saml:AttributeValue> 458

</saml:Attribute> 459 460

2.6 Authentication Event Assertion Attribute Definitions 461

The Authentication Event Assertion, as described in the SAML Profile, provides the IDA service with 462 additional contextual information regarding the authentication event to be used for transactional 463 monitoring purposes. In the case of version 1.2 of the SAML Profile this contextual information is to be 464 initially limited to IP Address (of the user-agent used for authentication) and the level of assurance 465 achieved (as returned within the <AuthnContext>). Additional attribute definitions will be added during 466 the lifetime of this profile following elaboration with Identity Providers and Service Providers. 467

2.6.1 IPAddress 468

This value represents the IP Address as used by the user-agent when authenticating the principal. 469

Name: TXN_IPaddress 470

The single <AttributeValue> element contains a IPAddressType as specified in the profile-specific 471 schema in section 2.4. 472 473

<saml:Attribute FriendlyName="IPAddress" Name="TXN_IPaddress" 474 NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> 475 <saml:AttributeValue 476 xsi:type="ida:IPAddressType">10.168.8.2</saml:AttributeValue> 477 </saml:Attribute> 478

479


2.7 Fraud Event Contextual Information Assertion Attribute Definitions 480

The Fraud Event Contextual Information Assertion, as described in the SAML Profile, provides the IDA 481 service with additional contextual information regarding a fraud event. 482

2.7.1 GPG45Status 483

This value represents the resulting status of the GPG45 IPV process where fraudulent activity has been 484 identified by the identity provider. 485

Name: FECI_GPG45Status 486

The single <AttributeValue> element contains a GPG45StatusType as specified in the profile-487 specific schema in section 2.4. Note that the latest values for the GPG45 status attribute value 488 should be sourced from the IPV Operations Manual the example below is indicative only. IDPs 489 should return the “SAML Response – Fraud Warning Code” in this status field as specified in the IPV 490 Operations Manual. 491 492

<saml:Attribute FriendlyName="GPG45Status" Name="FECI_GPG45Status" 493 NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> 494 <saml:AttributeValue 495 xsi:type="ida:GPG45StatusType">FI01</saml:AttributeValue> 496 </saml:Attribute> 497

498

2.7.2 IDPFraudEventID 499

This value represents the unique IDP specific fraud event reference code. 500

Name: FECI_IDPFraudEventID 501

The single <AttributeValue> element contains a IDPFraudEventIDType as specified in the profile-502 specific schema in section 2.4. 503 504

<saml:Attribute FriendlyName="IDPFraudEventID" Name="FECI_IDPFraudEventID" 505 NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> 506 <saml:AttributeValue 507 xsi:type="ida:IDPFraudEventType">XYZ001975435</saml:AttributeValue> 508 </saml:Attribute> 509

510

Identity Assurance Hub Service Profile - SAML Attributes v1.2a

Documents

Transcript of Identity Assurance Hub Service Profile - SAML Attributes v1.2a