Enrich IdentityServer Documentation with OIDC and OAuth2 Flows section

[jawadatgithub]

Hi,

I think OIDC and OAuth2 Flows are core concept that need to be well documented in separate section, currently I am not able to arrive to decision on what flow (or grant) I should use. understanding each flow and providing recommendation where each flow best fit through use cases would save big time for the community, avoid confusions and reduce implementation variations.

I didn't come here to complain, I appreciate the hard work and high quality efforts invested in IdentityServer3. I would like to list and share my current understanding of flows:

Note for community:

A. I noticed that IdentityServer3 docs, samples and code use OIDC & OAuth2 terms interchangeably to refer to same thing in many areas. I think that's make sense because OIDC introduced as complement & extension for OAuth2, although in some cases that confuse me when I google some terms to gain further details and get little shock that OIDC or OAuth2 not related. i.e., 'Tenant' term is not mentioned in OAuth2. OIDC also not define what it mean! yet alot of DB schemas and OAuth libraries use tenant term, I guess its used in obsolete standards but people stick with it! B. IdentityServer3, STS, OP, OIDC server, OAuth2 server, CSP, IDP and others: means same thing (software that provide/issue tokens to clients) as explained in Terminology

[Important] Choosing wrong flow leads to security threat.

Part one: Flow Types and Origin

- OAuth2 standard specs defined 4 grants + extensibility for custom grant:

Note: grants and flows mean same thing, grant was the common term in OAuth2 specs and flow is the common term in OIDC specs.

This document will not focus on custom flow/grant.

1. authorization code

2. implicit

3. resource owner password credentials

4. client credentials

- OIDC standard specs Enriched Two OAuth2 flows (authorization code & implicit) to support Authentication, and introduced new flow called:

5. Hybrid Flow

- IdentityServer3 Support all flows (below snippet copied from IdentityServer3 core) :

//OpenID Connect flows. (this another example of using OIDC term to refer for OAuth2 & OIDC)
public enum Flows
    {
        AuthorizationCode = 0,  //introduced in OAuth2 then extended by OIDC.
        Implicit = 1,           //introduced in OAuth2 then extended by OIDC.
        Hybrid = 2,             //introduced in OIDC
        ClientCredentials = 3,  //OIDC specs didn't extend this flow.
        ResourceOwner = 4,      //OIDC specs didn't extend this flow.
        Custom = 5,
    }

Part Two: Explaining each of the five flow types

for time being, I will highlight what I know, through feedbacks and corrections I will update and reformat...

Q. What Does OAuth2 & OIDC Flows really mean?

A. its mechanism/approach/process (set of steps) that allow client to obtain token(s) from STS/OP through Endpoints. in other words, the whole life cycle of any Authentication & Authorization request is bound by one of the flows. so its essential to first understand the meaning of endpoints, clients, tokens and terms already explained in IdentityServer3 docs.

The main purpose of introducing multiple flow/grant types is to authenticate & authorize access to protected resources in various ways with different security credentials due to the variation of HTTP services based application architectures.

Q. Out of the 11 Endpoints implemented in IdentityServer3, Which are related to Authentication/Authorization request in all flow types?

A. In all flow types, any Authentication/Authorization request will be received by Authorization Endpoint or Token Endpoint only. so only two Endpoints handle the initial request. all other endpoints play important roles but not used during Authentication/Authorization request. and since flows focus on how Authentication/Authorization request being handled, this document will only focus on Authorization Endpoint & Token Endpoint.

- Authorization Endpoint: (in IdentityServer3 docs called: Authorization/Authentication Endpoint) Used to request:

• identity token, access token, both tokens (implicit flow & hybrid flow).
• authorization codes (authorization code flow & hybrid flow).

You either use a web browser or a web view to start the process.

- Token Endpoint: Used to programmatically request or refresh tokens (authorization code flow, hybrid flow, resource owner password credential flow, client credentials flow and custom grant types).

Note: All requests to the token endpoint must be authenticated - either pass client id and secret via Basic Authentication or add client_id and client_secret fields to the POST body. In other words, don't imagine that all authentication requests in all flows handled by Authorization endpoint, Authorization Endpoint will only provide authentication (identity token) for Implicit flow and Hybrid flow.

[Important] ID tokens are meant for the client. Access tokens are meant for APIs. Don't send id tokens to APIs. ONLY case id_token sent to STS is EndSessionRequest but its optional.

Q. Which Flow Type in OpenID Connect (OIDC) / IdentityServer3 best fit the SPA use case?

A. Implicit flow designed for spa, client apps without server-side. Implicit flow is the default flow in IdentityServer3. although Implicit flow require redirectUri, it should be known that Google, Facebook, MS, Twitter, StackOverflow, GitHub, Yahoo...all follow the redirectUri concept. the main idea is any client (like web browser, native app) can't be trusted in Internet zone. in other words, if the SPA deployed in Intranet zone (on premise where all clients and users well known) (trusted environment) then its possible to honor seamless login experience over security. but since Intranet is pretty fast I still recommend to use Implicit flow for sake of consistency (would you like to make different branch of your code base if later on same SPA need to be deployed over internet?!)

Q. Which Flow Types designed to be used ONLY in trusted environment (like backend REST API/ micro-services isolated from internet, or owned servers/devices, in general: trusted OAuth2 clients)?

A.

• Resource Owner Password Credential Flow (ROPCF) [it involve human: app show its own login page then pass user/pass... to STS].
• Client Credential flow [machine to machine (API to API): supply client-id and secret].

  Q. Authorization Code vs Implicit vs Hybrid vs Resource Owner Password Credential vs Client Credential Flows?

A. Authorization Code Flow:

• Returns an authorization code that can then be exchanged for an ID token and access token.
• Authentication request require client id and secret to retrieve the tokens.
• Tokens not revealed to User Agent.
• Support long lived access (through the use of refresh tokens).
• Obtains the authorization code from the Authorization Endpoint.
• All tokens are returned from the token endpoint.
• Suitable only for clients who are capable of maintaining a client secret between itself and the STS securely (trusted environment or trusted OAuth2 Clients) (Example: server side MVC applications).
• [Important] Avoid/Don't send access token to browser, after code obtained, webserver can talk with STS through the received code to obtain access token without browser involvement .

Implicit Flow:

• Requests tokens without explicit client authentication, instead using the redirect URI to verify the client identity. (means in one round trip client can directly obtain identity token & access token).
• Long lived tokens are not supported by design (refresh tokens aren't allowed for implicit flow). but in IdentityServer3 you can set/use long lived access tokens, or keep obtaining new ones through TokenManager JS helper library that can keep renewing tokens from an iframe (tradeoff between security and productivity).
• Tokens revealed to User Agent.
• All tokens are returned from the Authorization endpoint.
• Does not use/communicate with the token endpoint.
• Mainly used by web browser clients such as scripting clients, angularjs apps and SPA.

Hybrid Flow:

• Combination of Implicit Flow and Authorization Code Flow.
• It allows to request a combination of identity token, access token and code via the front channel using either a fragment encoded redirect (native and JS based clients) or a form post (server-based web applications).
• Tokens revealed to User Agent.
• Support long lived access (through the use of refresh tokens).
• Obtains the authorization code from the Authorization Endpoint. (authorization code is mandatory in Hybrid Flow, otherwise Hybrid Flow will be clone of Implicit Flow).
• Tokens are returned from authorization endpoint & token endpoint (totally depend on response_type value in the initial request to authorization endpoint) (if all tokens returned from token endpoint Hybrid Flow will be clone of Authorization Code Flow).
• Hybrid flow can be spotted whenever you see a response type of code combined with some other response type, e.g. id_token or token (or both).
• Usage varies e.g. scenarios where your client app can make immediate use of an identity token to get access to the user’s identity but also retrieve an authorization code that that can be used (e.g. by a backend service) to request a refresh token and thus gaining long lived access to resources.
• Typically used for clients that have their functionality distributed across a JavaScript part and a server-side part.
• My definition for Hybrid Flow: enrich Implicit Flow with long lived access using refresh tokens feature of the Authorization Code Flow. AND, enrich Authorization Code Flow with obtaining identity token &/or access token in single round trip using Implicit Flow.

Resource Owner Password Credential Flow:

• Pure OAuth2 Flow, OpenID Connect got nothing to-do with this flow because no end user identity involved (so id_token can't be obtained).
• The user provide service credentials (username and password) directly to the application ( (e.g., login UI), which uses the credentials to obtain an access token from the service.
• Supposed to be used by the applications that are owned by the resource server itself, and not any other third party.
• Support long lived access (through the use of refresh tokens).
• All tokens are returned from the token endpoint.
• can be used to migrate existing clients using direct authentication schemes such as HTTP Basic or Digest authentication to OAuth2 by converting the stored credentials to an access token (allows for legacy applications to incrementally transition to OAuth2).
• Doesn't support SSO with 3rd party STS/OP because for every STS/OP you need the user to enter his/her un/pass.
• Should only be used when there is a high degree of trust between the resource owner and the client, and when alternative flows (like Authorization Code Flow) not available/viable.
• This grant/flow type carries a higher risk than other grant types because it maintains the password anti-pattern OAuth2 protocol seeks to avoid.
• The client could abuse the password, or the password could unintentionally be disclosed to an attacker (e.g., via log files or other records kept by the client) (e.g., if STS is twitter and they allow ROPCF for 3rd party apps, then the apps have access to the user twitter password and username, which already happened years ago).
• STS/AS and client SHOULD minimize use of this grant type and utilize other grant/flow types whenever possible.

Client Credential Flow:

• Pure OAuth2 Flow, OpenID Connect got nothing todo with this flow because no end user identity involved (so id_token can't be obtained).
• refresh token SHOULD NOT be included/issued (since this flow not require user approval/involvement, new token can be easily obtained if the current expired).
• Typically used when the client is acting on its own behalf (the client is also the resource owner) or is requesting access to protected resources based on an authorization previously arranged with the AS/STS (excellent for embedded services and backend applications).
• MUST only be used by confidential clients.
• All tokens (actually access token is the only token in this flow) are returned from the token endpoint.
• Examples of when this might be useful include if an application wants to update its registered description or redirect URI, or access other data stored in its service account via the API.

---

Remark: MS OpenID Connect authentication middleware [Microsoft.Owin.Security.OpenIdConnect] [its client library for OIDC server] only support Hybird Flow. I think this is not a big deal since Thinktecture.IdentityModel provide OIDC and Oauth2 client library that support all flows.

Sources:

http://identityserver.github.io/Documentation/ https://www.scottbrady91.com/OpenID-Connect/OpenID-Connect-Flows http://wso2.com/library/articles/2014/06/open-id-connect/ http://leastprivilege.com/ http://oauthlib.readthedocs.org/en/latest/oauth2/grants/grants.html https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2 http://tools.ietf.org/html/rfc6749 http://openid.net/specs/openid-connect-core-1_0.html

this all what I know now, please help me refine and understand Flows and its relation with endpoints clearly and deeply. I followed this project anonymously for over 2 months now and consumed all related videos on Vimeo and docs as well as keep tracking of [http://leastprivilege.com/] and [http://brockallen.com/]... but still far from mastering the whole life cycle. if any bit of information listed above is invalid, not accurate or misleading then please highlight ASAP.

[brockallen]

Yes, all good ideas. 1) It's a time thing -- we only have so much time, and 2) I'm not sure we see it as our responsibility to document the specs to be more human readable. Of course this helps so that people can understand IdSvr better, but it gets back to the time issue and priorities.

Of course, this is where the community can get involved -- feel free to make a blog post. We can certainly link to it.

[jawadatgithub]

thanks for the input, please keep this issue open until I refine my understanding of the topic and update the post periodically [I assume one week will be sufficient]. at the end this should help save time to quickly answer many questions raised under IdentityServer3, I will also try to contribute in community questions.

about the OIDC and OAuth2 specs, its very hard to draw conclusion for use cases of Flows. so I will try to document my understanding of that gradually.

when I start looking to IdentityServer3 I wanted like many others (as appear in IdentityServer3 issues) to avoid the login redirect, but after reading and watching all your videos as well Dominick videos. I understood that's not the way to go unless I am fine with losing valuable features of IdS3 STS such SSO.

about blog post: yes I will do that in case you don't want include section for flows.

thanks again for your time.

[omidkrad]

Thank you, I think people will find this very useful. IdSrv has a very clean and well designed code, but it's still hard to grasp all the functionality from code. Documentation like this helps me and other people get started faster as people usually don't dive in the specs first to explore a new library. @jawadatgithub you can also create a public gist for this so people can fork it and help you with updates. But it would be best if it is added next to the rest of the IdSrv docs.

[omidkrad]

"don't imagine that all authentication requests in all flows handled by Authorization endpoint, Authorization Endpoint will only provide authentication (identity token) for Implicit flow."

Are you sure? In the samples I see Hybrid clients, MVC FormPost client, MVC CodeFlowClient also use the Authorization endpoint.

[jawadatgithub]

@omidkrad

1. sorry for the late response.
2. about Hybrid you are correct, I updated.
3. about FormPost client: Defines how to return OAuth2/OIDC Response parameters: means its not introducing new flow, based on my understanding FormPost only work with (depends on) code, Implicit & Hybrid flows check here.
4. CodeFlow: as explained in 'vs' question: Authorization Endpoint only provide code, but Id_token (authentication request) obtained from token endpoint. in other words, in code flow: authorization endpoint not responsible for authentication, in samples: you can see it clearly.
5. I will add note later that clarify OIDC authentication extension for OAuth2: in summary: OIDC authentication is based on Authenticate User Identity only, in OAuth2 all flows require authentication but not in the context of user identity. (for example: Client Credential Flow is not meant at all with user identity (or OIDC in general) but its still include authentication.
6. thank you for taking time review the draft, please keep highlighting any concerns or inputs.

[omidkrad]

Regarding # 2, I think it also includes Code flow? no?

[jawadatgithub]

thanks for following up,

I am not sure what you mean by # 2. let me clarify further, please notice the bold terms:

In other words, don't imagine that all authentication requests in all flows handled by Authorization endpoint, Authorization Endpoint will only provide authentication (identity token) for Implicit flow and Hybrid flow.

as I explained in point 4: CodeFlow: as explained in 'vs' question: Authorization Endpoint only provide code, but Id_token (authentication request) obtained from token endpoint. in other words, in code flow: authorization endpoint not responsible for authentication, in samples: you can see it clearly.

does that answer and clarify your input?

[jawadatgithub]

I finished drafting the document. I followed @omidkrad advice and made Gist:

OIDC and OAuth2 Flows.md

Please let me know if you have any further comments or feedbacks within 24 hours before closing this issue. I hope its good enough to be embedded in Identityserver3 docs or at least linked..

[omidkrad]

This looks good @jawadatgithub, also thanks for clarifying about CodeFlow.

[DoubleExposure]

Thanks. Valuable post!!!