OIO Open ID Connect Profiles Version 0.2

Status: Early draft Date: 24.03.2020

- 2 -

1 INTRODUCTION .................................................................................................... 3 1.1 PREFACE .............................................................................................................. 3 1.2 AUDIENCE ............................................................................................................ 3 1.3 USAGE SCENARIOS .............................................................................................. 3 1.4 OVERVIEW OF SPECIFICATIONS .......................................................................... 3

2 NOTATION AND TERMINOLOGY .................................................................... 5 2.1 TERMINOLOGY .................................................................................................... 5

3 SCENARIO OVERVIEW ....................................................................................... 6 3.1 OVERVIEW OF PROTOCOL FLOWS ....................................................................... 7 3.2 PRE-REQUISITES .................................................................................................. 7 3.3 AUTHORIZATION MODELS ................................................................................... 8

3.3.1 Scopes granted by end-user .............................................................................. 8 3.3.2 Scopes granted by API provider (WSP) ......................................................... 10

4 APP AUTHORIZATION PROFILE ................................................................... 11 4.1.1 Step 1: SP App opens browser with authorization request ............................ 12 4.1.2 Step 2: Authorization endpoint receives authentication request ................... 14 4.1.3 Step 3: Authorization server issues an authorization code ............................ 15 4.1.4 Step 4: SP App receives the authorization code ............................................. 15 4.1.5 Step 5: SP App presents the authorization code at the token endpoint .......... 15 4.1.6 Step 6: Token endpoint validates the authorization code and issues the tokens

requested ......................................................................................................... 16 4.1.7 Step 7: SP App validates response ................................................................. 16

5 TOKEN REQUEST PROFILE ............................................................................ 18 5.1.1 Step 1: SP App sends Token Request ............................................................. 18 5.1.2 Step 2: Token Server validates request and returns token .............................. 19

6 TOKEN RENEWAL PROFILE ........................................................................... 21 6.1 USING A REFRESH TOKEN ................................................................................. 21 6.2 TOKEN REVOCATION ......................................................................................... 21

7 API ACCESS PROFILE ....................................................................................... 23

8 SECURITY REQUIREMENTS ........................................................................... 25

9 REFERENCES ....................................................................................................... 26

- 3 -

1 Introduction1.1 Preface

TheDanishAgencyforDigitisationisplanningtoestablishcentralinfrastructureinNemLog-in3tosupportnativeAppsandmanagetheiraccesstoexternalAPIsof-feredbypublicandprivateserviceproviders.

ThenewcomponentswillamongotherthingsincludeanAuthorizationServer,aTo-kenServerandwebportalsforregistrationandmanagementofAppsandAPIs.Theinfrastructurewillensureauthenticationoftheend-userbasedon[NSIS]andsubse-quentAppauthorizationbasedonend-userconsentfollowedbyissuanceandman-agementofsecuritytokens–similartohowtheexistingNemLog-insolutionsup-portswebapplicationsandSOAP-servicesbasedonSAMLandWS-Trust.

Thefirststepinrealizinganewinfrastructureistoestablishthenecessaryspecifica-tionsandprofilesthatensuresinteroperabilityandahighsecuritylevel.Thisdocu-mentcontainsdeploymentprofilesofOpenIDConnect[OIDC]andOAuth2.0detail-ingprotocolsfortheinteractionbetweenanAppandanAuthorizationServerandTokenServer.ThespecificationsarewrittenwithNemLog-in3inmindbutcanfreelybeusedelsewhere.TheprofilesfocusonAppscenariosexclusively.

1.2 Audience

Thedocumentiswrittenforatechnicalaudienceincludingarchitects,securitypro-fessionalsanddevelopersfamiliarwithOAuth2.0,OpenIDConnect,JWT,REST,TLSandotherrelatedtechnologiesandspecifications.

1.3 UsageScenarios

ThisprofileisintendedforusewithinDanishpublicsectorfederationswhereinfor-mationaboutauthenticatedidentitiesisfederatedacrossserviceproviders.Thegoalistoachievestandardization,interoperability,securityandprivacy,whileenablingre-useofcommonimplementations.

Thecurrentversionfocusesexclusivelyonthemostcommonscenariosinvolvingna-tiveApps.Moreadvancedusecasesmayhoweverbeaddedlater–includingscenar-ioswithfederatedAuthorizationServersorAPIsexchangingincomingtokensfordownstreaminvocationofotherAPIs.

1.4 OverviewofSpecifications

Asetofspecificationsanddocumentswillbedeveloped,coveringvariousaspectsofAppscenarios:

- 4 -

• ThisOIDCProfilecoversprotocolsfortheinteractionbetweenanAppandanAuthorizationServerandTokenServer.ThegoalistohaveAccessTokensis-suedtoanAppwhichthenbeusedtogainaccesstoanexternalAPI.

• TheOIOJWTTokenProfile[OIOJWT]specifiesformatsforJWTtokensusedwiththisprofile,includingclaims,privilegesandsignatures.ItisinspiredbytheOIOSAML3.0WebSSOprofile[OIOSAML]andOIOBasicPrivilegeProfile[OIO-BPP].

• GuidelinesforAppimplementationwillcoversecuritybestpractice,includ-inghowtoprotecttokensandauthenticateend-usersinanApp.ItcoverstheinternalpartsofanAppandnottheprotocolsusedtocommunicatewiththeinfrastructure.

• TermsandconditionsforusingtheNemLog-ininfrastructuresolutionwillbedefined,includingexpectedbehaviorofServiceProviders,termsofuse,re-sponsibilitiesetc.

• AguidetotheregistrationportalinNemLog-inwilldescribehowAppsandAPIsareregisteredandgovernedincludingrelevantmetadata,certificates,scopes,approvalprocessesetc.

ThefirstthreespecificationsintheabovelistareindependentofNemLog-inandcanbeusedeverywhere.Inparticular,earlylocalimplementationsofAuthorizationandTokenServerscanusetheminordertopavethewayforasmoothtransitionfromalocaltoacentralimplementationprovidedbyNemLog-in.Thisapproachthusmini-mizestheriskofredoingtheApporAPIimplementationatalaterstage.

ThelasttwodocumentsarespecifictoNemLog-in’sfutureimplementationandarenotoncriticalpathforearly,localimplementations.

- 5 -

2 NotationandterminologyThekeywords"MUST","MUSTNOT","REQUIRED","SHALL","SHALLNOT","SHOULD","SHOULDNOT","RECOMMENDED","NOTRECOMMENDED","MAY",and"OPTIONAL"inthisdocumentaretobeinterpretedasdescribedinBCP14[RFC2119][RFC8174]when,andonlywhen,theyappearinallcapitals,asshownhere.

Thisspecificationusesthefollowingtypographicalconventionsintext:<ns:Ele-ment>,Attribute,Datatype,OtherCode.Thenormativerequirementsofthisspecificationareindividuallylabeledwithauniqueidentifierinthefollowingform:[OIO-EXAMPLE-01].Allinformationwithintheserequirementsshouldbeconsiderednormativeunlessitissetinitalictype.Italicizedtextisnon-normativeandisintendedtoprovideadditionalinformationthatmaybehelpfulinimplement-ingthenormativerequirements.

2.1 Terminology

Thisspecificationinvolvesthefollowingactors:

• SPApp-ServiceProviderAppactingintheroleofclientinOAuthandOpenIDConnectsense.Itisapublic,nativeAppthatprovidesservicestotheend-userandconsumesoneormoreexternal(REST)APIse.g.forretrievingorupdatingdataabouttheend-user.

• SPAPI–ServiceProviderAPI.AnAPIofferedbyaServiceProviderwhichisprotectedbyatrustedAuthorization-andTokenServer.TheAPIServicePro-vidercanbethesameoradifferentorganizationprovidingtheSPApp.

• End-userinstallinganSPApponhispersonalmobiledeviceandauthorizingAppaccessonhis/herbehalf.

• AuthorizationServer–acentralOAuth2.0infrastructurecomponent(inthefuturedeliveredbyNemLog-in).

• TokenServer–OIDC/OAuth2.0infrastructurecomponent(inthefuturede-liveredbyNemLog-in)thatissuestokenswhichprovideaccesstoexternalAPIs.

- 6 -

3 ScenariooverviewThefigurebelowillustratesthemaincomponentsandtheirinteractionswhenanSPAppisenrolledbytheuser:

Themainprinciplesare:

• AppAccesstoexternalAPIsisobtainedbypresentingavalidsecuritytokenissuedbyatrustedTokenServer.Thesecuritytokenprovidestheclaimsnec-essaryforenforcingtheAPI’saccesscontrolpolicy.

• Theend-userauthenticatestoacentralAuthorizationServerviaaseparateuseragent(e.g.browser);theAuthorizationServermayinvokeanexternalSAMLIdentityProviderwhichprovidesauthenticationoftheend-user(e.g.basedonMitIDasshowninthefigureorsomethingelse).

• TheAuthorizationserverissuesanauthorizationcode(accordingtotheOAuthauthorizationcodeflow).

• TheAuthorizationcodeisfirstexchangedforasetoftokens:anIDTokentobeconsumedwithintheApp,anAccessTokentobeusedwiththeTokenServerandaRefreshTokenalsousedwiththeTokenServer.

• TheAppcansubsequentlyexchangetheAccessTokenforaServiceTokenwiththeTokenServer–theServiceTokenissimplyanAccessTokenforanexternalAPIprotectedbytheinfrastructure.

AlltokensexcepttheRefreshtokenareshort-lived(e.g.onehour)whichensuresthattheyarerenewedoftenandthereforegetupdatedfrequently.Moredetailsonthisisdescribedinchapter6.

- 7 -

3.1 Overviewofprotocolflows

ThisspecificationprofilesanumberofprotocolflowswhereanAppinteractswithanexternalAuthorizationandTokenServerusingOAuth2.0andOpenIDConnect.Requirementsfortheindividualstepsareprofiledinordertoensureinteroperabil-ity,narrowimplementationchoices,andachieveahighsecuritylevelandcompati-bilitywithexistingmodelsandinfrastructure.

Themainflowsare:

• NativeAppAuthorizationwheretheAppisinstalledandpersonalizedforthefirsttime,describedinchapter4.

• IssuanceofaServiceTokentoanexternalSPAPI(STSflow),describedinchapter.5.

• RenewalofexpiredAccessTokensisdescribedinchapter6.Here,alsothetimeoutpoliciesandrevocationoftokensisdescribed.

• UsingaServiceTokentogetaccesstoanAPIisdescribedinchapter7.

Notealsothatgenericsecurityrequirements(e.g.fortransportsecurity)describedinchapter8applytoallprofiles.

3.2 Pre-requisites

Anumberofpre-requisitesareassumedtobeinplacebeforetheaboveflowscanbeexecuted:

• Theend-userhasobtainedrelevantcredentialsneededforauthentication(e.g.NemID,MitIDorcredentialfromlocalIdP).

• Theend-userhasapersonaldevice1.Otherflowsshouldbeusedfornon-per-sonaldeviceswheresecuritytokenscannotbepersistedonthedevice.

• TheSPApphasbeeninstalledontheend-userdevice(e.g.fromapublicappstoreoraclosedappstore).

• TheSPAppandSPAPIhavebeenregisteredandconfiguredwiththeAuthor-izationServerincludingtheirtypeandparameters:

o Relevantidentifiers(e.g.EntityIDs)havebeenassignedforAppandAPIinstancessuchthattheycanbereferencedintokensandprotocolmessages.

o TheSPAppmusthaveregisteredauniqueredirectURIforreturningtheauthorizationresponsetotheSPApp,andtheURIschemeshouldbebasedonadomainnamethatisunderthecontroloftheserviceprovideroftheApp.Moredetailsaredescribedinchapter4.

o NecessaryprivilegesandscopeshavebeendefinedfortheSPAppandSPAPIsuchthattheycanberequestedbytheSPAppandissuedinto-kens.Seesection3.3fordetails.

1 TheprofilesassumethatsecuritytokenscanbepersistedinAppsincludingalong-livedRefresh-to-ken.TheriskprofileoftheAppandusertermsmaydefinewhetheritisacceptabletodothisonade-vicesharedinafamilyorsharedamongcolleaguesinworkplaceenvironment.

- 8 -

o Claimssetshavebeendefinedduringregistration.TheOIOJWTpro-file[OIOJWT]definesmandatoryclaimsbutanyoptionalclaimsneededbyanApporAPIshouldberegistered.

o Metadataandcertificateshavebeenexchangedinadvanceaspartoftrustestablishment.Inparticular,theSPApphasbeenconfiguredwith(pinned)TLSservercertificatesandtokensigningcertificates,suchthattransportconnectionsandtokenscanbesecurelyvalidated.

Theactualregistrationprocesswhichestablishesthesepre-conditionswillnotbedescribedinthisdocumentasitishighlyimplementationspecific.Forexample,inNemLog-intheregistrationwillbebasedontheexistingadministrationportal.

3.3 Authorizationmodels

Thissectiondescribestheauthorizationmodels.AcentraldesigngoalhasbeentoreusetheexistingmechanismsforwebapplicationsandSOAPwebservices(inpar-ticulartheOIOBasicPrivilegeProfile)suchthatAPIproviderscanreuseexistinglogicandaccesscontrolpolicies.Otherauthorizationmodelscanbeaddedlaterifneeded.

3.3.1 Scopes granted by end-user

AfundamentaldesignprincipleinOAuth(andhencethisprofile)isthattheend-usershouldauthorizeaccessgrantedtotheclient(heretheSPApp)byauthenticatingtotheAuthorizationServerandprovidingexplicitconsentfortheApptoactonhisbe-half.ThisisaccomplishedbyincludingasetofOAuthscopesintheauthorizationre-questfromtheSPApp,whichallowstheAuthorizationServertoobtaintheneces-saryconsentfromtheend-userandreflectitinissuedtokens.Thisconsentbothco-verstheauthorizationtoobtainanOIDCIDTokenaswellasauthorizationtoinvokeexternalAPIs(SPAPI).

Therefore,theinitialscopevaluesprovidedbytheSPAppintheauthorizationre-quest(seenextsection)hastocontainsufficientscopestocoverallAPIsandscopeswhichtheSPAppneedstoinvokeontheend-user’sbehalf.IftheSPAppatalaterstage(e.g.alaterversion)needsfurtheraccess(newAPIorscope),afreshauthori-zationrequestisrequiredwiththeadditionalscopesadded–whichtheusercanthenconsentto.

AsspecifiedintheJWTTokenProfile[OIOJWT],AccessTokensforSPAPIswillcon-tainprivilegesaccordingtothemodeldefinedinOIOBasicPrivilegeProfile.Privi-legesareURIsdefinedbyaServiceProviderrepresentingaspecificaccesswiththatServiceProvider.Thus,themeaning,granularityandconsenttextofprivilegesisde-finedentirelybytheServiceProvider.

- 9 -

Itisassumed,thatprivilegestoberequestedandassertedintokenswillberegis-teredinadvance(bytheServiceProvider)withtheAuthorizationandTokenServerinasindicatedintheexamplebelow:

Privilege info Example values

SP EntityID https://ngdp.digst.dk

Privilege URI https://ngdp.digst.dk/priv/read_mail

OAuth scope shorthand2

xq7j

Description This privilege grants access to read mail from a citizen inbox in the NGdP solution.

UI Context text (DK)

“Vil du give samtykke til, at denne App tilgår din Digitale Post fra det offentlige?”

TheAuthorizationServerregistrationprocessensuresuniquenessofEntityIDs,priv-ilegesURIs,scopeshorthandsetc.andensuresproperownership(e.g.anadmincanonlyadministerrelevantAppsandAPIs).

Thus,iftheSPAppincludesthexq7jshorthandinthescopeparameter(seechapter4),theAuthorizationServerwillprompttheend-userforconsenttoauthorizetheSPApptoaccesshismailintheNGdPsolution,andifconsentisgranted,theSPAppwillsubsequentlybeabletoobtainanAccessTokenfortherelevantSPAPI,wheretheassociatedprivilegeURIhttps://ngdp.digst.dk/priv/read_mailisincludedwithscopeofthecitizen.

BelowisgivenanexampleoftheresultingJSONstructurewithintheAccessTokenbasedontheOIOJWTProfile[OIOJWT],wheretheprivilegeisincludedwithscope3of“1202801024”(CPRnumberofcitizen):

2 In order to keep requests small enough to fit in HTTP headers used with the OIDC authentication re-quest, privileges are suggested to have a unique short-hand such that the entire URI is not necessary. 3 Note that the scope in OIO Basic Privilege Profile should not be confused with scope in OAuth / OIDC. The first is the context of a privilege (e.g. person or organization the privilege applies to) and the latter corresponds to a given access requested (similar to a privilege in OIO BPP).

{ "privilegegroups" : [ { "privilege" : "https://ngdp.digst.dk/priv/read_mail", "scope" : "urn:dk:gov:saml:cprNumberIdentifier:1202801024", } ] }

- 10 -

Asimilarmodelcanbeusedforotherscopesandfordatarestrictions;seetheOIOJWTProfile[OIOJWT]fordetails.

3.3.2 Scopes granted by API provider (WSP)

Inadditiontoscopesgrantedbytheend-user,theAuthorizationServermayallowtheAPIprovidertograntprivileges/scopestocertainAppsindependentoftheuser.

ThisissimilartothecurrentmechanismintheNemLog-inSTS,whereaWSP(WebServiceProvider)candefineanumberofprivileges,whichcanthenbegrantedtocertainWebServiceConsumers–i.e.clientsoftheWSP.Theassignmentofprivi-legesisdonebytheWSPadministratorintheNemLog-inadministrationportal.

AsimilarmodelcanbeusedwithAppsandAPIs–actingasWSCandWSPrespec-tively.Itcanbeusedtograntspecificaccessonlytocertainclients.

ThismodelrequiresthattheAuthorizationServerisabletosecurelyauthenticateanAppasbeingofaparticulartype.SinceapublicnativeAppscannothavesecretsem-beddedintheirinstallationpackage(theywouldbetrivialtoextractbyothers),theauthenticationoftheAppmustbeperformedviaothermechanismssuchasusingaclaimed“https”schemeURIredirection describedin[RFC8252].ThispreventsotherAppinstancesfromclaimingURIsfromdomainstheydon’tcontrol.

PrivilegesgrantedbytheAPIproviderwillberepresentedinthesamewayasuser-grantedprivilegesexcepttheyhaveadifferentscopebeingtheAppEntityIDinsteadoftheend-userCPR-number:

{ "privilegegroups" : [ { "privilege" : "https://ngdp.digst.dk/priv/read_mail", "scope" : "https://digst.dk/ngdp/apps/borger_dk_client", } ] }

- 11 -

4 AppAuthorizationProfileThischapterspecifiesaprofileofOpenIDConnect(usingthe[OAuth]2.0authoriza-tioncodegrant)usedfortheinitialauthorizationandpersonalizationoftheSPApp.Theprofileisprimarilybasedon[OIDC],[OAuth]and[RFC8252].

Themainstepsofthefloware:

1. TheSPAppopensabrowserwithanauthorization4request.2. TheAuthorizationendpointreceivestheauthorizationrequest,authenticates

theuser,andobtainsend-userconsentfortherequestedscopes.Authenticat-ingtheusermayinvolvechainingtootherauthenticationsystems.

3. TheAuthorizationserverissuesanauthorizationcodetotheredirectURI.4. TheSPAppreceivestheauthorizationcodefromtheredirectURI.5. TheSPApppresentstheauthorizationcodeatthetokenendpoint.6. Thetokenendpointvalidatestheauthorizationcodeandissuesthetokensre-

quested.7. TheSPAppvalidatestheresponse(notshownonfigureabove).

[OIDC-01]

TheAppauthorizationprotocolMUSTfollowthe[OAuth]2.0authorizationcodegranttypeasdefinedinsection4.1of[OAuth].Unlessotherwisestatedexplicitly,therequirementsfromthisspecificationapplydirectly.

4 Note that in [OIDC] this is called an authentication request, whereas OAuth calls it an authorization re-quest.

- 12 -

4.1.1 Step 1: SP App opens browser with authorization5 request [OIDC-02]

TherequestparametersintheauthorizationrequestMUSTfollowthere-quirementsspecifiedinthetablebelow:

Parameter Man-da-tory

Usage

scope Y MUST contain the ‘openid’ scope value as well as scopes for external APIs which the user should authorize. See section 3.3 for a description of the au-thorization model.

response_type Y MUST be set to ‘code’

client_id Y MUST be set to the SP App identifier (Entity ID) pre-registered with the Au-thorization Server.

redirect-uri Y The SP App MUST use a claimed “https” scheme URI redirection when sup-ported by the client platform6 (e.g. “https://app.example.com/oauth2redi-rect/example-provider”). This ensures the identity of the destination app to the authorization server by the operating system. If the mechanism is not supported, the SP App SHOULD instead uses a “cus-tom URL scheme” for URI redirection, and it MUST be URI scheme based on a domain name under control of the App developer as described in RFC7595. It is REQUIRED that a unique redirect URI is used for each authorization server used by the SP App.

state Y To mitigate CSRF-style attacks over inter-app URI communication channels (so called "cross-app request forgery"), it is REQUIRED that the SP App includes a high-entropy secure random number (>=128 bit) in the "state" parameter of the authorization request.

code_challenge Y The SP App MUST use the Proof Key for Code Exchange ([PKCE], RFC7636) ex-tension to OAuth and include a code_challenge being a high-entropy crypto-graphic random STRING containing 128 characters. The code_challenge is a obtained as hash of the secret code_verifier: code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_ challenge_method

Y MUST be ‘S256’ (see [PKCE]).

nonce Y MUST include a high-entropy secure random number (>=128 bit) in order to prevent ID token replay.

amr_values N String that specifies the amr value that the Authorization Server is being re-quested to use for processing this Authentication Request. In this profile NSIS levels are used, and the minimum NSIS level is specified as one of the below NSIS levels:

5 Actually, it is both an authentication and authorization request. 6 This is supported both on iOS and Android 6.0 and above.

- 13 -

https://data.gov.dk/concept/core/nsis/loa/Low https://data.gov.dk/concept/core/nsis/loa/Substantial https://data.gov.dk/concept/core/nsis/loa/High The Authorization Server SHOULD ensure that the end-user is authenticated at least to the specified NSIS level.

Note:PKCEisaproof-of-possessionextensiontoOAuth2.0thatprotectstheauthori-zationcodefrombeingusedifitisintercepted.Theextensionhastheclientgenerateasecretverifier;itpassesahashofthisverifierintheinitialauthorizationrequest,andmustpresenttheunhashedverifierwhenredeemingtheauthorizationcode.Anappthatinterceptedtheauthorizationcodewouldnotbeinpossessionofthisse-cret,renderingthecodeuseless.

[OIDC-03]

ThefollowingrequestparametersSHOULDNOTbeusedwiththisprofile:display,acr_values,prompt,response_mode,max_age7,andid_token_hint8.

Otherrequestparametersdefinedin[OIDC]and[OAuth]andnotmentionedhereareallOPTIONAL.

[OIDC-04]

OAuth2.0authorizationrequestsfromtheSPAppMUSTbesentthroughex-ternaluseragents(i.e.notembeddedwebviews).Otherwise,theSPAppmaybeabletocopyusercredentialsandcookies.In-appbrowsertabsMAYbeusediftheyseparatesecuritycontextfromtheSPApp.

Exampleauthenticationrequest:

Thefollowingisthenon-normativeexamplerequestthatwouldbesentbytheUserAgenttotheAuthorizationServerinresponsetotheHTTP302redirectresponsebytheSPApp(withlinewrapswithinvaluesfordisplaypurposesonly):

GET /authorize? response_type=code &scope=openid &client_id=https%3A%2F%2Fclient.example.org%2Fcb &state=af0ifjsldkj &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb HTTP/1.1 &code_challenge=qjrzSW9gMiUgpUvqgEPE4_-8swvyCtfOVvg55o5S_es &code_challenge_method=S256 Host: server.example.com

7 This parameter is not necessary since the profile requires ‘fresh’ user authentication. 8 The login_hint parameter may possibly be used to facilitate MitID App switch. This has to be clarified further when MitID specifications are available.

- 14 -

4.1.2 Step 2: Authorization endpoint receives authentication request [OIDC-05]

TheAuthorizationServerMUSTvalidatetherequestasspecifiedinsection3.1.2.2(AuthenticationRequestValidation)of[OIDC]includingthatallre-quiredparametersmentionedabove(section4.1.1)arepresent.Hence,thescopeparameterMUSTcontaintheopenid scopevalue.Asspecifiedin[OAuth],AuthorizationServersSHOULDignoreunrecognizedrequestparameters.

[OIDC-06]

TheAuthorizationServerSHOULDNOTrequireclientauthenticationforpub-licnativeappsusingasharedsecret.

[OIDC-07]

TheAuthorizationServerMUSTrejectaredirect_uriinrequeststhatdoesn’texactlymatchtheonethatwaspreviouslyregistered.

Note:Asmentionedunderprerequisites,theSPAppmustregisteritscompleteredi-rectURIwiththeAuthorizationServeranditmustbeuniquefortheAuthorizationserver.[OIDC-08]

TheAuthorizationServerMUSTrecordthe[PKCE]challengeandmethodintherequestandrejectrequestsnotcontainingtheseparameters.

[OIDC-09]

Iftherequestisvalid,theAuthorizationServerMUSTauthenticatetheend-userattheNSISlevelofassurancedefinedintherequest9.ItMUSTbeafreshauthenticationoftheend-user(e.g.SSOisnotpermitted).

[OIDC-10]

Aftersuccessfulauthenticationoftheend-user,theAuthorizationServerMUSTobtain(andsecurelystore)userconsenttothescopesdefinedintherequest.

9 As mentioned previously, an external authentication server (e.g. SAML IdP) may be used for this pur-pose.

- 15 -

TheuserSHOULDbeabletodecide/grantconsentperscopeintherequest(suchthatitisnotallornothing).

4.1.3 Step 3: Authorization server issues an authorization code [OIDC-11]

Aftersuccessfulauthenticationoftheend-userandgrantedconsent,theAu-thorizationServerMUSTissueanauthorizationcode,andtheAuthorizationResponseMUSTreturntheparametersdefinedinSection4.1.2of[OAuth]byaddingthemasqueryparameterstotheredirect_urispecifiedintheAuthor-izationRequestusingtheapplication/x-www-form-urlencodedformat.

Thefollowingisanon-normativeexamplesuccessfulresponseusingthisflow(withlinewrapswithinvaluesfordisplaypurposesonly):

HTTP/1.1 302 Found Location: https://client.example.org/cb? code=SplxlOBeZQQYbYS6WxSbIA &state=af0ifjsldkj &nonce=a8jf0dfjslkai

4.1.4 Step 4: SP App receives the authorization code

[OIDC-12]TheSPAppMUSTvalidatetheresponseaccordingto[OAuth]especiallySec-tions4.1.2and10.12.

[OIDC-13]

TheSPAppMUSTvalidatestateandnonce inresponsesandMUSTrejectre-sponsesiftheydonotmatchapendingoutgoingauthorizationrequest.TheSPAppMUSTfurthercomparetheredirectURIintheresponsetothevalueusedintheauthorizationrequest(step1)andMUSTverifythattheURIonwhichtheauthorizationresponsewasreceivedexactlymatchesit.

4.1.5 Step 5: SP App presents the authorization code at the token endpoint [OIDC-14]

TheSPAppMUSTsendatokenrequesttothetokenendpointtoobtainato-kenresponseasdescribedinSection3.2of[OAuth],usingthegrant_typevalueauthorization_code.

- 16 -

[OIDC-15]TheSPAppMUSTincludethePKCEcode_verifiersecretmatchingthecode_challengesentinstep1.

Thefollowingisanon-normativeexampleofaTokenRequest(withlinewrapswithinvaluesfordisplaypurposesonly): POST /token HTTP/1.1 Host: server.example.com Content-Type: application/x-www-form-urlencoded grant_type=authorization_code& code=SplxlOBeZQQYbYS6WxSbI& redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb& code_verifier=JDu29BkSH99283aS client_id=https%3A%2F%2Fclient.example.org NotethatnoAuthorizationHTTPheaderisincludedsincepublicclientsdonothavecredentialsissued.

4.1.6 Step 6: Token endpoint validates the authorization code and issues the to-kens requested

[OIDC-16]

TheTokenendpointMUSTvalidatetheTokenRequestasdescribedinOpenIDConnectCoresection3.1.3.2includingthepresentedauthorizationcode,PKCEcode_verifierandvalueofredirect_uri parameter.

[OIDC-17]

TheTokenendpointMUSTissueanIDToken,anAcccesTokenandMAYis-sueaRefreshTokenaccordingtosection3.1.3.3ofOpenIDConnectCore.

[OIDC-18]

TheIDTokenMUSTbeaJWTtokenaccordingtotheOIOJWTProfile[OIOJWT]andincludeanat_hashclaim.TheAccessTokenandRefreshTokensareopaqueandSHOULDincludeatleast128bitofentropy.

4.1.7 Step 7: SP App validates response [OIDC-19]

TheSPAppMUSTvalidatetheresponseaccordingtosection3.1.3.5(TokenResponseValidation)ofOIDCCore.Inaddition,theat_hashvalueMUSTbe

- 17 -

validatedasspecifiedinsection3.1.3.6ofOIDCtoensurebindingbetweenAccessTokenandIDToken.

[OIDC-20]

TheSPAppMUSTvalidatethatthesignatureoftheIDTokenisvalid,thatisusesanallowedsigningalgorithmdefinedintheOIOJWTProfile[OIOJWT],andwithapinned10tokensigningcertificateoftheAuthorizationServer.ItMUSTalsoverify,thatitistheaudience(aud claim)ofthetoken.

[OIDC-21]

TheSPAppMUSTcheckthattheresultingNSISassurancelevelintheIDTo-kenlivesuptoitsrequirementsaswellasotherclaimsintheIDtokenre-quiredbytheSPApp.

Thefollowingisanon-normativeexampleofasuccessfulTokenResponse11: HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store Pragma: no-cache { "access_token": "SlAV32hkKG", "token_type": "Bearer", "refresh_token": "8xLOxBtZp8", "expires_in": 3600, "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzc yI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5 NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZ fV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5Nz AKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6q Jp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJ NqeGpe-gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7Tpd QyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoS K5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4 XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg" }

10 E.g. part of the App configuration. 11 Example from OpenID ID Connect Core – the shown id_token is not OIO JWT token compliant if de-coded.

- 18 -

5 TokenRequestProfileThischapterdescribesatokenrequestprofilebuildingontheOAuth2.0clientcre-dentialsgrantflow.Intheprofile,theSPApprequestsaServiceToken12(foraspe-cificSPAPIandwithscopescoveringthisAPI)andauthorizestherequestusinganAccessTokenfortheTokenServiceissuedduringtheAppAuthorizationProfilede-scribedinchapter4.IfmultipleAPIsaretobeaccessedbytheSPApp,multipleto-kenshavetoberequested.

TheTokenSerververifiesthatthepresentedAccessTokenisvalid,andthattheend-userhaspreviouslyauthorizedtheSPAppinstance(holdingtheAccessToken)tousetherequestedscopes(viatheconsentgatheredinstep3oftheAppAuthoriza-tionProfile).Iftherequestissuccessful,theTokenServerissuesanewtoken(Ser-viceToken)fortheAPIaccordingtothe[OIOJWT]Profile,therethescopesareen-codedasprivilegesinaJSONstructure.Seealsosection3.3forfurtherdetail.

5.1.1 Step 1: SP App sends Token Request [OIDC-51]

ThetokenrequestMUSTusethe[OAuth]2.0clientcredentialsgranttypeasdefinedinsection4.4of[OAuth].Unlessotherwisestatedexplicitly,there-quirementsfromthe[OAuth]specificationapplydirectly.

12 TheServiceTokenisanAccessToken,buthasadifferentnametodistinguishitfromtheAccessTo-kenissuedintheAppAuthorizationProfiledescribedinchapter4.

- 19 -

[OIDC-52]

TherequestparametersinthetokenrequestMUSTfulfilltherequirementsspecifiedinthetablebelow:

Parameter Man-

da-tory

Usage

client_id Y Value MUST be set to the SP App identifier (Entity ID) pre-registered with the Authorization Server.

sub Y Value MUST be the sub field (user identifier) from an ID Token issued in the App Authorization Flow described in chapter 4.

grant_type Y Value MUST be client_credentials

scope Y Value MUST contain list of scope values belonging to at most one external SP API registered with the Authorization Server.

[OIDC-53]

ThetokenrequestMUSTbeauthorizedusinganAccessTokenobtainedinpreviousAppAuthorizationFlowandprovidedviatheHTTPAuthorization headerusingtheBearer authenticationschemedefinedin[RFC6750].Seechapter4fordetails.

AsampleTokenRequestisshownbelow: POST /token HTTP/1.1 Host: server.example.com Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/x-www-form-urlencoded client_id=https%3A%2F%2Fclient.example.org%2Fcb &sub=https%3A%2F%2Fdata.gov.dk%2Fmodel%2Fcore%2Feid%2Fperson%2Fuuid%2F 123e4567-e89b-12d3-66554400 &grant_type=client_credentials &scope=xq7j%20uq2ja%20sdh34

5.1.2 Step 2: Token Server validates request and returns token [OIDC-54]

TheTokenServerMUSTverifythattheAccessTokenisvalidandisissuedtoanSPAppinstancewiththestatedclient_idtype.

[OIDC-55]

- 20 -

TheTokenServerMUSTverifytherequest,includingthatrequestedscopevalueshavebeenpreviouslybeenconsentedbytheend-userbeforetheAc-cessTokenwasissued.Further,isMUSTbeverified,thatrequestedscopesonlybelongtooneSPAPI.

[OIDC-56]

Iftherequestissuccessful,theTokenServerMUSTissueaServiceTokenac-cordingto[OIOJWT]Profilewiththerequestedscopesconvertedtoprivi-leges.Thisincludesbothuser-grantedscopesandServiceProvidergrantedscopes(seesection3.3fordetails.)

[OIDC-57]

TheServiceTokenSHOULDhaveavalidityperiodofmaximum1hour. AsampleTokenResponseisshownbelow13-notethattheServiceTokenisre-turnedintheaccess_token fieldaccordingtoOIDCconventions: HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store Pragma: no-cache { "token_type": "Bearer", "expires_in": 3600, "access_token": ”eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzc yI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5 NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZ fV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5Nz AKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6q Jp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJ NqeGpe-gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7Tpd QyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoS K5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4 XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg" }

13 Example from Open ID Connect – the shown Access Token is not OIO JWT token compliant if de-coded.

- 21 -

6 TokenRenewalProfileRefreshTokensarecredentialsusedtoobtainAccessTokens.Refreshtokensareis-suedtotheclientbytheAuthorizationServerandareusedtoobtainanewaccesstokenwhenthecurrentAccessTokenbecomesinvalidorexpires.TheprofilesdescribedinthisdocumentrelyontheprinciplethatissuedAccessandServiceTokensarerelativelyshort-lived(e.g.onehour)suchthathavetobere-freshedoften.Thisapproachhasseveralbenefits:

• Ashortvalidityperiodreducesattackwindows.• Continuouslyrefreshingtokensmeansthattheircontentcan/willbeupdated

–e.g.iftheuserhaswithdrawntheirconsenttoanApporiftheApphasbeenrevoked.

• RecipientsofAccessTokens(e.g.APIproviders)arenotburdenedwithhav-ingtocheckfortokenrevocationbycallingexternalservices.

• TokenrevocationfunctionalitycanbefocusedonRefreshTokens,whichhaveapotentiallylongervalidityperiod.ItcanbehandledinternallyintheAuthorizationandTokenServers.

WhenallAccessTokensandtheRefreshTokenhaveexpired,theSPApphastoob-tainnewtokensusingtheAppAuthorizationProfiledescribedinchapter4.Userin-teractioncanbeavoidedaslongastheRefreshTokenremainsvalid.

6.1 UsingaRefreshTokenAnSPAppwithavalidRefreshTokencanuseittoobtainanewAccessTokenfortheTokenServer,andthenusethisAccessTokentoobtainnewServiceTokensforSPAPIsusingtheprofilesdescribedpreviously.Refreshtokensareusedwiththerefresh_tokengranttypeasdescribedinsection12of[OIDC];belowisshownanexample: POST /token HTTP/1.1 Host: server.example.com Content-Type: application/x-www-form-urlencoded client_id=s6BhdRkqt3 &grant_type=refresh_token &refresh_token=8xLOxBtZp8 &scope=openid%20profile

6.2 Tokenrevocation[OIDC-61]

AuthorizationServersthatissuelong-lived(>8hours)RefreshTokensMUSTprovideamechanismtorevokethosetokensincludingatokenrevocation

- 22 -

endpointcompliantwith[RFC7009].Thus,tokenscanberevokedbymakinganHTTPPOSTrequesttothetokenendpointURLasspecifiedinthisRFC.

ThisprofiledoesnotdefinethespecificcircumstancesorpolicieswhereRefreshto-kenshavetoberevoked–onlythecapabilitytorevokethemisrequired.Examplesofcircumstancesthatcouldleadtorevocationinspecificimplementationsare:

• Auserinterfacecouldbeprovidedtotheend-usersallowingthethemtore-vokeRefreshtokensforindividualAppinstancesorallinstancesrunningonaparticulardevice(e.g.whentheuserhaslosthis/herdevice).Thismightalsobeusedbysupportpersonnelincasetheend-userhastemporarilylosttheirabilitytoauthenticate(e.g.becausetheircredentialisonthesamede-vice).

• RefreshTokensthatarenotfrequentlyusedcouldbesettoberevokedauto-matically(e.g.3monthsofinactivity).

• SPAppscanbeprogrammedtorequestrevocationwhencertaincriteriaaremetontheend-userdevice–forexampleiftheuserhaschangedbiometryontheirphone,ifawronguser-pinisenteredacertainnumberoftimes,oranindicationofcompromiseisdetected.

• Externalevents(e.g.theuserrevokingtheirusercredentialsuchasNemIDorMitID)couldbeconfiguredtoautomaticallyrevokeRefreshTokensenrolledandauthorizedwiththecredential.Othereventscouldbethattheuseriden-tityisrevoked(e.g.anemployeeidentitynolongerbeingassociatedwithacompany),oranAPIproviderrevokingallaccesstoanSPApp.

RevocationpoliciesareinternaltotheimplementationoftheAuthorizationServeranddonotaffectthewireprotocol;theyarethereforelefttoimplementationstode-cide.

- 23 -

7 APIAccessProfileThischapterdescribeshowanSPAppcaninvokeanexternalSPAPIusingaServiceTokenobtainedviathemechanismsdescribedintheTokenRequestprofileinchap-ter5. [OIDC-71]

TheSPAppMUSTpasstheServiceToken14inanAuthorizationHTTPheaderwithtokentypeBearerasdescribedin[RFC6750].

Example15:

14 The Service Token is an Access Token in OAuth sense. 15 Notethatthetokenintheexampleaboveisnotarealtokenandcannotbedecoded.

GET /resource/1 HTTP/1.1 Host: example.com Authorization: Bearer 7Fjfp0ZBr1H8JgaJs97Jb.8shJgaJs97Jb.asd&DSasdaJs97Jb

Notethatisprofileisfornowrestrictedto‘bearer’tokenswhichissufficientformostscenariosincombinationwithstrongtransportsecurity(seechapter8)andshorttokenlifetime.Thismeansasecuritytokenwiththepropertythatanypartyinpossessionofthetoken(a"bearer")canusethetokeninanywaythatanyotherpartyinpossessionofitcan.Usingabearertokendoesnotrequireabearertoprovepossessionofcryptographickeymaterial(proof-of-possession).Othermechanismsmaybeconsideredduringthefurtherdevelopmentoftheprofileincluding:

• HTTPMacAuthentication(https://tools.ietf.org/id/draft-ietf-oauth-v2-http-mac-00.html)

• Holder-of-keytokensasdefinedintheOIOIDWSRESTProfile1.0(https://digitaliser.dk/resource/526486).

• Usingthe“OpenIDConnectTokenBoundauthentication”draftspecification,whereahashofthetokenbindingIDfromtheTLSsessionsisincludedinthetoken’sconfirmationclaim(cnf).ThismechanismisbasedonTLSextensionswhichmaybeproblematictosupportinAppswheretheTLSstackisfixed.

However,noneoftheabovemechanismsseemtobewidelyimplementedandre-quiringtheirusecouldhurtinteroperabilityanduseofstandardclientlibraries.Further,theyrequiretheestablishmentofeitherasharedsymmetrickeybetweentheclientandtheserver,apublic/privatekeyparioruseTLSclientcertificateswhichcanbeproblematicwithpublicnativeclients.

- 24 -

[OIDC-72]

TheSPAPIMUSTvalidatethereceivedServiceTokenincluding(asamini-mum)thatitisnotexpired,thatitissignedbyatrustedTokenServerusinganallowedalgorithm,thattheSPAPIistheintendedaudienceofthetoken(aud field),andthatrequiredprivilegesareincluded(priv field).Seethe[OIOJWT]profilefordetails.

[OIDC-73]

TheSPAPIMUSTvalidatethatNSISassurancelevel(fortheend-userauthen-tication)describedintheAccessToken(amr field)issufficientaccordingtolocalaccesspolicy.TheSPAPIMAYalsoconsidertheauthenticationtimeoftheend-user,(auth_timefield)beforeaccessisgranted.

- 25 -

8 SecurityRequirementsThesecurityrequirementsbelowapplytoallprotocolprofilesinthisdocument.

[OIDC-81]

AlltransportcommunicationbetweentheclientSPAppandtheauthorizationinfrastructureMUSTuseTLS1.2orhigherandSHOULDonlyuseciphersuitessupportingperfectforwardsecrecy.ServersMUSTrejectnegotiationofinsecureTLSconnections.Thedocument[NIST800-52](section“MinimumRequirementsforTLSServers”)orsubsequentrevisionmayserveasrefer-enceforanacceptableleveloftransportsecurity.

[OIDC-82]

ClientsMUSTpinserverTLScertificates(e.g.maintainalistoftrustedTLSservercertificatesaspartoftheirconfiguration).

[OIDC-83]

JWTAccessTokensandServiceTokensMUSTfollowtheOIOJWTProfile[OIOJWT].

[OIDC-84]

ImplementationsMUSTfollowrequirementsin[RFC8252].

[OIDC-85]

SPAppsMUSTbetreatedaspublicnativeappclientsandMUSTNOThaveanysecretsembeddedintheirinstallationpackage.

- 26 -

9 References • [JWA] Jones,M.,“JSONWebAlgorithms(JWA),”draft-ietf-jose-json-web-algo-

rithms(workinprogress),July2014.

• [JWE] Jones,M.,Rescorla,E.,andJ.Hildebrand,“JSONWebEncryption(JWE),”draft-ietf-jose-json-web-encryption(workinprogress).

• [JWK] Jones,M.,“JSONWebKey(JWK),”draft-ietf-jose-json-web-key(workinprogress),July2014.

• [JWS] Jones,M.,Bradley,J.,andN.Sakimura,“JSONWebSignature(JWS),”draft-ietf-jose-json-web-signature(workinprogress),July2014.

• [JWT] Jones,M.,Bradley,J.,andN.Sakimura,“JSONWebToken(JWT),”draft-ietf-oauth-json-web-token(workinprogress),July2014.

• [NSIS]”NationalStandardforIdentitetersSikringsniveauer2.0.1”.https://digst.dk/it-loesninger/nemlog-in/det-kommende-nemlog-in/vejledninger-og-standarder/nsis-standarden/

• [OIOSAML] ”OIOSAMLWebSSOProfile3.0”.https://digst.dk/it-loesninger/nemlog-in/det-kommende-nemlog-in/vejledninger-og-standarder/oiosaml-30/

• [OIO-BPP]”OIOBasicPrivilegeProfile1.1”.https://www.digitaliser.dk/resource/2377872

• [RFC6819]“OAuth2.0ThreatModelandSecurityConsiderations”,IETF.https://tools.ietf.org/html/rfc6819

• [RFC8252]“OAuth2.0forNativeApps”,IETF.

• [RFC6750]“TheOAuth2.0AuthorizationFramework:BearerTokenUsage”,IETF,https://tools.ietf.org/html/rfc6750

• [RFC7009]”OAuth2.0TokenRevocation”,IETF.

• [OIDC]“OpenIDConnectCore1.0incorporatingerrataset1,November2014”,OpenID.Net.

• [OAuth]“TheOAuth2.0AuthorizationFramework”,RFC6749,IETF,October2012.

• [OIOJWT]“OIOJWTTokenProfile”,DanishAgencyforDigitisation.

• [NSIS]“NationalStandardforIdentitetersSikringsniveauer2.0.1”,Digitaliseringsstyrelsen.https://digst.dk/it-loesninger/nemlog-in/det-kommende-nemlog-in/vejledninger-og-standarder/nsis-standarden/