#standards
-
On AMP for Email by Jason Rodriguez
Philosophically, I’m completely against Google’s AMP project and AMP for Email, too. I will always side with the open web and the standards that power it, and AMP is actively working against both. I’m all-in on a faster web for everyone, but I just can’t get behind Google’s self-serving method for providing that faster web.
-
How not to replace email (jamey.thesharps.us)
I’d say the single most important lesson to take away here, for a technology project at least, is that interoperability is key.
- Assume that no matter how amazing your new tech is, people are going to adopt it slowly.
- Give your early adopters every chance you can to use your offering together with the existing tools that they will continue to need in order to work with people who haven’t caught up yet.
- And if you’re building a communication tool, make it as simple as possible for others to build compatible tools, because they will expand the network of people your users can communicate with to populations you haven’t thought of and probably don’t understand.
-
WebSub and IndieAuth Published on w3.org!
Today, we published the last of the two W3C specs I am editing! WebSub was published as a W3C Recommendation, and IndieAuth was published as a Working Group Note.
WebSub
WebSub is a standardized way for publishers to notify subscribers when new content is available. It was formerly known as PubSubHubbub, which was hard to say, so I'm glad we renamed it.
https://www.w3.org/TR/websub/ One of our goals with WebSub was to ensure that existing PubSubHubbub implementations would still be compliant, so there are already lots of implementations in the wild! If you're publishing content online, want to receive realtime updates when feeds are updated, or are building a tool to facilitate either of these, WebSub is a great fit! You can use the tool at websub.rocks while building your implementation to get immediate feedback!
Thanks to everyone who contributed to the spec, and especially my co-editor Julien!
IndieAuth
IndieAuth is an identity layer on top of OAuth 2.0, and used by Micropub clients. Micropub was published as a W3C Recommendation in May of last year. Today, IndieAuth was published as a W3C Working Group Note.
https://www.w3.org/TR/indieauth/ The Social Web Working Group did not set out with the goal to standardize any sort of authentication mechanism, but since almost all of the Micropub implementations already supported the same mechanism, we decided to publish a "Note" to that effect. (The Micropub implementations that don't use IndieAuth use hard-coded tokens as a shortcut.) Notes are quite different from Recommendations in the eyes of the W3C, as described by this sentence: "The publication of a NOTE by the Consortium implies no endorsement of any kind." The goal of publishing this Note was to capture the current state of interoperable implementations.
One of the things I like most about the W3C standardization process is that specs are published after they describe things that are working, rather than published as an aspirational blueprint. We kind of pushed that definition to an extreme with IndieAuth, since there have been live interoperable IndieAuth implementations for several years now. Previously, I had written up several guides for how to implement the various roles in the IndieAuth flow, but never written it down as its own spec. The guides were certainly useful, as was clearly demonstrated by the fact that people were following them to build out various parts of the ecosystem. But there is also a need for a spec to lay things out and remove any ambiguities along the way.
Thanks to everyone who helped iron out the details of the language in the spec! We made a lot of good progress over the last few months!
What's Next?
So with these two specs published today, we've taken quite a lot of the IndieWeb building blocks through the W3C process!
-
Webmention - enables direct site-to-site commenting and other interactions
- Post Type Discovery - once you receive a Webmention, this algorithm helps your site know what to do with the contents
- Micropub - enables apps to create content on a website
-
WebSub - enables real-time subscriptions to web pages and feeds
- IndieAuth - a way to log in to sites with your domain name, and allow Micropub apps to post to your site
- jf2 - a post serialization format used by some Webmention services and other tools
So here's a few specs and tools that I'm working in the immediate future:
IndieAuth test suite - Like webmention.rocks, micropub.rocks and websub.rocks, I plan to make a tool that will help test your IndieAuth implementation. It will do things like throw tricky situations at your client to ensure you're handling the edge cases properly.
Finally finish renaming indieauth.com - I never should have called it that, since it's doing two completely separate things. You can read about the details here.
Microsub - Microsub is currently an early draft spec. The goal of Microsub is to do for reader interfaces what Micropub did for publishing interfaces. A Microsub server provides a standardized API that reader clients can use to show content. This will help make developing IndieWeb readers a lot easier, and also allows you to keep your subscription list in a server that you control rather than letting the reader own the list.
Monocle - Monocle is my Microsub implementation. It subscribes to feeds and presents a them as a Microsub server so that I can use any Microsub client to view everything. There's still a lot of work ahead for me here, but it's my goal to finally stop using IRC as a reader by getting Monocle to the point of being functional enough to cover all my use cases.
As always, you can help me and the rest of the IndieWeb out by adding support for any of these specs on your own website! We are always excited to welcome new people to the IndieWeb chat if you have any questions!
-
Webmention - enables direct site-to-site commenting and other interactions
-
Your friendly reminder that without open standards, you're not "buying" smarthome hardware, you're renting it. http://www.businessinsider.com/googles-nest-closing-smart-home-company-revolv-bricking-devices-2016-4 -
Just used an Apple USB-C/HDMI adapter to connect a Windows laptop to a projector. #standards #ftw
-
A short note about web standards from your friends at Known (stream.withknown.com)
Any new web standard must be easy enough to understand and implement that a developer can get something up and running in an afternoon. HTML, HTTP and RSS all adhere to these principles. So do the indieweb protocols, which is why we support them and think they are likely to succeed.
-
Talking to DC | Adam Bosworth's Weblog (adambosworth.net)
Standards work best when they are focused. Don’t build an 18 wheeler to drive a city block. Standards often fail because committees with very different complex goals come together without actual working implementations to sanity check both the complexity (see point 1 above) and the intelligibility (see point 2 above).
-
So you implemented an OAuth 2.0 API...
While OAuth 2.0 is a good framework for building an API, the spec itself leaves many things un-specified, and it's up to the implementer to make a decision based on their own security requirements. As such, most OAuth 2.0 implementations are not interoperable, which is often cited as a failure of OAuth 2.0. On the other hand, the current state of OAuth 2.0 implementations is that they are often similar enough that developers don't need to learn too many new concepts when dealing with them.
This post documents all the ways in which OAuth 2.0 implementations may differ. All implementations of OAuth 2.0 have made decisions about these things (whether intentional or not), otherwise they are incomplete implementations.
Every place in the spec that mentions things are a "MUST" are assumed to be implemented correctly. In other words, this does not ask you to verify that you implemented required parts of the framework correctly.
Client Registration (Section 2)
How do developers register a new client application?
- on a web page (link to registration page)
- programmatically (link to docs)
- other (please describe)
Aside from the client type and redirect URIs, what information is required or requested when registering an application?
- application name
- web page
- description
- logo image
- acceptance of legal terms
- other info:
Client ID (Section 2.2)
Clients should avoid making assumptions about the length of the client ID.
What is the maximum string length of client IDs issued?
Client Authentication (Section 2.3)
What form of client authentication is supported?
- Client ID and secret (this is the most common)
- Public/private key pair
- Other
Client Password (Section 2.3.1)
If clients are issued a
client_secret, which authentication mechanisms are supported for client identification:- HTTP
Authorizationheader (HTTP Basic Auth) - POST body parameters,
client_idandclient_secret(not recommended)
Other Client Authentication Methods (Section 2.3.2)
If clients are not issued a
client_secret, describe any other HTTP authentication schemes used to authenticate clients:Protocol Endpoints (Section 3)
Please specify the authorization endpoint and token endpoints. (note: this is only required here if your endpoints are specified in your documentation)
- Authorization endpoint:
- Token endpoint:
How do clients obtain the location of the authorization and token endpoints? The most common way is to specify them in the API documentation, although an automatic discovery method may be used instead.
- API Documentation
- Other method:
Authorization Endpoint (Section 3.1)
How does the authorization endpoint authenticate users? (e.g. requires username and password logins each visit? maintains session cookies?)
Response Types (Section 3.1.1)
Aside from "code" and "token", are any additional response types supported?
- Yes, additional types:
- No
Redirect Endpoint Confidentiality (Section 3.1.2.1)
- Are redirect endpoints required to be HTTPS? Yes No
- If HTTPS is not required, does the authorization endpoint warn users about the insecure redirect endpoint? Yes No
Redirect URI Registration (Section 3.1.2.2)
Registration of the redirect endpoints is required for public clients and clients using the "implicit" grant type. Aside from these uses, are all clients required to register redirect URIs?
- Are all clients required to register their redirect URIs? Yes No
- Is the registered redirect URI required to match exactly? Yes No
- If both previous answers are "no", does the authorization server support a variable query string component of the registered redirect URI? Yes No
- Can clients register multiple redirect URIs? Yes No
Note: if registration of redirect URIs is not required for all clients, then your authorization endpoint can be used by an attacker as an open redirector.
Invalid Redirect Endpoint (Section 3.1.2.4)
- Does the authorization endpoint inform the user that a given redirect endpoint is invalid?
Yes No
If the answer is "no", please describe what happens when an invalid redirect URI is provided in an authorization request. (The authorization endpoint must not redirect to this endpoint.)
Access Token Scope (Section 3.3)
- Is it possible for the authorization server to ignore (or add) scopes to the values requested during authorization? (For example, giving users the ability to not grant certain scopes requested by the application.) Yes No
- Does the authorization server document the default scope if none is specified during authorization? Yes (Documentation URL: ) No
Authorization Response (Section 4.1.2)
- What is the lifetime of authorization codes? (Maximum of 10 minutes is recommended)
- If an authorization code is used more than once, does the authorization server revoke all access tokens granted using the authorization code? Yes No
- What is the maximum size of authorization codes issued?
List any other parameters returned, as well as their maximum sizes:
Authorization Error Response (Section 4.1.2.1)
- If the request fails due to an invalid redirect URI or missing client ID, does the authorization server inform the user of the error? Yes No
- Does the error response contain an
error_descriptionfield with a human-readable description of the error that occurred? Yes No - Does the error response contain an
error_urifield which links to a human-readable web page about the error? Yes No
Implicit Grant (Section 4.2)
Implicit Grant Access Token Response (Section 4.2.2)
When does the access token response include an
expires_inparameter?- Always
- Sometimes
- Never
If the
expires_inparameter is not returned, the default value of the expiration is:Does the response always include the scope of the access token? (Optional if it's identical to the scope requested by the client.) Yes No
What is the maximum size of authorization codes issued?
List any other parameters returned, as well as their maximum sizes:
Authorization Error Response (Section 4.2.2.1)
- If the request fails due to an invalid redirect URI or missing client ID, does the authorization server inform the user of the error? Yes No
- Does the error response contain an
error_descriptionfield with a human-readable description of the error that occurred? Yes No - Does the error response contain an
error_urifield which links to a human-readable web page about the error? Yes No
Password Credentials Grant Type (Section 4.3)
Describe what types of clients can use the password credentials grant type:
Authorization Request (Section 4.3.1)
Describe how the user enters their credentials, e.g. a username and password prompt, client certificate auth, or whether the server uses or requires two-factor auth:
Access Token Request (Section 4.3.2)
Since the access token request involves sending the user's password to the authorization server, the server must protect against brute-force attacks. Describe what type of protection is used, e.g. rate limiting, sending alerts to the user, etc:
Access Token Response (Section 4.3.3)
- Does the client receives a refresh token when using the password credentials grant type? Yes No
Client Credentials Grant (Section 4.4)
What type of client authentication is used for the client credentials grant? e.g. client ID and secret, public key auth, etc.
- Client Credentials (client ID and secret)
- Others:
Can clients use the client credentials grant to request access to resources of other users who have been previously authorized? Yes No
If yes, describe how clients indicate which user they requesting an access token for. E.g. specifying a username, user ID, opaque token, etc.
Access Token Response (Section 4.4.3)
- Does the client receive a refresh token when using the client credentials grant type? (Not recommended) Yes No
Extension Grants (Section 4.5)
Authorization servers may support additional extension grant types such as SAML. List any additional grant types that are supported, along with links to their documentation.
Successful Access Token Response (Section 5.1)
- Does the access token response include an
expires_inparameter indicating the lifetime in seconds of the access token? Yes No - If not, what is the default value: , or describe another way the expiration time is indicated:
- Refresh tokens are returned for the following grant types:
- Authorization Code
- Implicit
- Client Credentials
- Refresh Token
- None of the above
- Describe any other conditions under which a refresh token is or is not returned when requesting an access token. E.g. only for specific clients, etc:
- What is the maximum size of access tokens issued?
- What is the maximum size of refresh tokens issued?
- List any other parameters returned, as well as their maximum sizes:
Error Response (Section 5.2)
- Does the error response contain an
error_descriptionfield with a human-readable description of the error that occurred? Yes No - Does the error response contain an
error_urifield which links to a human-readable web page about the error? Yes No
Refreshing an Access Token (Section 6)
- Does the authorization server issue new refresh tokens when a refresh token is used? Yes No
- If a new refresh token is issued, is the existing refresh token revoked? Yes No
Accessing Protected Resources (Section 7)
Describe how the resource server validates access tokens: (e.g. uses the authorization server's private API, shares cryptography keys, shares a database connection)
Describe how clients send the access token to the resource server. This typically involves sending the access token in the "Authorization" request header.
Access Token Type (Section 7.1)
Which access token types are accepted?
- Bearer tokens
- MAC tokens
- Others:
Error Response (Section 7.2)
Does the resource server inform the client of an error? Yes No
New Authentication Schemes
If you are using a new authentication scheme (other than Bearer tokens), there are several things to take into account when handling error responses. Please describe the following:
- How your new authentication scheme provides error status codes to the client
- What is the name of the error parameter? (e.g.
error) - Does your scheme also return an
error_descriptionparameter? Yes No - Does your scheme also return an
error_uriparameter? Yes No
Security Considerations (Section 10)
Client Authentication (Section 10.1)
- Are client passwords (or other credentials) issued to clients for specific devices? (e.g. an individual installation of an application on a device gets unique credentials.) Yes No
- When clients are unable to use authentication such as a
client_secret, does the authorization server employ other means to validate the client's identity?- Requires registration of redirect URIs for clients
- Involves the user in confirming the client's identity
- Other:
- No
Client Impersonation (Section 10.2)
- Does the authorization server provide the user with information about the client? Yes No
- ... about the requested scope? Yes No
- ... and lifetime of the request? Yes No
- Describe the security measures taken to ensure repeated authorization requests come from the original client and not an impersonator:
-
OAuth 2 Simplified
This post describes OAuth 2 in a simplified format to help developers and service providers implement the protocol.
The OAuth 2 spec itself leaves many decisions up to the implementor. Instead of describing all possible decisions that need to be made to successfully implement OAuth 2, this post makes decisions that are appropriate for most implementations.
Table of Contents
- Roles: Applications, APIs and Users
- Creating an App
- Authorization: Obtaining an access token
- Making Authenticated Requests
- Differences from OAuth 1.0
- Resources
Roles
The Third-Party Application: "Client"
The client is the application that is attempting to get access to the user's account. It needs to get permission from the user before it can do so.
The API: "Resource Server"
The resource server is the API server used to access the user's information.
The User: "Resource Owner"
The resource owner is the person who is giving access to some portion of their account.
Creating an App
Before you can begin the OAuth process, you must first register a new app with the service. When registering a new app, you usually register basic information such as application name, website, a logo, etc. In addition, you must register a redirect URI to be used for redirecting users to for web server, browser-based, or mobile apps.
Redirect URIs
The service will only redirect users to a registered URI, which helps prevent some attacks. Any HTTP redirect URIs must be protected with TLS security, so the service will only redirect to URIs beginning with "https". This prevents tokens from being intercepted during the authorization process.
Client ID and Secret
After registering your app, you will receive a client ID and a client secret. The client ID is considered public information, and is used to build login URLs, or included in Javascript source code on a page. The client secret must be kept confidential. If a deployed app cannot keep the secret confidential, such as Javascript or native apps, then the secret is not used.
The first step of OAuth 2 is to get authorization from the user. For browser-based or mobile apps, this is usually accomplished by displaying an interface provided by the service to the user.
OAuth 2 provides several "grant types" for different use cases. The grant types defined are:
- Authorization Code for apps running on a web server
- Implicit for browser-based or mobile apps
- Password for logging in with a username and password
- Client credentials for application access
Each use case is described in detail below.
Web Server Apps
Web server apps are the most common type of application you encounter when dealing with OAuth servers. Web apps are written in a server-side language and run on a server where the source code of the application is not available to the public.
Authorization
Create a "Log In" link sending the user to:
https://oauth2server.com/auth?response_type=code& client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=photosThe user sees the authorization prompt
If the user clicks "Allow," the service redirects the user back to your site with an auth code
https://oauth2client.com/cb?code=AUTH_CODE_HEREYour server exchanges the auth code for an access token
POST https://api.oauth2server.com/token grant_type=authorization_code& code=AUTH_CODE_HERE& redirect_uri=REDIRECT_URI& client_id=CLIENT_ID& client_secret=CLIENT_SECRETThe server replies with an access token
{ "access_token":"RsT5OjbzRn430zqMLgV3Ia" }or if there was an error
{ "error":"invalid_request" }Security: Note that the service must require apps to pre-register their redirect URIs.
Browser-Based Apps
Browser-based apps run entirely in the browser after loading the source code from a web page. Since the entire source code is available to the browser, they cannot maintain the confidentiality of their client secret, so the secret is not used in this case.
Authorization
Create a "Log In" link sending the user to:
https://oauth2server.com/auth?response_type=token& client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=photosThe user sees the authorization prompt
If the user clicks "Allow," the service redirects the user back to your site with an access token
https://oauth2client.com/cb#token=ACCESS_TOKENThat's it, there's no other steps! At this point, some Javascript code can pull out the access token from the fragment (the part after the #) and begin making API requests.
If there was an error, you will instead receive an error code in the URI fragment, such as:
https://oauth2client.com/cb#error=access_deniedMobile Apps
Like browser-based apps, mobile apps also cannot maintain the confidentiality of their client secret. Because of this, mobile apps must also use an OAuth flow that does not require a client secret.
Authorization
Create a "Log in" button sending the user to either the native app of the service on the phone, or a mobile web page for the service. On iPhone, apps can register a custom URI protocol such as "facebook://" so the native Facebook app is launched whenever a URL with that protocol is visited. On Android, apps can register URL matching patterns which will launch the native app if a URL matching the pattern is visited.
iPhone
If the user has the native Facebook app installed, direct them to the following URL:
fbauth2://authorize?response_type=token&client_id=CLIENT_ID &redirect_uri=REDIRECT_URI&scope=emailIn this case, your redirect URI looks like
fb00000000://authorizewhere the protocol is "fb" followed by your app's client ID. This means your app must be registered to open URLs with that protocol.Android or Others
If the user does not have the Facebook iPhone app, or for other devices, you can launch a mobile browser to the standard web authorization URL.
https://facebook.com/dialog/oauth?response_type=token &client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=emailThe user will see the authorization prompt
After clicking "Okay", the user will be redirected back to your application by a URL like
fb00000000://authorize#token=ACCESS_TOKENYour mobile application can parse out the access token from the URI and begin using it to make API requests.
Others
Password
OAuth 2 also provides a "password" grant type which can be used to exchange a username and password for an access token directly. Since this obviously requires the application to collect the user's password, it should only be used by apps created by the service itself. For example, the native Twitter app could use this grant type to log in on mobile or desktop apps.
To use the password grant type, simply make a POST request like the following:
POST https://api.oauth2server.com/token grant_type=password& username=USERNAME& password=PASSWORD& client_id=CLIENT_IDThe server replies with an access token in the same format as the other grant types.
Note, the client secret is not included here under the assumption that most of the use cases for password grants will be mobile or desktop apps, where the secret cannot be protected.
Application access
In some cases, applications may wish to update their own information such as their website URL or application icon, or they may wish to get statistics about the users of the app. In this case, applications need a way to get an access token for their own account, outside the context of any specific user. OAuth provides the client_credentials grant type for this purpose.
To use the client credentials grant type, make a POST request like the following:
POST https://api.oauth2server.com/token grant_type=client_credentials& client_id=CLIENT_ID& client_secret=CLIENT_SECRETYou will get an access token response in the same format as the other grant types.
Making Authenticated Requests
Now that you have an access token, you can make requests to the API. You can quickly make an API request using cURL as follows:
curl -H "Authorization: Bearer RsT5OjbzRn430zqMLgV3Ia" \ https://api.oauth2server.com/1/meThat's it! Make sure you always send requests over HTTPS and never ignore invalid certificates. HTTPS is the only thing protecting requests from being intercepted or modified.
Differences from OAuth 1.0
OAuth 1.0 was largely based on existing proprietary protocols such as Flickr's "FlickrAuth" and Google's "AuthSub". The result represented the best solution based on actual implementation experience. However, after several years of working with the protocol, the community learned enough to rethink and improve the protocol in three main areas where OAuth 1.0 proved limited or confusing:
Authentication and Signatures
The majority of developers' confusion and annoyance with OAuth 1.0 was due to the cryptographic requirements of signing requests with the client ID and secret. Losing the ability to easily copy and paste cURL examples made it much more difficult to get started quickly.
OAuth 2 recognizes this difficulty and replaces signatures with requiring HTTPS for all communications between browsers, clients and the API.
User Experience and Alternative Authorization Flows
OAuth includes two main parts, obtaining an access token, and using the access token to make requests. OAuth 1.0 works best for desktop web browsers, but fails to provide a good user experience for native desktop and mobile apps or alternative devices such as game or TV consoles.
OAuth 2 supports a better user experience for native applications, and supports extending the protocol to provide compatibility with future device requirements.
Performance at Scale
As larger providers started to use OAuth 1.0, the community quickly realized the protocol does not scale well. Many steps require state management and temporary credentials, which require shared storage and are difficult to synchronize across data centers. OAuth 1.0 also requires that the API server has access to the application's ID and secret, which often breaks the architecture of most large providers where the authorization server and API servers are completely separate.
OAuth 2 supports the separation of the roles of obtaining user authorization and handling API calls. Larger providers needing this scalability are free to implement it as such, and smaller providers can use the same server for both roles if they wish.
Resources
Credit: Some content adapted from hueniverse.com.
More information is available on oauth.net
-
Introducing IndieAuth
IndieAuth is a service that implements RelMeAuth, originally proposed by Tantek Çelik in February 2010. The original algorithm was described in a short text update on Tantek's website. Later that evening, Jeff Lindsay and Paul Tarjan implemented RelMeAuth in an open source Python library at Hacker Dojo and discussed/tested it in IRC. Tantek later launched a RelMeAuth prototype on his domain, which you can try out at tantek.com/relmeauth.
In 2011, we held the first IndieWebCamp in Portland. The registration process involved setting up OpenID on your own domain (or delegating your domain to an OpenID provider), and signing in to the IndieWebCamp Wiki and adding yourself to the guest list. Most people were able to successfully complete this intentional barrier to entry, but there were still parts that were cumbersome.
It was suggested that for the 2012 IndieWebCamp, we handle registrations via RelMeAuth instead, to slightly lower the barrier to entry. I shuddered at facing the daunting task of writing multiple OAuth clients as MediaWiki extensions in order to properly support RelMeAuth. It was then that the idea of IndieAuth.com was born.
What I needed was to write the RelMeAuth and OAuth client code once and be able to use it on any website needing authentication from here on out. I decided to build IndieAuth.com as a hosted service that anyone can easily use if they want to support RelMeAuth logins. By abstracting our the rel="me" and OAuth client logic into a very simple HTTP+JSON interface, it is now possible to quickly write a web page needing authentication by relying on IndieAuth.com to do the legwork.
In March 2012, I built a prototype of the site and gave a quick explanation in the #indiewebcamp IRC channel. A few days later, I launched this site on indieauth.com!
