OAuth allows users to grant third-party access to their resources like API's and websites without sharing their passwords. It uses authorization codes to obtain access tokens securely. The document discusses OAuth concepts like actors, endpoints, grant types and flows in detail to explain how OAuth works and how to implement it using PingFederate as the authorization server.

1. 1
* E-mails: sales@nexright.com

2. OAuthisanopenprotocolstandardforWebAPIauthorization.OAuthprovidesamethodforuserstograntthird-partyaccesstotheirresourceswithoutsharingtheirpasswords.
What is OAuth?
OAuth is an open protocol standard for Web API authorization
2
Nasrin Sohrabi

3. Why using OAuth2.0 ?
one way to address REST security issues is with the open source protocol OAuth
1) Lack of standards and support of RESTfulAPI
Askingauserfortheirpasswordhasanumberofside-effectsuchas:
Trust:ausermaynottrustprovidingtheirpasswordtoyourapplication.
Expandedaccessandrisks:Whentheuserprovidestheirpasswordtoyourapplication,yougetaccesstonotonlythedatayourapplicationneeds,butallotherdataintheuser’saccount.Theapplicationhasanobligationtoitsuserstosecurelystorethesepasswordsandpreventthemfromleaking.Manydevelopersdonotwanttheriskexposureofhavingthisadditionalresponsibility.
Decreasedusersensitivitytophishing:Eveniftheuseriscomfortableprovidingtheirpasswordtoyourapplication,makingtheusercomfortabledoingthisaroundtheWebcanhavenegativelong-termeffects,suchasmakingphishingscamsmoreeffective.
Limitedreliability:Whenauserchangestheirpassword,yourapplicationnolongerhasaccesstotheirdata.
Revocationchallenges:Theonlywayausercanrevokeaccesstoyourapplicationisbychangingtheirpassword,whichalsorevokesaccesstoallotherapps.
Passwordsbecomerequired:WhenanAPIprovidersupportsfederatedauthenticationmechanismssuchasOpenIDorSAML,usersmaynothavepasswordsontheiraccounts.ThismakesitimpossibleforthoseuserstouseapplicationspoweredbytheAPI.
Difficultyimplementingstrongerauthentication:IfanAPIproviderrequirespasswordsforAPIauthentication,itbecomeschallengingtoimproveaccountsecuritywithtechnologieslikeCAPTCHAsormultifactorauthentication(suchasone-timepasswordtokens).
2)PasswordAnti-Pattern
Within move towards SaaS–trend towards API access to data/services to supplement/replace browser access.
Clear trend for these APIs is towards REST.
3) Cloud APIs
4) Native Mobile Applications
3
Nasrin Sohrabi

4. Client Application
User Agent
How does OAuth2.0 work?
OAuth 2.0 protocol uses a number of actors to achieve the main tasks of getting, validating, and using an access token
4
Nasrin Sohrabi
Authorization Server
Resource Server
Resource Owner

5. The main Actors are:
User or Resource Owner
Theactualenduser,responsibleforauthenticationandtoprovideconsenttosharetheirresourceswiththerequestingclient
User Agent
Theuser’sbrowser.usedforredirect‐basedflowswheretheusermustauthenticateandoptionallyprovideconsenttosharetheirresources.
Client
Authorization Server (AS)
Resource Server (RS)
The Client Application that is requesting an access token on behalf of the end user.
A server capable of issuing tokens, obtaining authorization, and authenticating resource owners.
The target application or API that provides the requested resources. This actor will validate an access token to provide authorization for theaction. (The server hosting protected resources)
5
Nasrin Sohrabi

6. Oauth2.0 provides four standard grant typesandan extension grant type that can beusedto customize the authentication and authorization process depending on the application requirements:
Server Side Web Application Flow (Authorization Code Flow)
Client Side Web Application Flow (Implicit Grant Flow)
Resource Owner Password Flow
Client Credentials
Extension Grant
6
Nasrin Sohrabi
OAuth2.0 Grant Types

7. Authorization Code
Resource Owner Cridential
Implicit
Client Credentials
Used for most Web and mobile application scenarios that want to call REST Web services. uses the user agent to transport an intermediate code, which is then exchanged for the OAuth2 tokens.
Scenariowhereclientisnotabletosafelyhidetheclientsecret(e.g. clientsideJavaScriptapplication).UsestheuseragenttotransportTheOAuth2tokens.
Whenapplicationneedstocontroltheloginform(e.g.NativeMobileapp). Exchangesausername/passwordcombinationfortheOAuth2tokens.
Whenauserisnotinvolved.AccesstokenonlyrequiredforaservicetocallaRESTwebservice.ExchangestheclientcredentialsforanOAuth2Accesstoken.
Extension Grant Type
Used To Extend The Oauth2.0 Grant Types For specific Scenarios (e.g. the SAML bearer extension grant).
7
Nasrin Sohrabi

8. Some of the important terminologies that use during work with OAuth:
Client key:
Client Secret:
Authorization
Code:
Access Token:
Refresh Token:
AvalueusedbytheconsumertoidentifyitselftotheServiceProvider.
A secret used by the consumer to establish ownership of the consumer key.
Avalueusedbytheconsumertoobtainauthorizationfromtheuser,andexchangedforanAccessToken
Atokenusedbytheclienttomakeauthenticatedrequestsonbehalfoftheresourceowner.
Atokenusedbytheclienttoobtainanewaccesstokenwithouthavingtoinvolvetheresourceowner.
8
Nasrin Sohrabi

9. 9
AS Enpoint
Authorization Endpoints:
• used, via user-agent redirection, to authenticate and obtain authorization from the resource owner.
• End user on the front channel.
Token Endpoints
• Used to exchange an authorization grant for an access token.
• Client on the back channel.
Client Endpoint
Redirection URI
• After completing its interaction with the resource owner, the AS directs the resource owner's user-agent back to the client at the client’s redirection URI.
• Front channel callback.
Nasrin Sohrabi
Endpoints

10. The application developer will be responsible for the user-facing Elements Of theprocess.
They will needto authenticate the user and interface with the back-end APIs. There are three main actions an application developer needs to handle to implement OAuth2: 1) Get an access token. 2) Use an access token. 3) Refresh an access token(optional).
10
Nasrin Sohrabi
In the following slides, I will explained how to get an OAuth access token from PingFederate infrastructure, based on Authorization code grant type.

11. Authorizationgrantisaclientredirectbasedflow.Inthisscenario,theuserwillberedirectedtothePingFederateauthorizationendpointviatheuseragent(i.e.webbrowser).ThisuseragentwillbeUsedtoauthenticatetheenduserandallowthemtograntaccesstotheclient.Oncetheuserhasbeenauthorized,anintermediatecodewillbegrantedbytheauthorizationserverandreturnedTotheclientapplicationviatheuseragent.Lastly,theclientwillswapthiscodeforanOauthaccesstoken.
11
Nasrin Sohrabi

12. Authorization code grant process
Request Authorization
Obtain User Authorization
Exchange Code for Access Token
Validate and Perform Actions
There are 4 main steps to the authorization code grant type process:
The client redirects the user to the Authorization Endpoint (Ping Federate)to request an authorization code.
The Resource Owner (User) grants permissions for the
client to access resource data. The authorization code is given to the client (callback
from auth. server).
The authorization code is exchanged for an access token given to the client by the Token Endpoint (Ping Federate) .
The Resource Server validates the Access Token and gives access to the client if validation is successful
12
Nasrin Sohrabi

13. Client
Authorization EndPoint
(PingFederate)
Token EndPoint
(PingFederate)
Resource Server
Grant Authorization Code
Direct user To Resource Provider
User Authentication
Grant permissions
Request Authorization Code
Request Access Token
Grant Access Token
Direct users To the client with authcode
1
Obtain Authorization code
2
Obtain Authorization to use code
Access Protected Resources
Validate Token
Use Access Token
3
Exchange Code for Access Token
4
Client Uses Resources
13
Nasrin Sohrabi

14. Phases in detail:
Theclientrequestsresourcedata,whichredirectstheuserthroughanauthorizationprocessinordertoobtainanauthorizationcode.AftertheuserauthenticatesandauthorizesaccessatPingFederate,acallback(viaanHTTP
redirect)willbemadebacktotheclientapplicationwiththeauthorizationcodeinthequeryStringlike(https://localhost:9031/OAuthPlayground/case1callback.jsp?state=&code=5qJvl5hWL20KS6ZKzQ- eZAYBjF0coxe3YhPaAhM2).Now,theclientsitesendsanhttprequesttoexchangetheauthorizationcodeobtainedinthecallbackforthedesiredtokens(typicallyanaccesstokenandarefreshtoken).TheprocessofexchangingrequirestheclienttocommunicatewiththePingFederateTokenEndpoint(https://<pf>/as/token.oauth2)withthefollowingparameters:client_id,granttype=authorizationcodeandtheauthorizationcodereceivedinthepreviousstep.Forsecurityreasonsthecodecanonlybeusedonce.TheresultisanHTTP200responsetotheclientindicatingsuccessfromtheTokenendpoint.TheresponseisreturnedformattedinJSON(JavaScriptObjectotation) containingtheOAuthAccessToken.Theclientcannowusetheaccesstokentoperformactionsusingthedataitrequiresontheresourceserverbeforethetokenisexpired.TheresourceserverreceivestheaccesstokenandperformsavalidationcheckwiththeTokenendpointtomakesurethetokenisvalidbeforeperformingtherequiredaction.
14
Nasrin Sohrabi

15. Authorization Endpoint
Web Client
(Our application)
Browser
Token Endpoint
1
4
3
2
1
Request query string includes the OAuth client ID, response type and requested scopes and redirect uri.
Request
Redirect to Authorization Server
3
5
15
Nasrin Sohrabi
PingFederate Server

16. WebapplicationredirectsusertoAuthorizationServer(AS),whichisPingFederate,atitsauthorizationendpoint(https://<pf>/as/authorization.oauth2).RequestquerystringincludestheOAuthclientID,responsetype(inthiscaseauthorizationcode)andrequestedscopesandstate.
UserauthenticatestoASviaIdPadapterorIdPconnection.Afterauthentication,userseesconfirmationpagewithrequestedscopesfromtheOAuthclientredirect,andclicks"Approve”
ASredirectsuserbacktoclientsitewithAuthorizationCodeinquerystring.
WebsiteresolvesAuthorizationCodetoanOAuthtoken(AccessToken[andRefreshToken])viaAPIcalltotheASTokenEndpoint(https://<pf>/as/token.oauth2)
TheresultisanHTTP200responsetotheclientindicatingsuccessfromtheTokenEndpoint.TheresponseisreturnedformattedinJSON(JavaScriptObjectNotation)
containingtheOAuthAccessToken
2
4
5
1
3
16
Nasrin Sohrabi

17. An example of authorization request from user and retrieve authorization code
https://localhost:9031/as/authorization.oauth2?
client_id=ac_client&
response_type=code&
scope=edit&
redirect_uri=sample%3A%2F%2Foauth2%2Fcode%2Fcb
17
Nasrin Sohrabi

18. 18
References:
1. Ryan Boyd, Getting Started with OAuth2.0, published by O’REILLY, February 2012.
2. OAuth2 Developers Guide, PingIdentity, 07/09/2014.
3. PingFederate Administrator’s Manual, June 27, 2014 .
4. Ryan Boyd, OAuth2 Identity and Data Access, 2012.
5. John DaSilva, Ping Identity and OAuth and OpenIDConnect In Action with PingFederate Hands-On, 7/8/2013.
6. OAuth2 Tutorial, Ping Identity, July 2014.
Nasrin Sohrabi

19. 19
Nasrin Sohrabi