National Identity Exchange Federation REST …NIEF REST Services Profile Version 1.0 ii 6.8.2 REST...
Transcript of National Identity Exchange Federation REST …NIEF REST Services Profile Version 1.0 ii 6.8.2 REST...
NationalIdentityExchangeFederation
RESTServicesProfile
Version1.0
July31,2018
NIEF REST Services Profile Version 1.0
i
Table of Contents
TABLEOFCONTENTS I
1. TARGETAUDIENCEANDPURPOSE 3
2. NIEFIDENTITYTRUSTFRAMEWORKANDTERMINOLOGY 3
3. REFERENCES 3
4. NOTATIONFORNORMATIVECONTENT 5
5. OVERVIEW 5
6. NIEFRESTSERVICEINTERACTIONPROFILES 56.1 NIEFOPENIDCONNECTSINGLESIGN-ONSIP 56.1.1 MOTIVATINGUSECASE(NON-NORMATIVE) 66.1.2 OPENIDCONNECTRELYINGPARTYREQUIREMENTS 76.1.3 OPENIDCONNECTIDENTITYPROVIDERREQUIREMENTS 86.2 NIEFRESTCONSUMER-PROVIDERSIP 86.2.1 MOTIVATINGUSECASE(NON-NORMATIVE) 86.2.2 RESTSERVICECONSUMERREQUIREMENTS 96.2.3 RESTSERVICEPROVIDERREQUIREMENTS 96.3 NIEFRESTSINGLESIGN-ONCONSUMER-PROVIDERSIP 96.3.1 MOTIVATINGUSECASE(NON-NORMATIVE) 106.3.2 RESTSERVICECONSUMERREQUIREMENTS 116.3.3 RESTSERVICEPROVIDERREQUIREMENTS 116.4 NIEFRESTDELEGATED-CONSUMER-PROVIDERSIP 126.4.1 MOTIVATINGUSECASE(NON-NORMATIVE) 126.4.2 RESTSERVICECONSUMERREQUIREMENTS 136.4.3 RESTSERVICEPROVIDERREQUIREMENTS 146.5 NIEFRESTCONSUMER-AUTHORIZERSIP 146.5.1 MOTIVATINGUSECASE(NON-NORMATIVE) 156.5.2 RESTSERVICECONSUMERREQUIREMENTS 166.5.3 AUTHORIZATIONSERVICEREQUIREMENTS 166.5.4 RESTSERVICEPROVIDERREQUIREMENTS 166.6 NIEFRESTSINGLESIGN-ONCONSUMER-AUTHORIZERSIP 166.6.1 MOTIVATINGUSECASE(NON-NORMATIVE) 176.6.2 RESTSERVICECONSUMERREQUIREMENTS 186.6.3 AUTHORIZATIONSERVICEREQUIREMENTS 186.6.4 RESTSERVICEPROVIDERREQUIREMENTS 196.7 NIEFRESTDELEGATED-CONSUMER-AUTHORIZERSIP 196.7.1 MOTIVATINGUSECASE(NON-NORMATIVE) 196.7.2 RESTSERVICECONSUMERREQUIREMENTS 216.7.3 AUTHORIZATIONSERVICEREQUIREMENTS 226.7.4 RESTSERVICEPROVIDERREQUIREMENTS 226.8 NIEFRESTASSERTIONDELEGATESERVICESIP 226.8.1 MOTIVATINGUSECASE(NON-NORMATIVE) 22
NIEF REST Services Profile Version 1.0
ii
6.8.2 RESTSERVICECONSUMERREQUIREMENTS 246.8.3 ASSERTIONDELEGATESERVICEREQUIREMENTS 256.9 NIEFRESTATTRIBUTEPROVIDERSIP 286.9.1 MOTIVATINGUSECASE(NON-NORMATIVE) 286.9.2 ATTRIBUTECONSUMERREQUIREMENTS 306.9.3 ATTRIBUTEPROVIDERREQUIREMENTS 316.10 NIEFOPENIDCONNECTDYNAMICCLIENTREGISTRATIONSIP 326.10.1 MOTIVATINGUSECASE(NON-NORMATIVE) 326.10.2 OPENIDCONNECTRELYINGPARTYREQUIREMENTS 326.10.3 OPENIDPROVIDERREQUIREMENTS 336.11 NIEFOAUTHDYNAMICCLIENTREGISTRATIONSIP 336.11.1 MOTIVATINGUSECASE(NON-NORMATIVE) 346.11.2 OAUTHCLIENTREQUIREMENTS 346.11.3 OAUTHAUTHORIZATIONSERVERREQUIREMENTS 34
7. SUPPORTINGPROFILES 357.1 CLIENTAUTHENTICATIONREQUIREMENTSFOROAUTHTOKENENDPOINTS 357.1.1 RESTSERVICECONSUMERREQUIREMENTS 357.1.2 TOKENENDPOINTREQUIREMENTS 357.2 SAMLASSERTIONREQUIREMENTS 367.3 AUTHORIZERSIPBASEREQUIREMENTS 377.3.1 RSCREQUIREMENTS 377.3.2 ASREQUIREMENTS 377.3.3 RSPREQUIREMENTS 387.4 RESTASSERTIONDELEGATESERVICESUPPORTINGREQUIREMENTS 387.4.1 RESTADSSCOPEREQUIREMENTS 387.4.2 ADSCLAIMSOBJECTREQUIREMENTS 387.4.3 ADSAUTHORIZATIONREQUESTREQUIREMENTS 397.4.4 ADS-OOBTOKENREQUESTREQUIREMENTS 407.5 RESTATTRIBUTEPROVIDEROUT-OF-BANDACCESSTOKENREQUESTS 407.5.1 RESTAP-OOBACCESSTOKENREQUESTREQUIREMENTS 417.6 SELF-SIGNEDOAUTHACCESSTOKENPROFILE 417.6.1 MOTIVATINGUSECASE(NON-NORMATIVE) 417.6.2 SELF-ISSUEDOAUTHACCESSTOKENREQUIREMENTS 417.7 DEFINITIONOFBASEURI 427.7.1 EXAMPLES(NON-NORMATIVE) 427.8 TLSREQUIREMENTS 42
NIEF REST Services Profile Version 1.0
3
1. Target Audience and Purpose This document specifies technical interoperability requirements for connection tooperationalendpointsthatleveragetheNationalIdentityExchangeFederation(NIEF)andthatadheretotheRepresentationalStateTransfer(REST)paradigm1.Thetargetaudienceincludes technical representatives of organizations that intend to participate in NIEF asIdentity Provider Organizations (IDPOs), Service Provider Organizations (SPOs), ServiceConsumer Organizations (SCOs), Attribute Provider Organizations (APOs), or somecombinationoftheseroles.2Italsoincludesvendors,contractors,andconsultantswho,aspartoftheirprojectorproductimplementation,havearequirementtoestablishtechnicalinteroperabilitywithNIEFendpoints.This document focuses only on issues of technical interoperability. It does not covergovernance, policy, or other nontechnical interoperability requirements. For moreinformation about those topics, see [NIEF Bylaws] and [NIEF OPP]. In addition, thisdocumentfocusesonlyonRESTservices.ItdoesnotaddressSOAPWebServices;see[NIEFS2S]forSOAPWebServicesinteractionprofiles.2. NIEF Identity Trust Framework and Terminology ThisdocumentisonecomponentoftheNIEFIdentityTrustFramework.See[NIEFOPP]formoreinformationaboutthefullNIEFIdentityTrustFramework.Thisdocumentcontainslanguagethatusestechnicaltermsrelatedtofederations,identitymanagement, Web services, and other related technologies. To minimize confusion forreaders,itisimportantthateachtechnicaltermhaveaprecisedefinition.Accordingly,alltechnicaltermsinthisdocumentaretobeinterpretedasdescribedin[NIEFTerms],[OIDCCore],and[OAuthCore].3. References Table 1 and Table 2 contain a list of documents that pertain to the specifications andrequirements described in this document (including components from theNIEF IdentityAssuranceFrameworkandindustrystandards).
Document References for NIEF Identity Assurance Framework Components
Document ID Document Name and URL if Applicable NIEF Bylaws NIEF Center Bylaws NIEF OPP NIEF Center Operational Policies and Procedures NIEF S2S NIEF Web Services System-to-System Profile NIEF Terms NIEF Terminology Reference NIEF Trust NIEF Cryptographic Trust Model Table 1: Document References for NIEF Identity Assurance Framework Components
1Seehttp://en.wikipedia.org/wiki/Representational_state_transferformoreinformationaboutREST.2See[NIEFTerms]forterminologyrelatedtovariousorganizationalandtechnicalrolesinNIEF.
NIEF REST Services Profile Version 1.0
4
Document References for Industry and Government Standards Document ID Document Name and URL FIPS 140-2 Federal Information Processing Standard (FIPS) Publication 140-2, Security
Requirements for Cryptographic Modules December 3, 2002 http://csrc.nist.gov/publications/fips/fips140-2/fips1402.pdf
RFC 2119 Key Words for Use in RFCs to Indicate Requirement Levels Internet Engineering Task Force (IETF) Request for Comments (RFC) 2119 https://tools.ietf.org/html/rfc2119
OAuth Core The OAuth 2.0 Authorization Framework IETF RFC 6749 http://tools.ietf.org/html/rfc6749
OAuth Bearer The OAuth 2.0 Authorization Framework: Bearer Token Usage IETF RFC 6750 http://tools.ietf.org/html/rfc6750
JSON JavaScript Object Notation (JSON) Data Interchange Format IETF RFC 7159 http://tools.ietf.org/html/rfc7159
JWT JSON Web Token (JWT) IETF RFC 7519 https://tools.ietf.org/html/rfc7519
OAuth Assertions
Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants IETF RFC 7521 https://tools.ietf.org/html/rfc7521
OAuth SAML2 SAML 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants IETF RFC 7522 https://tools.ietf.org/html/rfc7522
OAuth JWT JWT Profile for OAuth 2.0 Client Authentication and Authorization Grants IETF RFC 7523 https://tools.ietf.org/html/rfc7523
OAuth DCR OAuth 2.0 Dynamic Client Registration Protocol IETF RFC 7591 https://tools.ietf.org/html/rfc7591
OIDC Core OpenID Connect Core 1.0 http://openid.net/specs/openid-connect-core-1_0.html
OIDC Disc OpenID Connect Discovery 1.0 http://openid.net/specs/openid-connect-discovery-1_0.html
OIDC DCR OpenID Connect Dynamic Client Registration 1.0 http://openid.net/specs/openid-connect-registration-1_0.html
SAML2 Security Assertion Markup Language, Version 2.0 http://wiki.oasis-open.org/security
SAML2 Profiles
Profiles for the OASIS Security Assertion Markup Language (SAML) Version 2.0. OASIS Standard, March 15, 2005 http://docs.oasis-open.org/security/saml/v2.0/saml-profiles-2.0-os.pdf
SAML2 Delegation
SAML 2.0 Condition for Delegation Restriction, Version 1.0 OASIS Committee Specification 01, November 15, 2009 http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-delegation-cs-01.html
SOAP W3C SOAP Note, May 8, 2000 http://www.w3.org/TR/2000/NOTE-SOAP-20000508/
RFC4648 The Base16, Base32, and Base64 Data Encodings IETF RFC 4648 https://tools.ietf.org/html/rfc4648
Table 2: Document References for Industry Standards
NIEF REST Services Profile Version 1.0
5
4. Notation for Normative Content This document contains both normative and non-normative content. Sections containingnormative content are marked appropriately. In those sections, the key words “MUST,”“MUST NOT,” “REQUIRED,” “SHALL,” “SHALL NOT,” “SHOULD,” “SHOULD NOT,”“RECOMMENDED,” “MAY,” and “OPTIONAL” are to be interpreted as described in [RFC2119]. 5. Overview ThisdocumentspecifiesserviceinteractionprofilesforsecureRepresentationalStateTransfer(REST)serviceusecases.RESTisasetofservice-orientedarchitecture(SOA)guidelines,principles,andconstraintsfordesigningservicesthatareefficient,simple,andscalable;andRESTdescribesthearchitectureoftheWorldWideWeb.Webservicesandapplicationprogramminginterfaces(APIs)towhichRESTconstraintsareappliedareoftendescribedas“RESTful”.ForamorethoroughoverviewofREST,seetheWikipediaarticleonRESTathttp://en.wikipedia.org/wiki/Representational_state_transfer.RESTisoftenpositionedincontrasttotheSimpleObjectAccessProtocol(SOAP),andwhilebothcanbeusedtospecifyWebservices,therearemanydifferencesbetweenthetwo.SOAPisastandardizedspecification,whileRESTisanarchitecturalparadigmthathasnostandardizedspecification.SOAPistransportagnosticwhileRESTassumestheuseofHTTP.TheWS-*suiteofspecificationsextendSOAPwithsecurityfeatures,whilespecificationssuchasOAuthandOpenIDConnectweredesignedtoprovideWebsecurityinaRESTfulmanner.ThisdocumentprovidesRESTfulalternativestotheSOAP-basedWebServicesinteractionprofilesdefinedin[NIEFS2S].ThisProfileisconcernedwithsecurefederatedidentityandsecureserviceinteractions.APIdesignanddatapayload-specificprotectionsareoutofscope.Notethatsincetheterm“Webservice”isoftentiedtotheuseofSOAP,thisdocumentusestheterm“RESTservice”instead.NotethatallreferencestoOAuthrefertoOAuth2.0andallreferencestoSAMLrefertoSAML2.0.6. NIEF REST Service Interaction Profiles Thissectiondefinestheserviceinteractionprofiles(SIPs)forRESTservices.6.1 NIEF OpenID Connect Single Sign-On SIP TheNIEFOpenIDConnect(OIDC)SingleSign-On(SSO)SIPprofilesandconstrainsOpenIDConnect1.0(see[OIDCCore])forimplementingRESTfulSSO.
NIEF REST Services Profile Version 1.0
6
6.1.1 Motivating Use Case (Non-Normative) ThisSIPderivesitsmotivationfromtheneedforanSSOalternativethatlendsitselftoeaseofimplementationandintegrationwithotherNIEFRESTProfiles.ThisSIPprofilestheOIDC1.0SSOprotocolsdefinedin[OIDCCore].OIDChasthreedifferentmethodsofaccomplishingSSO,calledAuthorizationCodeFlow,ImplicitFlow,andHybridFlow.IntheAuthorizationCodeFlow,theOIDCRelyingParty(RP)firstredirectstheuseragent(UA)toobtainanauthorizationcode,whichisanOAuthauthorizationgrant,fromtheIdentityProvider’s(IDP’s)AuthorizationEndpoint.TheRPthenusestheauthorizationcodetoretrieveanIDtokendirectlyfromtheIDP’sTokenEndpoint.TheRPcanalsoretrieveanOAuthaccesstokenfromtheIDP’sTokenEndpoint;thisaccesstokencanbeusedtoretrievesupplementuserattributesfromtheIDP’sUserInfoEndpoint.IntheImplicitFlow,theRPreceivesanIDtoken,andoptionallyanaccesstoken,fromtheIDP’sAuthorizationEndpoint.TheHybridFlowallowsforoptionalityinhowtheClientreceivestheIDtokenandtheaccesstoken.Ingeneral,OIDCSSOconsistsofthefollowingsteps.
1. Auserconnectshis/herUAtoanOIDCRPinordertoaccessaresourceatthatRP. The user is currently unauthenticated at the RP. The RP discovers theuser’sOIDCIDP.OIDCIDPdiscoveryisoutofscopeforthisSIP.3TheRPsendsan OIDC authentication request to the IDP by redirecting the UA with therequesttotheIDP’sAuthorizationEndpoint.
2. The Authorization Endpoint processes the request. In this step, it
authenticatestheEnd-UserandobtainsconsentfromtheuserforreleasingauserassertionabouttheEnd-UsertotheRP.ThedetailsofthisareoutofscopeofthisSIP.
3. Depending on the details in the metadata the Authorization Endpoint has
abouttheRPandintheauthenticationrequest,uponsuccessfulauthenticationandconsent,theAuthorizationEndpointreturnsanauthenticationresponsethatcontainssomecombinationofanauthorizationcode,OIDCIDtoken,andaccesstoken.AnOIDCIDtokencontainstheverifieduseridentifier,metadataabouttheauthenticationevent,andoptionally,attributesabouttheEnd-User.AnaccesstokencanbeusedbytheRPtoretrievesupplementaluserattributesfromtheIDP’sUserInfoEndpoint.
4. TheRP processes the response. In this step, if theRP received anOIDC ID
token, then it validates that token, optionally retrieves supplementalattributes,andprovidestheEnd-UserwithaccesstotherequestedresourceinaccordancewiththeRP’saccesscontrolpolicy.
3SeeSectionError!Referencesourcenotfound.forguidanceonOIDCIDPdiscovery.
NIEF REST Services Profile Version 1.0
7
5. [Optional]IftheRPreceivedanauthorizationcode,thenitusesthatcodeinatokenrequesttotheIDP’sTokenEndpointtoobtainanOIDCIDtokenand/oraccesstoken,asnecessary.
6. [Optional]TheTokenEndpointprocessesandvalidatesthetokenrequest.In
thisstep,theTokenEndpointauthenticatestheRP.
7. [Optional] The Token Endpoint returns a token response that contains anOIDCIDtoken,andifrequested,anaccesstoken.
8. [Optional] The Client processes the token response, optionally retrieves
supplemental attributes, and provides the End-User with access to therequestedresourceinaccordancewiththeRP’saccesscontrolpolicy.
Figure1depictsthisSIP.
Figure1:DiagramoftheOpenIDConnectSingleSign-OnSIP
6.1.2 OpenID Connect Relying Party Requirements
1. TheRPMUSTconformto[OIDCCore]asaRelyingParty.
NIEF REST Services Profile Version 1.0
8
2. When authenticating to the Token Endpoint of the IDP, the RP MUSTauthenticateinaccordancewithSection7.1.
6.1.3 OpenID Connect Identity Provider Requirements
1. TheOIDCIDP(IDP)MUSTconformto[OIDCCore]asanOpenIDProvider.
2. TheTokenEndpointoftheIDPMUSTauthenticatetheRPinaccordancewithSection7.1.
6.2 NIEF REST Consumer-Provider SIP TheNIEFRESTConsumer-ProviderSIPenablesaRESTServiceConsumer(RSC)toconnecttoaRESTServiceProvider(RSP)toaccessahostedresource,withoutactingdirectlyonbehalfofauser.6.2.1 Motivating Use Case (Non-Normative) ThisSIPconsistsofthefollowingsteps:
1. TheRSCsendsaresourcerequesttotheRSPoveraTLSchannelinwhichtheRSCauthenticatestheRSP.
2. TheRSPprocessestheresourcerequest.Inthisstep,theRSPauthenticatesthe
RSCandmakesanaccesscontroldecisionfortherequest.
3. TheRSPsendsaresourceresponsetotheRSC.
4. TheRSCprocessestheresourceresponse.Figure2depictsthisSIP.
NIEF REST Services Profile Version 1.0
9
Figure 2: Diagram of the REST Consumer-Provider SIP
6.2.2 REST Service Consumer Requirements
1. TheRSCMUSTcommunicatewiththeRSPviaHTTPoverTLS.
2. TheRSCMUSTauthenticatetheRSPviaitsTLSservercertificate.
3. TheRSCMUSTverifytrustintheauthenticatedRSP.
4. TheRSCMUSTauthenticatetotheRSPviaTLSclientcertificateauthentication.6.2.3 REST Service Provider Requirements
1. TheRSPMUSTexposeitsresourcesviaHTTPoverTLS.
2. TheRSPMUSTauthenticatetheRSCviaTLSclientcertificateauthentication.
3. TheRSPMUSTverifytrustintheauthenticatedRSC.6.3 NIEF REST Single Sign-On Consumer-Provider SIP TheNIEFRESTSingleSign-OnConsumer-ProviderSIPenablesaRESTServiceConsumer(RSC),whileactingonbehalfofanend-user,toconnecttoaRESTServiceProvider(RSP)toaccessahostedresource,wheretheend-userisauthenticatedviaasinglesign-onmechanism.
NIEF REST Services Profile Version 1.0
10
6.3.1 Motivating Use Case (Non-Normative) ThisSIPisusefulinscenarioswheretheRSPcanactasasinglesign-onclienttoauthenticatetheend-user,theRSPneedstoauthenticatetheRSC,andtheRSCcanactonbehalfoftheend-userbyfunctioningastheend-user’sHTTPuser-agent.In thisSIP, theRSCmusteitherdeliverauserassertiontotheRSPfromatrustedIDPordeliversessiontokensthathavebeenpreviouslyprovidedbytheRSP.TheRSPusestheuserassertionorsessiontokenstoestablishauser-authenticatedsession.WhentheRSCdeliversanewuserassertiontotheRSP,theRSPthenmaysupplynewsessiontokenstotheRSC.Inaddition,theRSPmustauthenticatetheRSCoverthissession.Then,theRSCsubmitsHTTPresource requests on behalf of the end-user over the session, and the RSP may makeauthorizationdecisionsbasedonattributesabouttheuser,RSC,andresourcerequest.ThisSIPreliesonsinglesign-on(SSO)fortheRSPtoobtaintheuserassertion.Specifically,thisSIPonlyallowstheuseoftheNIEFWebBrowserUser-to-SystemProfile(SAMLSSO),whichisdefinedin[NIEFU2S],ortheNIEFOpenIDConnect(OIDC)SSOSIP,whichisdefinedinSection6.1ofthisdocument.TheseSSOprofilesallowSP/RP-initiatedorIDP-initiatedSSOtransactions.Figure3depictstheRESTSingleSign-OnConsumer-ProviderSIP.
NIEF REST Services Profile Version 1.0
11
Figure3:DiagramoftheRESTSingleSign-OnConsumerProviderSIP
6.3.2 REST Service Consumer Requirements
1. TheRSCMUSTbeabletofacilitateatleastoneofthefollowingSSOprofilesasanHTTPuser-agent.
a. NIEFWebBrowserUser-to-SystemProfile
b. NIEFOpenIDConnectSSOSIP
2. TheRSCMUSTcommunicatewiththeRSPviaHTTPoverTLS.
3. TheRSCMUSTauthenticatetheRSPviatheRSP’sTLSservercertificate.
4. TheRSCMUSTverifytrustintheauthenticatedRSP.
5. TheRSCMUSTauthenticatetotheRSPviaTLSclientcertificateauthentication.
6.3.3 REST Service Provider Requirements
NIEF REST Services Profile Version 1.0
12
1. TheRSPMUSTmeetatleastoneofthefollowingSSOrequirements.
a. ConformtotheNIEFOpenIDConnectSSOSIPasaRelyingParty(RP).
b. ConformtotheNIEFWebBrowserUser-to-SystemProfileasaServiceProvider(SP).
2. TheRSPMUSTexposeitsresourcesviaHTTPoverTLS.
3. TheRSPMUSTauthenticatetheRSCviaTLSclientcertificateauthentication.
4. TheRSPMUSTverifytrustintheauthenticatedRSC.
5. UponinitiationofaTLSchannelwithanRSC,theRSPMUSTauthenticatetheend-
userusingoneofthefollowingmethods.
a. ConductSSOviaeithertheNIEFOpenIDConnectSSOSIPortheNIEFWebBrowserUser-to-SystemProfile.AftercompletionoftheSSOprocess,theRSPMAYsetasessioncookiewiththeRSC.
b. ReceiveasessioncookiefromtheRSCthatwaspreviouslyissuedbytheRSP.
6.4 NIEF REST Delegated-Consumer-Provider SIP TheNIEFRESTDelegated-Consumer-ProviderSIPenablesaRESTServiceConsumer(RSC),whileactingonbehalfofauser,toconnecttoaRESTServiceProvider(RSP)toaccessahostedresource,wheretheuserisidentifiedbyadelegateduserassertion.6.4.1 Motivating Use Case (Non-Normative) ThisSIP introducesauserauthenticationeventanduserassertion into theRESTservicetransaction. In this SIP, the RSC is also a Web portal, and it performs a REST servicetransactionwithanRSPonbehalfoftheuser.Itconsistsofthefollowingsteps:
1. TheRSC,actingonbehalfofauser,obtainsadelegateduserassertionfromtheuser’sIDP.ThedelegateduserassertionmustbeanOIDCIDtokenorSAMLassertion.HowthishappensisoutofscopeforthisSIP.TheRESTAssertionDelegateService(ADS)SIP,definedinSection6.8canbeusedbytheRSCtoobtainadelegateduserassertion.
2. TheRSCsendsaresourcerequesttotheRSPoveraTLSchannelinwhichthe
RSCauthenticatestheRSP.Theresourcerequestcontainsthedelegateduserassertion.
3. TheRSPprocessestheresourcerequest.Inthisstep,theRSPauthenticatesthe
RSCandmakesanaccesscontroldecisionontherequest.Thisdecisionmay
NIEF REST Services Profile Version 1.0
13
be based on attributes about theRSC and about the user identified by thedelegateduserassertion.
4. TheRSPreturnsaresourceresponsetotheRSC.
5. TheRSCprocessestheresourceresponse.
Figure4depictstheRESTDelegated-Consumer-ProviderSIP.
Figure4:DiagramoftheRESTDelegated-Consumer-ProviderSIP
6.4.2 REST Service Consumer Requirements
1. TheRSCMUSTconformto[OAuthCore]asanOAuthClient.
2. TheRSCMUSTacquireadelegateduserassertionfromatrustedIDPoftheEnd-UserthatdenotestotheRSPthattheRSCisactingonbehalfoftheEnd-User.ThisdelegateduserassertionMUSTbeeitheranOpenIDConnect(OIDC)IDtokeninaccordancewithSection2of[OIDCCore]thatissignedandserializedusingtheJWSCompactSerializationinaccordancewith[JWS],oraSAMLassertioninaccordancewithSection7.2.TheRSCisNOTrequiredtoverifythattheacquireddelegateduser
NIEF REST Services Profile Version 1.0
14
assertionconformstotheserequirements;however,theRSCMUSTensurethattheIDPthatissuestheassertionisawarethatitneedstoissueaconformingassertion.4
3. TheRSCMUSTconnecttothetargetresourceviaTLS.
4. WhenestablishingaTLSchannel,theRSCMUSTauthenticatetheRSPviatheRSP’s
TLSservercertificate.
5. TheRSCMUSTverifytrustintheRSP.
6. TheRSCMUSTusetheacquireduserassertionasabearertokenintheresourcerequestitsendstotheRSP,inaccordancewith[OAuthBearer].
6.4.3 REST Service Provider Requirements
1. TheRSPMUSTconformto[OAuthCore]asanOAuthResourceServer.
2. TheRSPMUSTexposeitsresourcesviaTLS.
3. TheRSPMUSTperformthevalidationstepsinthefollowingsub-itemsontheOAuthaccesstokenthatitreceivesfromtheRSC.
a. VerifythattheaccesstokenisavalidOAuthbeareraccesstokenasdefinedin
Section7of[OAuthCore]andin[OAuthBearer].
b. VerifythattheaccesstokenisanOIDCIDtokenasdefinedinSection2of[OIDCCore]thathasbeensignedandserializedwiththeJWSCompactSerializationinaccordancewith[JWS],oranSAMLassertionthatconformstoSection7.2.
c. Validatethedigitalsignature.
d. VerifythatthesignaturecertificateisassociatedwithatrustedIDP.
e. VerifythattheRSPisidentifiedintheaudienceofthetoken.
f. Verifythatthetimestampontheaccesstokenisnottoofarinthepast
accordingtoRSPpolicy.6.5 NIEF REST Consumer-Authorizer SIP
4TheassertionsissuedbytheIDPmaybeencryptedusinganencryptionkeyoftheRSP;inthiscase,theRSCwillnotbeableinspectthecontentsoftheassertion.TheRSCcanuseaprotocolsuchastheNIEFAssertionDelegateService(ADS)SIPtomeetthisrequirement.
NIEF REST Services Profile Version 1.0
15
TheNIEFRESTConsumer-AuthorizerSIPenablesaRESTServiceConsumer(RSC)toobtainanauthorizationtokenfromaRESTAuthorizationService(AS)tousetosubmitapre-authorizedresourcerequesttoaRESTServiceProvider(RSP),withoutactingdirectlyonbehalfofanEnd-User.6.5.1 Motivating Use Case (Non-Normative) ThisSIPaddressesascenarioinwhichtheRSPdoesnotmakeitsownauthorizationdecisions,andmustbeaccessedwithanauthorizationtokenthathasbeenissuedbyanAuthorizationService(AS).InthisSIP,theRSCisnotactingonbehalfofanEnd-User.Itconsistsofthefollowingsteps:
1. TheRSCsendsanauthorizationtokenrequesttotheASoveraTLSchannelinwhichtheRSCauthenticatestheAS.TheauthorizationtokenrequestidentifiesthetargetRSPandmaycontaininformationabouttherequestedaccessintheOAuth“scope”parameter.
2. The AS processes the authorization token request. In this step, the AS
authenticatestheRSC.Also,theASusesinformationintheauthorizationtokenrequesttomakeanauthorizationdecisionaboutwhatresourcestheRSCcanaccessattheRSP.ThisdecisionmaybebasedonattributesabouttheRSC.
3. Uponsuccessfulauthorization,theASreturnsanauthorizationtokenresponse
thatcontainsanauthorizationtokenthattheRSCcanusetosendauthorizedresourcerequeststotheRSP.
4. The RSC processes the authorization token response and extracts the
authorizationtoken.
5. TheRSCsendsaresourcerequest,whichincludestheauthorizationtoken,totheRSP.Inthisstep,theRSCinitiatesestablishmentofaTLSchannelwiththeRSPinwhichtheRSCauthenticatestheRSP.
6. TheRSPprocesses the resource request. In this step, theRSPvalidates the
authorizationtoken.Also,theRSPusesinformationintheauthorizationtokentomakeanaccesscontroldecisionontheresourcerequest.
7. TheRSPreturnsaresourceresponsetotheRSC.
8. TheRSCprocessestheresourceresponse.
Figure5depictsthisSIP.
NIEF REST Services Profile Version 1.0
16
Figure5:DiagramoftheRESTConsumer-AuthorizerSIP
6.5.2 REST Service Consumer Requirements
1. TheRSCMUSTconformtotherequirementsinSection7.3.1.
2. TheRSCMUSTusetheOAuthClientCredentialsAuthorizationGrantinaccordancewithSection4.4of[OAuthCore].
6.5.3 Authorization Service Requirements
1. TheASMUSTconformtotherequirementsinSection7.3.2.
2. TheASMUSTverifythatthetokenrequestitreceivesusestheClientCredentialsAuthorizationGrantinaccordancewithSection4.4of[OAuthCore].
6.5.4 REST Service Provider Requirements
1. TheRSPMUSTconformtotherequirementsinSection7.3.3.6.6 NIEF REST Single Sign-On Consumer-Authorizer SIP
NIEF REST Services Profile Version 1.0
17
TheNIEFRESTSSOConsumer-AuthorizerSIPenablesaRESTServiceConsumer(RSC),whileactingonbehalfofanEnd-User,toobtainanauthorizationtokenfromaRESTAuthorizationService(AS)tousetosubmitapre-authorizedresourcerequesttoaRESTServiceProvider(RSP),wheretheASauthenticatestheuserviaasinglesign-onmechanism.6.6.1 Motivating Use Case (Non-Normative) ThisSIPaddressesthescenariowhereanRSCactsonbehalfoftheend-user,theRSPreliesonaRESTAStomakeauthorizationdecisions,andtheAScanactasasinglesign-onclienttoauthenticatetheend-user.InthisSIP,theRSCmayfunctionastheuser-agentorrelyonanexternaluser-agent.RSCauthenticationbytheASisoptional.ThisSIPcombinesOAuthwithSSO.TheRSCactsasanOAuthClientandcanusetheOAuthImplicitFloworOAuthAuthorizationCodeFlowtoobtainanOAuthaccesstokenfromtheAS.TheASactsasanOAuthAuthorizationServer,andtheRSPactsasanOAuth-ProtectedResourceServer.ThisSIPconsistsofthefollowingsteps.
1. TheRSCsendsanauthorizationrequesttotheASviaredirectingtheUser-Agent.
2. TheASauthenticatestheEnd-UserbyfacilitatingSSOviatheuser-agent.ThisSIPsupportstheNIEFOpenIDConnect(OIDC)SSOSIPandtheNIEFWebBrowserUser-to-SystemProfile(SAMLSSO).
3. Afterend-userauthentication,theASmakesanauthorizationdecisiononwhether
toallowtheRSCtoactonbehalfoftheend-usertomaketherequestedaccess.Also,theASmayobtainconsentfromtheend-userfortherequestedaccess.
4. Uponsuccessfulauthorizationandconsent,theASredirectstheuser-agentbackto
theRSCwitheitheranaccesstokenoranauthorizationcode.IftheRSCreceivesanauthorizationcode,thenitsendsatokenrequesttotheTokenEndpointoftheAStoexchangetheauthorizationcodeforanaccesstoken.
5. TheRSCsendsresourcerequeststotheRSP,passingtheaccesstokenwiththe
request.
6. TheRSPvalidatestherequestandtheaccesstoken,providesaccessaccordingtotheaccesstoken.
7. TheRSPreturnsanappropriateresourceresponse.
8. TheRSCprocessestheresourceresponse.
Figure6depictsthisSIP.
NIEF REST Services Profile Version 1.0
18
Figure6:DiagramoftheRESTSSOConsumer-AuthorizerSIP
6.6.2 REST Service Consumer Requirements
1. TheRSCMUSTconformtotherequirementsinSection7.3.1.
2. TheRSCMUSTusetheOAuthImplicitFlowasdefinedinSection4.2of[OAuthCore],ortheOAuthAuthenticationCodeFlowasdefinedinSection4.1of[OAuthCore].
6.6.3 Authorization Service Requirements
1. TheASMUSTconformtotherequirementsinSection7.3.2.
2. TheASMUSTmeetatleastoneofthefollowingSSOrequirements.
a. ConformtotheNIEFOpenIDConnectSSOSIPasaRelyingParty(RP).
b. ConformtotheNIEFWebBrowserUser-to-SystemProfileasaServiceProvider(SP).
NIEF REST Services Profile Version 1.0
19
3. TheASMUSTsupporteithertheOAuthImplicitFlowasdefinedinSection4.2of[OAuthCore],ortheOAuthAuthorizationCodeFlowasdefinedinSection4.1of[OAuthCore],orboth.
4. TheAuthorizationEndpointoftheASMUSTuseoneofthefollowingmethodsto
authenticatetheEnd-User.
a. ConductSSOviaeithertheNIEFOpenIDConnectSSOSIPortheNIEFWebBrowserUser-to-SystemProfile.AftercompletionoftheSSOprocess,theASMAYsetasessioncookiewiththeUser-Agent.
b. ReceiveasessioncookiefromtheUser-Agentthatwaspreviouslyissuedby
theAS.6.6.4 REST Service Provider Requirements
1. TheRSPMUSTconformtotherequirementsinSection7.3.3.6.7 NIEF REST Delegated-Consumer-Authorizer SIP TheNIEFRESTDelegated-Consumer-AuthorizerSIPenablesaRESTServiceConsumer(RSC),whichisactingonbehalfofanEnd-User,toobtainanauthorizationtokenfromaRESTAuthorizationService(AS)tousetosubmitapre-authorizedresourcerequesttoaRESTServiceProvider(RSP),wheretheuserisidentifiedbyadelegateduserassertion.6.7.1 Motivating Use Case (Non-Normative) ThisSIPaddressesascenarioinwhichtheRSPdoesnotmakeitsownauthorizationdecisions,andmustbeaccessedwithanauthorizationtokenthathasbeenissuedbyanAuthorizationService(AS).InthisSIP,theRSCisactingonbehalfofanEnd-User.Itconsistsofthefollowingsteps:
1. TheRSC,actingonbehalfofanEnd-User,obtainsadelegateduserassertionfromtheuser’s IDPthatcanbeprovidedtotheAS.Theassertionmaybeadelegated SAML assertion or an OIDC ID token. How the RSC obtains theassertionisoutofscopeforthisSIP.However,itmayusetheRESTAssertionDelegateService(ADS)SIP,whichisdefinedinSection6.8,toaccomplishthis.
2. TheRSCsendsanOAuthtokenrequesttotheTokenEndpointoftheASovera
TLS channel in which the RSC authenticates the AS. The token requestidentifies the target RSP andmay contain information about the requestedaccessintheOAuth“scope”parameter.Also,theRSCincludesthedelegateduserassertionobtainedinstep1inthetokenrequest.
3. The token endpoint processes the token request. In this step, the token
endpointauthenticatestheRSC.Also,thetokenendpointusesinformationin
NIEF REST Services Profile Version 1.0
20
thetokenrequesttomakeanauthorizationdecisionaboutwhatresourcestheRSCcanaccessattheRSP.ThisdecisionmaybebasedonattributesabouttheRSCaswellasattributesinthedelegatedassertion.
4. Uponsuccessfulauthorization,theASreturnsatokenresponsetotheRSC.The
tokenresponsecontainsanOAuthaccesstokenthattheRSCcanusetosendauthorizedresourcerequeststotheRSP.
5. TheRSCprocessesthetokenresponseandextractstheaccesstoken.
6. TheRSCsendsaresourcerequest,whichincludestheaccesstoken,totheRSP.
Inthisstep,theRSCinitiatesestablishmentofaTLSchannelwiththeRSPinwhichtheRSCauthenticatestheRSP.
7. TheRSPprocessestheresourcerequest. In thisstep, theRSPvalidatesand
mayhonortheaccesstokenandprocesstherequestaccordingly.
8. TheRSPreturnsaresourceresponsetotheRSC.
9. TheRSCprocessestheresourceresponse.Figure7depictsthisSIP.
NIEF REST Services Profile Version 1.0
21
Figure7:DiagramoftheRESTDelegated-Consumer-AuthorizerSIP
6.7.2 REST Service Consumer Requirements
1. TheRSCMUSTconformtotherequirementsinSection7.3.1.
2. TheRSCMUSTacquireadelegateduserassertion,fromatrustedIDP,thatdenotestotheRSPthattheRSCisactingonbehalfoftheEnd-User.ThisassertionMUSTbeeitheranOpenIDConnect(OIDC)IDtokeninaccordancewithSection2of[OIDCCore]thatissignedandserializedusingtheJWSCompactSerializationinaccordancewith[JWS],oraSAMLassertionthatconformstoSection7.2.TheRSCisNOTrequiredtoverifythattheacquireduserassertionconformstotheserequirements;however,theRSCMUSTensurethattheIDPthatissuestheassertionisawarethatitneedstoissueaconformingassertion.5
3. TheRSCMUSTpresentthedelegateduserassertionastheOAuthauthorization
granttothetokenendpointoftheASinaccordancewitheither[OAuthJWT]or[OAuthSAML2].
5TheassertionsissuedbytheIDPmaybeencryptedusinganencryptionkeyoftheRSP;inthiscase,theRSCwillnotbeableinspectthecontentsoftheassertion.TheRSCcanuseaprotocolsuchastheNIEFAssertionDelegateService(ADS)SIPtomeetthisrequirement.
NIEF REST Services Profile Version 1.0
22
6.7.3 Authorization Service Requirements
1. TheASMUSTconformtotherequirementsinSection7.3.2.
2. TheTokenEndpointoftheASMUSTacceptfromtheRSCanauthorizationgrantthateitherconformsto[OAuthJWT]orconformsto[OAuthSAML].
3. TheTokenEndpointoftheASMUSTperformthevalidationstepsinthefollowing
sub-items,inadditiontothevalidationstepsin[OAuthJWT]or[OAuthSAML],tovalidatetheassertionintheauthorizationgrant.
a. TheTokenEndpointMUSTverifythatthesigningcertificateoftheassertion
isassociatedwithatrustedIDP.
b. TheTokenEndpointMUSTverifythattheRSCisanauthorizedpartyoftheassertion.
c. TheTokenEndpointMUSTbeamemberoftheaudiencespecifiedbythe
assertion.6.7.4 REST Service Provider Requirements
1. TheRSPMUSTconformtotherequirementsinSection7.3.3.6.8 NIEF REST Assertion Delegate Service SIP TheNIEFRESTAssertionDelegateServiceSIPenablesaRESTServiceConsumer(RSC)toobtainadelegateduserassertionfromanAssertionDelegateService(ADS)foruseataRESTServiceProvider.TheRSCmayredirecttheUserAgenttotheADSsotheEnd-Usercanprovidein-bandconsent,oriftheRSChasbeenpreviouslyissuedauserassertionfortheEnd-User,thenitmayexchangethatassertionforthedelegatedassertionviadirectlycommunicatingwiththeADS.6.8.1 Motivating Use Case (Non-Normative) SomeSIPs,suchastheRESTDelegated-Consumer-ProviderSIPandtheRESTDelegated-Consumer-AuthorizerSIP,requireanRSCtoobtainadelegateduserassertionforuseatanRSP.ThisSIPprovidesamethodforanRSCtoobtainsuchanassertionfromaRESTAssertionDelegateService(ADS).TheassertionmaybeaSAMLassertionoranOIDCIDtoken.TheADSobtainsin-bandorout-of-bandconsentfromtheEnd-User,basedonthedelegationrequestsentbytheRSC.Toaccomplishin-bandconsent,theRSCneedstobeabletoredirecttheEnd-User’sUserAgent(UA)totheADS.Toaccomplishout-of-bandconsent,theRSCneedstohavepreviouslybeenissuedauserassertionfortheEnd-User.
NIEF REST Services Profile Version 1.0
23
ThisSIPisbasedonOIDC,withtheRSCactingasanOIDCRelyingParty(RP)andtheADSactingasanOpenIDProvider.TheADSprovidesadelegateduserassertiontotheRSCina“delegated_assertion”parameterdefinedinthisSIP.Figure8depictsthisSIPwiththeuseofin-bandconsent,andFigure9depictsthisSIPwiththeuseofout-of-bandconsent.
Figure8:DiagramoftheRESTAssertionDelegateServiceSIPwithIn-BandConsent
NIEF REST Services Profile Version 1.0
24
Figure9:DiagramoftheRESTAssertionDelegateServiceSIPwithOut-of-BandConsent
6.8.2 REST Service Consumer Requirements
1. TheRSCMUSTconformto[OIDCCore]asaRelyingParty.
2. TheRSCMUSTdiscovertheappropriateADStouseforthecurrentuser.6
3. RequestssubmittedbytheRSCtotheAuthorizationEndpointoftheADSMUSTbeADSIn-Band(ADS-IB)authorizationrequeststhatconformtotherequirementsinSection7.4.3.
4. IftheRSCobtainsanOAuthauthorizationcodefromtheADSinresponseto
submittinganADS-IBauthorizationrequesttotheAuthorizationEndpointinwhichthevalueofthe“response_type”parameteris“code”,thentheRSCMAYsubmitanaccesstokenrequesttotheTokenEndpointoftheADS.ThisaccesstokenrequestMUSTconformtotherequirementsinSection3.1.3.1of[OIDCCore].
5. WheninteractingwiththeTokenEndpoint,theRSCMUSTauthenticatetotheToken
EndpointinaccordancewithSection7.1.
6. TheRSCMAYsubmitADSOut-Of-Band(ADS-OOB)tokenrequeststhatconformtotherequirementsinSection7.4.4,totheTokenEndpointoftheADS.TheRSCMUSTuseanassertionthatithaspreviouslybeenissuedbyanIDPassociatedwiththeADS,astheassertionintheADS-OOBtokenrequest.
6SeeSectionError!Referencesourcenotfound.forguidanceonperformingADSdiscovery.
NIEF REST Services Profile Version 1.0
25
6.8.3 Assertion Delegate Service Requirements
1. TheADSMUSTconformto[OIDCCore]asanOpenIDProvider.
2. UponreceiptofanADSauthorizationrequestattheAuthorizationEndpointoftheADS(i.e.,ifthe“scope”parameteroftherequestincludes“openid”andanADSscopevalueinaccordancewithSection7.4.1),theAuthorizationEndpointMUSTperformthefollowingstepstovalidatetherequest.
a. VerifythattherequestconformstoSection7.4.3.
b. Verifythatthevalueofthe“client_id”parameteridentifiesatrustedRSC.
c. Verifythatthetargetresourcespecifiedinthe“resource_uri”parameterof
therequestisabaseURIofatrustedRSP.
Thefailureofanyvalidationstepconstitutesanerrorcondition.
3. TheAuthorizationEndpointMUSTprocesseveryvalidatedADSauthorizationrequestinaccordancewiththefollowingrequirements.
a. TheAuthorizationEndpointMUSTauthenticatetheEnd-Userinaccordance
withSection3.1.2.3of[OIDCCore].
b. TheAuthorizationEndpointMUSTobtainEnd-UserconsentforreleasingtherequesteddelegateduserassertioninaccordancetoSection3.1.2.4of[OIDCCore].
4. Ifthevalueofthe“response_type”ofavalidatedADSauthorizationrequestis
“code”,andiftheAuthorizationEndpointsuccessfullyobtainedEnd-Userconsent,thentheAuthorizationEndpointMUSTreturnanOAuthauthorizationcodeinaccordancewithSection3.1.2.5of[OIDCCore].TheauthorizationcodeMUSTsignify,totheTokenEndpointoftheADS,authorizationtoreleasetherequesteddelegateduserassertiontotheRSC.
5. Ifthevalueofthe“response_type”ofavalidatedADSauthorizationrequestis
“delegated_assertion”,andiftheAuthorizationEndpointsuccessfullyobtainedEnd-Userconsent,thentheAuthorizationEndpointMUSTreturnaresponsemessageinaccordancewiththerequirementsinthefollowingsub-items.
a. TheresponsemessageMUSTbesenttotheredirectURIthatwasspecifiedin
the“redirect_uri”parameteroftherequest.
b. TheresponsemessageMUSTincludethe“delegated_assertion”parameteraddedtothefragmentcomponentoftheredirectURI.Thevalueofthis
NIEF REST Services Profile Version 1.0
26
parameterMUSTbeanassertionthatiseitheranOIDCIDtokenoraSAMLassertioninaccordancewiththeADSscopevalueoftherequest.
c. TheADSMUSTbetheissueroftheassertion.
d. TheRSCMUSTbeanauthorizedpartyoftheassertion.
e. Thevalueofthe“resource_uri”parameteroftherequestMUSTbeincluded
intheaudienceoftheassertion.
f. TheADSMUSTdigitallysigntheassertion.
g. TheresponsemessageMUSTincludethe“state”parameteraddedtothefragmentcomponentoftheredirectURIiftherequestcontainedthe“state”parameter.Thevalueofthe“state”parameteroftheresponse,ifitexists,MUSTmatchthevalueofthe“state”parameteroftherequest.7
6. Uponreceiptofatokenrequest,theTokenEndpointMUSTauthenticatetheRSCin
accordancewithSection7.1.
7. UponreceiptofatokenrequestthatusesanOAuthgranttype(see[OAuthCore])of“code”attheTokenEndpoint,theTokenEndpointMUSTvalidatetherequestinaccordancewiththerequirementsinthefollowingsub-items.
a. TheTokenEndpointMUSTverifythattherequestisanOAuthauthorization
codeflowaccesstokenrequestasdefinedinSection4.1.3of[OAuthCore].Ifthisvalidationstepfails,thentherequestdoesnotapplytothisSIPandtheADSbehaviorisundefined.
b. TheTokenEndpointMUSTverifythatthevalueofthe“code”parameterof
therequestisanOAuthauthorizationcodethatwasprovidedtotheRSCinresponsetoanADSauthorizationrequestinaccordancewithSection7.4.3.Ifthisvalidationstepfails,thentherequestdoesnotapplytothisSIPandtheADSbehaviorisundefined.
c. TheTokenEndpointMUSTvalidatetherequestinaccordancewithSection
3.1.3.2of[OIDCCore].
8. AfteraTokenEndpointsuccessfullyvalidatesatokenrequestthatusesanOAuthgranttype(see[OAuthCore])of“code”,theTokenEndpointMUSTprovidearesponseinaccordancewiththefollowingrequirements.
7TheparameterSHOULDbeusedforpreventingcross-siterequestforgeryasdescribedinSection10.12of[OAuthCore].
NIEF REST Services Profile Version 1.0
27
a. TheresponsemessageMUSTusethe“application/json”mediatypeandthecontentoftheresponsemessagepayloadMUSTbeaJSONobjectinaccordancewith[JSON].
b. ThepayloadMUSTincludea“delegated_assertion”member.Thevalueofthis
memberMUSTbeanassertionthatiseitheranOIDCIDtokenoraSAMLassertioninaccordancewiththeADSscopevalueoftheoriginalADS-IBauthorizationrequest.
c. TheADSMUSTbetheissueroftheassertion.
d. TheRSCMUSTbeanauthorizedpartyoftheassertion.
e. Thevalueofthe“resource_uri”parameteroftherequestMUSTbeincluded
intheaudienceoftheassertion.
f. TheADSMUSTdigitallysigntheassertion.
9. UponreceiptofanADS-OOBtokenrequestattheTokenEndpoint(i.e.,iftherequestconformstoItem#1ofSection7.4.4),theADSMUSTperformthestepsinthefollowingsub-itemstovalidatetherequest.
a. TheADSMUSTverifythattherequestisvalidinaccordancewithSection
7.4.4.
b. TheADSMUSTvalidatethesignatureoftheassertionusedintheauthorizationgrant.
c. TheADSMUSTverifythattheADSisassociatedwiththesigningkeyusedto
signtheassertion.
d. TheADSMUSTverifythattheissuervalueoftheassertionmatchestheissuervalueoftheADS.
e. TheADSMUSTverifythattheRSCthatsuppliedtheassertionisidentifiedin
theassertion’saudience.
f. TheTokenEndpointMUSTverifytrustintheidentifiedRSC.
Iftherequestisnotvalid,thentheADSMUSTprocessanerrorconditioninaccordancewithSection3.1.3.4of[OIDCCore].
10. AftertheADSsuccessfullyvalidatesanADS-OOBtokenrequest,theADSMUST
obtain,orhavepreviouslyobtained,out-of-bandconsentfromthesubjectforreleasingtherequestedassertion.Ifthisstepfails,thentheADSMUSTprocessanerrorconditioninaccordancewithSection3.1.3.4of[OIDCCore].
NIEF REST Services Profile Version 1.0
28
11. Uponobtainingsuccessfulconsent,theADSMAYissuetherequesteddelegateduser
processtherequestinaccordancewiththefollowingrequirements.Fortheserequirements,thesubjectistheentityidentifiedbythesubjectoftheassertionusedintheauthorizationgrantintherequest.
g. TheresponsemessageMUSTusethe“application/json”mediatypeandthe
contentoftheresponsemessagepayloadMUSTbeaJSONobjectinaccordancewith[JSON].
h. ThepayloadoftheresponsemessageMUSTincludea“delegated_assertion”
member.ThevalueofthismemberMUSTbeanassertionthatiseitheranOIDCIDtokenoraSAMLassertioninaccordancewiththeADSscopevalueoftheoriginalADS-IBauthorizationrequest.
i. TheADSMUSTbetheissueroftheassertionintheresponsemessage.
j. TheRSCMUSTbeanauthorizedpartyoftheassertionintheresponse
message.
k. Thevalueofthe“resource_uri”parameteroftherequestMUSTbeincludedintheaudienceoftheassertionintheresponsemessage.
l. TheADSMUSTdigitallysigntheassertionintheresponsemessage.
6.9 NIEF REST Attribute Provider SIP TheNIEFRESTAttributeProviderSIPenablesaRESTAttributeConsumer(AC)toobtainsupplementalclaimsaboutanEnd-UserfromaRESTAttributeProvider(AP).ThisSIPsupportsACsredirectingtheUserAgenttotheAPsothattheEnd-Usercangrantin-bandconsent,aswellasACscommunicatingdirectlywiththeAPandtheAPobtainingout-of-bandEnd-Userconsent.6.9.1 Motivating Use Case (Non-Normative) OIDCdefinesaUserInfoEndpoint,whichprovidesuserclaimstoOIDCRelyingParties(RPs)wheretheEnd-Usergrantsin-bandconsentduringhis/hercurrentsessionwiththeRP.ThisSIPprovidesforin-bandEnd-UserconsentviamandatingtheuseofanOIDCUserInfoEndpoint.ThisissuitableforRESTServiceConsumers(RSCs),whichwhenprovidingresourcestoanEnd-User,willbeconnectedtotheEnd-User’suseragent(UA).However,NIEFRESTServiceProviders(RSPs)thatexposeserviceinterfaces,andnotuserinterfaces,donotestablishactivesessionsdirectlywithEnd-UsersviatheirUAs.Toaddressthisscenario,thisSIPalsoprovidesamethodforRSPstoobtainuserclaimsfromAPsaboutEnd-Userswhohavegrantedconsenttothereleaseoftheirclaimsout-of-bandfromtheAPtransactions.
NIEF REST Services Profile Version 1.0
29
RequestersofuserclaimsarecalledRESTAttributeConsumers(ACs),andareOAuthClients.RESTAPsareOpenIDProvidersthatbehaveinaccordancewith[OIDCCore]andextensionsasdefinedinthenormativerequirementsforthisSIP.Figure10depictsthisSIPwiththeuseofin-banduserconsent,andFigure11depictsthisSIPwiththeuseofout-of-banduserconsent.
Figure10:DiagramoftheRESTAttributeProviderSIPwithIn-BandConsent
NIEF REST Services Profile Version 1.0
30
Figure11:DiagramoftheRESTAttributeProviderSIPwithOut-of-BandConsent
6.9.2 Attribute Consumer Requirements
1. TheACMUSTconformto[OIDCCore]asaRelyingParty.
2. TheACMUSTonlysubmitrequeststotrustedAPs.
3. InordertoobtainclaimswithouthavinganactivesessionwiththeEnd-User’sUserAgent,theACMUSThavepreviouslyobtainedanOIDCIDtokenorSAMLassertionaboutthesubjectfromanIDPthat’sassociatedwiththeAP.ThisassertionMUSTconformtotherequirementsinthefollowingsub-items.
a. TheassertionMUSThavebeensignedwithakeyassociatedwiththeAP.
b. TheissuervalueoftheassertionMUSTmatchtheissuervalueoftheAP.
c. TheACMUSTbeidentifiedintheaudienceoftheassertion.
4. InordertoobtainclaimswithouthavinganactivesessionwiththeEnd-User’sUser
Agent,theACMUSTsubmitanAPOut-Of-Band(AP-OOB)accesstokenrequestto
NIEF REST Services Profile Version 1.0
31
theTokenEndpointoftheAP.ThisrequestMUSTconformtothefollowingrequirements.
a. TherequestMUSTconformtotherequirementsinSection7.5.
b. TheACMUSTsupplythepreviouslyobtainedassertionastheassertionused
intheauthorizationgrant.
5. WhenauthenticatingtotheTokenEndpointoftheAP,theACMUSTauthenticateinaccordancewithSection7.1.
6.9.3 Attribute Provider Requirements
1. TheAPMUSTconformto[OIDCCore]asanOpenIDProvider.
2. TheAPMUSTdeployanAuthorizationEndpointiftheAPsupportstheauthorizationcode,implicitflow,orhybridflowinaccordancewith[OIDCCore].
3. TheAPMUSTdeployaTokenEndpointinaccordancewith[OIDCCore]ifanyofthe
followingconditionshold.
a. TheAPsupportstheauthorizationcodeflowinaccordancewithSection3.1of[OIDCCore].
b. TheAPsupportsAP-OOBaccesstokenrequestsinaccordancewithSection
7.5.
4. TheAPMUSTdeployaUserInfoEndpointinaccordancewith[OIDCCore].
5. WhencommunicatingwithanAC,theTokenEndpointoftheAPMUSTauthenticatetheACinaccordancewithSection7.1.
6. UponreceiptofanAP-OOBaccesstokenrequest(i.e.,iftherequestconformsto
Section7.5),thentheTokenEndpointMUSTvalidatetherequestinaccordancewiththerequirementsinthefollowingsub-items.
a. TheTokenEndpointMUSTvalidatethesignatureoftheassertionusedinthe
authorizationgrant.
b. TheTokenEndpointMUSTverifythattheAPisassociatedwiththesigningkeyusedtosigntheassertion.
c. TheTokenEndpointMUSTverifythattheissuervalueoftheassertion
matchestheissuervalueoftheAP.
NIEF REST Services Profile Version 1.0
32
d. TheTokenEndpointMUSTverifythattheRESTACthatsuppliedtheassertionisidentifiedintheassertion’saudience.
e. TheTokenEndpointMUSTverifytrustintheidentifiedRESTAC.
7. AftersuccessfullyvalidatinganAP-OOBaccesstokenrequest,theTokenEndpoint
MAYreturnanaccesstoken,anOIDCIDtoken,orboth,inaccordancewiththerequirementsinthefollowingsub-items.Fortheserequirements,thesubjectistheentityidentifiedbythesubjectoftheassertionusedintheauthorizationgrantintherequest.
a. TheTokenEndpointMAYreturnanOAuthaccesstokeninaccordancewith
[OAuthCore]andinaccordancewith[OIDCCore].TheaccesstokenMUSTonlyallowtheACtoaccess,fromtheUserInfoEndpoint,claimsthatthesubjecthasauthorizedtoreleasetotheAC.
b. TheTokenEndpointMAYreturnanOIDCIDtokeninaccordancewith[OIDC
Core].TheOIDCIDtokenMUSTonlyincludeclaimsthatthesubjecthasauthorizedtoreleasetotheAC.
6.10 NIEF OpenID Connect Dynamic Client Registration SIP TheNIEFOpenIDConnectDynamicClientRegistrationSIPprofilestheOIDCDynamicClientRegistrationprotocol(see[OIDCDCR])toprovidenormativerulesfortheuseofinitialaccesstokens.6.10.1 Motivating Use Case (Non-Normative) TheOIDCDynamicClientRegistration(DCR)protocoldefinesamethodforanOIDCRelyingParty(RP)todynamicallyregisteritsconfigurationmetadatawithanOpenIDProvider(Provider)attheProvider’sRegistrationEndpoint.[OIDCDCR]providesamechanismforRegistrationEndpointstoactasOAuthprotectedresourcesand,assuch,requireregistrationrequeststobeprotectedviatheuseofOAuthaccesstokens.Theseaccesstokensthatareusedin[OIDCDCR]arecalled“initialaccesstokens”.Thecontentandstructureofinitialaccesstokensareoutofscopefor[OIDCDCR].TheNIEFOpenIDConnectDynamicClientRegistrationSIPprofiles[OIDCDCR]byspecifyingrequirementsforhowOpenIDProvidersandOIDCRPscreateandconsumeinitialaccesstokens.NotethatthisSIPappliesgenerallytoallOIDCProvidersandClients,notonlythoseendpointsthatconformtootherNIEFRESTSIPs.6.10.2 OpenID Connect Relying Party Requirements
1. TheOIDCRP(Client)MUSTconformto[OIDCDCR]asanOIDCRelyingParty.
NIEF REST Services Profile Version 1.0
33
2. WhensubmittingaregistrationrequesttoanOpenIDProvider’sregistrationendpoint,theClientMUSTverifytrustintheProvider’scertificatethatwasusedtoestablishtheTLSconnection.
3. WhensubmittingaregistrationrequesttoaProvider’sRegistrationEndpoint,the
ClientMUSTsupplyaself-issuedinitialaccesstokenthatconformstotherequirementsinthefollowingsub-items.
a. ThetokenMUSTconformtotherequirementsinSection7.6.2.
b. Thevalueofthe“aud”claimofthetokenMUSTbetheissueridentifierofthe
Provider.
4. TheClientMUSTsupplytheinitialaccesstokeninaccordancewith[OAuthBearer].6.10.3 OpenID Provider Requirements
1. TheOpenIDProvider(Provider)MUSTconformto[OIDCDCR]asanOpenIDProvider.
2. UponreceiptofaregistrationrequestfromanOIDCRP,theProviderMUSTverify
thattherequestcontainsaninitialaccesstokeninaccordancewith[OAuthBearer].
3. TheProviderMUSTvalidatethetokenbyperformingtheverificationstepsinthefollowingsub-items.
a. TheProviderMUSTverifythatthetokenisaJWTthatconformstothe
requirementsinSection7.6.2.
b. TheProviderMUSTverifytrustinthekeyusedtosignthetoken.
c. TheProviderMUSTverifythatthekeyusedtosignthetokenisassociatedwiththeentityidentifiedbythe“iss”claiminthetoken.
d. TheProviderMUSTverifythatthevalue“aud”claimofthetokenisitsissuer
identifier.
Ifanyoftheaboveverificationstepsfail,thentheProviderMUSTrejecttherequestinaccordancewithSection3.3of[OIDCDCR].
6.11 NIEF OAuth Dynamic Client Registration SIP TheNIEFOAuthDynamicClientRegistrationSIPprofilestheOAuthDCRprotocol(see[OAuthDCR])toprovidenormativerulesfortheuseofinitialaccesstokens.
NIEF REST Services Profile Version 1.0
34
6.11.1 Motivating Use Case (Non-Normative) TheOAuthDCRprotocoldefinesamethodforanOAuthClient(Client)todynamicallyregisteritsconfigurationmetadatawithanOAuthAuthorizationServer(Server)attheServer’sRegistrationEndpoint,whichmaybeanOAuthprotectedresource.[OAuthDCR]providesamechanismforRegistrationEndpointstoactasOAuthprotectedresourcesand,assuch,requireregistrationrequeststobeprotectedviatheuseofOAuthaccesstokens.Theseaccesstokensthatareusedin[OAuthDCR]arecalled“initialaccesstokens”.Thecontentandstructureofinitialaccesstokensareoutofscopefor[OAuthDCR].TheNIEFOAuthDynamicClientRegistrationSIPprofiles[OAuthDCR]byspecifyingrequirementsforhowOAuthAuthorizationServersandClientscreateandconsumeinitialaccesstokens.NotethatthisSIPappliesgenerallytoallOAuthClientsandAuthorizationServers,notonlythoseendpointsthatconformtootherNIEFRESTSIPs.6.11.2 OAuth Client Requirements
1. TheOAuthClient(Client)MUSTconformto[OAuthDCR]asanOAuthClient.
2. WhensubmittingaregistrationrequesttoanOAuthAuthorizationServer’s(Server’s)RegistrationEndpoint,theClientMUSTverifytrustintheServer’scertificatethatwasusedtoestablishtheTLSconnection.
3. WhensubmittingaregistrationrequesttoaServer’sRegistrationEndpoint,the
ClientMUSTsupplyaself-issuedinitialaccesstokenthatconformstotherequirementsinthefollowingsub-items.
a. ThetokenMUSTconformtotherequirementsinSection7.6.2.
b. Thevalueofthe“aud”claimofthetokenMUSTbetheissueridentifierofthe
Server.
4. TheClientMUSTsupplytheinitialaccesstokeninaccordancewith[OAuthBearer].6.11.3 OAuth Authorization Server Requirements
1. TheOAuthAuthorizationServer(Server)MUSTconformto[OAuthDCR]asanOAuthAuthorizationServer.
2. UponreceiptofaregistrationrequestfromanOAuthClient,theServerMUSTverify
thattherequestcontainsaninitialaccesstokeninaccordancewith[OAuthBearer].
3. TheServerMUSTvalidatethetokenbyperformingtheverificationstepsinthefollowingsub-items.
NIEF REST Services Profile Version 1.0
35
a. TheServerMUSTverifythatthetokenisaJWTthatconformstotherequirementsinSection7.6.2.
b. TheServerMUSTverifytrustinthekeyusedtosignthetoken.
c. TheServerMUSTverifythatthekeyusedtosignthetokenisassociatedwith
theentityidentifiedbythe“iss”claiminthetoken.
d. TheServerMUSTverifythatthevalue“aud”claimofthetokenisitsissueridentifier.
Ifanyoftheaboveverificationstepsfail,thentheServerMUSTrejecttherequestinaccordancewithSection4.2of[OAuthDCR].
7. Supporting Profiles ThissectioncontainssetsofrequirementsthatareusedbytheSIPsfromSection6.7.1 Client Authentication Requirements for OAuth Token Endpoints InseveralNIEFRESTSIPs,anOAuthTokenEndpointisrequiredtoauthenticateanRSCactingasanOAuthClientorOIDCRP.Thissectionprovidesnormativerequirementsforperformingthisauthentication.7.1.1 REST Service Consumer Requirements
1. TheRSCMUSTsupportatleastoneofthefollowingHTTPclientauthenticationmechanisms.
a. AclientauthenticationmechanismdefinedinSection9of[OIDCCore],
exceptthe“none”mechanism.Thesemechanismsinclude“client_secret_basic”,“client_secret_post”,“client_secret_jwt”,and“private_key_jwt”.
b. SAMLbearertokenauthenticationasdefinedin[OAuthSAML2]andas
follows.
i. TheClientMUSTuseaself-issuedSAMLassertion.
ii. TheSAMLassertionMUSTconformtotherequirementsinSection7.2.
c. TLSclientcertificateauthentication.7.1.2 Token Endpoint Requirements
NIEF REST Services Profile Version 1.0
36
1. TheTokenEndpointMUSTauthenticatetheRSCusingexactlyoneofthefollowingHTTPclientauthenticationmechanisms.
a. AclientauthenticationmechanismdefinedinSection9of[OIDCCore],
exceptthe“none”mechanism.Thesemechanismsinclude“client_secret_basic”,“client_secret_post”,“client_secret_jwt”,and“private_key_jwt”.
b. SAMLbearertokenauthenticationasdefinedin[OAuthSAML2]andas
follows.
i. TheServerMUSTverifythattheSAMLassertionconformstotherequirementsinSection7.2.
c. TLSclientcertificateauthentication.
7.2 SAML Assertion Requirements ThissectioncontainsnormativerequirementsforSAMLassertionsthatareusedintheNIEFRESTSIPs.ThisincludesrequirementsfordelegatedSAMLassertions.AdelegatedSAMLassertionisaSAMLassertionthatassertsthattheentitytowhichtheassertionwasissuedisactingonbehalfofthesubjectoftheassertion.Theentitytowhichtheassertionwasissuediscalledan“authorizedparty”oftheassertion.
1. TheSAMLassertion(assertion)MUSTconformtotherequirementsinSection2.3.3of[SAML2Core].
2. TheassertionMUSTcontaina<Conditions>elementwithan<AudienceRestriction>
elementwithan<Audience>elementthatidentifiestheintendedaudience.
3. TheassertionMUSTcontaina<Subject>element.
4. The<Subject>elementMUSTcontainatleastone<SubjectConfirmation>elementinaccordancewiththerequirementsinthefollowingsub-items.
a. The<SubjectConfirmation>elementMUSThaveaMethodattributewitha
valueof"urn:oasis:names:tc:SAML:2.0:cm:bearer".
b. Iftheassertiondoesnothaveasuitable“NonOnOrAfter”attributeonthe<Conditions>element,thenthe<SubjectConfirmation>elementMUSTcontaina<SubjectConfirmationData>element.
c. Whenpresent,the<SubjectConfirmationData>elementMUSThavea
“Recipient”attribute.
NIEF REST Services Profile Version 1.0
37
5. TheassertionMUSThaveanexpirythatlimitsthetimewindowduringwhichitcanbeused.TheexpirycanbeexpressedeitherastheNotOnOrAfterattributeofthe<Conditions>elementorastheNotOnOrAfterattributeofasuitable<SubjectConfirmationData>element.
6. Iftheassertiondenotesanauthorizedpartyactingonbehalfoftheassertion’s
subject,thentheassertionMUSTidentifytheauthorizedpartyasadelegateinaccordancewith[SAML2Delegation].
7. TheassertionMUSTbedigitallysignedorhaveamessageauthenticationcode
appliedbytheIssuer.
8. TheassertionMUSTbeencodedusingbase64urlwherethepaddingbitsaresettozeroinaccordancewith[RFC4648],andtheencodedassertionMUSTNOTbelinewrappedorcontainpadcharacters(suchas“=”).8
7.3 Authorizer SIP Base Requirements ThissectioncontainsbaserequirementsforRESTServiceConsumers(RSCs),AuthorizationServices(ASs),andRESTServiceProviders(RSPs)fortheRESTConsumer-AuthorizerSIP(seeSection6.5)andtheRESTDelegated-Consumer-AuthorizerSIP(seeSection6.6).7.3.1 RSC Requirements
1. TheRSCMUSTconformto[OAuthCore]asanOAuthClient.
2. AllredirectionURIsusedbytheRSCMUSTuseTLS.
3. TheRSCMUSTsubmitOAuthauthorizationrequeststoonlytrustedASes.
4. WhencommunicatingwiththeTokenEndpointoftheAS,theRSCMUSTauthenticatetotheTokenEndpointinaccordancewithSection7.1.
5. WhencommunicatingwiththeTokenEndpointoftheAS,theRSCMUSTverifytrust
intheTokenEndpoint.7.3.2 AS Requirements
1. TheASMUSTconformto[OAuthCore]asanOAuthAuthorizerServer.
2. WhencommunicatingwithanRSC,theTokenEndpointoftheASMUSTauthenticatetheRSCinaccordancewithSection7.1.
3. TheTokenEndpointMUSTverifytrustinauthenticatedRSCs.
8TheseSAMLassertionencodingrulescomefrom[OAuthSAML2].
NIEF REST Services Profile Version 1.0
38
4. TheASMUSTensurethateveryOAuthaccesstoken(token)itissuesconformsto
thefollowingrequirements.
a. ThetokenMUSThavemechanismsthatallowRSPstoverifytheauthenticityandintegrityofthetoken.
b. TheaccesstokenMUSThaveamechanismthatallowsRSPstodetermine
whentheaccesstokenhasexpired.7.3.3 RSP Requirements
1. TheRSPMUSTconformto[OAuthCore]asanOAuthResourceServer.
2. TheRSPMUSTexposeitsresourcesviaTLS.
3. TheRSPMUSTperformthevalidationstepsinthefollowingsub-items,inadditiontothevalidationstepsinSection7of[OAuthCore],tovalidatetheaccesstokenpresentedbytheRSC.
a. TheRSPMUSTverifythatittruststheASthatissuedtheaccesstoken.
b. TheRSPMUSTverifytheauthenticityandintegrityoftheaccesstoken.
c. TheRSPMUSTverifythattheaccesstokenhasnotexpired.
7.4 REST Assertion Delegate Service Supporting Requirements ThissectionspecifiessupportingrequirementsfortheRESTAssertionDelegateServiceSIP(seeSection6.8).7.4.1 REST ADS Scope Requirements ARESTADSscopevalueMUSTbeoneofthefollowing.
1. Thevalue“ads-saml2-bearer”denotesarequestforadelegatedSAMLassertion.
2. Thevalue“ads-oidc-id-bearer”denotesarequestforanOIDCIDtoken.7.4.2 ADS Claims Object Requirements
1. AnADSClaimsobjectMUSTbeaJSONobjectthatconformstoSection5.5of[OIDCCore].
2. Inaddition,theobjectMAYcontainatop-levelmembercalled“delegated_assertion”.
ThismemberisaJSONobjectthatrequeststhatthelistedindividualclaimsbe
NIEF REST Services Profile Version 1.0
39
returnedinthedelegatedassertion.ThestructureofthisobjectMUSTconformtothestructureofthe“userinfo”and“id_token”objectsasdefinedinSection5.5of[OIDCCore].
7.4.3 ADS Authorization Request Requirements
1. AnHTTPrequestisanADSauthorizationrequestifitisanOAuthauthorizationrequestinaccordancewith[OAuthCore]thathasa“scope”parameterwhosevalueisaspacedelimitedsetofstringscopevaluesthatincludesanADSscopevalueinaccordancewithSection7.4,andincludesthevalue“openid”.The“scope”parameterMAYincludeotherscopevalues.
2. AnADSauthorizationrequestisvalidifitconformstotherequirementsinthe
followingsub-items.
a. Thevalueofthe“response_type”parameterMUSTbeeither“code”or“delegated_assertion”.
b. TherequestMUSThavea“resource_uri”parameter.Thevalueofthis
parameterMUSTabaseURIoftheresource(s)towhichthedelegateduserassertionisdestined.
c. TherequestMAYhavea“display”parameter.Ifthisparameterexists,it
MUSTconformtothe“display”parameterrequirementsinSection3.1.2.1of[OIDCCore].
d. TherequestMAYhavea“prompt”parameter.Ifthisparameterexists,it
MUSTconformtothe“prompt”parameterrequirementsinSection3.1.2.1of[OIDCCore].
e. TherequestMAYhavea“max_age”parameter.Ifthisparameterexists,it
MUSTconformtothe“max_age”parameterrequirementsinSection3.1.2.1of[OIDCCore].
f. TherequestMAYhavea“ui_locale”parameter.Ifthisparameterexists,it
MUSTconformtothe“ui_locale”parameterrequirementsinSection3.1.2.1of[OIDCCore].
g. TherequestMAYhavean“id_token_hint”parameter.Ifthisparameterexists,
itMUSTconformtothe“id_token_hint”parameterrequirementsinSection3.1.2.1of[OIDCCore].
h. TherequestMAYhavea“saml_token_hint”parameter.Ifthisparameter
exists,itMUSTconformtothe“id_token_hint”parameterrequirementsinSection3.1.2.1of[OIDCCore],whereaSAMLassertionisusedinsteadofan
NIEF REST Services Profile Version 1.0
40
OIDCIDtoken.SAMLassertionsMUSTconformtotherequirementsinSection7.2.
i. TherequestMAYhavea“login_hint”parameter.Ifthisparameterexists,it
MUSTconformtothe“login_hint”parameterrequirementsinSection3.1.2.1of[OIDCCore].
j. TherequestMAYhavean“acr_values”parameter.Ifthisparameterexists,it
MUSTconformtothe“acr_values”parameterrequirementsinSection3.1.2.1of[OIDCCore].
k. TherequestMAYhavea“state”parameter.Ifthisparameterexists,itMUST
conformtothe“state”parameterrequirementsinSection3.1.2.1of[OIDCCore].
l. TherequestMAYhave“claims”parameter.Ifthisparameterexists,itsvalue
MUSTbeaJSONobjectthatconformstoSection7.4.2.7.4.4 ADS-OOB Token Request Requirements
1. AnHTTPrequestthatissenttoanOpenIDConnectTokenEndpointisanAssertionDelegateServiceOut-Of-Band(ADS-OOB)tokenrequestifithasa“scope”parameterwhosevalueisaspacedelimitedsetofstringscopevaluesthatincludesanADSscopevalueinaccordancewithSection7.4,andincludesthevalue“openid”.The“scope”parameterMAYincludeotherscopevalues.
2. AnADS-OOBaccesstokenrequestisvalidifitconformstotherequirementsinthe
followingsub-items.
a. TherequestMUSThavea“resource_uri”parameter.ThevalueofthisparameterMUSTabaseURIoftheresource(s)towhichthedelegateduserassertionisdestined.
b. TherequestMAYhave“claims”parameter.Ifthisparameterexists,itsvalue
MUSTbeaJSONobjectthatconformstoSection7.4.2.
c. TherequestMUSTuseanauthorizationgrantthatconformstoeither[OAuthJWT]or[OAuthSAML2].
7.5 REST Attribute Provider Out-of-Band Access Token Requests ARESTAttributeProviderOut-Of-Band(AP-OOB)accesstokenrequestisanOAuthaccesstokenrequestthatuseseitherthe[OAuthJWT]or[OAuthSAML2]authorizationgrant.TherequestusestheclaimsfeatureofOpenIDConnecttoexpressrequestsforparticularclaims.
NIEF REST Services Profile Version 1.0
41
7.5.1 REST AP-OOB Access Token Request Requirements AnHTTPrequestisanAP-OOBaccesstokenrequestifitconformstotherequirementsinthefollowingsub-items.
1. TherequestMUSTbeanOAuthaccesstokenrequestinaccordancewith[OAuthCore].
2. TherequestMUSTuseanauthorizationgrantthatconformstoeither[OAuthJWT]
or[OAuthSAML2].
3. TherequestMUSThavea“scope”parameterwhosevalueisaspacedelimitedsetofstringvalues.Thevalueofthe“scope”parameterMUSTinclude“openid”.
4. TherequestMAYhavea“claims”parameter.Thesemanticsandvalueofthis
parameterMUSTconformtotherequirementsinSection5.5of[OIDCCore].7.6 Self-Signed OAuth Access Token Profile Thisprofilespecifieshowself-signedJWTscanbeusedbyOAuthClientsasaccesstokenswhencommunicatingwithOAuthprotectedresources.7.6.1 Motivating Use Case (Non-Normative) MultipleNIEFSIPsrequireorallowOAuthClientsorOpenIDConnectClients(Clients)tocommunicateonbehalfofthemselveswithOAuth-protectedResourceServerswithouttheuseofOAuthAuthorizationServers.TheseSIPsincludetheNIEFOpenIDConnectDynamicClientRegistrationSIP(seeSection9)andtheNIEFOAuthDynamicClientRegistrationSIP(seeSection6.11).Thisprofilespecifiesnormativerequirementsontheuseofself-signedJWTsthatmaybeusedasaccesstokensinthesescenarios.TheserequirementsarebasedontherequirementsforusingJWTsforOAuthclientauthenticationasdefinedin[OAuthJWT].Notethattheuseoftheterm“OAuthClient”hereinincludesOpenIDConnectClientsandNIEFRESTServiceConsumers.7.6.2 Self-Issued OAuth Access Token Requirements
1. Theaccesstoken(token)MUSTbeaJWTthatconformsto[JWT].
2. ThetokenMUSTcontainan"iss"(issuer)claim.ThesemanticsofthisclaimareasspecifiedinSection4.1.1of[JWT].ThevalueofthisclaimMUSTbeastringthatistheclientidentifieroftheOAuthClient(Client)thatisissuingthetoken.
NIEF REST Services Profile Version 1.0
42
3. ThetokenMUSTcontaina"sub"(subject)claim.ThesemanticsofthisclaimareasspecifiedinSection4.1.2of[JWT].ThevalueofthisclaimMUSTbeastringthatistheclientidentifieroftheClientthatisissuingthetoken.
4. ThetokenMUSTcontainan"aud"(audience)claim.Thesemanticsofthisclaimare
asspecifiedinSection4.1.3of[JWT].ThevalueofthisclaimMUSTbeastringthatistheidentifieroftheOAuthprotectedresourcetowhichthetokenisbeingsent
5. ThetokenMUSTcontainan"exp"(expiration)claim.Thesemanticsofthisclaimare
asspecifiedin,anduseofthisclaimMUSTconformto,Section4.1.4of[JWT].
6. ThetokenMUSTcontainan"iat"(issuedat)claim.Thesemanticsofthisclaimareasspecifiedin,anduseofthisclaimMUSTconformto,Section4.1.6of[JWT].
7. TheJWTMUSTbesignedinaccordancewith[JWS].
8. ThesignedJWTMUSTbeencodedviatheJWSCompactSerializationinaccordance
with[JWS].7.7 Definition of Base URI Whenusedinthisdocument,theterm“baseURI”isdefinedasfollows.AURI(thefirstURI)isabaseURIofasecondURIifthefollowingconditionshold.
1. TheschemepartofbothURIsareequivalent.
2. TheauthoritypartofbothURIsareempty,ortheauthoritypartofbothURIsareequivalent.
3. ThepathcomponentofthesecondURIincludesthepathcomponentofthefirstURI.
ThisconditionholdswhenthepathcomponentofbothURIsareequivalent.
4. Thequeryandfragmentpartsarenotconsideredinthiscomparison.7.7.1 Examples (Non-Normative)
1. “http://nief.org/trust/”isabaseURIof“http://nief.org/trust/example/one/”.
2. “http://nief.org/trust”isNOTabaseURIof“http://sub.nief.org/trust/example/one/”,sincetheauthoritycomponentofbothURIsarenotequivalent.
7.8 TLS Requirements TLSchannelsusedinaccordancewiththisProfileSHOULDuseTLSversion1.1orhigher,andMUSTbeconfiguredtoprovideanti-replay,confidentiality,andintegrityprotections.