2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.

0draft37

Draft N.Sakimura TOC

NRI
J.Bradley
PingIdentity
M.Jones
Microsoft
B.deMedeiros
Google
C.Mortimore
Salesforce
August3,2015

OpenIDConnectBasicClientImplementer'sGuide
1.0draft37
Abstract

OpenIDConnect1.0isasimpleidentitylayerontopoftheOAuth2.0protocol.Itenables
ClientstoverifytheidentityoftheEndUserbasedontheauthenticationperformedbyan
AuthorizationServer,aswellastoobtainbasicprofileinformationabouttheEndUserin
aninteroperableandRESTlikemanner.

ThisOpenIDConnectBasicClientImplementer'sGuide1.0containsasubsetoftheOpenID
ConnectCore1.0specificationthatisdesignedtobeeasytoreadandimplementforbasic
WebbasedRelyingPartiesusingtheOAuthAuthorizationCodeFlow.Thisdocument
intentionallyduplicatescontentfromtheCorespecificationtoprovideaselfcontained
implementer'sguideforbasicWebbasedRelyingPartiesusingtheOAuthAuthorization
CodeFlow.

OpenIDProvidersandnonWebbasedapplicationsshouldinsteadconsulttheCore
specification.

TableofContents

1.Introduction
1.1.RequirementsNotationandConventions
1.2.Terminology
1.3.Overview
2.ProtocolElements
2.1.CodeFlow
2.1.1.ClientPreparesAuthenticationRequest
2.1.1.1.RequestParameters
2.1.2.ClientSendsRequesttoAuthorizationServer
2.1.3.AuthorizationServerAuthenticatesEndUser
2.1.4.AuthorizationServerObtainsEndUserConsent/Authorization
2.1.5.AuthorizationServerSendsEndUserBacktoClient
2.1.5.1.EndUserGrantsAuthorization
2.1.5.2.EndUserDeniesAuthorizationorInvalidRequest
2.1.6.ClientObtainsIDTokenandAccessToken
2.1.6.1.ClientSendsCode
2.1.6.2.ClientReceivesTokens
2.2.IDToken
2.2.1.IDTokenValidation
2.3.UserInfoEndpoint
2.3.1.UserInfoRequest
2.3.2.SuccessfulUserInfoResponse
2.3.3.UserInfoErrorResponse

http://openid.net/specs/openidconnectbasic1_0.html 1/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37

2.4.ScopeValues
2.5.StandardClaims
2.5.1.AddressClaim
2.5.2.ClaimsLanguagesandScripts
2.5.3.ClaimStabilityandUniqueness
3.Serializations
3.1.QueryStringSerialization
3.2.FormSerialization
4.StringOperations
5.TLSVersion
6.ImplementationConsiderations
6.1.DiscoveryandRegistration
7.SecurityConsiderations
7.1.TLSRequirements
8.PrivacyConsiderations
8.1.PersonallyIdentifiableInformation
8.2.DataAccessMonitoring
8.3.Correlation
8.4.OfflineAccess
9.IANAConsiderations
10.References
10.1.NormativeReferences
10.2.InformativeReferences
AppendixA.Acknowledgements
AppendixB.Notices
AppendixC.DocumentHistory
Authors'Addresses

TOC
1.Introduction

ThisOpenIDConnectBasicClientImplementer'sGuide1.0containsasubsetofthe
OpenIDConnectCore1.0[OpenID.Core]specificationthatisdesignedtobeeasytoread
andimplementforbasicWebbasedRelyingPartiesusingtheOAuth2.0 [RFC6749]
AuthorizationCodeFlow.ThisdocumentintentionallyduplicatescontentfromtheCore
specificationtoprovideaselfcontainedimplementer'sguideforbasicWebbasedRelying
PartiesusingtheOAuthAuthorizationCodeFlow.Shouldtherebeanyconflictsbetween
thecontentsofthisimplementer'sguideandtheOpenIDConnectCorespecification,the
lattertakesprecedence.

Seethe OpenIDConnectImplicitClientImplementer'sGuide1.0[OpenID.Implicit]for
arelatedguideforbasicWebbasedRelyingPartiesusingtheOAuthImplicitFlow.OpenID
ProvidersandnonWebbasedapplicationsshouldinsteadconsulttheCorespecification.
ThisguideomitsimplementationandsecurityconsiderationsforOpenIDProvidersand
nonWebbasedapplications.

Asbackground,the OAuth2.0AuthorizationFramework[RFC6749]and OAuth2.0

BearerTokenUsage[RFC6750]specificationsprovideageneralframeworkforthird
partyapplicationstoobtainanduselimitedaccesstoHTTPresources.Theydefine
mechanismstoobtainanduseAccessTokenstoaccessresourcesbutdonotdefine
standardmethodstoprovideidentityinformation.Notably,withoutprofilingOAuth2.0,it
isincapableofprovidinginformationabouttheauthenticationofanEndUser.Readersare
expectedtobefamiliarwiththesespecifications.

OpenIDConnectimplementsauthenticationasanextensiontotheOAuth2.0authorization
process.UseofthisextensionisrequestedbyClientsbyincludingtheopenidscopevalue
intheAuthorizationRequest.AnAuthorizationRequestusingtheseextensionsiscalledan
AuthenticationRequest.

Informationabouttheauthenticationperformedisreturnedina JSONWebToken(JWT)
[JWT]calledanIDToken(see Section2.2).OAuth2.0AuthenticationServers
implementingOpenIDConnectarealsoreferredtoasOpenIDProviders(OPs).OAuth2.0
ClientsusingOpenIDConnectarealsoreferredtoasRelyingParties(RPs).

http://openid.net/specs/openidconnectbasic1_0.html 2/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37

ThisdocumentassumesthattheRelyingPartyhasalreadyobtainedconfiguration
informationabouttheOpenIDProvider,includingitsAuthorizationEndpointandToken
Endpointlocations.ThisinformationisnormallyobtainedviaDiscovery,asdescribedin
OpenIDConnectDiscovery1.0[OpenID.Discovery],ormaybeobtainedviaother
mechanisms.

Likewise,thisdocumentassumesthattheRelyingPartyhasalreadyobtainedsufficient
credentialsandprovidedinformationneededtousetheOpenIDProvider.Thisisnormally
doneviaDynamicRegistration,asdescribedin OpenIDConnectDynamicClient
Registration1.0[OpenID.Registration],ormaybeobtainedviaothermechanisms.

TOC
1.1.RequirementsNotationandConventions

Thekeywords"MUST","MUSTNOT","REQUIRED","SHALL","SHALLNOT","SHOULD",
"SHOULDNOT","RECOMMENDED","NOTRECOMMENDED","MAY",and"OPTIONAL"inthis
documentaretobeinterpretedasdescribedin [RFC2119].

Inthe.txtversionofthisdocument,valuesarequotedtoindicatethattheyaretobe
takenliterally.Whenusingthesevaluesinprotocolmessages,thequotesMUSTNOTbe
usedaspartofthevalue.IntheHTMLversionofthisdocument,valuestobetaken
literallyareindicatedbytheuseofthisfixedwidthfont.

Allusesof JSONWebSignature(JWS)[JWS]datastructuresinthisdocumentutilizethe
JWSCompactSerializationtheJWSJSONSerializationisnotused.

WhentheRFC2119languageappliestothebehaviorofOpenIDProviders,itisinthis
documentforexplanatoryvaluetohelpClientimplementersunderstandtheexpected
behaviorofOpenIDProviders.

TOC
1.2.Terminology

Thisdocumentusestheterms"AccessToken","AuthorizationCode","Authorization
Endpoint","AuthorizationGrant","AuthorizationServer","Client","ClientAuthentication",
"ClientIdentifier","ClientSecret","GrantType","ProtectedResource","RedirectionURI",
"RefreshToken","ResourceOwner","ResourceServer","ResponseType",and"Token
Endpoint"definedby OAuth2.0[RFC6749],theterms"ClaimName","ClaimValue",
"JSONWebToken(JWT)",and"JWTClaimsSet"definedby JSONWebToken(JWT)
[JWT],theterms"HeaderParameter"and"JOSEHeader"definedby JSONWeb
Signature(JWS)[JWS],andtheterm"UserAgent"definedby RFC7230[RFC7230].

Thisdocumentalsodefinesthefollowingterms:

Authentication
ProcessusedtoachievesufficientconfidenceinthebindingbetweentheEntity
andthepresentedIdentity.
AuthenticationRequest
OAuth2.0AuthorizationRequestusingextensionparametersandscopesdefined
byOpenIDConnecttorequestthattheEndUserbeauthenticatedbythe
AuthorizationServer,whichisanOpenIDConnectProvider,totheClient,which
isanOpenIDConnectRelyingParty.
Claim
PieceofinformationassertedaboutanEntity.
ClaimsProvider
ServerthatcanreturnClaimsaboutanEntity.
EndUser
Humanparticipant.
Entity
Somethingthathasaseparateanddistinctexistenceandthatcanbeidentified
inacontext.AnEndUserisoneexampleofanEntity.
IDToken

http://openid.net/specs/openidconnectbasic1_0.html 3/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37

JSONWebToken(JWT)[JWT]thatcontainsClaimsabouttheAuthentication
event.ItMAYcontainotherClaims.
Identifier
ValuethatuniquelycharacterizesanEntityinaspecificcontext.
Issuer
EntitythatissuesasetofClaims.
IssuerIdentifier
VerifiableIdentifierforanIssuer.AnIssuerIdentifierisacasesensitiveURL
usingthehttpsschemethatcontainsscheme,host,andoptionally,portnumber
andpathcomponentsandnoqueryorfragmentcomponents.
OpenIDProvider(OP)
OAuth2.0AuthorizationServerthatiscapableofAuthenticatingtheEndUser
andprovidingClaimstoaRelyingPartyabouttheAuthenticationeventandthe
EndUser.
PairwisePseudonymousIdentifier(PPID)
IdentifierthatidentifiestheEntitytoaRelyingPartythatcannotbecorrelated
withtheEntity'sPPIDatanotherRelyingParty.
PersonallyIdentifiableInformation(PII)
Informationthat(a)canbeusedtoidentifythenaturalpersontowhomsuch
informationrelates,or(b)isormightbedirectlyorindirectlylinkedtoanatural
persontowhomsuchinformationrelates.
RelyingParty(RP)
OAuth2.0ClientapplicationrequiringEndUserAuthenticationandClaimsfrom
anOpenIDProvider.
SubjectIdentifier
LocallyuniqueandneverreassignedidentifierwithintheIssuerfortheEnd
User,whichisintendedtobeconsumedbytheClient.
UserInfoEndpoint
ProtectedResourcethat,whenpresentedwithanAccessTokenbytheClient,
returnsauthorizedinformationabouttheEndUserrepresentedbythe
correspondingAuthorizationGrant.
Validation
Processintendedtoestablishthesoundnessorcorrectnessofaconstruct.
Verification
Processintendedtotestorprovethetruthoraccuracyofafactorvalue.
VoluntaryClaim
ClaimspecifiedbytheClientasbeingusefulbutnotEssentialforthespecific
taskrequestedbytheEndUser.

IMPORTANTNOTETOREADERS:Theterminologydefinitionsinthissectionareanormative
portionofthisdocument,imposingrequirementsuponimplementations.Allthecapitalized
wordsinthetextofthisdocument,suchas"IssuerIdentifier",referencethesedefined
terms.Wheneverthereaderencountersthem,theirdefinitionsfoundinthissectionmust
befollowed.

TOC
1.3.Overview

TheOpenIDConnectprotocol,inabstract,followsthefollowingsteps.

1.TheRP(Client)sendsarequesttotheOpenIDProvider(OP).
2.TheOPauthenticatestheEndUserandobtainsauthorization.
3.TheOPrespondswithanIDTokenandusuallyanAccessToken.
4.TheRPcansendarequestwiththeAccessTokentotheUserInfoEndpoint.
5.TheUserInfoEndpointreturnsClaimsabouttheEndUser.

Thesestepsareillustratedinthefollowingdiagram:

++++
||||
||(1)AuthNRequest>||
||||
||++||

http://openid.net/specs/openidconnectbasic1_0.html 4/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37

||||||
|||End|<(2)AuthN&AuthZ>||
|||User|||
|RP||||OP|
||++||
||||
||<(3)AuthNResponse||
||||
||(4)UserInfoRequest>||
||||
||<(5)UserInfoResponse||
||||
++++

TOC
2.ProtocolElements

AuthenticationRequestscanfollowoneofthreepaths:theAuthorizationCodeFlow,the
ImplicitFlow,ortheHybridFlow.TheAuthorizationCodeFlowisintendedforClientsthat
cansecurelymaintainaClientSecretbetweenthemselvesandtheAuthorizationServer,
whereastheImplicitFlowisintendedforClientsthatcannot.However,theAuthorization
CodeflowissometimesalsousedbyNativeapplicationsandotherClientsinordertobe
abletoobtainaRefreshToken,evenwhentheycannotensurethesecrecyoftheClient
Secretvalue.TheHybridFlowcombinesaspectsoftheAuthorizationCodeFlowandthe
ImplicitFlow.ItenablesClientstoobtainanIDTokenandoptionallyanAccessTokenwith
onlyoneroundtriptotheAuthorizationServer,possiblyminimizinglatency,whilestill
enablingClientstolatergettokensfromtheTokenEndpointespeciallyaRefreshToken.

ThisdocumentonlyprovidesinformationthatissufficientforbasicClientsusingtheCode
Flow.

TOC
2.1.CodeFlow

TheCodeFlowconsistsofthefollowingsteps:

1.ClientpreparesanAuthenticationRequestcontainingthedesiredrequest
parameters.
2.ClientsendstherequesttotheAuthorizationServer.
3.AuthorizationServerauthenticatestheEndUser.
4.AuthorizationServerobtainsEndUserConsent/Authorization.
5.AuthorizationServersendstheEndUserbacktotheClientwithcode.
6.ClientsendsthecodetotheTokenEndpointtoreceiveanAccessTokenandID
Tokenintheresponse.
7.ClientvalidatesthetokensandretrievestheEndUser'sSubjectIdentifier.

TOC
2.1.1.ClientPreparesAuthenticationRequest

WhentheRPwishestoAuthenticatetheEndUserordeterminewhethertheEndUseris
alreadyAuthenticated,theClientpreparesanAuthenticationRequesttobesenttothe
AuthorizationEndpoint.

CommunicationwiththeAuthorizationEndpointMUSTutilizeTLS.See Section7.1for
moreinformationonusingTLS.

ClientsMAYconstructtherequestusingtheHTTPGETortheHTTPPOSTmethodasdefined
in RFC7231[RFC7231].

IfusingtheHTTPGETmethod,theparametersareserializedusingtheQueryString
Serialization,per Section3.1.IfusingtheHTTPPOSTmethod,therequestparametersare

http://openid.net/specs/openidconnectbasic1_0.html 5/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37

addedtotheHTTPrequestentitybodyusingtheapplication/xwwwformurlencoded
formatasdefinedby [W3C.REChtml40119991224].

ThefollowingisanonnormativeexampleofanAuthenticationRequestURL(withline
wrapswithinvaluesfordisplaypurposesonly):

https://server.example.com/authorize?
response_type=code
&client_id=s6BhdRkqt3
&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
&scope=openid%20profile
&state=af0ifjsldkj

TOC
2.1.1.1.RequestParameters

ThissubsetofOpenIDConnectusesthefollowingOAuth2.0requestparameters:

response_type
REQUIRED.ThisvalueMUSTbecode.ThisrequeststhatbothanAccessToken
andanIDTokenbereturnedfromtheTokenEndpointinexchangeforthecode
valuereturnedfromtheAuthorizationEndpoint.
client_id
REQUIRED.OAuth2.0ClientIdentifiervalidattheAuthorizationServer.
scope
REQUIRED.OpenIDConnectrequestsMUSTcontaintheopenidscopevalue.
OPTIONALscopevaluesofprofile,email,address,phone,and
offline_accessarealsodefined.See Section2.4formoreaboutthescope
valuesdefinedbythisdocument.
redirect_uri
REQUIRED.RedirectionURItowhichtheresponsewillbesent.ThisURIMUST
exactlymatchoneoftheRedirectionURIvaluesfortheClientpreregisteredat
theOpenIDProvider,withthematchingperformedasdescribedinSection6.2.1
of [RFC3986](SimpleStringComparison).TheRedirectionURISHOULDusethe
httpsschemehowever,itMAYusethehttpscheme,providedthattheClient
Typeisconfidential,asdefinedinSection2.1ofOAuth2.0,andprovidedthe
OPallowstheuseofhttpRedirectionURIsinthiscase.TheRedirectionURI
MAYuseanalternatescheme,suchasonethatisintendedtoidentifyacallback
intoanativeapplication.
state
RECOMMENDED.Opaquevalueusedtomaintainstatebetweentherequestand
thecallback.Typically,CrossSiteRequestForgery(CSRF,XSRF)mitigationis
donebycryptographicallybindingthevalueofthisparameterwithabrowser
cookie.

Thisdocumentalsodefinesthefollowingrequestparameters:

nonce
OPTIONAL.StringvalueusedtoassociateaClientsessionwithanIDToken,and
tomitigatereplayattacks.Thevalueispassedthroughunmodifiedfromthe
AuthenticationRequesttotheIDToken.SufficiententropyMUSTbepresentin
thenoncevaluesusedtopreventattackersfromguessingvalues.Onemethod
toachievethisistostoreacryptographicallyrandomvalueasanHttpOnlya
sessioncookieanduseacryptographichashofthevalueasthenonce
parameter.Inthatcase,thenonceinthereturnedIDTokeniscomparedtothe
hashofthesessioncookietodetectIDTokenreplaybythirdparties.Useofthe
nonceisOPTIONALwhenusingthecodeflow.
display
OPTIONAL.ASCII [RFC20]stringvaluethatspecifieshowtheAuthorization
ServerdisplaystheauthenticationandconsentuserinterfacepagestotheEnd
User.Thedefinedvaluesare:

page
http://openid.net/specs/openidconnectbasic1_0.html 6/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37

TheAuthorizationServerSHOULDdisplaytheauthentication
andconsentUIconsistentwithafullUserAgentpageview.If
thedisplayparameterisnotspecified,thisisthedefault
displaymode.
popup
TheAuthorizationServerSHOULDdisplaytheauthentication
andconsentUIconsistentwithapopupUserAgentwindow.
ThepopupUserAgentwindowshouldbeofanappropriatesize
foraloginfocuseddialogandshouldnotobscuretheentire
windowthatitispoppingupover.
touch
TheAuthorizationServerSHOULDdisplaytheauthentication
andconsentUIconsistentwithadevicethatleveragesatouch
interface.
wap
TheAuthorizationServerSHOULDdisplaytheauthentication
andconsentUIconsistentwitha"featurephone"typedisplay.

TheAuthorizationServerMAYalsoattempttodetectthecapabilitiesoftheUser
Agentandpresentanappropriatedisplay.
prompt
OPTIONAL.Spacedelimited,casesensitivelistofASCIIstringvaluesthat
specifieswhethertheAuthorizationServerpromptstheEndUserfor
reauthenticationandconsent.Thedefinedvaluesare:

none
TheAuthorizationServerMUSTNOTdisplayanyauthentication
orconsentuserinterfacepages.Anerrorisreturnedifan
EndUserisnotalreadyauthenticatedortheClientdoesnot
havepreconfiguredconsentfortherequestedClaimsordoes
notfulfillotherconditionsforprocessingtherequest.The
errorcodewilltypicallybelogin_required,
interaction_required.Thiscanbeusedasamethodto
checkforexistingauthenticationand/orconsent.
login
TheAuthorizationServerSHOULDprompttheEndUserfor
reauthentication.IfitcannotreauthenticatetheEndUser,it
MUSTreturnanerror,typicallylogin_required.
consent
TheAuthorizationServerSHOULDprompttheEndUserfor
consentbeforereturninginformationtotheClient.Ifitcannot
obtainconsent,itMUSTreturnanerror,typically
consent_required.
select_account
TheAuthorizationServerSHOULDprompttheEndUserto
selectauseraccount.ThisenablesanEndUserwhohas
multipleaccountsattheAuthorizationServertoselect
amongstthemultipleaccountsthattheymighthavecurrent
sessionsfor.Ifitcannotobtainanaccountselectionchoice
madebytheEndUser,itMUSTreturnanerror,typically
account_selection_required.

ThepromptparametercanbeusedbytheClienttomakesurethattheEndUser
isstillpresentforthecurrentsessionortobringattentiontotherequest.Ifthis
parametercontainsnonewithanyothervalue,anerrorisreturned.
max_age
OPTIONAL.MaximumAuthenticationAge.Specifiestheallowableelapsedtimein
secondssincethelasttimetheEndUserwasactivelyauthenticatedbytheOP.If
theelapsedtimeisgreaterthanthisvalue,theOPMUSTattempttoactivelyre
authenticatetheEndUser.Whenmax_ageisused,theIDTokenreturnedMUST
includeanauth_timeClaimValue.
ui_locales
OPTIONAL.EndUser'spreferredlanguagesandscriptsfortheuserinterface,
representedasaspaceseparatedlistof BCP47[RFC5646]languagetagvalues,
orderedbypreference.Forinstance,thevalue"frCAfren"representsa
http://openid.net/specs/openidconnectbasic1_0.html 7/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37

preferenceforFrenchasspokeninCanada,thenFrench(withoutaregion
designation),followedbyEnglish(withoutaregiondesignation).Anerror
SHOULDNOTresultifsomeoralloftherequestedlocalesarenotsupportedby
theOpenIDProvider.
claims_locales
OPTIONAL.EndUser'spreferredlanguagesandscriptsforClaimsbeing
returned,representedasaspaceseparatedlistof BCP47[RFC5646]language
tagvalues,orderedbypreference.AnerrorSHOULDNOTresultifsomeorallof
therequestedlocalesarenotsupportedbytheOpenIDProvider.
id_token_hint
OPTIONAL.IDTokenpreviouslyissuedbytheAuthorizationServerbeingpassed
asahintabouttheEndUser'scurrentorpastauthenticatedsessionwiththe
Client.IftheEndUseridentifiedbytheIDTokenisloggedinorisloggedinby
therequest,thentheAuthorizationServerreturnsapositiveresponse
otherwise,itSHOULDreturnanerror.Whenpossible,anid_token_hint
SHOULDbepresentwhenprompt=noneisusedandaninvalid_requesterror
MAYbereturnedifitisnothowever,theserverSHOULDrespondsuccessfully
whenpossible,evenifitisnotpresent.TheAuthorizationServerneednotbe
listedasanaudienceoftheIDTokenwhenitisusedasanid_token_hint
value.
login_hint
OPTIONAL.HinttotheAuthorizationServerabouttheloginidentifiertheEnd
Usermightusetologin(ifnecessary).ThishintcanbeusedbyanRPifitfirst
askstheEndUserfortheiremailaddress(orotheridentifier)andthenwants
topassthatvalueasahinttothediscoveredauthorizationservice.Itis
RECOMMENDEDthatthehintvaluematchthevalueusedfordiscovery.This
valueMAYalsobeaphonenumberintheformatspecifiedforthephone_number
Claim.TheuseofthisparameterislefttotheOP'sdiscretion.
acr_values
OPTIONAL.RequestedAuthenticationContextClassReferencevalues.Space
separatedstringthatspecifiestheacrvaluesthattheAuthorizationServeris
beingrequestedtouseforprocessingthisauthenticationrequest,withthe
valuesappearinginorderofpreference.TheAuthenticationContextClass
satisfiedbytheauthenticationperformedisreturnedastheacrClaimValue,as
specifiedin Section2.2.TheacrClaimisrequestedasaVoluntaryClaimby
thisparameter.

TOC
2.1.2.ClientSendsRequesttoAuthorizationServer

HavingconstructedtheAuthenticationRequest,theClientsendsittotheAuthorization
EndpointusingHTTPS.

ThefollowingisanonnormativeexampleHTTP302redirectresponsebytheClient,which
triggerstheUserAgenttomakeanAuthenticationRequesttotheAuthorizationEndpoint
(withlinewrapswithinvaluesfordisplaypurposesonly):

HTTP/1.1302Found
Location:https://server.example.com/authorize?
response_type=code
&client_id=s6BhdRkqt3
&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
&scope=openid%20profile
&state=af0ifjsldkj

ThefollowingisthenonnormativeexamplerequestthatwouldbesentbytheUserAgent
totheAuthorizationServerinresponsetotheHTTP302redirectresponsebytheClient
above(withlinewrapswithinvaluesfordisplaypurposesonly):

GET/authorize?
response_type=code
http://openid.net/specs/openidconnectbasic1_0.html 8/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37

&client_id=s6BhdRkqt3
&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
&scope=openid%20profile
&state=af0ifjsldkjHTTP/1.1
Host:server.example.com

TOC
2.1.3.AuthorizationServerAuthenticatesEndUser

TheAuthorizationServerlogsintheEndUserorverifieswhethertheEndUserislogged
in,dependingupontherequestparametervaluesused.IfinteractionwiththeEndUser
occursoveranHTTPchannel,itMUSTuseTLS,asper Section7.1.Theexact
authenticationmethodsusedareoutofscopeforthisdocument.

TOC
2.1.4.AuthorizationServerObtainsEndUserConsent/Authorization

TheAuthorizationServerobtainsanauthorizationdecisionfortherequestedClaims.This
candonebypresentingtheEndUserwithadialoguethatenablestheEndUserto
recognizewhatisbeingconsentingtoandgrantconsentorbyestablishingconsentvia
othermeans(forexample,viapreviousadministrativeconsent).

TheopenidscopevaluedeclaresthatthisOAuth2.0requestisanOpenIDConnect
request.UseofallotherscopevaluesisOPTIONAL.

TOC
2.1.5.AuthorizationServerSendsEndUserBacktoClient

Oncetheauthorizationisdetermined,theAuthorizationServerreturnsasuccessful
responseoranerrorresponse.

TOC
2.1.5.1.EndUserGrantsAuthorization

IftheEndUsergrantstheaccessrequest,theAuthorizationServerissuesacodeand
deliversittotheClientbyaddingthefollowingqueryparameterstothequerycomponent
oftheRedirectionURIusingtheapplication/xwwwformurlencodedformatasdefined
inSection4.1.2of OAuth2.0[RFC6749].

code
REQUIRED.OAuth2.0AuthorizationCode.
state
OAuth2.0statevalue.REQUIREDifthestateparameterispresentinthe
AuthorizationRequest.ClientsMUSTverifythatthestatevalueisequaltothe
valueofstateparameterintheAuthorizationRequest.

Thefollowingisanonnormativeexample(withlinewrapsforthedisplaypurposesonly):

HTTP/1.1302Found
Location:https://client.example.org/cb?
code=SplxlOBeZQQYbYS6WxSbIA
&state=af0ifjsldkj

TOC
2.1.5.2.EndUserDeniesAuthorizationorInvalidRequest

http://openid.net/specs/openidconnectbasic1_0.html 9/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37

IftheEndUserdeniestheauthorizationortheEndUserauthenticationfails,the
AuthorizationServerMUSTreturntheerrorAuthorizationResponseasdefinedin4.1.2.1
of OAuth2.0[RFC6749].(HTTPerrorsunrelatedtoRFC6749arereturnedtotheUser
AgentusingtheappropriateHTTPstatuscode.)

TOC
2.1.6.ClientObtainsIDTokenandAccessToken

TheClientthenmakesanAccessTokenRequestusingtheAuthorizationCodetoobtain
tokensfromtheTokenEndpointinthefollowingmanner:

TOC
2.1.6.1.ClientSendsCode

AClientmakesaTokenRequestbypresentingitsAuthorizationGrant(intheformofan
AuthorizationCode)totheTokenEndpointusingthegrant_typevalue
authorization_code,asdescribedinSection4.1.3of OAuth2.0[RFC6749].TheClient
MUSTauthenticatetotheTokenEndpointusingtheHTTPBasicmethod,asdescribedin
2.3.1ofOAuth2.0.(Thismethodistheoneidentifiedbyusingtheclient_secret_basic
authenticationmethodvaluein OpenIDConnectDiscovery1.0[OpenID.Discovery]).

TheClientsendstheparameterstotheTokenEndpointusingtheHTTPPOSTmethodand
theFormSerialization,per Section3.2,asdescribedinSection4.1.3of OAuth2.0
[RFC6749].

CommunicationwiththeTokenEndpointMUSTutilizeTLS.See Section7.1formore
informationonusingTLS.

ThefollowingisanonnormativeexampleofsuchaTokenRequest(withlinewrapsforthe
displaypurposesonly):

POST/tokenHTTP/1.1
Host:server.example.com
Authorization:BasicczZCaGRSa3F0MzpnWDFmQmF0M2JW
ContentType:application/xwwwformurlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

TOC
2.1.6.2.ClientReceivesTokens

TheClientreceivesaresponsewiththefollowingparametersasdescribedinSection4.1.4
of OAuth2.0[RFC6749].TheresponseSHOULDbeencodedusingUTF8 [RFC3629].

access_token
REQUIRED.AccessTokenfortheUserInfoEndpoint.
token_type
REQUIRED.OAuth2.0TokenTypevalue.ThevalueMUSTbeBearer,as
specifiedin OAuth2.0BearerTokenUsage[RFC6750],forClientsusingthis
subset.
id_token
REQUIRED.IDToken.
expires_in
OPTIONAL.ExpirationtimeoftheAccessTokeninsecondssincetheresponse
wasgenerated.
refresh_token
OPTIONAL.RefreshToken.

http://openid.net/specs/openidconnectbasic1_0.html 10/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37

TheClientcanthenusetheAccessTokentoaccessprotectedresourcesatResource
Servers.

Thefollowingisanonnormativeexample(withlinewrapsforthedisplaypurposesonly):

HTTP/1.1200OK
ContentType:application/json
CacheControl:nocache,nostore
Pragma:nocache

{
"access_token":"SlAV32hkKG",
"token_type":"Bearer",
"expires_in":3600,
"refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
"id_token":"eyJ0...NiJ9.eyJ1c...I6IjIifX0.DeWt4Qu...ZXso"
}

TOC
2.2.IDToken

TheIDTokenisasecuritytokenthatcontainsClaimsabouttheauthenticationofanEnd
UserbyanAuthorizationServerwhenusingaClient,andpotentiallyotherrequested
Claims.TheIDTokenisrepresentedasa JSONWebToken(JWT)[JWT].

ThefollowingClaimsareusedwithintheIDToken:

iss
REQUIRED.IssuerIdentifierfortheIssueroftheresponse.Theissvalueisa
casesensitiveURLusingthehttpsschemethatcontainsscheme,host,and
optionally,portnumberandpathcomponentsandnoqueryorfragment
components.
sub
REQUIRED.SubjectIdentifier.Locallyuniqueandneverreassignedidentifier
withintheIssuerfortheEndUser,whichisintendedtobeconsumedbythe
Client,e.g.,24400320orAItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4.It
MUSTNOTexceed255ASCIIcharactersinlength.Thesubvalueisacase
sensitivestring.
aud
REQUIRED.Audience(s)thatthisIDTokenisintendedfor.ItMUSTcontainthe
OAuth2.0client_idoftheRelyingPartyasanaudiencevalue.ItMAYalso
containidentifiersforotheraudiences.Inthegeneralcase,theaudvalueisan
arrayofcasesensitivestrings.Inthecommonspecialcasewhenthereisone
audience,theaudvalueMAYbeasinglecasesensitivestring.
exp
REQUIRED.ExpirationtimeonorafterwhichtheIDTokenMUSTNOTbe
acceptedforprocessing.Theprocessingofthisparameterrequiresthatthe
currentdate/timeMUSTbebeforetheexpirationdate/timelistedinthevalue.
ImplementersMAYprovideforsomesmallleeway,usuallynomorethanafew
minutes,toaccountforclockskew.ItsvalueisaJSON [RFC7159]number
representingthenumberofsecondsfrom19700101T00:00:00Zasmeasuredin
UTCuntilthedate/time.See RFC3339[RFC3339]fordetailsregarding
date/timesingeneralandUTCinparticular.
iat
REQUIRED.TimeatwhichtheJWTwasissued.ItsvalueisaJSONnumber
representingthenumberofsecondsfrom19700101T00:00:00Zasmeasuredin
UTCuntilthedate/time.
auth_time
TimewhentheEndUserauthenticationoccurred.ItsvalueisaJSONnumber
representingthenumberofsecondsfrom19700101T00:00:00Zasmeasuredin
UTCuntilthedate/time.Whenamax_agerequestismadethenthisClaimis
REQUIREDotherwise,itsinclusionisOPTIONAL.

http://openid.net/specs/openidconnectbasic1_0.html 11/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37

nonce
OPTIONAL.StringvalueusedtoassociateaClientsessionwithanIDToken,and
tomitigatereplayattacks.Thevalueispassedthroughunmodifiedfromthe
AuthenticationRequesttotheIDToken.TheClientMUSTverifythatthenonce
ClaimValueisequaltothevalueofthenonceparametersentinthe
AuthenticationRequest.IfpresentintheAuthenticationRequest,Authorization
ServersMUSTincludeanonceClaimintheIDTokenwiththeClaimValuebeing
thenoncevaluesentintheAuthenticationRequest.Thenoncevalueisacase
sensitivestring.
at_hash
OPTIONAL.AccessTokenhashvalue.ThisisOPTIONALwhentheIDTokenis
issuedfromtheTokenEndpoint,whichisthecaseforthissubsetofOpenID
Connectnonetheless,anat_hashClaimMAYbepresent.Itsvalueisthe
base64urlencodingoftheleftmosthalfofthehashoftheoctetsoftheASCII
representationoftheaccess_tokenvalue,wherethehashalgorithmusedisthe
hashalgorithmusedinthealgHeaderParameteroftheIDToken'sJOSE
Header.Forinstance,ifthealgisRS256,hashtheaccess_tokenvaluewith
SHA256,thentaketheleftmost128bitsandbase64urlencodethem.The
at_hashvalueisacasesensitivestring.
acr
OPTIONAL.AuthenticationContextClassReference.Stringspecifyingan
AuthenticationContextClassReferencevaluethatidentifiestheAuthentication
ContextClassthattheauthenticationperformedsatisfied.Thevalue"0"
indicatestheEndUserauthenticationdidnotmeettherequirementsof ISO/IEC
29115[ISO29115]level1.Authenticationusingalonglivedbrowsercookie,for
instance,isoneexamplewheretheuseof"level0"isappropriate.
Authenticationswithlevel0SHOULDNOTbeusedtoauthorizeaccesstoany
resourceofanymonetaryvalue.AnabsoluteURIoran RFC6711[RFC6711]
registerednameSHOULDbeusedastheacrvalueregisterednamesMUST
NOTbeusedwithadifferentmeaningthanthatwhichisregistered.Parties
usingthisclaimwillneedtoagreeuponthemeaningsofthevaluesused,which
maybecontextspecific.Theacrvalueisacasesensitivestring.
amr
OPTIONAL.AuthenticationMethodsReferences.JSONarrayofstringsthatare
identifiersforauthenticationmethodsusedintheauthentication.Forinstance,
valuesmightindicatethatbothpasswordandOTPauthenticationmethodswere
used.ThedefinitionofparticularvaluestobeusedintheamrClaimisbeyond
thescopeofthisdocument.Partiesusingthisclaimwillneedtoagreeuponthe
meaningsofthevaluesused,whichmaybecontextspecific.Theamrvalueisan
arrayofcasesensitivestrings.
azp
OPTIONAL.AuthorizedpartythepartytowhichtheIDTokenwasissued.If
present,itMUSTcontaintheOAuth2.0ClientIDofthisparty.ThisClaimisonly
neededwhentheIDTokenhasasingleaudiencevalueandthataudienceis
differentthantheauthorizedparty.ItMAYbeincludedevenwhentheauthorized
partyisthesameasthesoleaudience.Theazpvalueisacasesensitivestring
containingaStringOrURIvalue.

IDTokensMAYcontainotherClaims.AnyClaimsusedthatarenotunderstoodMUSTbe
ignored.

IDTokensSHOULDNOTusetheJWSorJWEx5u,x5c,jku,orjwkHeaderParameter
fields.Instead,keysusedforIDTokensarecommunicatedinadvanceusingDiscoveryand
Registrationparameters.

ThefollowingisanonnormativeexampleofthesetofClaims(theJWTClaimsSet)
base64urldecodedfromanIDToken:

{
"iss":"https://server.example.com",
"sub":"24400320",
"aud":"s6BhdRkqt3",
"exp":1311281970,

http://openid.net/specs/openidconnectbasic1_0.html 12/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37

"iat":1311280970
}

TOC
2.2.1.IDTokenValidation

Ifanyofthevalidationproceduresdefinedinthisdocumentfail,anyoperationsrequiring
theinformationthatfailedtocorrectlyvalidateMUSTbeabortedandtheinformationthat
failedtovalidateMUSTNOTbeused.

TheClientMUSTvalidatetheIDTokenintheTokenResponse.Todothis,theClientcan
splittheIDTokenattheperiod(".")characters,takethesecondsegment,andbase64url
decodeittoobtainaJSONobjectcontainingtheIDTokenClaims,whichMUSTbe
validatedasfollows:

1.TheIssuerIdentifierfortheOpenIDProvider(whichistypicallyobtained
duringDiscovery)MUSTexactlymatchthevalueoftheiss(issuer)Claim.
2.TheClientMUSTvalidatethattheaud(audience)Claimcontainsitsclient_id
valueregisteredattheIssueridentifiedbytheiss(issuer)Claimasan
audience.TheIDTokenMUSTberejectediftheIDTokendoesnotlistthe
Clientasavalidaudience,orifitcontainsadditionalaudiencesnottrustedby
theClient.
3.IftheIDTokencontainsmultipleaudiences,theClientSHOULDverifythatan
azpClaimispresent.
4.Ifanazp(authorizedparty)Claimispresent,theClientSHOULDverifythatits
client_idistheClaimValue.
5.ThecurrenttimeMUSTbebeforethetimerepresentedbytheexpClaim
(possiblyallowingforsomesmallleewaytoaccountforclockskew).
6.TheiatClaimcanbeusedtorejecttokensthatwereissuedtoofarawayfrom
thecurrenttime,limitingtheamountoftimethatnoncesneedtobestoredto
preventattacks.TheacceptablerangeisClientspecific.
7.IftheacrClaimwasrequested,theClientSHOULDcheckthattheasserted
ClaimValueisappropriate.ThemeaningandprocessingofacrClaimValuesis
outofscopeforthisdocument.
8.Whenamax_agerequestismade,theClientSHOULDchecktheauth_time
Claimvalueandrequestreauthenticationifitdeterminestoomuchtimehas
elapsedsincethelastEndUserauthentication.

TOC
2.3.UserInfoEndpoint

TheUserInfoEndpointisanOAuth2.0ProtectedResourcethatreturnsClaimsaboutthe
authenticatedEndUser.ThelocationoftheUserInfoEndpointMUSTbeaURLusingthe
httpsscheme,whichMAYcontainport,path,andqueryparametercomponents.The
returnedClaimsarerepresentedbyaJSONobjectthatcontainsacollectionofnameand
valuepairsfortheClaims.

CommunicationwiththeUserInfoEndpointMUSTutilizeTLS.See Section7.1formore
informationonusingTLS.

TOC
2.3.1.UserInfoRequest

ClientssendrequeststotheUserInfoEndpointtoobtainClaimsabouttheEndUserusing
anAccessTokenobtainedthroughOpenIDConnectAuthentication.TheUserInfoEndpoint
isan OAuth2.0[RFC6749]ProtectedResourcethatcomplieswiththe OAuth2.0Bearer
TokenUsage[RFC6750]specification.TherequestSHOULDusetheHTTPGETmethodand
theAccessTokenSHOULDbesentusingtheAuthorizationheaderfield.

ThefollowingisanonnormativeexampleofaUserInfoRequest:

http://openid.net/specs/openidconnectbasic1_0.html 13/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37

GET/userinfoHTTP/1.1
Host:server.example.com
Authorization:BearerSlAV32hkKG

TOC
2.3.2.SuccessfulUserInfoResponse

TheUserInfoClaimsMUSTbereturnedasthemembersofaJSONobject.Theresponse
bodySHOULDbeencodedusingUTF8.TheClaimsdefinedin Section2.5canbe
returned,ascanadditionalClaimsnotspecifiedthere.

IfaClaimisnotreturned,thatClaimNameSHOULDbeomittedfromtheJSONobject
representingtheClaimsitSHOULDNOTbepresentwithanulloremptystringvalue.

Thesub(subject)ClaimMUSTalwaysbereturnedintheUserInfoResponse.

NOTE:Duetothepossibilityoftokensubstitutionattacks,theUserInfoResponseisnot
guaranteedtobeabouttheEndUseridentifiedbythesub(subject)elementoftheID
Token.ThesubClaimintheUserInfoResponseMUSTbeverifiedtoexactlymatchthesub
ClaimintheIDTokeniftheydonotmatch,theUserInfoResponsevaluesMUSTNOTbe
used.

TheClientMUSTverifythattheOPthatrespondedwastheintendedOPthroughaTLS
servercertificatecheck,per RFC6125[RFC6125].

TOC
2.3.3.UserInfoErrorResponse

Whenanerrorconditionoccurs,theUserInfoEndpointreturnsanErrorResponseas
definedinSection3of OAuth2.0BearerTokenUsage[RFC6750].

TOC
2.4.ScopeValues

OpenIDConnectClientsusescopevaluesasdefinedin3.3of OAuth2.0[RFC6749]to
specifywhataccessprivilegesarebeingrequestedforAccessTokens.Thescopes
associatedwithAccessTokensdeterminewhatresourceswillbeavailablewhentheyare
usedtoaccessOAuth2.0protectedendpoints.ForOpenIDConnect,scopescanbeusedto
requestthatspecificsetsofinformationbemadeavailableasClaimValues.This
documentdescribesonlythescopevaluesusedbyOpenIDConnect.

OpenIDConnectallowsadditionalscopevaluestobedefinedandused.Scopevaluesused
thatarenotunderstoodbyanimplementationSHOULDbeignored.

ClaimsrequestedbythefollowingscopesaretreatedbyAuthorizationServersas
VoluntaryClaims.

OpenIDConnectdefinesthefollowingscopevalues:

openid
REQUIRED.InformstheAuthorizationServerthattheClientismakinganOpenID
Connectrequest.Iftheopenidscopevalueisnotpresent,thebehavioris
entirelyunspecified.
profile
OPTIONAL.ThisscopevaluerequestsaccesstotheEndUser'sdefaultprofile
Claims,whichare:name,family_name,given_name,middle_name,nickname,
preferred_username,profile,picture,website,gender,birthdate,
zoneinfo,locale,andupdated_at.
email
OPTIONAL.Thisscopevaluerequestsaccesstotheemailandemail_verified
Claims.

http://openid.net/specs/openidconnectbasic1_0.html 14/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37

address
OPTIONAL.ThisscopevaluerequestsaccesstotheaddressClaim.
phone
OPTIONAL.Thisscopevaluerequestsaccesstothephone_numberand
phone_number_verifiedClaims.
offline_access
OPTIONAL.ThisscopevaluerequeststhatanOAuth2.0RefreshTokenbeissued
thatcanbeusedtoobtainanAccessTokenthatgrantsaccesstotheEndUser's
UserInfoEndpointevenwhentheEndUserisnotpresent(notloggedin).

MultiplescopevaluesMAYbeusedbycreatingaspacedelimited,casesensitivelistof
ASCIIscopevalues.

TheClaimsrequestedbytheprofile,email,address,andphonescopevaluesare
returnedfromtheUserInfoEndpoint,asdescribedin Section2.3.2.

Insomecases,theEndUserwillbegiventheoptiontohavetheOpenIDProviderdecline
toprovidesomeorallinformationrequestedbyRPs.Tominimizetheamountof
informationthattheEndUserisbeingaskedtodisclose,anRPcanelecttoonlyrequesta
subsetoftheinformationavailablefromtheUserInfoEndpoint.

ThefollowingisanonnormativeexampleofascopeRequest:

scope=openidprofileemailphone

TOC
2.5.StandardClaims

ThissubsetofOpenIDConnectdefinesasetofstandardClaims.Theyarereturnedinthe
UserInfoResponse.

Member Type Description

sub string SubjectIdentifierfortheEndUserattheIssuer.
EndUser'sfullnameindisplayableformincludingallname
name string parts,possiblyincludingtitlesandsuffixes,orderedaccordingto
theEndUser'slocaleandpreferences.
Givenname(s)orfirstname(s)oftheEndUser.Notethatin
given_name string somecultures,peoplecanhavemultiplegivennamesallcanbe
present,withthenamesbeingseparatedbyspacecharacters.
Surname(s)orlastname(s)oftheEndUser.Notethatinsome
cultures,peoplecanhavemultiplefamilynamesornofamily
family_name string
nameallcanbepresent,withthenamesbeingseparatedby
spacecharacters.
Middlename(s)oftheEndUser.Notethatinsomecultures,
peoplecanhavemultiplemiddlenamesallcanbepresent,with
middle_name string
thenamesbeingseparatedbyspacecharacters.Alsonotethat
insomecultures,middlenamesarenotused.
CasualnameoftheEndUserthatmayormaynotbethesame
nickname string asthegiven_name.Forinstance,anicknamevalueofMike
mightbereturnedalongsideagiven_namevalueofMichael.
ShorthandnamebywhichtheEndUserwishestobereferredto
attheRP,suchasjanedoeorj.doe.ThisvalueMAYbeany
preferred_username string validJSONstringincludingspecialcharacterssuchas@,/,or
whitespace.TheRPMUSTNOTrelyuponthisvaluebeingunique,
asdiscussedin Section2.5.3.
URLoftheEndUser'sprofilepage.ThecontentsofthisWeb
profile string
pageSHOULDbeabouttheEndUser.
picture string URLoftheEndUser'sprofilepicture.ThisURLMUSTrefertoan

http://openid.net/specs/openidconnectbasic1_0.html 15/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37

imagefile(forexample,aPNG,JPEG,orGIFimagefile),rather
thantoaWebpagecontaininganimage.NotethatthisURL
SHOULDspecificallyreferenceaprofilephotooftheEndUser
suitablefordisplayingwhendescribingtheEndUser,ratherthan
anarbitraryphototakenbytheEndUser.
URLoftheEndUser'sWebpageorblog.ThisWebpageSHOULD
website string containinformationpublishedbytheEndUseroranorganization
thattheEndUserisaffiliatedwith.
EndUser'spreferredemailaddress.ItsvalueMUSTconformto
email string the RFC5322[RFC5322]addrspecsyntax.TheRPMUSTNOT
relyuponthisvaluebeingunique,asdiscussedin Section2.5.3.
TrueiftheEndUser'semailaddresshasbeenverified
otherwisefalse.WhenthisClaimValueistrue,thismeansthat
theOPtookaffirmativestepstoensurethatthisemailaddress
email_verified boolean wascontrolledbytheEndUseratthetimetheverificationwas
performed.Themeansbywhichanemailaddressisverifiedis
contextspecific,anddependentuponthetrustframeworkor
contractualagreementswithinwhichthepartiesareoperating.
EndUser'sgender.Valuesdefinedbythisdocumentarefemale
gender string andmale.OthervaluesMAYbeusedwhenneitherofthedefined
valuesareapplicable.
EndUser'sbirthday,representedasan ISO8601:2004
[ISO86012004]YYYYMMDDformat.TheyearMAYbe0000,
indicatingthatitisomitted.Torepresentonlytheyear,YYYY
birthdate string formatisallowed.Notethatdependingontheunderlying
platform'sdaterelatedfunction,providingjustyearcanresultin
varyingmonthandday,sotheimplementersneedtotakethis
factorintoaccounttocorrectlyprocessthedates.
Stringfromzoneinfo [zoneinfo]timezonedatabase
zoneinfo string representingtheEndUser'stimezone.Forexample,
Europe/ParisorAmerica/Los_Angeles.
EndUser'slocale,representedasa BCP47[RFC5646]language
tag.Thisistypicallyan ISO6391Alpha2[ISO6391]language
codeinlowercaseandan ISO31661Alpha2[ISO31661]
countrycodeinuppercase,separatedbyadash.Forexample,
locale string
enUSorfrCA.Asacompatibilitynote,someimplementations
haveusedanunderscoreastheseparatorratherthanadash,
forexample,en_USRelyingPartiesMAYchoosetoacceptthis
localesyntaxaswell.
EndUser'spreferredtelephonenumber. E.164[E.164]is
RECOMMENDEDastheformatofthisClaim,forexample,+1
(425)5551212or+56(2)6872400.Ifthephonenumber
phone_number string
containsanextension,itisRECOMMENDEDthattheextensionbe
representedusingthe RFC3966[RFC3966]extensionsyntax,for
example,+1(604)5551234ext=5678.
TrueiftheEndUser'sphonenumberhasbeenverified
otherwisefalse.WhenthisClaimValueistrue,thismeansthat
theOPtookaffirmativestepstoensurethatthisphonenumber
wascontrolledbytheEndUseratthetimetheverificationwas
phone_number_verified boolean performed.Themeansbywhichaphonenumberisverifiedis
contextspecific,anddependentuponthetrustframeworkor
contractualagreementswithinwhichthepartiesareoperating.
Whentrue,thephone_numberClaimMUSTbeinE.164format
andanyextensionsMUSTberepresentedinRFC3966format.
EndUser'spreferredpostaladdress.Thevalueoftheaddress
JSON
address memberisaJSON [RFC4627]structurecontainingsomeorall
object
ofthemembersdefinedin Section2.5.1.
TimetheEndUser'sinformationwaslastupdated.Itsvalueisa
updated_at number JSONnumberrepresentingthenumberofsecondsfrom1970
0101T00:00:00ZasmeasuredinUTCuntilthedate/time.

http://openid.net/specs/openidconnectbasic1_0.html 16/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37
Table1:ReservedMemberDefinitions

Followingisanonnormativeexampleofsucharesponse:

{
"sub":"248289761001",
"name":"JaneDoe",
"given_name":"Jane",
"family_name":"Doe",
"preferred_username":"j.doe",
"email":"janedoe@example.com",
"picture":"http://example.com/janedoe/me.jpg"
}

TheUserInfoEndpointMUSTreturnClaimsinJSONformatunlessadifferentformatwas
specifiedduringRegistration [OpenID.Registration].TheUserInfoEndpointMUSTreturn
acontenttypeheadertoindicatewhichformatisbeingreturned.Thefollowingare
acceptedcontenttypes:

ContentType FormatReturned
application/json plaintextJSONobject
application/jwt JSONWebToken(JWT)

TOC
2.5.1.AddressClaim

TheAddressClaimrepresentsaphysicalmailingaddress.ImplementationsMAYreturn
onlyasubsetofthefieldsofanaddress,dependingupontheinformationavailableand
theEndUser'sprivacypreferences.Forexample,thecountryandregionmightbe
returnedwithoutreturningmorefinegrainedaddressinformation.

ImplementationsMAYreturnjustthefulladdressasasinglestringintheformattedsub
field,ortheyMAYreturnjusttheindividualcomponentfieldsusingtheothersubfields,or
theyMAYreturnboth.Ifbothvariantsarereturned,theySHOULDbedescribingthesame
address,withtheformattedaddressindicatinghowthecomponentfieldsarecombined.

formatted
Fullmailingaddress,formattedfordisplayoruseonamailinglabel.Thisfield
MAYcontainmultiplelines,separatedbynewlines.Newlinescanberepresented
eitherasacarriagereturn/linefeedpair("\r\n")orasasinglelinefeed
character("\n").
street_address
Fullstreetaddresscomponent,whichMAYincludehousenumber,streetname,
PostOfficeBox,andmultilineextendedstreetaddressinformation.Thisfield
MAYcontainmultiplelines,separatedbynewlines.Newlinescanberepresented
eitherasacarriagereturn/linefeedpair("\r\n")orasasinglelinefeed
character("\n").
locality
Cityorlocalitycomponent.
region
State,province,prefecture,orregioncomponent.
postal_code
Zipcodeorpostalcodecomponent.
country
Countrynamecomponent.

TOC
2.5.2.ClaimsLanguagesandScripts

http://openid.net/specs/openidconnectbasic1_0.html 17/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37

HumanreadableClaimValuesandClaimValuesthatreferencehumanreadablevalues
MAYberepresentedinmultiplelanguagesandscripts.Tospecifythelanguagesand
scripts, BCP47[RFC5646]languagetagsareaddedtomembernames,delimitedbya#
character.Forexample,family_name#jaKanaJPexpressestheFamilyNamein
KatakanainJapanese,whichiscommonlyusedtoindexandrepresentthephoneticsof
theKanjirepresentationofthesamerepresentedasfamily_name#jaHaniJP.As
anotherexample,bothwebsiteandwebsite#deClaimValuesmightbereturned,
referencingaWebsiteinanunspecifiedlanguageandaWebsiteinGerman.

SinceClaimNamesarecasesensitive,itisstronglyRECOMMENDEDthatlanguagetag
valuesusedinClaimNamesbespelledusingthecharactercasewithwhichtheyare
registeredintheIANA"LanguageSubtagRegistry" [IANA.Language].Inparticular,
normallylanguagenamesarespelledwithlowercasecharacters,regionnamesarespelled
withuppercasecharacters,andscriptsarespelledwithmixedcasecharacters.However,
sinceBCP47languagetagvaluesarecaseinsensitive,implementationsSHOULDinterpret
thelanguagetagvaluessuppliedinacaseinsensitivemanner.

PertherecommendationsinBCP47,languagetagvaluesforClaimsSHOULDonlybeas
specificasnecessary.Forinstance,usingfrmightbesufficientinmanycontexts,rather
thanfrCAorfrFR.Wherepossible,OPsSHOULDtrytomatchrequestedClaimlocales
withClaimsithas.Forinstance,iftheClientasksforaClaimwithade(German)
languagetagandtheOPhasavaluetaggedwithdeCH(SwissGerman)andnogeneric
Germanvalue,itwouldbeappropriatefortheOPtoreturntheSwissGermanvaluetothe
Client.(Thisintentionallymovesasmuchofthecomplexityoflanguagetagmatchingto
theOPaspossible,tosimplifyClients.)

Aclaims_localesrequestcanbeusedtospecifythepreferredlanguagesandscriptsto
useforthereturnedClaims.

WhentheOPdetermines,eitherthroughtheclaims_localesparameter,orbyother
means,thattheEndUserandClientarerequestingClaimsinonlyonesetoflanguages
andscripts,itisRECOMMENDEDthatOPsreturnClaimswithoutlanguagetagswhenthey
employthislanguageandscript.ItisalsoRECOMMENDEDthatClientsbewrittenina
mannerthattheycanhandleandutilizeClaimsusinglanguagetags.

TOC
2.5.3.ClaimStabilityandUniqueness

Thesub(subject)andiss(issuer)Claims,usedtogether,aretheonlyClaimsthatanRP
canrelyuponasastableidentifierfortheEndUser,sincethesubClaimMUSTbelocally
uniqueandneverreassignedwithintheIssuerforaparticularEndUser,asdescribedin
Section2.2.Therefore,theonlyguaranteeduniqueidentifierforagivenEndUseristhe
combinationoftheissClaimandthesubClaim.

AllotherClaimscarrynosuchguaranteesacrossdifferentissuersintermsofstability
overtimeoruniquenessacrossusers,andIssuersarepermittedtoapplylocalrestrictions
andpolicies.Forinstance,anIssuerMAYreuseanemailClaimValueacrossdifferent
EndUsersatdifferentpointsintime,andtheclaimedemailaddressforagivenEndUser
MAYchangeovertime.Therefore,otherClaimssuchasemail,phone_number,and
preferred_usernameandMUSTNOTbeusedasuniqueidentifiersfortheEndUser.

TOC
3.Serializations

ArequestmessageMAYbeserializedusingoneofthefollowingmethods:

1.QueryStringSerialization
2.FormSerialization

TOC
3.1.QueryStringSerialization
http://openid.net/specs/openidconnectbasic1_0.html 18/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37

InordertoserializetheparametersusingtheQueryStringSerialization,theClient
constructsthestringbyaddingtheparametersandvaluestothequerycomponentusing
theapplication/xwwwformurlencodedformatasdefinedby
[W3C.REChtml40119991224].QueryStringSerializationistypicallyusedinHTTPGET
requests.

Followingisanonnormativeexampleofthisserialization(withlinewrapswithinvalues
fordisplaypurposesonly):

GET/authorize?scope=openid
&response_type=code
&client_id=s6BhdRkqt3
&redirect_uri=https%3A%2F%2Fclient.example.org%2FcbHTTP/1.1
Host:server.example.com

TOC
3.2.FormSerialization

ParametersandtheirvaluesareFormSerializedbyaddingtheparameternamesand
valuestotheentitybodyoftheHTTPrequestusingtheapplication/xwwwform
urlencodedformatasdefinedby [W3C.REChtml40119991224].FormSerializationis
typicallyusedinHTTPPOSTrequests.

Followingisanonnormativeexampleofthisserialization(withlinewrapswithinvalues
fordisplaypurposesonly):

POST/authorizeHTTP/1.1
Host:server.example.com
ContentType:application/xwwwformurlencoded

scope=openid
&response_type=code
&client_id=s6BhdRkqt3
&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb

TOC
4.StringOperations

ProcessingsomeOpenIDConnectmessagesrequirescomparingvaluesinthemessagesto
knownvalues.Forexample,theClaimNamesreturnedbytheUserInfoEndpointmightbe
comparedtospecificClaimNamessuchassub.ComparingUnicode [UNICODE]strings,
however,hassignificantsecurityimplications.

Therefore,comparisonsbetweenJSONstringsandotherUnicodestringsMUSTbe
performedasspecifiedbelow:

1.RemoveanyJSONappliedescapingtoproduceanarrayofUnicodecode
points.
2.UnicodeNormalization [USA15]MUSTNOTbeappliedatanypointtoeither
theJSONstringortothestringitistobecomparedagainst.
3.ComparisonsbetweenthetwostringsMUSTbeperformedasaUnicodecode
pointtocodepointequalitycomparison.

Inseveralplaces,thisdocumentusesspacedelimitedlistsofstrings.Inallsuchcases,
theASCIIspacecharacter(0x20)MUSTbetheonlycharacterusedforthispurpose.

TOC
5.TLSVersion

http://openid.net/specs/openidconnectbasic1_0.html 19/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37

WheneverTransportLayerSecurity(TLS)isusedbythisdocument,theappropriate
version(orversions)ofTLSwillvaryovertime,basedonthewidespreaddeploymentand
knownsecurityvulnerabilities.Atthetimeofthiswriting,TLSversion1.2 [RFC5246]is
themostrecentversion,buthasaverylimiteddeploymentbaseandmightnotbereadily
availableforimplementation.TLSversion1.0 [RFC2246]isthemostwidelydeployed
versionandwillprovidethebroadestinteroperability.

TOC
6.ImplementationConsiderations

ThisdocumentdefinesfeaturesusedbyRelyingPartiesusingtheOAuthAuthorization
CodeFlow.TheseRelyingPartiesMUSTimplementthefeaturesthatarelistedinthis
documentasbeing"REQUIRED"oraredescribedwitha"MUST".

TOC
6.1.DiscoveryandRegistration

SomeOpenIDConnectinstallationscanuseapreconfiguredsetofOpenIDProviders
and/orRelyingParties.Inthosecases,itmightnotbenecessarytosupportdynamic
discoveryofinformationaboutidentitiesorservicesordynamicregistrationofClients.

However,ifinstallationschoosetosupportunanticipatedinteractionsbetweenRelying
PartiesandOpenIDProvidersthatdonothavepreconfiguredrelationships,theySHOULD
accomplishthisbyimplementingthefacilitiesdefinedinthe OpenIDConnectDiscovery
1.0[OpenID.Discovery]and OpenIDConnectDynamicClientRegistration1.0
[OpenID.Registration]specifications.

TOC
7.SecurityConsiderations

Forsecurityconsiderationsotherthanthoselistedbelow,refertothe OpenIDConnect
Core1.0[OpenID.Core]specification.

TOC
7.1.TLSRequirements

ImplementationsMUSTsupportTLS.Whichversion(s)oughttobeimplementedwillvary
overtime,anddependonthewidespreaddeploymentandknownsecurityvulnerabilities
atthetimeofimplementation.Atthetimeofthiswriting,TLSversion1.2 [RFC5246]is
themostrecentversion,buthasverylimitedactualdeployment,andmightnotbereadily
availableinimplementationtoolkits.TLSversion1.0 [RFC2246]isthemostwidely
deployedversion,andwillgivethebroadestinteroperability.

Toprotectagainstinformationdisclosureandtampering,confidentialityprotectionMUST
beappliedusingTLSwithaciphersuitethatprovidesconfidentialityandintegrity
protection.

WheneverTLSisused,aTLSservercertificatecheckMUSTbeperformed,per RFC6125
[RFC6125].

TOC
8.PrivacyConsiderations

TOC
8.1.PersonallyIdentifiableInformation

http://openid.net/specs/openidconnectbasic1_0.html 20/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37

TheUserInfoResponsetypicallycontainsPersonallyIdentifiableInformation(PII).Assuch,
EndUserconsentforthereleaseoftheinformationforthespecifiedpurposeSHOULDbe
obtainedatorpriortotheauthorizationtimeinaccordancewithrelevantregulations.The
purposeofuseistypicallyregisteredinassociationwiththeredirect_uris.

OnlynecessaryUserInfodatashouldbestoredattheClientandtheClientSHOULD
associatethereceiveddatawiththepurposeofusestatement.

TOC
8.2.DataAccessMonitoring

TheResourceServerSHOULDmakeEndUsers'UserInfoaccesslogsavailabletothemso
thattheycanmonitorwhoaccessedtheirdata.

TOC
8.3.Correlation

ToprotecttheEndUserfromapossiblecorrelationamongClients,theuseofaPairwise
PseudonymousIdentifier(PPID)asthesub(subject)SHOULDbeconsidered.

TOC
8.4.OfflineAccess

OfflineaccessenablesaccesstoClaimswhentheuserisnotpresent,posinggreater
privacyriskthantheClaimstransferwhentheuserispresent.Therefore,itisprudentto
obtainexplicitconsentforofflineaccesstoresources.Thisdocumentmandatestheuseof
thepromptparametertoobtainconsentunlessitisalreadyknownthattherequest
complieswiththeconditionsforprocessingtherequestineachjurisdiction.

WhenanAccessTokenisreturnedinthefrontchannel,thereisagreaterriskofitbeing
exposedtoanattacker,whocouldlateruseittoaccesstheUserInfoendpoint.Ifthe
AccessTokendoesnotenableofflineaccessandtheservercandifferentiatewhetherthe
Clientrequesthasbeenmadeofflineoronline,theriskwillbesubstantiallyreduced.
Therefore,thisdocumentmandatesignoringtheofflineaccessrequestwhentheAccess
Tokenistransmittedinthefrontchannel.Notethatdifferentiatingbetweenonlineand
offlineaccessfromtheservercanbedifficultespeciallyfornativeclients.Theservermay
wellhavetorelyonheuristics.Also,theriskofexposurefortheAccessTokendeliveredin
thefrontchannelfortheResponseTypesofcodetokenandtokenisthesame.Thus,the
implementationsshouldbepreparedtodetectthechannelfromwhichtheAccessToken
wasissuedanddenyofflineaccessifthetokenwasissuedinthefrontchannel.

Notethatalthoughtheseprovisionsrequireanexplicitconsentdialoguethroughthe
promptparameter,themerefactthattheuserpressedan"accept"buttonetc.,mightnot
constituteavalidconsent.Developersshouldbeawarethatfortheactofconsenttobe
valid,typically,theimpactofthetermshavetobeunderstoodbytheEndUser,the
consentmustbefreelygivenandnotforced(i.e.,otheroptionshavetobeavailable),and
thetermsmustfairandequitable.Ingeneral,itisadvisablefortheservicetofollowthe
requiredprivacyprinciplesineachjurisdictionandrelyonotherconditionsforprocessing
therequestthansimplyexplicitconsent,asonlineselfservice"explicitconsent"often
doesnotformavalidconsentinsomejurisdictions.

TOC
9.IANAConsiderations

ThisdocumentmakesnorequestsofIANA.

TOC
10.References
http://openid.net/specs/openidconnectbasic1_0.html 21/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37

TOC
10.1.NormativeReferences

[E.164] InternationalTelecommunicationUnion,E.164:Theinternationalpublictelecommunication
numberingplan,2010.
[IANA.Language] IANA,LanguageSubtagRegistry.
[ISO29115] InternationalOrganizationforStandardization,ISO/IEC29115:2013Informationtechnology
SecuritytechniquesEntityauthenticationassuranceframework,ISO/IEC29115,
March2013.
[ISO31661] InternationalOrganizationforStandardization,ISO31661:1997.Codesfortherepresentation
ofnamesofcountriesandtheirsubdivisionsPart1:Countrycodes,1997.
[ISO6391] InternationalOrganizationforStandardization,ISO6391:2002.Codesfortherepresentationof
namesoflanguagesPart1:Alpha2code,2002.
[ISO86012004] InternationalOrganizationforStandardization,ISO8601:2004.Dataelementsandinterchange
formatsInformationinterchangeRepresentationofdatesandtimes,2004.
[JWS] Jones,M.,Bradley,J.,andN.Sakimura,JSONWebSignature(JWS),RFC7515,
DOI10.17487/RFC7515,May2015.
[JWT] Jones,M.,Bradley,J.,andN.Sakimura,JSONWebToken(JWT),RFC7519,
DOI10.17487/RFC7519,May2015.
[OpenID.Core] Sakimura,N.,Bradley,J.,Jones,M.,deMedeiros,B.,andC.Mortimore,OpenIDConnectCore
1.0,August2015.
[OpenID.Discovery] Sakimura,N.,Bradley,J.,Jones,M.,andE.Jay,OpenIDConnectDiscovery1.0,August2015.
[OpenID.Registration] Sakimura,N.,Bradley,J.,andM.Jones,OpenIDConnectDynamicClientRegistration1.0,
August2015.
[RFC20] Cerf,V.,ASCIIformatforNetworkInterchange,STD80,RFC20,DOI10.17487/RFC0020,
October1969.
[RFC2119] Bradner,S.,KeywordsforuseinRFCstoIndicateRequirementLevels,BCP14,RFC2119,
DOI10.17487/RFC2119,March1997.
[RFC2246] Dierks,T.andC.Allen,TheTLSProtocolVersion1.0,RFC2246,DOI10.17487/RFC2246,
January1999.
[RFC3339] Klyne,G.andC.Newman,DateandTimeontheInternet:Timestamps,RFC3339,
DOI10.17487/RFC3339,July2002.
[RFC3629] Yergeau,F.,UTF8,atransformationformatofISO10646,STD63,RFC3629,
DOI10.17487/RFC3629,November2003.
[RFC3966] Schulzrinne,H.,ThetelURIforTelephoneNumbers,RFC3966,DOI10.17487/RFC3966,
December2004.
[RFC3986] BernersLee,T.,Fielding,R.,andL.Masinter,UniformResourceIdentifier(URI):Generic
Syntax,STD66,RFC3986,DOI10.17487/RFC3986,January2005.
[RFC4627] Crockford,D.,Theapplication/jsonMediaTypeforJavaScriptObjectNotation(JSON),
RFC4627,DOI10.17487/RFC4627,July2006.
[RFC5246] Dierks,T.andE.Rescorla,TheTransportLayerSecurity(TLS)ProtocolVersion1.2,
RFC5246,DOI10.17487/RFC5246,August2008.
[RFC5322] Resnick,P.,Ed.,InternetMessageFormat,RFC5322,DOI10.17487/RFC5322,October2008.
[RFC5646] Phillips,A.,Ed.andM.Davis,Ed.,TagsforIdentifyingLanguages,BCP47,RFC5646,
DOI10.17487/RFC5646,September2009.
[RFC6125] SaintAndre,P.andJ.Hodges,RepresentationandVerificationofDomainBasedApplication
ServiceIdentitywithinInternetPublicKeyInfrastructureUsingX.509(PKIX)Certificatesin
theContextofTransportLayerSecurity(TLS),RFC6125,DOI10.17487/RFC6125,March2011.
[RFC6711] Johansson,L.,AnIANARegistryforLevelofAssurance(LoA)Profiles,RFC6711,
DOI10.17487/RFC6711,August2012.
[RFC6749] Hardt,D.,Ed.,TheOAuth2.0AuthorizationFramework,RFC6749,DOI10.17487/RFC6749,
October2012.
[RFC6750] Jones,M.andD.Hardt,TheOAuth2.0AuthorizationFramework:BearerTokenUsage,
RFC6750,DOI10.17487/RFC6750,October2012.
[RFC7159] Bray,T.,Ed.,TheJavaScriptObjectNotation(JSON)DataInterchangeFormat,RFC7159,
DOI10.17487/RFC7159,March2014.
[RFC7230] Fielding,R.,Ed.andJ.Reschke,Ed.,HypertextTransferProtocol(HTTP/1.1):Message
SyntaxandRouting,RFC7230,DOI10.17487/RFC7230,June2014.
[RFC7231] Fielding,R.,Ed.andJ.Reschke,Ed.,HypertextTransferProtocol(HTTP/1.1):Semanticsand
Content,RFC7231,DOI10.17487/RFC7231,June2014.
[UNICODE] TheUnicodeConsortium,TheUnicodeStandard.
[USA15] Davis,M.andK.Whistler,UnicodeNormalizationForms,UnicodeStandardAnnex15,062015.
[W3C.REChtml401 Raggett,D.,Hors,A.,andI.Jacobs,HTML4.01Specification,WorldWideWebConsortium
19991224] RecommendationREChtml40119991224,December1999(HTML).
[zoneinfo] PublicDomain,Thetzdatabase,June2011.

TOC
10.2.InformativeReferences

[OpenID.Implicit] Sakimura,N.,Bradley,J.,Jones,M.,deMedeiros,B.,andC.Mortimore,OpenIDConnectImplicit

http://openid.net/specs/openidconnectbasic1_0.html 22/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37

ClientImplementer'sGuide1.0,July2015.

TOC
AppendixA.Acknowledgements

TheOpenIDCommunitywouldliketothankthefollowingpeoplefortheircontributionsto
thisdocument:

NaveenAgarwal(naa@google.com),Google

CasperBiering(cb@peercraft.com),Peercraft

JohnBradley(ve7jtb@ve7jtb.com),PingIdentity

TimBray(tbray@textuality.com),Google

JohnnyBufu(jbufu@janrain.com),Janrain

BrenodeMedeiros(breno@google.com),Google

PamelaDingle(pdingle@pingidentity.com),PingIdentity

GeorgeFletcher(george.fletcher@corp.aol.com),AOL

RolandHedberg(roland.hedberg@adm.umu.se),UniversityofUmea

RyoIto(ryo.ito@mixi.co.jp),mixi,Inc.

EdmundJay(ejay@mgi1.com),Illumila

MichaelB.Jones(mbj@microsoft.com),Microsoft

TorstenLodderstedt(t.lodderstedt@telekom.de),DeutscheTelekom

NovMatake(nov@matake.jp),Independent

ChuckMortimore(cmortimore@salesforce.com),Salesforce

AnthonyNadalin(tonynad@microsoft.com),Microsoft

HidekiNara(hdknr@ictact.co.jp),TactCommunications

AxelNennker(axel.nennker@telekom.de),DeutscheTelekom

DavidRecordon(dr@fb.com),Facebook

JustinRicher(jricher@mitre.org),MITRE

NatSakimura(nsakimura@nri.co.jp),NomuraResearchInstitute,Ltd.

LukeShepard(lshepard@fb.com),Facebook

AndreaskreSolberg(andreas.solberg@uninett.no),UNINET

PaulTarjan(pt@fb.com),Facebook

TOC
AppendixB.Notices

Copyright(c)2015TheOpenIDFoundation.

TheOpenIDFoundation(OIDF)grantstoanyContributor,developer,implementer,orother
interestedpartyanonexclusive,royaltyfree,worldwidecopyrightlicensetoreproduce,
preparederivativeworksfrom,distribute,performanddisplay,thisImplementersDraftor
FinalSpecificationsolelyforthepurposesof(i)developingspecifications,and(ii)
implementingImplementersDraftsandFinalSpecificationsbasedonsuchdocuments,
providedthatattributionbemadetotheOIDFasthesourceofthematerial,butthatsuch
attributiondoesnotindicateanendorsementbytheOIDF.
http://openid.net/specs/openidconnectbasic1_0.html 23/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37

Thetechnologydescribedinthisspecificationwasmadeavailablefromcontributionsfrom
varioussources,includingmembersoftheOpenIDFoundationandothers.Althoughthe
OpenIDFoundationhastakenstepstohelpensurethatthetechnologyisavailablefor
distribution,ittakesnopositionregardingthevalidityorscopeofanyintellectualproperty
orotherrightsthatmightbeclaimedtopertaintotheimplementationoruseofthe
technologydescribedinthisspecificationortheextenttowhichanylicenseundersuch
rightsmightormightnotbeavailableneitherdoesitrepresentthatithasmadeany
independentefforttoidentifyanysuchrights.TheOpenIDFoundationandthecontributors
tothisspecificationmakeno(andherebyexpresslydisclaimany)warranties(express,
implied,orotherwise),includingimpliedwarrantiesofmerchantability,noninfringement,
fitnessforaparticularpurpose,ortitle,relatedtothisspecification,andtheentireriskas
toimplementingthisspecificationisassumedbytheimplementer.TheOpenIDIntellectual
PropertyRightspolicyrequirescontributorstoofferapatentpromisenottoassertcertain
patentclaimsagainstothercontributorsandagainstimplementers.TheOpenIDFoundation
invitesanyinterestedpartytobringtoitsattentionanycopyrights,patents,patent
applications,orotherproprietaryrightsthatmaycovertechnologythatmayberequired
topracticethisspecification.

TOC
AppendixC.DocumentHistory

[[Toberemovedfromthefinaldocument]]

37

ReferencedcompletedRFCs.
AddedmissingURLsinreferences.
Changedtouse"CacheControl:nocache,nostore"and"Pragma:nocache"
inexamples.
TrackedterminologychangesmadeinthereferencedIETFspecssinceerrata
set1.
UpdatedtheRFC2616referencestoRFC7230orRFC7231,asappropriate.

36

Referencedspecificationversionsincorporatingerrataset1.

35

Updateddatesforspecscontainingerrataupdates.
UpdatedreferencestoprefinalIETFspecs.
ReplacedusesofthetermsJWSHeader,JWEHeader,andJWTHeaderwiththe
JOSEHeadertermthatreplacedthemintheJOSEandJWTspecifications.
Fixed#954Added"NOTRECOMMENDED"tothelistofRFC2119terms.

34

Fixed#918WordinginconsistencyinTokenRequestlanguage.
Changedusesof"thisspecification"to"thisdocument".

33

UpdateddatesforfinalOpenIDConnectspecifications.

32

Editorialcorrections.

31

Fixed#896ReplacedthetermAuthorizationRequestwithAuthentication
Request,whereapplicable.
IncorporatedtermsdefinedbytheJWTspecification.
AppliedproofreadingcorrectionsbyMichaelB.Jones.

30

http://openid.net/specs/openidconnectbasic1_0.html 24/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37

Updatedtheresponse_typelanguage.
Fixed#878Generalizeddescriptionoferrorsthatcanbereturnedwhen
id_token_hint"isused.
Providedmorecontextintheintroduction.
ExpandedtheAuthenticationRequestexampletoshowboththe302redirect
responsebytheClientandtheresultingHTTPGETrequestsentbytheUser
Agent.

29

TrackededitorialchangesappliedtoOpenIDConnectCore.
Fixed#862Clarifiedazpdefinition.
Fixed#878Definednegativeresponsefor"id_token_hint".
ReplacedusesoftheOpenIDConnectMessagesandOpenIDConnectStandard
specificationswithOpenIDConnectCore.
Fixed#884ChangedthedescriptionsofBasicandImplicitfrombeingprofiles
tobeingimplementer'sguidescontainingsubsetsofOpenIDConnectCore.

28

Fixed#847Correctedtypeofupdated_attonumber.
Statedthatredirect_urimatchesmustbeexact,withmatchingperformed
asdescribedinSection6.2.1ofRFC3986(SimpleStringComparison).
Fixed#854Clarifiedthattheacr_valuesvaluesareinorderofpreference
andthatacr_valuesrequeststheacrClaimasaVoluntaryClaim.
Fixed#858IncorporatedelementsoftheIssuerIdentifierdefinitionintothe
issClaimdescription.
Fixed#859AddedIMPORTANTNOTETOREADERSabouttheterminology
definitionsbeinganormativepartofthespecification.

27

Fixed#834DescribedhowtooptionallyusenoncevaluesintheBasic
specification.
Fixed#833Statedthatanat_hashClaimMAYbepresentintheIDToken.
Statedthatsufficiententropymustbepresentinnoncevaluestoprevent
attackersfromguessingvalues.
StatedthattheAuthorizationServerneednotbelistedasanaudienceofthe
IDTokenwhenitisusedasanid_token_hintvalue.
Restrictedthemeaningoftheazp(authorizedparty)Claimtosimplybethe
singlepartytowhichtheIDTokenwasissued.
StatedthattheJWSCompactSerializationisalwaysusedforJWSdata
structures.

26

Fixed#825Replacedupdated_time,whichusedtheRFC3339textualtime
format,withupdated_at,usingthenumerictimeformatusedbyiat,etc.
Fixed#829Statedthatadditionalscopevaluescanbedefinedandusedand
thatscopevaluesthatarenotunderstoodshouldbeignored.
Fixed#831StatedthatJWSandJWEheaderparametersusedto
communicatekeyvaluesandkeyreferencesshouldnotbeusedinIDTokens,
sincethesearecommunicatedinadvanceusingDiscoveryandRegistration
parameters.
Fixed#712and#830Clarifiedtheazpdescriptionandmadeazpmulti
valued,likeaud.

25

Fixed#802Clarifiedrecommendationsandresponsibilitiesforproducingand
consumingClaimswithandwithoutlanguagetags.
Fixed#797Clarifiedtheintendedsemanticsofemailverificationandthat
thepreciseverificationrulesarecontextspecific.
Fixed#806Addedphone_number_verifiedClaim.
Fixed#800Specifiedthatphonenumberextensionsaretoberepresented
usingRFC3966extensionsyntax.
http://openid.net/specs/openidconnectbasic1_0.html 25/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37

Fixed#795SpecifiedthatemailaddressesmustconformtotheRFC5322
addrspecsyntax.
Fixed#808Specifiedthatphonenumbersmaybeusedaslogin_hint
values.
Fixed#801RemovedschemaandidparameterstoUserInfoEndpoint.Also
fixedrelatedissue#791Removedinvalid_schemaerror.
Fixed#793,#796,and#799AllownameClaimstocontainmultiplespace
separatednames.
Fixed#794Requiredpicturetorefertoanimagefilethatisapictureofthe
EndUser.
Fixed#811Specifythatlanguagetagcomponentsshouldbespelledusingthe
charactercasesregisteredintheIANALanguageSubtagRegistry.
Fixed#812Clarifiedthatlanguagetagvaluesusedneednotbeunnecessarily
specific.
Fixed#816Changed"mustunderstand"languageto"MUSTbeignoredifnot
understood".

24

Fixed#711Awkwardphrase"ThefollowingClaimsareREQUIREDand
OPTIONAL".
Fixed#712"azp"definitionclarification.
Fixed#713Explicitlyrequire"sub"claimtobereturnedfromUserInfo
endpoint.
Fixed#716Client/server2119blurriness.
Fixed#732Capitalizenameof"Bearer"authenticationscheme.
Fixed#738Behaviorwhen"openid"scopeisomitted.
AddedSecurityConsiderationssectionaboutTLSversionrequirementsand
usage.
RemovedlanguageaboutclientsthatdonotsupportTLS.Alsoremoved
languageaboutsupportingothertransportlayermechanismswithequivalent
securitytoTLS.
Statethatwhenanyvalidationsfail,anyoperationsrequiringtheinformation
thatfailedtocorrectlyvalidateMUSTbeabortedandtheinformationthat
failedtovalidateMUSTNOTbeused.
Addedid_token_hintparametertoBasic,sinceitSHOULDbepresentwhen
prompt=noneisused.
Fixed#742Addednewui_localesparameter.
Fixed#743Addedclaims_localesparameter.
Fixed#744Addedmax_ageparameter.
Fixed#765Addednewacr_valuesparameter.
Fixed#597Changedrepresentationofomittedyearinbirthdatefrom9999
to0000.
Fixed#726Clientauthenticationclarifications.
Clarifiedwhenthehttpschemecanandcannotbeusedinredirect_uri
values.
StatedthattheazpClaimisonlyneededwhenthepartyrequestingtheID
TokenisdifferentthantheaudienceoftheIDToken.
Uselegalacrvaluesinexamples.
Fixed#789Addedamr(authenticationmethodsreferences)Claim.

23

Fixed#620UpdateSection2.2.6.2.toallowforothertokentypes,butmake
bearermandatorytosupportforbasicclients.
AddedImplementationConsiderationssection.
Fixed#698Inconsistentuseofarticles.
Addedauth_timedefinitiontoIDTokenschema.
Fixed#655SpecifyUTF8asencodingschemewhenevernecessary.

22

Fixed#687Inconsistencybetweenuser_idandprnclaims.Thefixchanged
thesenames:user_id>sub,user_id_types_supported>
subject_types_supported,user_id_type>subject_type,andprn>sub.
http://openid.net/specs/openidconnectbasic1_0.html 26/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37

Fixed#689TrackJWTchangethatallowsJWTstohavemultipleaudiences.
Fixed#660ClarifiedthatreturningthesubvaluefromtheUserInfoendpoint
ismandatory.
Fixed#636IDTokenauthorizedpartyclaim.
Fixed#539Addscopeforofflineaccess.
Fixed#689addedcautionaboutunrecognizedaudiences.
Fixed#693Addedlogin_hint
Updatedscopestext.

21

addedinformativedefinitionofnoncein2.2.1
ClarifiedthattheclientMUSTcheckthattheissuerisvalidforthetoken
endpoint
RE#607addexampledecodedid_tokenfornonselfissued.
Fixed#666JWSsignaturevalidationvs.verification.
Fixed#682Changeremainingusesof"birthday"to"birthdate".
ReferencedOAuth2.0RFCsRFC6749andRFC6750.

20

Addedpreferred_usernameclaimunderprofilescope
AddedIDTokensectiontodescriberequiredclaims
Addedsectiononclaimstability

19

FixedSection2.2.5.1toreturncodeinaqueryparameterratherthana
fragment
Removedclaims_in_id_tokenscopevalue,perdecisiononJune15,2012
specialworkinggroupcall

18

Use"code"response_typeinsteadof"tokenid_token"inBasicProfile,per
issue#567
Changedverifiedtoemail_verified,perissue#564
RemovedCheckIDEndpoint,perissue#570
RemovedrequirementforIDTokensignaturevalidationfromBasicProfile,per
issue#568
RemoveduseofnoncefromBasicProfile,perissue#569
Changedclient.example.comtoclient.example.org,perissue#251
Addedclaims_in_id_tokenscopedefinitiontoBasicandImplicit,perissue
#594
UsestandardstrackversionofJSONWebTokenspec(draftietfoauthjson
webtoken)

17

Removed"embedded"displaytype,sinceitssemanticswerenotwelldefined,
perissue#514
Addhashandhashcheckofaccess_tokenandcodetoid_token,perissue
#510
AddexampleJScodeforclient
UpdatedNotices
UpdatedReferences

16

AddediatasarequiredclaiminIDTokens
Enumeratedclaimsrequestedbythe"profile"scopevalue
AddedtextaboutimplicitflowtoAbstract

15

Removeddefinitionandusageforassertionandclaimobject
emailscopeallowsaccesstothe'verified'claim

http://openid.net/specs/openidconnectbasic1_0.html 27/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37

Removedlanguagepertainingtocustomuserinfoschemas
Moveddisplay=nonetoprompt=none
Addedadditional'display'parameteroptions
Redefined'nonce'inAuthorizationRequest.ChangedtoREQUIREDparameter.
Changedusageof"approval"to"consent"
UseRFC6125toverifyTLSendpoints
AllowothergenderstringsinUserInfoschema
IDTokenMUSTbeJWT
RECOMMENDEDE.164formatforUserInfo'phone_number'claim
ChangedUserInfoErrorResponsetoaugmentandreturnOAuth2.0Bearer
TokenErrorResponse
CheckIDEndpointSHOULDusePOST
Addedsectionaboutstringcomparisonrulesneeded
AddedResponseEncodingaccordingtoMultipleResponseTypesspec
Makeopenidscopeprovideuser_idfromuserinfoendpoint
ChangedSecurityConsiderationstorefertocorrespondingsectioninStandard
CheckIDEndpointusesIDTokenasAccessTokenaccordingtoBearerToken
spec
UpdateJohnBradleyemailandaffiliationforImplementer'sDraft
Removedinvalid_id_tokenerrorcodes
ReplacequeryStringwithpostBodyvariableinexampleJS

14

Changedsection3.2.1torefertoaccess_tokenticket#134.
Bumpedversion+date.
Changed7.4insecurityconsiderationstoshownoneisREQUIRED.
Changed3.2.4.1UserInfotoUserInfoperTicket#137.
Changedformattingof7.1perticket#140.

13

Changedcheck_sessiontocheck_id.
schema=openidnowrequiredwhenrequestingUserInfo.
Removedissued_to,sincenotwelldefined.
Removeddisplayvaluespopup,touch,andmobile,sincenotwelldefined.

12

Ticket#48ChangedCheckSessiontotaketheid_tokenasaparameter.

11

Renamedfrom"Lite"to"BasicClient".
Numerouscleanups,includingupdatingreferences.

10

Addbackid_tokentotheresponsetypeperissue27.
Changedendpointnameinexamplefromid_tokentocheck_session.
Addedtoken_typetotheresponseandexplanationsoftheoptional
parameters.

09

Cleanuptypos.
Cleanupscopeexplanation.
Fix3.2.4.1toincludeid_tokeninresponse.

08

AddednoteaboutOPneedingtoreadthefullspec.
RevertedbacktoGETforintrospectionbasedonGooglefeedback.
Changedscopestoopenid,profile,address,andemailtomakethem
additive.
ChangedintrospectiontoCheckSessionEndpointtobeconsistentwithsession
management.

http://openid.net/specs/openidconnectbasic1_0.html 28/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37

Changedvalidationrules,theChecksessionendpointwillreturnanerrorfor
expiredorinvalidtokens,sotheClientdoesn'tneedtocheckexpiration.
Addedexplanationofwhyanid_tokenisusedtoverifyidentityratherthanthe
userinfoAccessToken.

07

Changedintrospectiontopost
Changeduserinfofromidtouser_idtobeconsistentwithintrospection
endpoint.
Fixedintrospectionexampletouseid_tokenratherthanaccesstoken.
Removedaskingforid_tokeninresponsetype.
FixedSection3tobeclearitisclientsecretthatismaintainedbetweenthe
clientandtheOP.

06

OnlyrequirethetokenflowinLite.Removedcodeflow.
Makeid_tokenrequired.Theid_tokenistreatedasopaque.
Rearrangedsectionsforreadability.
DroppedtheschemaparametertotheIntrospectionendpoint,whichwas
formerlyastringwiththevalueuser_id.Thisisunnecessarysincethe
id_tokenparameteralreadycanbeusedtodisambiguatetheintendeduses(s)
oftheendpoint.
DroppedtherequestedaudiencefromtheLitespec,whichwasformerlythe
identifierofthetargetaudienceoftheresponse.Thiscouldbepartofthe
Standardspec,butisanadvancedscenario,andsonotappropriateforLite.
ReferencetheDiscoveryandRegistrationspecs,sincethey'reneededfor
interactionbetweennonpreconfiguredparties(sothatOpenIDConnect
installationscanbeOpen).

05

CorrectedissuesraisedbyCasperBiering.
CreatedtheOpenIDConnectLitespecification.

04

CorrectissuesraisedbyPamDingleanddiscussedonthemailinglistafterthe
7Jul11workinggroupcall.
Adoptedlong_names.

03

CorrectissuesraisedbyJohnnyBufuanddiscussedonthe7Jul11working
groupcall.

02

Consistencyandcleanuppass,includingremovingunusedreferences.

01

Initialdraft

TOC
Authors'Addresses
NatSakimura
NomuraResearchInstitute,Ltd.
Email:nsakimura@nri.co.jp
URI:http://nat.sakimura.org/

JohnBradley
PingIdentity
Email:ve7jtb@ve7jtb.com
URI:http://www.threadsafe.com/

http://openid.net/specs/openidconnectbasic1_0.html 29/30
2017518 Draft:OpenIDConnectBasicClientImplementer'sGuide1.0draft37
MichaelB.Jones
Microsoft
Email:mbj@microsoft.com
URI:http://selfissued.info/

BrenodeMedeiros
Google
Email:breno@google.com
URI:http://stackoverflow.com/users/311376/breno

ChuckMortimore
Salesforce
Email:cmortimore@salesforce.com
URI:https://twitter.com/cmort

http://openid.net/specs/openidconnectbasic1_0.html 30/30