OAuth And OpenID Connect Primer - Axiomatics

OAuth and OpenID Connect Primer

OAUTH 2.0 AND OPENID CONNECT ARE TWO STANDARDS THATARE ACTIVELY USED IN API SECURITY. THIS DOCUMENT DESCRIBESTHE SPECIFICATIONS IN THE CONTEXT OF API SECURITY.OAuth 2.0OAUTH (PRONOUNCED “OH-AUTH”) is an open standard for token-based authentication. OAuthenables an end user’s (known as a Resource Owner) account information to be used by third-partyservices (called a Client), without exposing the user’s password.THE DRAFT RFC 6749 STANDARD STATES THAT:The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service,either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTPservice, or by allowing the third-party application to obtain access on its own behalf.OAuth enables third-party services consume a user’s data held by another service. OAuth helps avoid users having to sharetheir passwords. OAuth typically is used for HTTP-based RESTful APIs and the calls to get tokens are RESTful as well.JSON is the format of the messages.You may have used financial aggreator websites like Mint.com which ask you to store your credentials for your bank orinvestment account in their site. Financial institutions are moving to an OAuth model to prevent users from having to storetheir passwords at sites like Mint.com.OAuth 2.0 is the version most commonly utilized today. This document will refer to OAuth 2.0 as just OAuth and no earlierversions of the specification will be utilized here. Axiomatics 2016OAuth and OpenID Connect Primer2

OAUTH CONSISTS OF THE FOLLOWINGCOMPONENTS: Access dataCLIENT APPLICATION - the application requestingaccess to a set of resourcesRESOURCE SERVER - the target API applicationwhich contains the resources the client applicationAppAccessservicewants to get access to Issue authZ code/access tokenDelegateauthenticationauthorizationRESOURCE OWNER - the person who owns theresources and / or data ResourceServerClientApplicationAUTHORIZATION SERVER - the entity that issuesaccess and refresh tokens to clients on behalf of theGrant accessResourceOwnerAuthorizationServerresource serverThis diagram (source: Oracle) illustrates the components in a three-legged OAuth Authorization Grant flow. The mostcommon flow is a three-legged authorization grant flow. The following example describes each leg in the context of ourfinancial aggregator example:Leg One involves a user-agent (browser interaction) where a user (say, Alice) has an account at a bank (saySafeBank). Alice wants to use MoneyView to aggregate her financial views from SafeBank and other applications.MoneyView will redirect Alice to SafeBank, where Alice will authenticate (however SafeBank does its authentication).Alice will then be presented with the option to delegate consent to MoneyView to access Alice’s records at SafeBank,possibly with some granularity (checking, savings, investments) as designed by SafeBank and MoneyView. OnceAlice consents for MoneyView to access her SafeBank records, SafeBank will redirect her user-agent (browser) backto MoneyView with an Authorization Grant code.Leg Two involves MoneyView requesting and receiving an Access Token from SafeBank via API calls. MoneyViewuses the Authorization Code (representing Alice’s consent) along with its client credentials to ask for an Access Token.SafeBank will return this Access Token, along with a Refresh Token. he Access Token typically is very short lived (lessthan an hour) while Refresh Tokens are valid for an extended period (like a year typically). When Alice comes toMoneyView the next day, MoneyView will have to pull her records from SafeBank with a new Access Token since thefirst one will have expired. SafeBank will ask for a new Access Token with the Refresh Token. The API calls involvedin issuing and refreshing the Access Token are leg two. There is no browser interaction involved. Alice may bebrowsing MoneyView’s website, which may trigger the start of a Leg Two transaction, but it is the MoneyView APIinteraction that is defined by the specification. Axiomatics 2016OAuth and OpenID Connect Primer3

Leg Three involves MoneyView access the SmartBank APIs using the Access Token acquired in Leg Two. SmartBankemploys a Resource Server, which has the responsibility to consume the Access Token and validate that tokenagainst the same authority, or OAuth Authorization Server, that issued the token. The Authorization Server may returnadditional attributes about Alice. Once validated, the Resource Server allows the API response to be returned to theclient, MoneyView.Two-legged OAuth Flows do not involve the Leg One process of getting user (or Resource Owner) consent. It typicallyinvolves a pre-determined set of scope and consent for what is often a system-to-system transaction.THERE ARE SEVERAL OAUTH FLOWS DEFINED IN ADDITION TO AUTHORIZATION GRANT:All of these OAuth flows involve exchanging tokens. The Access Token itself does not contain any identifying informationabout the user or client. It is opaque, which makes it safe to pass over the internet. OAuth itself does not validate the trustof the client, so often there is some kind of authentication mechanism in addition to the OAuth to validate that the request iscoming from a trusted client and not a rogue client that has stolen an Access Token going over the wire. Axiomatics 2016 Authorization Grant Implicit Grant– JWT Resource Owner– SAML Bearer Client CredentialsOAuth and OpenID Connect Primer Extension Grants4

OpenID Connect (OIDC)OpenID-Connect (OIDC) extends the OAuth 2.0 standard by providing an identity layer on top of OAuth 2.0. OIDC introducesa token called an ID Token. Where an OAuth access token is opaque, i.e. without any claims within the token itself, OIDCdefines a ID Token that has verified claims about the identity of the user. The OAuth Authorization Server looks for a specificscope token request called “openid”. When it receives the openid scope request, the OAuth Authorization Server switchesto OIDC mode. The ID Token is returned alongside the access token:The ID Token is a JSON Web Token (JWT) and can containwhen and where the user’s identity was validated, such aswhether they used multi-factor authentication (MFA). TheID Token can also provide various attributes about theuser’s identity. The Client receives this token and can usethe ID Token to make the application more identity-aware.{ “access token”: “B70UYlAX32I0M8AT18C5”,“token type”: “Bearer”,“refresh token”: “4gH9SK768xLOxBtZp8”,“expires in”: 7200,In OAuth 2.0, scopes are wide-open and can be defined“id token”: “ long encoded string ofin any way. OIDC defines a number of required scopes,characters ” }where OAuth leaves this unbounded. OIDC mandatesattributes like phone, email, and address, but also allowsfor additional discretionary scopes.The OIDC specification also provides an UserInfo Endpoint.This service providers a way for the Client to attain additional{ “sub”: “alice”,attributes or claims about the Resource Owner, when the“groupIds”: [ “sales”,”administrators” ],Resource Owner delegates access to those attributes.“given name”: “Alice”,“name”: “Alice Smith”,“email”: “alice@example.com”,“phone number”: “617-515-9999”,“address”: “123 Main St., Boston, MAOpenID-Connect is similar only in name and branding tothe original OpenID 1.0 and 2.0 standards. The predecessorsof OIDC consisted of people having an identifier, in a URIformat K7z.snengfrom an identity provider like Yahoo or Google that could02345” }be used to sign-in to websites that had incorporated OpenIDcapabilities to make the site an OpenID service provider.Unfortunately, the technology was susceptible to phishingand didn’t have a high adoption rate. Axiomatics 2016OAuth and OpenID Connect Primer5

525 W Monroe St, Suite 2310Chicago, IL 60661, USATel: 1 (312) 374-3443Västmannagatan 4S-111 24 Stockholm, SwedenTel: 46 (0)8 51 510 240webinfo@axiomatics.com www.axiomatics.com twitter.com/axiomatics

OpenID Connect (OIDC) OpenID-Connect (OIDC) extends the OAuth 2.0 standard by providing an identity layer on top of OAuth 2.0. OIDC introduces a token called an ID Token. Where an OAuth access token is opaque, i.e. without any claims within the token itself, OIDC defines a ID Token