Understanding Authentication

Building apps is fun. Authentication and security on the other hand...arguably, not as much. But these concepts are crucially important to understand as the world continues to move to where everything is connected. In order to interact with Shapeways’ feature set, your application will need access to user accounts and information with OAuth.

OAuth is an authorization framework that enables applications (“Clients”) to obtain access on behalf on resource owners (“Users”) over the internet. There are two versions of OAuth, each valid, but with respective pros and cons. Shapeways currently supports both.

  • OAuth1.0a provides a method strictly for web server-side implementations.
  • OAuth 2.0 expands upon its predecessor with a framework that enables not only traditional full-stack web server applications, but also mobile apps, single page web applications, and desktop software.

The concepts can be a bit confusing, but the below will try to unpack the terminology and the considerations through a series of hypothetical real-life examples.


Create an App

After clicking on the Create App button, you’ll be prompted to include some more detail about your app:

  • Application Name: Choose a title for your Shapeways App - this title may be shown during authentication, in Shapeways App Gallery, and on products that are generated using your app.
  • Application Website: Enter a link to the location of your application - this link will be used to direct users from the Shapeways App Gallery, and on products that are generated using your app.
  • Application Description: Write a description of your application - describe the types of products your app will create, why your app is unique, and any other information you'd like people to know.
  • Application Photo: Upload a 75x75px thumbnail for your application - this image will be displayed next to your application name during authentication, in the Shapeways App Gallery, and on products that are generated by using your app.
  • Default CategoryModels you upload and configure would be placed in the default category.
  • Redirect URI: (OAuth 2.0 only; optional but recommended) The redirect URI is where Shapeways will redirect the User after they authorize (or deny) your Application, and therefore the part of your Application that will handle authorization codes or access tokens. This is important to prevent man-in-the-middle phishing attacks in which attackers attempt to trick the Client into attaching the User’s access token to the attacker’s account.

Once your application is registered, Shapeways will issue "client credentials" in the form of a Client Id and a Client Secret (OAuth 2.0) and a Consumer Key and Consumer Secret (OAuth 1.0a)

Client ID and Secret (OAuth 2.0)

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, however, must be kept confidential. If a deployed app cannot keep the secret confidential, such as single-page Javascript apps or native apps, then the secret is not used.

If you are thinking about creating a single-page app or browser based app, it is recommended that you destroy the Client Secret from within the application settings:


Consumer Key and Secret (OAuth 1.0a)

OAuth 1.0a requires the cryptographic signing of a special oauth_signature parameter that needs to be passed in the Authorization header of the HTTP request among others (more on this later).

What is important to note here is that OAuth 1.0a only supports applications that can ensure confidentiality of Secrets and implements certain forms of cryptography (ie. HMAC-SHA1). This would best represent hosted web services like that of one built with Ruby on Rails, Django, LAMP, Node.JS, etc. The Consumer Key, like the Client Id, is public information and is passed along in the header as identifying information of the Application.


General OAuth Roles

Client (a.k.a the Application)

An application making protected resource requests on behalf of the User and with his/her/its authorization. The term Client does not imply any particular implementation characteristics (e.g. whether the application executes on a server, a desktop, or other devices)..

Resource Owner (a.k.a the User)

The resource owner is the User who authorizes an Application to access their account.

Note: In other implementations of OAuth 2.0, there is a notion of “scope”, in which the authorization server limits the kind of access (ie. read or write access) when granting the access tokens. Shapeways currently does not yet support scopes, but it is on our roadmap.

Resource Server (Shapeways)

The server hosting the protected resources (User models, products, orders), capable of accepting and responding to protected resource requests using access tokens.

Authorization Server (Shapeways)

The server issuing access tokens to the client after successfully authenticating the User and obtaining authorization.

Disclaimer: these Roles and Flow diagram are typically used when describing OAuth 2.0. While semantically there are different terms in OAuth 1.0a, the concepts are effectively the same.


OAuth 2.0

Choosing a Grant

A grant is a method of acquiring an access token. Deciding which grants to implement depends on the type of client the end user will be using, and the experience you want for your users. This can get complicated so we’ve constructed to help you decide:

Authorization Code

The authorization code grant type is the most commonly used because it is optimized for server-side applications, where source code is not publicly exposed, and Client Secret confidentiality can be maintained. This grant should be very familiar if you’ve ever signed into an application using your Facebook or Google account.

  1. User received link to authorize the Client
    https://api.shapeways.com/oauth2/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=CALLBACK_URL
  2. User authorizes the Client

    When the User is directed to the link, they must first log in to Shapeways, to authenticate their identity (unless they are already logged in). Then they will be prompted by the service to authorize access to their account. Here is an example authorize application prompt:

  3. The Client is granted an authorization code

    If the user clicks "Authorize", Shapeways redirects the User to a redirect URI, which was specified during the Client registration, along with an authorization code.

    https://yourwebsite.com/callback?code=AUTHORIZATION_CODE
  4. The Client users the authorization code to request an Access Token

    The application requests an access token from the API, by passing the authorization code along with authentication details, including the client secret, to the API token endpoint.

    https://api.shapeways.com/oauth2/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=CALLBACK_URL
  5. The Client receives an Access Token

    If the authorization is valid, the Shapeways’ API will send a response containing the access token (and optionally, a refresh token) to the application.

                                    {
                                        "access_token": "ACCESS_TOKEN",
                                        "token_type": "bearer",
                                        "expires_in": 3600,
                                        "refresh_token": "REFRESH_TOKEN"
                                    }
                                

Now you can make API calls simply by passing in the access token in the Authorization header.


Implicit Grant

The implicit grant type is used for mobile apps and web applications like single-page (browser-based) applications and apps for iOS and Android. Since the entire source code exists on the browser or device, there is no assurance that the Client Secret can be confidentially maintained. This flow does not authenticate the identity of the application or Client, and relies on the redirect URI to serve this purpose.

The implicit grant does not support refresh tokens.

  1. User received link to authorize the Client
    https://api.shapeways.com/oauth2/authorize?response_type=token&client_id=CLIENT_ID&redirect_uri=CALLBACK_URL
  2. User authorizes the Client

    When the User is directed to the link, they must first log in to Shapeways, to authenticate their identity (unless they are already logged in). Then they will be prompted by the service to authorize access to their account. Here is an example authorize application prompt:

  3. Browser/Device receives Access Token with Redirect URI
    https://yourwebsite.com/callback#access_token=ACCESS_TOKEN&token_type=bearer&expires_in=3600
  4. Parsing the Access Token from the URI
    1. The Browser/Device follows the URI
    2. The Client sends logic to extract the Access Token from the URI
    3. The Client extracts and saves the Access Token

    Now the application is authorized! It may use the token to access the User's account via the service API until the token expires or is revoked.


Authorization Code (No Secret)

Note: Previously, it was recommended that browser-based, mobile, and native apps use the "Implicit" flow, which returns an access token immediately and does not have a token exchange step. In the time since the spec was originally written, the industry best practice has changed to recommend that the authorization code flow be used without the client secret. This provides more opportunities to create a secure flow, such as using the state parameter.

  1. User received link to authorize the Client
    https://api.shapeways.com/oauth2/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=CALLBACK_URL&state=RANDOM_TEXT_TO_BE_VERIFIED_LATER
  2. User authorizes the Client

    When the User is directed to the link, they must first log in to Shapeways, to authenticate their identity (unless they are already logged in). Then they will be prompted by the service to authorize access to their account. Here is an example authorize application prompt:

  3. The Client is granted an authorization code

    If the user clicks "Authorize", Shapeways redirects the User to a redirect URI, which was specified during the Client registration, along with an authorization code.

    https://yourwebsite.com/callback?code=AUTHORIZATION_CODE&state=RANDOM_TEXT_TO_BE_VERIFIED_NOW

    You should first compare this state value to ensure it matches the one you started with. You can typically store the state value in a cookie, and compare it when the user comes back. This ensures your redirection endpoint isn't able to be tricked into attempting to exchange arbitrary authorization codes.


The remainder steps are identical to the original Authorization Code steps.


Client Credentials

The simplest of all of the OAuth 2.0 grants, this grant is suitable for machine-to-machine authentication where a specific user’s permission to access data is not required.

Here is an example POST request:

  1. User requests the Token
    https://api.shapeways.com/oauth2/token

    1. Content-Type header is application/x-www-form-urlencoded
      Body (x-www-form-urlencoded):
      { "grant_type": "client_credentials", "client_id": CLIENT_ID, "client_secret": CLIENT_SECRET }
    2. Authorization Header (recommended)

      Base64Encoded string of "<client id>:<client secret>"

      Authorization Basic BASE64ENCODED(CLIENT_ID:CLIENT_SECRET)

      Body (form-data):

      { "grant_type": "client_credentials" }
  2. The Client receives an Access Token

    If the authorization is valid, the Shapeways’ API will send a response containing the access token (and optionally, a refresh token) to the application.

                                    {
                                        "access_token": "ACCESS_TOKEN",
                                        "token_type": "bearer",
                                        "expires_in": 3600,
                                        "refresh_token": "REFRESH_TOKEN"
                                    }
                                

Now the application is authorized! It may use the token to access the user's account via the service API until the token expires or is revoked.


Refresh Token

After an access token expires, using it to make a request from the API will result in an "Invalid Token Error". At this point, if a refresh token was included when the original access token was issued, it can be used to request a fresh access token from the authorization server.

Here is an example POST request, using a refresh token to obtain a new access token:

  1. User requests the Token
    https://api.shapeways.com/oauth2/token

    1. Content-Type header is application/x-www-form-urlencoded
      Body (x-www-form-urlencoded):
      { "grant_type": "refresh_token", "client_id": CLIENT_ID, "refresh_token": REFRESH_TOKEN }
    2. Authorization Header (recommended)

      Base64Encoded string of "<client id>:<client secret>"

      Authorization Basic BASE64ENCODED(CLIENT_ID:CLIENT_SECRET)

      Body (form-data):

      { "grant_type": "refresh_token" "refresh_token": REFRESH_TOKEN }
  2. The Client receives an Access Token

    If the authorization is valid, the Shapeways’ API will send a response containing the access token (and optionally, a refresh token) to the application.

                                    {
                                        "access_token": "ACCESS_TOKEN",
                                        "token_type": "bearer",
                                        "expires_in": 3600,
                                        "refresh_token": "REFRESH_TOKEN"
                                    }
                                

Now the application is authorized! It may use the token to access the user's account via the service API until the token expires or is revoked.


OAuth 1.0a

Three-legged Flow

The flow for OAuth 1.0a is similar to the Authorization Code flow of OAuth 2.0 with a few additions to the server-side.

Here is the breakdown of terms and parameters you should be aware of:

  • Consumer Key
  • Consumer Secret
  • Signature Method
  • Timestamp
  • Nonce
  • Version

What your application is required to do is to provide the Authorization Header with a cryptographic signature using a combination of the Consumer Key and Consumer Secret above and encrypting it with the Signature Method (recommended is HMAC-SHA256). The nonce and timestamp are used, generally speaking, to verify requests as valid and unique top prevent replay attacks.

  1. Client requests a Temporary Request Token
    https://api.shapeways.com/oauth1/request_token/v1

    The Authorization Header includes parameters from the construction of the OAuth request:

    Authorization OAuth oauth_consumer_key=CONSUMER_KEY, oauth_signature_method="HMAC-SHA1", oauth_timestamp=UNIX_TIMESTAMP, oauth_nonce=UNIQUE_ALPHANUM_TEXT, oauth_version="1.0", oauth_signature=SIGNATURE
  2. User authorizes the Client

    When the User is directed to an authorization link, they must first log in to Shapeways, to authenticate their identity (unless they are already logged in). Then they will be prompted by the service to authorize access to their account. Here is an example authorize application prompt:

    authentication_url=https://api.shapeways.com/login?oauth_token=TEMPORARY_TOKEN&oauth_token_secret=TEMPORARY_TOKEN_SECRET&oauth_callback_confirmed=true
  3. The Client receives a Verifier Code

    If the user clicks "Authorize", Shapeways redirects the User to a page with a Verifier Code (similar to an Authorization Code).

    Verifier code: VERIFIER_CODE
  4. The Client exchanges Temp Credentials and the Verifier Code for Access Tokens

    The application requests an access token from the API, by passing the verifier code along with a new signature constructed with the temporary credentials to the Authorization Server:

    https://api.shapeways.com/oauth1/access_token/v1?oauth_verifier=VERIFIER_CODE

    The Authorization Header includes parameters from the construction of the OAuth request:

    Authorization OAuth oauth_consumer_key=CONSUMER_KEY, oauth_token=TEMPORARY_TOKEN, oauth_signature_method="HMAC-SHA1", oauth_timestamp=UNIX_TIMESTAMP, oauth_nonce=UNIQUE_ALPHANUM_TEXT, oauth_version="1.0", oauth_signature=SIGNATURE
  5. The Client receives an Access token

    oauth_token=ACCESS_TOKEN&oauth_token_secret=ACCESS_SECRET

Now you can make API calls by signing your Authorization header with the Consumer and Access Secrets.

Authorization OAuth oauth_consumer_key=CONSUMER_KEY, oauth_token=ACCESS_TOKEN, oauth_signature_method="HMAC-SHA1", oauth_timestamp=UNIX_TIMESTAMP, oauth_nonce=UNIQUE_ALPHANUM_TEXT, oauth_version="1.0", oauth_signature=SIGNATURE

Pros and Cons of OAuth 1.0a vs 2.0

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.

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.

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.