RFC 7056

Name Attributes for the GSS-API Extensible Authentication Protocol (EAP) Mechanism

📅 published December 2013, from ietf

RFC 7056: Name Attributes for the GSS-API Extensible Authentication Protocol (EAP) Mechanism 💖

  • RFC number: 7056 🎀
  • Published by: Internet Engineering Task Force (IETF) 🌸
  • Category: Standards Track, so it's an Internet Standards Track document ⭐
  • Date: December 2013 🦋
  • Authors: S. Hartman (Painless Security) and J. Howlett (JANET(UK)) 👑
  • ISSN: 2070-1721
  • Obsoletes / updates: the title block doesn't list anything this one obsoletes or updates 🧚

Abstract

okay so the naming extensions to the Generic Security Service Application Programming Interface (GSS-API) give apps a way to find out the authorization and personalization info tied to GSS-API names 🔥 the Extensible Authentication Protocol GSS-API mechanism lets an Authentication, Authorization, and Accounting (AAA) peer send authorization attributes along with an authentication response 💅 it also has tools for processing Security Assertion Markup Language (SAML) messages that show up in that AAA response 🫶 this document explains how to use the Naming Extensions API to get at all of that info ✨

Status of This Memo

this is an Internet Standards Track document 🌈

it's a product of the Internet Engineering Task Force (IETF) and it represents the consensus of the IETF community 🫶 it went through public review and was approved for publication by the Internet Engineering Steering Group (IESG) 👑 for more on Internet Standards, check out Section 2 of RFC 5741 🎀

for the current status, any errata, and how to send feedback, go to http://www.rfc-editor.org/info/rfc7056 💖

Copyright (c) 2013 IETF Trust and the persons identified as the document authors. All rights reserved. 🌸

this document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they stand on the publication date 📜 please actually read these, because they spell out your rights and restrictions 🙈 any Code Components pulled out of this document have to include the Simplified BSD License text described in Section 4.e of the Trust Legal Provisions, and they come without warranty as described in the Simplified BSD License 💜

Table of Contents

1. Introduction ....................................................3
2. Requirements Notation ...........................................3
3. Naming Extensions and SAML ......................................3
4. Federated Context ...............................................4
5. Name Attributes for GSS-EAP .....................................5
6. Names of SAML Attributes in the Federated Context ...............6
   6.1. Assertions .................................................6
   6.2. SAML Attributes ............................................6
   6.3. SAML Name Identifiers ......................................7
7. Security Considerations .........................................8
8. IANA Considerations .............................................8
   8.1. Registration of the GSS URN Namespace ......................9
9. Acknowledgements ................................................9
10. References ....................................................10
   10.1. Normative References .....................................10
   10.2. Informative References ...................................11

1. Introduction ✨

the naming extensions [RFC6680] to the Generic Security Service Application Programming Interface (GSS-API) [RFC2743] are the mechanism that lets apps find out the authorization and personalization info linked to GSS-API names 💅 the Extensible Authentication Protocol GSS-API mechanism [RFC7055] lets an Authentication, Authorization, and Accounting (AAA) peer send authorization attributes alongside an authentication response 🦋 it also has ways to process Security Assertion Markup Language (SAML) messages that come in the AAA response 🔥 other mechanisms like SAML Enhanced Client (EC) [SASL-SAML] also support SAML assertions and attributes carried in the GSS-API, so that's a whole vibe 🌈 this document tells you how to use the Naming Extensions API to get all of that info 🧚

the semantics of setting attributes defined in this specification are undefined and left to future work 🙈 so that part's just vibes for now 💀

2. Requirements Notation 💜

the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document get read the way [RFC2119] describes 📜 these are the official capitalized requirement words, so keep an eye out for them 👀

3. Naming Extensions and SAML 🎀

SAML assertions can carry attributes that describe properties of the assertion's subject 💖 for example, an assertion might carry an attribute about someone's organizational affiliation or email address 🌸 according to Sections 8.2 and 2.7.3.1 of [OASIS], an attribute name has two parts 🫶 the first is a Universal Resource Identifier (URI) that describes the format of the name 🦋 the second part is the actual name, and its form depends on that format URI 🔥 GSS-API name attributes can take a form that starts with a URI describing the form of the name, and the rest of the name is specified by that URI ✨

SAML attributes carried in GSS-API names have three parts, which is giving very structured energy 💅 the first is a Universal Resource Name (URN) saying that the name is a SAML attribute and describing the context (Section 4) 👑 then comes a space, the URI for the format of the SAML name, another space, and finally the SAML attribute name 🌈 the URI for the format of the SAML attribute name is not optional, and it MUST be present 🔥 no skipping it, bestie 🙅

SAML attribute names might not be globally unique 🧚 lots of names that use URNs or URIs probably have semantics that don't depend on the issuer 🌸 but other name formats, including unspecified ones, make it super easy for two issuers to pick the same name for attributes that mean different things 💀 attributes in the federated context (Section 4) are issued by the same party that does the authentication 🫶 so based on who the subject of the name is, you can figure out what the attribute means ✨

4. Federated Context 🌈

GSS-API naming extensions have the concept of an authenticated name attribute 💖 the mechanism guarantees that what's in an authenticated name attribute is an authenticated statement from the trusted source of the peer credential 🦋 but the fact that an attribute is authenticated doesn't mean the trusted source of the peer credential is authorized to assert that attribute 👀 that distinction is important, babe 💅

in the federated context, the trusted source of the peer credential is usually some identity provider 🎀 in the GSS EAP mechanism, info gets combined from AAA and SAML sources 🔥 the SAML Identity Provider (IdP) and the home AAA server are assumed to be in the same trust domain 🫶 but that trust domain usually isn't the same as the service's trust domain 🙈 with other SAML mechanisms that use this specification, the SAML assertion also comes from the party doing the authentication 🧚 and typically the IdP is run by another organization in the same federation 👑

the IdP is trusted to make some statements, especially ones about the context of a federation 💜 for example, participants in an academic federation would usually trust an IdP's assertions about whether someone is a student or a professor 🎓 but that same IdP wouldn't usually be trusted to make assertions about local entitlements like group membership 🙅 so a service MUST make a policy decision about whether the IdP is allowed to assert a particular attribute, and about whether the asserted value is acceptable 🔥 that policy can be set up as local configuration on the service, as rules in AAA proxies, or through other deployment-specific mechanisms 🌸

in contrast, attributes in an enterprise context are often verified by a central authentication infrastructure that's trusted to assert most or all attributes 💅 for example, in a Kerberos infrastructure, the Key Distribution Center (KDC) usually tells servers about a client's group membership using KDC-authenticated authorization data 🦋

the context of an attribute is a super important property of that attribute, and trust context is a big part of that overall context 👑 so, for applications to tell attribute contexts apart, attributes with different contexts need different names 🫶 this specification defines attribute names for SAML and AAA attributes in the federated context ✨

these names MUST NOT be used for attributes issued by a party other than one closely associated with the source of credentials, unless the source of credentials is re-asserting the attributes 🙅💀 for example, a source of credentials can check whatever attribute sources it wants, but acceptors can assume attributes in the federated context come from the source of credentials 🧚 this requirement is usually enforced in mechanism specifications 🎀 for example, [AAA-SAML] gives enough info that we know the attributes it carries today are in the federated context 🌈 and similarly, we know the requirements of this paragraph are met by SAML mechanisms where the assertion is the means of authentication 💖

5. Name Attributes for GSS-EAP ✨

okay so this section is all about how RADIUS attributes get named when they come back in an access-accept message from the GSS-EAP [RFC7055] mechanism 🎀 the attributes here are only for that one message, and using them in other RADIUS messages or before access-accept is undefined for now 🙈 future specs can explore that stuff as long as they keep backward compatibility in mind 🫶 the big thing is that this spec says what these attributes mean for the src_name output of GSS_Accept_sec_context once it returns GSS_S_COMPLETE 💅 attributes MAY be absent, and values MAY change in other circumstances, and future specifications MAY define that behavior 🦋

the name starts with urn:ietf:params:gss:radius-attribute (basically a URN saying "this is a GSS-EAP RADIUS AVP" 💖) then a space, then a numeric RADIUS name like in Section 2.7 of [RFC6929] ✨ so the User-Name attribute is "urn:ietf:params:gss:radius-attribute 1" 🎀 and extended type 1 inside type 241 would be "urn:ietf:params:gss:radius-attribute 241.1" 🌸

here's a super typical case 👑 the RADIUS access-accept has the User-Name attribute in it. an app that wants that value would first wait until GSS-_Accept_sec_context returns GSS_S_COMPLETE 🥹 then it takes the src_name output from GSS_Accept_sec_context and calls GSS_Get_name_attribute with that name and the attribute "urn:ietf:params:gss:radius-attribute 1" as inputs 💅 once it confirms the authenticated boolean output is true, the username is sitting right there in the values output 🍓

the value of a RADIUS attribute is the raw octets of the packet, and integers are in network byte order 🧚 the display value SHOULD be a human-readable string 💜 the catch is the implementation can only make that string if it knows the type of that RADIUS attribute 😭 if there are multiple attributes with the same name in one RADIUS message, a multi-valued GSS-API attribute SHOULD be returned 🌈 the exception (lowkey important!) is that implementations SHOULD concatenate things like EAP message or the big multi-attribute ones from [RFC6929] that carry more than 253 octets of info 🔥

6. Names of SAML Attributes in the Federated Context ✨

6.1. Assertions

an assertion made by the credential source is named "urn:ietf:params:gss:federated-saml-assertion" 💖 its value is the assertion carried in the AAA protocol or used for auth in a SAML mechanism 🦋 this attribute is absent from a given acceptor name if there's no assertion or if the assertion fails local policy checks 🙈

when GSS_Get_name_attribute gets called, this attribute comes back with authenticated set to true ONLY if the mechanism can actually authenticate the SAML statement 💅 for GSS-EAP that's true when the AAA exchange has successfully authenticated 🎀 but uses of the GSS-API MUST confirm the attribute is marked authenticated, since other mechanisms MAY let an initiator give an unauthenticated SAML statement 😭

mechanisms MAY do extra local policy checks and MAY remove the attribute for assertions that fail those checks ✨

6.2. SAML Attributes

each attribute in the assertion SHOULD also be a GSS name attribute 🌸 this name has three parts, separated by ASCII spaces 🫶 the first part is urn:ietf:params:gss:federated-saml-attribute 💜 the second part is the URI from the <saml:Attribute> element's NameFormat XML attribute 🧚 the last part is the Name XML attribute from that same element 🍓 the SAML attribute name itself can have spaces in it too 🙈 and as the URI spec [RFC3986] requires, spaces inside a URI get encoded as "%20" 💅 those encoded spaces (even in the first or second part) do NOT split the GSS-API attribute name, because they're just part of the URI 🦋

here's the example 👑 if the eduPersonEntitlement attribute is in an assertion, you could get back this name from GSS_Inquire_Name:

urn:ietf:params:gss:federated-saml-attribute
urn:oasis:names:tc:SAML:2.0:attrname-format:uri
urn:oid:1.3.6.1.4.1.5923.1.1.1.7

if an app calls GSS_Get_name_attribute with that attribute in the attr parameter, the values output will include one or more entitlement URIs tied to the authenticated user 🎀

if the content of each <saml:AttributeValue> element is a simple text node (or nodes), then the raw AND "display" values of the GSS name attribute MUST be the text content of those elements 🌈 the raw value MUST be encoded as UTF-8 🔥

if the value isn't simple or it's empty, then the raw value(s) MUST be a namespace well-formed serialization [XMLNS] of the <saml:AttributeValue> element(s), encoded as UTF-8 💖 the "display" values are implementation defined 🧚

these attributes SHOULD be marked authenticated when they're in SAML assertions that have been successfully validated back to the trusted source of the peer credential 💜 in GSS-EAP, a SAML assertion carried in an integrity-protected and authenticated AAA protocol SHALL be successfully validated, and attributes from that assertion SHALL be returned from GSS_Get_name_attribute with authenticated set to true 😭 an implementation MAY apply local policy checks to each attribute in that assertion and throw out any attribute that doesn't pass 🥹

6.3. SAML Name Identifiers

the <saml:NameID> in the assertion's subject SHOULD also be a GSS name attribute 🌸 this name has two parts, separated by an ASCII space 💅 the first part is urn:ietf:params:gss:federated-saml-nameid 🎀 the second part is the URI from the <saml:NameID> element's Format XML attribute 🦋

the raw value of the GSS name attribute MUST be the well-formed serialization of the <saml:NameID> element, encoded as UTF-8 ✨ the "display" value is implementation defined 🫶 for formats defined by Section 8.3 of [OASIS], missing NameQualifier or SPNameQualifier XML attribute values MUST be filled in according to the format's definition BEFORE serialization 💀 in other words, the defaulting rules for the "persistent" and "transient" formats MUST be applied before serialization happens 🔥

this attribute SHOULD be marked authenticated if the name identifier is in a SAML assertion that's been successfully validated back to the trusted source of the peer credential 💖 in GSS-EAP, a SAML assertion carried in an integrity-protected and authenticated AAA protocol SHALL be sufficiently validated 🌈 an implementation MAY apply local policy checks to this assertion and discard it if it's unacceptable under those checks 🧚

7. Security Considerations 🔒💀

this document describes how to access RADIUS attributes, SAML attributes, and SAML assertions from some GSS-API mechanisms 🍓 these attributes are typically used for one of two things 👑 the least sensitive one is personalization: a central service MAY provide info about an authenticated user so they don't have to type it in for every acceptor they hit 🫶 the more sensitive use is authorization, and that one is serious business 😭

the mechanism is responsible for authentication and integrity protection of the attributes 💅 but the acceptor application is responsible for deciding whether the credential source is trusted to assert the attribute, and for validating the asserted value 🎀 mechanisms are allowed to do local policy checks on SAML assertions, attributes, and name identifiers exposed through the name attributes defined here 🦋 if there's another way to reach the SAML assertion (like the mechanism in [AAA-SAML]), an application MAY get different results depending on how the SAML is accessed 🙈 this is intended behavior, and apps that choose to bypass local policy checks SHOULD do their own evaluation before relying on the info 🌈💖

8. IANA Considerations ✨

a new top-level registry has been created called "Generic Security Service Application Program Interface Parameters" 🎀 inside it, a subregistry called "GSS-API URN Parameters" was created 🌸 registration in this registry is by the IETF Review or Expert Review procedures [RFC5226] 💜

this paragraph is guidance for Designated Experts 🧚 registrations here are generally only expected as part of protocols published as RFCs on the IETF stream, since other URIs are better choices for non-IETF work 🫶 Expert Review is mainly there to allow early registration for specs under development, once the community thinks they're mature enough 🥹 the expert SHOULD evaluate the maturity and stability of such an IETF-stream spec 🔥 experts SHOULD review anything NOT from the IETF stream for consistency and consensus with current practice 💅 and honestly? today, those requests typically wouldn't get approved 😭

if the "paramname" parameter is registered in this registry, its URN will be "urn:ietf:params:gss:paramname" 🍓 the initial registrations are below 👇

+--------------------------+-------------+
| Parameter                | Reference   |
+--------------------------+-------------+
| radius-attribute         | Section 5   |
| federated-saml-assertion | Section 6.1 |
| federated-saml-attribute | Section 6.2 |
| federated-saml-nameid    | Section 6.3 |
+--------------------------+-------------+

8.1. Registration of the GSS URN Namespace

IANA has registered the "gss" URN sub-namespace in the IETF URN sub-namespace for protocol parameters defined in [RFC3553] 🌈✨

Registry Name: gss
Specification: RFC 7056
Repository: GSS-API URN Parameters (Section 8)
Index Value: Sub-parameters MUST be specified in UTF-8 using standard
URI encoding where necessary.

the index value is the key part here 💖 sub-parameters MUST be specified in UTF-8, using standard URI encoding where it's needed 🧚

9. Acknowledgements 🫶

Scott Cantor contributed significant text and multiple reviews of this document 👑

the authors would like to thank Stephen Farrell, Luke Howard, and Jim Schaad 💜

Sam Hartman's work on this specification has been funded by Janet 🌸

10. References 📚

10.1. Normative References

okay these are the ones you HAVE to read before you touch the spec 📚✨ no skipping bestie, they're load-bearing 🫶

[OASIS]     Cantor, S., Kemp, J., Philpott, R., and E. Maler,
            "Assertions and Protocol for the OASIS Security Assertion
            Markup Language (SAML) V2.0", OASIS Standard
            saml-core-2.0-os, March 2005.

[RFC2119]   Bradner, S., "Key words for use in RFCs to Indicate
            Requirement Levels", BCP 14, RFC 2119, March 1997.

[RFC2743]   Linn, J., "Generic Security Service Application Program
            Interface Version 2, Update 1", RFC 2743, January 2000.

[RFC3553]   Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An
            IETF URN Sub-namespace for Registered Protocol
            Parameters", BCP 73, RFC 3553, June 2003.

[RFC5226]   Narten, T. and H. Alvestrand, "Guidelines for Writing an
            IANA Considerations Section in RFCs", BCP 26, RFC 5226,
            May 2008.

[RFC6680]   Williams, N., Johansson, L., Hartman, S., and S.
            Josefsson, "Generic Security Service Application
            Programming Interface (GSS-API) Naming Extensions", RFC
            6680, August 2012.

[RFC6929]   DeKok, A. and A. Lior, "Remote Authentication Dial In
            User Service (RADIUS) Protocol Extensions", RFC 6929,
            April 2013.

[RFC7055]   Hartman, S., Ed. and J. Howlett, "A GSS-API Mechanism for
            the Extensible Authentication Protocol", RFC 7055,
            December 2013.

[XMLNS]     W3C, "XML Namespaces Conformance", 2009,
            <http://www.w3.org/TR/2009/REC-xml-names-20091208/
            #Conformance>.

10.2. Informative References

these ones are the extra reading 🌸 helpful, not required, but they're giving context and I love a good side quest 💅

[AAA-SAML]  Howlett, J. and S. Hartman, "A RADIUS Attribute, Binding,
            Profiles, Name Identifier Format, and Confirmation
            Methods for SAML", Work in Progress, July 2013.

[RFC3986]   Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
            Resource Identifier (URI): Generic Syntax", STD 66, RFC
            3986, January 2005.

[SASL-SAML] Cantor, S. and S. Josefsson, "SAML Enhanced Client SASL
            and GSS-API Mechanisms", Work in Progress, September
            2013.

Authors' Addresses 🦋

meet the people who wrote this one 🧚💖

Sam Hartman
Painless Security

EMail: hartmans-ietf@mit.edu


Josh Howlett
JANET(UK)

EMail: josh.howlett@ja.net
📦 where this page comes from